flagon-io/g1t

public

1	import type { ChecksApi } from "./checks";
2	import type { CodeownersReport, PullCodeOwners } from "./codeowners";
3	import type { User, Viewer } from "./identity";
4	import type { PullBranchUpdate, RepoPath } from "./repos";
5	import type { Result } from "./result";
6	import type { MergeRules, RulesApi } from "./rules";
7
8	/**
9	* The filter on lists of issues and pull requests. An open pull request is
10	* a draft or one ready for review; a closed one was merged or closed
11	* without merging.
12	*/
13	export type State = "open" \| "closed";
14
15	/** Why an issue was closed. */
16	export type IssueReason = "completed" \| "not_planned";
17
18	/**
19	* Something that should change in a repository: a bug, a feature, a
20	* question. Opened by a person, an agent or an integration. Pull requests
21	* are made against it; the one that is merged resolves it.
22	*
23	* Issues and pull requests share one sequence of numbers per repository.
24	*/
25	export type Issue = {
26	id: string;
27	repoId: string;
28	/** Shown as `#12`. */
29	number: number;
30	title: string;
31	/** Markdown. Also what an agent is given to work from. */
32	body: string;
33	labels: string[];
34	state: State;
35	/** Set when closed. */
36	reason: IssueReason \| null;
37	/** The number of the pull request whose merge closed this issue. */
38	resolvedBy: number \| null;
39	/** Who opened it: a person, an integration, or g1t (`kind` `agent`) for one its agent filed while at work. */
40	author: User;
41	/**
42	* For an issue g1t's agent filed: the person it was working for. They may
43	* manage it as its author could. See `workOwner`.
44	*/
45	requestedBy: User \| null;
46	/** RFC 3339. */
47	createdAt: string;
48	/** RFC 3339. */
49	updatedAt: string;
50	/** RFC 3339. */
51	closedAt: string \| null;
52	/** Pull requests made against this issue, in any state. */
53	pullCount: number;
54	commentCount: number;
55	/** Usernames of the people it is assigned to. */
56	assignees: string[];
57	/** The numbers of the issues that have to be merged before this one is worked on. */
58	blockedBy: number[];
59	/**
60	* Whether a g1t agent takes it as soon as it can: at once, or when what it
61	* is blocked by has merged.
62	*/
63	queued: boolean;
64	/**
65	* The agent working on it now: the one behind its newest pull request
66	* that is still in progress in a fork, such as `g1t`.
67	*/
68	agent: string \| null;
69	/** The milestone it is in, if any. */
70	milestone?: MilestoneRef \| null;
71	};
72
73	/**
74	* A label of a repository: a name, a color and what it means. Issues and
75	* pull requests carry labels by name; names are lowercase.
76	*/
77	export type Label = {
78	name: string;
79	/** Six hex digits, without `#`. */
80	color: string;
81	description: string;
82	/** How many issues carry it, open or closed. */
83	issues: number;
84	/** How many pull requests carry it, in any state. */
85	pulls: number;
86	};
87
88	/** A milestone, as an issue or pull request names it. */
89	export type MilestoneRef = { number: number; title: string };
90
91	/**
92	* A goal, with an optional due date, that issues and pull requests are
93	* gathered under. Its progress is how many of them are closed.
94	*/
95	export type Milestone = {
96	/** Numbered from 1 in each repository, apart from issues. */
97	number: number;
98	title: string;
99	/** Markdown. */
100	description: string;
101	/** `YYYY-MM-DD`. */
102	dueOn: string \| null;
103	state: State;
104	/** Open issues and pull requests in it. */
105	openItems: number;
106	/** Closed issues, and merged or closed pull requests, in it. */
107	closedItems: number;
108	createdAt: string;
109	updatedAt: string;
110	closedAt: string \| null;
111	};
112
113	/** One milestone and what is in it, newest first. */
114	export type MilestoneDetail = { milestone: Milestone; issues: Issue[]; pulls: Pull[] };
115
116	/** How `setLabels` changes an item's labels. */
117	export type LabelChange = "set" \| "add" \| "remove";
118
119	/**
120	* Whose an issue or a pull request is to answer for: whoever asked g1t for
121	* it, or its author. They may change, close and steer it, are never asked to
122	* review it and cannot approve it, and see it as theirs. Mirrors
123	* `Pull::owner` in the Rust contracts.
124	*/
125	export function workOwner(item: Pick<Pull, "author" \| "requestedBy">): User {
126	return item.requestedBy ?? item.author;
127	}
128
129	/** `draft` is still being worked on; `open` is ready for review. */
130	export type PullStatus = "draft" \| "open" \| "merged" \| "closed";
131
132	/** Where the agent runs: on g1t's sandboxes, or in someone's own session. */
133	export type Runtime = "hosted" \| "external";
134
135	/**
136	* A proposed change. It is made either in a fork created for it, which is
137	* how agents work, or on a branch pushed to the repository itself.
138	*/
139	export type Pull = {
140	id: string;
141	repoId: string;
142	/** Shown as `#12`. */
143	number: number;
144	/** The number of the issue this is for, if any. */
145	issue: number \| null;
146	title: string;
147	/** Markdown: what changed and why. Set when marked ready. */
148	body: string \| null;
149	/** A label for the agent doing the work, e.g. `claude-code`. */
150	agent: string;
151	runtime: Runtime;
152	status: PullStatus;
153	/** The fork holding the change, unless it is on a branch. */
154	fork: RepoPath \| null;
155	/** The fork's repository id. */
156	forkRepoId: string \| null;
157	/** The branch of the repository holding the change, unless it is in a fork. */
158	branch: string \| null;
159	headCommit: string \| null;
160	/**
161	* For a merged pull request, what the branch pointed to before the merge.
162	* Comparing against it shows what the pull request changed.
163	*/
164	mergeBase: string \| null;
165	/** Username of whoever merged it. */
166	mergedBy: string \| null;
167	/** RFC 3339. */
168	mergedAt: string \| null;
169	/**
170	* Set on a pull request closed because another one for the same issue was
171	* merged: that one's number.
172	*/
173	supersededBy: number \| null;
174	/**
175	* Where the latest run of the issue's acceptance checks stands, if there
176	* has been one against the current head.
177	*/
178	checkStatus: CheckStatus \| null;
179	/** The files it changes, as of its latest push. */
180	files: ChangedFile[];
181	/** Usernames of the people it is assigned to. */
182	assignees: string[];
183	/**
184	* Those whose review was asked for: usernames, and `g1t` when a g1t
185	* agent was asked.
186	*/
187	reviewers: string[];
188	/**
189	* Teams whose review was asked for, as `workspace/slug`. A team stays here
190	* after review assignment picks people from it, who are in `reviewers`.
191	*/
192	teamReviewers?: string[];
193	/** The labels it carries, by name. */
194	labels?: string[];
195	/** The milestone it is in, if any. */
196	milestone?: MilestoneRef \| null;
197	/**
198	* The branch it merges into. Lists and `getPull` name it; null only in
199	* what services pass between themselves, for the default branch.
200	*/
201	base?: string \| null;
202	/** Who opened it: a person, or g1t (`kind` `agent`, username `g1t`) for a change g1t made. */
203	author: User;
204	/**
205	* For a change g1t made: the person who asked for it, by assigning an issue
206	* or handing g1t the work. They answer for it as its author would. See
207	* `workOwner`.
208	*/
209	requestedBy: User \| null;
210	/** RFC 3339. */
211	createdAt: string;
212	/** RFC 3339. */
213	updatedAt: string;
214	/**
215	* How sure g1t is of a g1t agent's change, from what it can observe, once
216	* the agent has finished it. Absent before then, and on changes g1t is
217	* not seeing through.
218	*/
219	confidence?: Confidence \| null;
220	/** Who last moved its head (a user id), and when; absent until a push after rulesets arrived. */
221	headPushedBy?: string;
222	headPushedAt?: string;
223	};
224
225	/** How sure g1t is that an agent's change is right. */
226	export type ConfidenceLevel = "low" \| "medium" \| "high";
227
228	/**
229	* How sure g1t is of a change an agent made, worked out from what can be
230	* observed: its checks, how often it was sent back, the reviewer agent's
231	* verdict, whether it touched tests, its size, where it reached, how close
232	* it came to its guardrails, and what it asked without an answer. The
233	* agent's own word can only lower it.
234	*/
235	export type Confidence = {
236	level: ConfidenceLevel;
237	/** A few words each, most telling first: what lowered it, or for `high`, what it rests on. */
238	reasons: string[];
239	/** What the agent said of its own change, if it said. */
240	selfReported: ConfidenceLevel \| null;
241	/** What the agent said it was unsure about. */
242	uncertainAbout: string[];
243	/** The agent run it was worked out after. */
244	runId: string \| null;
245	/** RFC 3339. */
246	assessedAt: string;
247	};
248
249	/** What became of the agent when an issue was opened and handed to it in one step. */
250	export type AgentStartStatus = "started" \| "queued" \| "not_started";
251
252	/** Whether the agent started, and if not, why and what fixes it. */
253	export type AgentStart = {
254	status: AgentStartStatus;
255	/**
256	* Why it did not start: `not_paid`, `trial_used`, `limit`, `paused`,
257	* `issue_cap`, `billing_unavailable` or `no_model`; `waiting` when queued.
258	*/
259	code: string \| null;
260	/** What happened, in a sentence or two, with what to do. */
261	message: string \| null;
262	/** Where the fix is: the workspace's billing or model settings. */
263	fixUrl: string \| null;
264	};
265
266	/** An issue opened and handed to g1t in one step. The issue exists whatever became of the agent. */
267	export type Delegated = {
268	issue: Issue;
269	/** The pull request the agent opened, when it started. */
270	pull: Pull \| null;
271	agent: AgentStart;
272	};
273
274	/**
275	* What to put an agent on: an issue's title, and what to do in plain words,
276	* with what done means if you like (a "Definition of done" section). What
277	* has to pass before it merges is the branch's required checks.
278	*/
279	export type DelegateInput = {
280	title: string;
281	body: string;
282	labels?: string[];
283	/** Deprecated: commands, added to the body under "Definition of done". */
284	checks?: string[];
285	};
286
287	/** One file a pull request changes, and by how much. */
288	export type ChangedFile = { path: string; additions: number; deletions: number };
289
290	/**
291	* Another pull request in progress that changes some of the same files. Two
292	* for the same issue are alternatives; two for different issues are heading
293	* for a conflict.
294	*/
295	export type Overlap = {
296	number: number;
297	title: string;
298	/** The number of the issue the other pull request is for. */
299	issue: number \| null;
300	/** The files both change. */
301	paths: string[];
302	};
303
304	/**
305	* On a pull request, `failed` means the merge queue took it out, until its
306	* head moves. The other states are from runs of commands written on issues,
307	* which g1t no longer runs.
308	*/
309	export type CheckStatus = "queued" \| "running" \| "passed" \| "failed" \| "errored";
310
311	/** How one command went, in a run recorded before checks were workflows. */
312	export type CheckResult = {
313	command: string;
314	passed: boolean;
315	/** Null when the command was stopped for taking too long. */
316	exitCode: number \| null;
317	/** What the command printed; the end of it, when there was a lot. */
318	output: string;
319	durationMs: number;
320	};
321
322	/**
323	* A record against a pull request's head: the merge queue taking it out,
324	* with why, or an earlier run of commands written on its issue.
325	*/
326	export type CheckRun = {
327	id: string;
328	/** The commit that was checked. */
329	headCommit: string;
330	status: CheckStatus;
331	results: CheckResult[];
332	/** Why the checks could not be run, when `status` is `errored`. */
333	error: string \| null;
334	/** RFC 3339. */
335	createdAt: string;
336	/** RFC 3339. */
337	finishedAt: string \| null;
338	};
339
340	/** A reviewer's decision on a pull request. */
341	export type Verdict = "approve" \| "request_changes";
342
343	/**
344	* A comment on an issue or a pull request. On a pull request it can sit on
345	* one line of the change, and it can carry a reviewer's verdict.
346	*/
347	export type Comment = {
348	id: string;
349	/**
350	* Something a person or an agent wrote, or something that happened: an
351	* assignment, a review asked for, a close.
352	*/
353	kind: "comment" \| "event";
354	author: User;
355	/**
356	* Markdown. For an event, what its author did, as the rest of a sentence
357	* that starts with their name: "assigned ana".
358	*/
359	body: string;
360	/** The file commented on, for a comment on a line. */
361	path: string \| null;
362	/** The line of that file, as numbered after the change. */
363	line: number \| null;
364	verdict: Verdict \| null;
365	/** RFC 3339. */
366	createdAt: string;
367	/** When its text was last edited, RFC 3339; absent if it never was. */
368	editedAt?: string;
369	};
370
371	export type NewComment = {
372	/** May be empty when approving. */
373	body: string;
374	path?: string;
375	line?: number;
376	verdict?: Verdict;
377	};
378
379	/** What a sandbox needs to carry out a check run. */
380	export type CheckJob = {
381	runId: string;
382	/** Lets the sandbox, and nothing else, report this run's results. */
383	token: string;
384	commands: string[];
385	/** The repository holding the commit: the fork, or the repository itself. */
386	source: RepoPath;
387	commit: string;
388	/** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
389	author: User;
390	/** Username of whoever wrote the checks: the issue's author. */
391	requestedBy: string;
392	repo: RepoPath;
393	number: number;
394	};
395
396	export type CheckReport = { results?: CheckResult[]; error?: string; skip?: boolean };
397
398	export type SessionEntryKind = "prompt" \| "message" \| "tool_call" \| "tool_result" \| "note";
399
400	/** One step of an agent's session: the "why" behind a pull request's commits. */
401	export type SessionEntry = {
402	seq: number;
403	kind: SessionEntryKind;
404	text: string;
405	/** For tool calls and results. */
406	tool: string \| null;
407	/** The fork's head commit when this entry was recorded, if known. */
408	commit: string \| null;
409	/** RFC 3339. */
410	at: string;
411	};
412
413	export type NewSessionEntry = Pick<SessionEntry, "kind" \| "text"> &
414	Partial<Pick<SessionEntry, "tool" \| "commit">>;
415
416	export type IssueDetail = {
417	issue: Issue;
418	/** Every pull request made against it, oldest first. */
419	pulls: Pull[];
420	comments: Comment[];
421	};
422
423	export type PullDetail = {
424	pull: Pull;
425	/** The issue it is for, if any. */
426	issue: Issue \| null;
427	comments: Comment[];
428	/** The latest record against its head: the merge queue taking it out. */
429	checks: CheckRun \| null;
430	/** Other pull requests in progress that change the same files. */
431	overlaps: Overlap[];
432	/**
433	* Whether the branch it would merge into has moved on without it, so that
434	* it has to catch up before it can merge.
435	*/
436	behind: boolean;
437	/** Whether a g1t agent is reviewing it right now. */
438	reviewPending: boolean;
439	/**
440	* Where it stands on its way to being merged, for a pull request g1t is
441	* seeing through. Null on anyone else's.
442	*/
443	lifecycle: Lifecycle \| null;
444	/**
445	* A merge was asked for while it was behind: g1t is bringing it up to
446	* date and will then land it.
447	*/
448	landing: boolean;
449	/** Why g1t stopped working on it, if it did. */
450	stalled: string \| null;
451	/** Messages people sent the agent while it worked, oldest first. */
452	messages: AgentMessage[];
453	/** What workflow runs said about its head commit, one per workflow. */
454	statuses?: CommitStatus[];
455	/**
456	* Whether it merges cleanly into the branch it targets, worked out ahead
457	* of time whenever either side moves.
458	*/
459	mergeable?: Mergeable;
460	/** When `mergeable` is `conflicting`: the files that conflict. */
461	conflicts?: string[];
462	/** Earlier records like `checks`, newest first, without their output. */
463	earlierChecks?: CheckRun[];
464	/**
465	* The checks the default branch's protection requires, each as it stands
466	* on the head commit. Empty when none are required.
467	*/
468	requiredChecks?: RequiredCheck[];
469	/**
470	* Who owns the files it changes (the CODEOWNERS file of the branch it
471	* merges into) and whose approval is still needed. Absent without one.
472	*/
473	codeOwners?: PullCodeOwners \| null;
474	/**
475	* The rules of the branch it merges into it does not meet yet, for whoever
476	* is looking: what refuses the merge, what they may bypass, and what rulesets
477	* in evaluate would refuse. Absent once it is closed or merged.
478	*/
479	rules?: MergeRules \| null;
480	};
481
482	/** Where a required check stands on a commit; `expected` when nothing has reported it yet. */
483	export type RequiredState = "success" \| "failure" \| "pending" \| "expected";
484
485	/** One check a branch's protection requires, as it stands on a commit. */
486	export type RequiredCheck = {
487	/** A workflow's name, such as `CI`, or another status's context. */
488	name: string;
489	state: RequiredState;
490	description: string \| null;
491	/** Where to see more: the workflow run, for one a workflow reported. */
492	targetUrl: string \| null;
493	};
494
495	/** A check name reported on a repository's commits lately, for choosing required checks. */
496	export type SeenCheck = {
497	name: string;
498	/** The events it was reported for, such as `pull_request`; empty for a status that names none. */
499	events: string[];
500	/** RFC 3339. */
501	lastSeen: string;
502	};
503
504	/**
505	* A status context's check name: `CI / pull_request` is the `CI` check,
506	* reported for a `pull_request` event. A context that does not end in an
507	* event, such as `g1t / deploy`, is its own name. As the work service reads it.
508	*/
509	export function checkName(context: string): string {
510	const at = context.lastIndexOf(" / ");
511	if (at <= 0) return context;
512	return STATUS_EVENTS.has(context.slice(at + 3)) ? context.slice(0, at) : context;
513	}
514
515	const STATUS_EVENTS = new Set([
516	"push",
517	"pull_request",
518	"pull_request_target",
519	"pull_request_review",
520	"merge_group",
521	"workflow_dispatch",
522	"workflow_run",
523	"workflow_call",
524	"schedule",
525	"release",
526	"issues",
527	"issue_comment",
528	"repository_dispatch",
529	]);
530
531	/**
532	* Whether a pull request merges cleanly into the branch it targets:
533	* `unknown` when it was never worked out or could not be, `checking` while
534	* a probe merges the two.
535	*/
536	export type Mergeable = "clean" \| "conflicting" \| "unknown" \| "checking";
537
538	/** What a sandbox needs to find out whether a pull request merges cleanly. */
539	export type MergecheckJob = {
540	pullId: string;
541	/** Lets the sandbox, and nothing else, report this probe. */
542	token: string;
543	repo: RepoPath;
544	number: number;
545	defaultBranch: string;
546	/** The default branch's commit to merge into. */
547	base: string;
548	/** The repository holding the change: its fork, or the repository. */
549	source: RepoPath;
550	/** The branch of `source` holding it. */
551	branch: string;
552	/** The change's commit. */
553	head: string;
554	/** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
555	author: User;
556	};
557
558	/** What a workflow run (or another tool) says about a commit. */
559	export type CommitStatus = {
560	/** What reported it, such as `CI / push`. */
561	context: string;
562	state: "pending" \| "success" \| "failure" \| "error";
563	description: string \| null;
564	targetUrl: string \| null;
565	updatedAt: string;
566	/** The integration that reported it: `actions`, `deployments`, `security`, `g1t` or `api`. */
567	source?: string;
568	/** Set on the status a check run stands as: the check run's id. */
569	checkRunId?: string;
570	};
571
572	/**
573	* A step on the way from an assigned issue to a pull request that is ready
574	* to merge. g1t takes each one without being asked: `working` (the agent is
575	* making the change), `checking`, `reviewing`, `revising` (the agent is
576	* addressing failed checks or a review), `catching_up` (merging in the
577	* branch it would land on), `answering` (woken to answer another agent),
578	* then `ready` for a person to merge. `needs_you`
579	* means g1t has stopped and a person decides what happens next.
580	*/
581	export type Stage =
582	\| "working"
583	\| "checking"
584	\| "reviewing"
585	\| "revising"
586	\| "catching_up"
587	\| "answering"
588	\| "queued"
589	\| "ready"
590	\| "needs_you";
591
592	export type Lifecycle = {
593	stage: Stage;
594	/** One sentence saying what is happening, or why it stopped. */
595	detail: string;
596	/** How many times the agent has been sent back to revise it. */
597	revisions: number;
598	};
599
600	/** What the runner needs to carry out a step of a pull request's lifecycle. */
601	export type LifecycleJob = {
602	pullId: string;
603	repo: RepoPath;
604	number: number;
605	/** Who the pull request belongs to (`workOwner`: whoever asked g1t for it, or its author). Sandboxes act as them. */
606	author: User;
607	/** The repository holding the change: its fork, or the repository itself. */
608	source: RepoPath;
609	/** The branch of the source holding the change; its default branch when null. */
610	branch: string \| null;
611	defaultBranch: string;
612	title: string;
613	description: string;
614	issue: Issue \| null;
615	/** For a revision: the failed checks or the review to address. */
616	feedback: string;
617	/** For a revision: which one this is, from 1. */
618	round: number;
619	};
620
621	/** An agent woken to answer what other agents sent it while it was not at work. */
622	export type Wake = { job: LifecycleJob; messages: AgentMessage[] };
623
624	/**
625	* `planning` while an agent reads the repository and writes it; `ready` for
626	* a person to read and apply; `failed` if it could not be written;
627	* `applied` once its issues are open.
628	*/
629	export type PlanStatus = "planning" \| "ready" \| "failed" \| "applied";
630
631	/** One issue a plan proposes. */
632	export type PlannedIssue = {
633	title: string;
634	/** Markdown: what to change, where, and why. */
635	body: string;
636	labels: string[];
637	/** What is true once it is done, in plain words; added to the issue's body under "Definition of done". */
638	done: string[];
639	/** The files it will most likely change. */
640	files: string[];
641	/**
642	* The positions, counting from 1, of earlier issues in the plan that have
643	* to be merged first.
644	*/
645	dependsOn: number[];
646	/** Its number, once the plan has been applied and it was kept. */
647	number: number \| null;
648	};
649
650	/** An outcome someone wrote, and the issues an agent proposes to get there. */
651	export type Plan = {
652	id: string;
653	repoId: string;
654	/** The outcome wanted, as written. */
655	brief: string;
656	status: PlanStatus;
657	/** The agent's account of how it split the work. */
658	summary: string;
659	issues: PlannedIssue[];
660	/** Why it could not be written, when `status` is `failed`. */
661	error: string \| null;
662	author: User;
663	/** RFC 3339. */
664	createdAt: string;
665	/** RFC 3339. */
666	finishedAt: string \| null;
667	/** Once applied: where each issue it opened stands now, in plan order. */
668	progress: IssueProgress[];
669	/** Questions and handoffs between its pull requests' agents, newest first. */
670	exchanges: AgentMessage[];
671	};
672
673	/** What a sandbox needs to write a plan. */
674	export type PlanJob = {
675	planId: string;
676	/** Lets the sandbox, and nothing else, report this plan. */
677	token: string;
678	brief: string;
679	repo: RepoPath;
680	};
681
682	/** An issue waiting for a g1t agent that can be given one now. */
683	export type ReadyIssue = {
684	repo: RepoPath;
685	number: number;
686	/** Who queued it, on whose say-so the agent works. */
687	actor: User;
688	};
689
690	/**
691	* How a repository wants its pull requests handled. A repository that has
692	* changed nothing has the defaults.
693	*/
694	export type RepoSettings = {
695	/**
696	* Land a g1t agent's pull request without a person once it is ready:
697	* checks passed and approved as the settings below require.
698	*/
699	autoMerge: boolean;
700	/**
701	* The checks that must pass on a pull request's head before it may merge
702	* into the default branch, by name: a workflow's name (`CI`) or another
703	* status's context (`g1t / deploy`). The same for people and agents, and
704	* for the merge queue.
705	*/
706	requiredChecks: string[];
707	/**
708	* Refuse to merge a pull request that does not contain the default
709	* branch's latest commits, so that what merges is what was checked. When
710	* off, merging one that is behind brings it up to date first.
711	*/
712	requireUpToDate: boolean;
713	/**
714	* How many approving reviews a pull request needs before it may merge. A
715	* reviewer who has since asked for changes blocks it.
716	*/
717	requiredApprovals: number;
718	/** Whether a g1t agent's approval counts towards `requiredApprovals`. */
719	countAgentApprovals: boolean;
720	/** Whether someone who may merge can bypass required checks that have not passed. */
721	allowIgnoringChecks: boolean;
722	/** Whether a g1t agent's pull request is reviewed by a second agent unasked. */
723	agentReview: boolean;
724	/**
725	* How many times a g1t agent is sent back to its pull request before a
726	* person is asked instead.
727	*/
728	maxRevisions: number;
729	/**
730	* Merge through a queue: pull requests are tested together with those
731	* ahead of them, and only a combination that passed reaches the default
732	* branch.
733	*/
734	mergeQueue: boolean;
735	/**
736	* Ask a person before merging a g1t agent's change whose confidence is
737	* low: auto-merge and the merge queue leave it until a person approves it.
738	*/
739	holdLowConfidence: boolean;
740	/**
741	* Refuse to merge until the code owners of every file it changes have
742	* approved, as many as each section asks. People only; `g1t` only where
743	* the file names `@g1t`.
744	*/
745	requireCodeOwnerReview?: boolean;
746	/** Username of the member who last changed the settings, if anyone has. */
747	updatedBy: string \| null;
748	/** RFC 3339. */
749	updatedAt: string \| null;
750	};
751
752	/** The settings a member can change. */
753	export type RepoSettingsInput = Omit<RepoSettings, "updatedBy" \| "updatedAt">;
754
755	/** The next step for a pull request g1t is seeing through, already claimed. */
756	export type Advance =
757	\| { action: "none" }
758	\| { action: "review" \| "revise" \| "catch_up"; job: LifecycleJob };
759
760	/** What a sandbox needs to review a pull request. */
761	export type ReviewJob = {
762	runId: string;
763	/** Lets the sandbox, and nothing else, report this review. */
764	token: string;
765	/** The repository holding the commit: the fork, or the repository itself. */
766	source: RepoPath;
767	commit: string;
768	repo: RepoPath;
769	defaultBranch: string;
770	number: number;
771	title: string;
772	description: string;
773	/** The issue the pull request is for, which says what it should achieve. */
774	issue: Issue \| null;
775	/** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
776	author: User;
777	/**
778	* The files it changes, as of its latest push: how large the change is,
779	* which decides the model that reviews it.
780	*/
781	files: ChangedFile[];
782	/**
783	* What among them runs, configures or guards things (CI workflows,
784	* secrets, infrastructure), once each. Any sends the review to the
785	* larger model.
786	*/
787	sensitive: string[];
788	};
789
790	export type OpenIssueInput = {
791	title: string;
792	body: string;
793	labels?: string[];
794	/** Deprecated: commands, added to the body under "Definition of done". */
795	checks?: string[];
796	/** The number of the milestone to put it in. Needs the Triage role. */
797	milestone?: number;
798	};
799
800	export type UpdateIssueInput = {
801	title?: string;
802	body?: string;
803	labels?: string[];
804	/** Usernames of the people it is assigned to; replaces the whole set. */
805	assignees?: string[];
806	/** The number of the milestone to put it in; 0 takes it out. */
807	milestone?: number;
808	};
809
810	export type OpenPullInput = {
811	/** The number of the issue this is for. */
812	issue?: number;
813	/** Defaults to the issue's title; required without an issue. */
814	title?: string;
815	/** What changed and why. Usually set later, when a draft is marked ready. */
816	body?: string;
817	/**
818	* A branch of the repository that already holds the change. The pull
819	* request is then ready for review at once and has no fork.
820	*/
821	branch?: string;
822	agent: string;
823	runtime: Runtime;
824	/** The branch to merge into: the default branch when left out. */
825	base?: string;
826	/**
827	* Opened from a branch as a draft, still being worked on: it can't merge,
828	* and agents' review routines wait, until it is marked ready.
829	*/
830	draft?: boolean;
831	};
832
833	/** One repository's pull requests from `pullsForRepos`, newest first. */
834	export type RepoPulls = {
835	repoId: string;
836	/** Draft and open. */
837	open: Pull[];
838	/** Merged and closed. */
839	closed: Pull[];
840	};
841
842	/** Issues, pull requests, comments and sessions. */
843	export interface WorkApi extends RulesApi, ChecksApi {
844	openIssue(actor: User, repo: RepoPath, input: OpenIssueInput): Promise<Result<Issue>>;
845	/**
846	* Opens an issue to put g1t on at once: refused, with nothing
847	* opened, unless `actor` may put agents to work in `repo`. The runner's
848	* `delegate` calls it, then starts the agent.
849	*/
850	delegateIssue(actor: User, repo: RepoPath, input: DelegateInput): Promise<Result<Issue>>;
851	/** Newest first. */
852	listIssues(
853	repo: RepoPath,
854	viewer: Viewer,
855	filter?: { state?: State; label?: string; milestone?: number },
856	): Promise<Result<Issue[]>>;
857	getIssue(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<IssueDetail>>;
858	/** The author or a member of the workspace may. */
859	updateIssue(actor: User, repo: RepoPath, number: number, input: UpdateIssueInput): Promise<Result<Issue>>;
860	closeIssue(actor: User, repo: RepoPath, number: number, reason?: IssueReason): Promise<Result<Issue>>;
861	reopenIssue(actor: User, repo: RepoPath, number: number): Promise<Result<Issue>>;
862	/** A repository's labels, by name, each with how many issues and pull requests carry it. */
863	listLabels(repo: RepoPath, viewer: Viewer): Promise<Result<Label[]>>;
864	/**
865	* Creates a label, or with `name` changes one; renaming it renames it on
866	* everything that carries it. Needs the Triage role.
867	*/
868	saveLabel(
869	actor: User,
870	repo: RepoPath,
871	label: { name?: string; newName?: string; color?: string; description?: string },
872	): Promise<Result<Label>>;
873	/** Removes a label from the repository and everything carrying it. */
874	deleteLabel(actor: User, repo: RepoPath, name: string): Promise<Result<boolean>>;
875	/** Adds the default labels the repository does not have yet; returns them all. */
876	addDefaultLabels(actor: User, repo: RepoPath): Promise<Result<Label[]>>;
877	/**
878	* The labels of an issue or a pull request, replaced, added to or taken
879	* from. Labels the repository lacks are created for someone with the
880	* Triage role. Returns its labels now.
881	*/
882	setLabels(
883	actor: User,
884	repo: RepoPath,
885	number: number,
886	labels: string[],
887	change?: LabelChange,
888	): Promise<Result<string[]>>;
889	/** Open ones by due date, then closed ones; both unless `state` says. */
890	listMilestones(repo: RepoPath, viewer: Viewer, state?: State): Promise<Result<Milestone[]>>;
891	getMilestone(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<MilestoneDetail>>;
892	/** Creates a milestone, or with `number` changes the fields given. Needs the Triage role. */
893	saveMilestone(
894	actor: User,
895	repo: RepoPath,
896	milestone: { number?: number; title?: string; description?: string; dueOn?: string; state?: State },
897	): Promise<Result<Milestone>>;
898	deleteMilestone(actor: User, repo: RepoPath, number: number): Promise<Result<boolean>>;
899	/** How many issues and pull requests are open. */
900	counts(repo: RepoPath, viewer: Viewer): Promise<Result<{ issues: number; pulls: number }>>;
901
902	/**
903	* On an issue or a pull request. On a pull request it may name a line of
904	* the change and carry a verdict; nobody can give a verdict on their own.
905	*/
906	addComment(actor: User, repo: RepoPath, number: number, comment: NewComment): Promise<Result<Comment>>;
907	/**
908	* Changes a comment's text. Its author may, and so may anyone with the
909	* Maintain role or higher; notes of what happened cannot be changed.
910	*/
911	editComment(actor: User, repo: RepoPath, commentId: string, body: string): Promise<Result<Comment>>;
912	/**
913	* Deletes a comment: its author, or anyone with the Maintain role or
914	* higher. A review that gave a verdict cannot be deleted, only edited.
915	*/
916	deleteComment(actor: User, repo: RepoPath, commentId: string): Promise<Result<boolean>>;
917
918	/**
919	* Always refused now: a pull request's checks are the workflows run on
920	* it. Kept for a runner from before.
921	*/
922	startChecks(pullId: string): Promise<Result<CheckJob>>;
923	/**
924	* What a sandbox says about a run from before checks were workflows: so
925	* one still finishing is recorded.
926	*/
927	reportChecks(runId: string, token: string, report: CheckReport): Promise<Result<CheckRun>>;
928	/** Begins a review by a g1t agent. For the runner service. */
929	startReview(pullId: string): Promise<Result<ReviewJob>>;
930	/** Records that a review could not be written. For the runner service. */
931	failReview(runId: string, token: string, error: string): Promise<Result<boolean>>;
932	/**
933	* Claims the probe of whether a pull request merges cleanly that a
934	* `pull.mergecheck` event asked for. Refused when it is no longer wanted
935	* or the repository has as many running as it may. For the runner service.
936	*/
937	startMergecheck(pullId: string): Promise<Result<MergecheckJob>>;
938	/** Records that a probe could not be carried out. For the runner service. */
939	failMergecheck(pullId: string, token: string, error: string): Promise<Result<Mergeable>>;
940
941	/**
942	* Works out the next step for a pull request g1t is seeing through and,
943	* if there is one to take now, claims it, so that it is taken once
944	* however often this is called. For the runner service.
945	*/
946	advance(pullId: string): Promise<Advance>;
947	/** Records that a step could not be carried out, so a person is asked. */
948	stall(pullId: string, reason: string): Promise<boolean>;
949	/** Ids of the open pull requests g1t is seeing through. */
950	managedPulls(repoId?: string): Promise<string[]>;
951
952	/** A repository's merge queue: what is in it, in order, and what recently left. */
953	queue(repo: RepoPath, viewer: Viewer): Promise<Result<QueueView>>;
954	/**
955	* The next batch of combined states to test for a repository, one per
956	* entry; empty while a batch is being tested or nothing waits.
957	*/
958	queueBuild(repoId: string): Promise<QueueJob[]>;
959	/** Reports that a combined state could not be built or checked. */
960	failQueue(entryId: string, token: string, error: string): Promise<Result<QueueState>>;
961	/** Sends the agent working on a pull request a message, for its next step. */
962	messageAgent(actor: User, repo: RepoPath, number: number, body: string): Promise<Result<AgentMessage>>;
963	/** Takes a pull request out of the merge queue. Members only. */
964	removeFromQueue(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
965
966	getSettings(repo: RepoPath, viewer: Viewer): Promise<Result<RepoSettings>>;
967	/** The check names reported on the repository's commits in the last 30 days, most recent first. */
968	seenChecks(repo: RepoPath, viewer: Viewer): Promise<Result<SeenCheck[]>>;
969	/** Members of the repository's workspace only. */
970	updateSettings(actor: User, repo: RepoPath, settings: RepoSettingsInput): Promise<Result<RepoSettings>>;
971	/** The CODEOWNERS file at a branch (the default when left out), checked. Needs Read. */
972	codeownersErrors(repo: RepoPath, viewer: Viewer, ref?: string \| null): Promise<Result<CodeownersReport>>;
973	/**
974	* What the runner needs to bring a pull request up to date because a
975	* merge of it was asked for. Null if none was.
976	*/
977	catchUpJob(pullId: string): Promise<LifecycleJob \| null>;
978	/**
979	* Claims a short step for the agent on a pull request to answer the
980	* questions and handoffs it was sent while not at work, and hands them
981	* over, marked read. Null when there is nothing waiting or it cannot
982	* take a step now.
983	*/
984	wakeForMessages(pullId: string): Promise<Wake \| null>;
985
986	/**
987	* Opens a pull request: a draft with a fork to push to, or, given a
988	* branch, one ready for review.
989	*/
990	openPull(actor: User, repo: RepoPath, input: OpenPullInput): Promise<Result<Pull>>;
991	/** Newest first. */
992	listPulls(
993	repo: RepoPath,
994	viewer: Viewer,
995	state?: State,
996	filter?: { label?: string; milestone?: number; base?: string },
997	): Promise<Result<Pull[]>>;
998	/**
999	* The newest `limit` open and closed pull requests of each repository,
1000	* in one call. Repositories the viewer cannot read, and forks, are left
1001	* out: ask those with `listPulls`.
1002	*/
1003	pullsForRepos(repoIds: string[], viewer: Viewer, limit: number): Promise<RepoPulls[]>;
1004	getPull(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<PullDetail>>;
1005	/**
1006	* Changes who a pull request is assigned to and whose review is asked
1007	* for; each list given replaces the whole set. Asking for `g1t`'s
1008	* review does not by itself start one: the runner's `review` does.
1009	*/
1010	updatePull(
1011	actor: User,
1012	repo: RepoPath,
1013	number: number,
1014	changes: {
1015	assignees?: string[];
1016	reviewers?: string[];
1017	labels?: string[];
1018	/** 0 takes it out of its milestone. */
1019	milestone?: number;
1020	/** The branch it merges into. Needs the Write role. */
1021	base?: string;
1022	},
1023	): Promise<Result<Pull>>;
1024	/**
1025	* Brings a pull request up to date with the default branch in seconds,
1026	* without a sandbox, when the two changed different files: the merge
1027	* commit is pushed to its branch as `actor`, who must be whoever opened
1028	* it (for a fork) or a member (for a branch). Otherwise `needs_agent`, and
1029	* nothing is pushed: the runner's `update` is the way on.
1030	*/
1031	catchUpPull(actor: User, repo: RepoPath, number: number): Promise<Result<PullBranchUpdate>>;
1032	/** Marks a draft ready for review and sets its description. */
1033	readyPull(actor: User, repo: RepoPath, number: number, summary: string): Promise<Result<Pull>>;
1034	closePull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
1035	/** Opens a closed pull request again, as the draft it was if it was closed as one. Never a merged one. */
1036	reopenPull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
1037	/** Turns an open pull request back into a draft; it leaves the merge queue. */
1038	convertPullToDraft(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
1039	/**
1040	* Lands the pull request on the repository's default branch. Unless
1041	* `keepIssueOpen`, that resolves the issue it was for: the issue closes
1042	* naming this pull request, and the others still in progress for it close
1043	* as superseded. Only members of the repository's workspace may merge.
1044	*
1045	* If the default branch has moved, the pull request is brought up to date
1046	* first and lands when that is done; it comes back still open, and
1047	* `PullDetail.landing` is true meanwhile. A repository that requires pull
1048	* requests to be up to date refuses instead.
1049	*/
1050	mergePull(
1051	actor: User,
1052	repo: RepoPath,
1053	number: number,
1054	options?: {
1055	keepIssueOpen?: boolean;
1056	/** Merge although required checks have not passed, where the rule requiring them allows it. */
1057	ignoreChecks?: boolean;
1058	/** Merge past rules a ruleset lets the actor bypass. Recorded as a bypass. */
1059	bypassRules?: boolean;
1060	},
1061	): Promise<Result<Pull>>;
1062	/**
1063	* Drafts and open pull requests the viewer started, most recently active
1064	* first, each with where it stands if g1t is seeing it through.
1065	*/
1066	listActivePulls(
1067	viewer: Viewer,
1068	): Promise<{ pull: Pull; issue: Issue \| null; lifecycle: Lifecycle \| null }[]>;
1069	/**
1070	* The issues and pull requests a person opened, a page at a time, only
1071	* on repositories the viewer may read. Not found for no such account.
1072	*/
1073	byAuthor(username: string, viewer: Viewer, filter?: AuthoredFilter): Promise<Result<Authored>>;
1074	/**
1075	* What a person did each day of the last year (issues and pull requests
1076	* opened, reviews given), only on repositories the viewer may read: the
1077	* calendar on their profile. Not found for no such account.
1078	*/
1079	contributions(username: string, viewer: Viewer): Promise<Result<Contributions>>;
1080
1081	/**
1082	* Records an outcome to plan for. Members only. For the runner service,
1083	* which starts the sandbox in which an agent writes the plan.
1084	*/
1085	startPlan(actor: User, repo: RepoPath, brief: string): Promise<Result<PlanJob>>;
1086	/** Records that a plan could not be written. For the runner service. */
1087	failPlan(planId: string, token: string, error: string): Promise<Result<boolean>>;
1088	/** Members only. */
1089	getPlan(repo: RepoPath, viewer: Viewer, id: string): Promise<Result<Plan>>;
1090	/** Newest first. Members only. */
1091	listPlans(repo: RepoPath, viewer: Viewer): Promise<Result<Plan[]>>;
1092	/**
1093	* Opens a plan's issues, each blocked by the ones it depends on. With
1094	* `assign`, each is queued for a g1t agent. `keep` holds the positions,
1095	* from 1, of the issues to open; all of them when absent. Once.
1096	*/
1097	applyPlan(
1098	actor: User,
1099	repo: RepoPath,
1100	id: string,
1101	options?: { assign?: boolean; keep?: number[] },
1102	): Promise<Result<Plan>>;
1103	/** Asks for a g1t agent to take an issue as soon as it can, or withdraws that. */
1104	queueIssue(actor: User, repo: RepoPath, number: number, queued: boolean): Promise<Result<boolean>>;
1105	/** Issues waiting for a g1t agent that can be given one now. For the runner. */
1106	readyIssues(repoId?: string): Promise<ReadyIssue[]>;
1107
1108	/** Open issues assigned to the viewer, most recently changed first. */
1109	listAssignedIssues(viewer: Viewer): Promise<Issue[]>;
1110
1111	appendSession(actor: User, repo: RepoPath, number: number, entries: NewSessionEntry[]): Promise<Result<{ count: number }>>;
1112	readSession(repo: RepoPath, number: number, viewer: Viewer, afterSeq?: number): Promise<Result<SessionEntry[]>>;
1113	}
1114
1115	/**
1116	* What to pass `ReposApi.compare` to see what a pull request changes.
1117	*
1118	* A fork is compared as a whole. A branch is compared by name while the
1119	* pull request is open, and by the commit it was merged or closed at
1120	* afterwards, so later pushes to the branch do not change the record.
1121	*/
1122	export function pullComparison(pull: Pull): {
1123	repoId: string;
1124	base: string \| null;
1125	head: string \| null;
1126	/** The branch it merges into, which it is compared from. */
1127	baseBranch: string \| null;
1128	} {
1129	const baseBranch = pull.base ?? null;
1130	if (pull.forkRepoId) return { repoId: pull.forkRepoId, base: pull.mergeBase, head: null, baseBranch };
1131	const settled = pull.status === "merged" \|\| pull.status === "closed";
1132	return {
1133	repoId: pull.repoId,
1134	base: pull.mergeBase,
1135	head: (settled && pull.headCommit) \|\| pull.branch,
1136	baseBranch,
1137	};
1138	}
1139
1140
1141	/** Where a pull request in a merge queue stands. */
1142	/** Where one issue of an applied plan stands. */
1143	export type IssueProgress = {
1144	number: number;
1145	title: string;
1146	/**
1147	* `blocked`, `waiting` (for an agent), `open`, a lifecycle stage,
1148	* `landed` or `closed`.
1149	*/
1150	state: string;
1151	detail: string;
1152	/** The issues it is waiting on that are still open. */
1153	blockedBy: number[];
1154	pull: number \| null;
1155	agent: string \| null;
1156	};
1157
1158	/** A message a person sent an agent at work on a pull request. */
1159	export type AgentMessage = {
1160	id: string;
1161	author: string;
1162	body: string;
1163	createdAt: string;
1164	/** When the agent received it; null until then. */
1165	deliveredAt: string \| null;
1166	/** `message` from a person; from an agent a `question`, `handoff` or `answer`. */
1167	kind: "message" \| "question" \| "handoff" \| "answer";
1168	/** The pull request whose agent sent it, when an agent did. */
1169	fromNumber: number \| null;
1170	/** The pull request it was sent to. */
1171	toNumber: number;
1172	/** The reply to a question or handoff, once there is one. */
1173	answer: string \| null;
1174	declined: boolean;
1175	/** For the sending agent: what to expect when the one it asked is not at work. */
1176	hint?: string;
1177	};
1178
1179	export type QueueState = "waiting" \| "testing" \| "passed" \| "failed" \| "landed" \| "removed";
1180
1181	/** One pull request's place in a merge queue. */
1182	export type QueueEntry = {
1183	id: string;
1184	number: number;
1185	title: string;
1186	agent: string;
1187	state: QueueState;
1188	/** The pull requests merged ahead of it in the state being tested, in order. */
1189	ahead: number[];
1190	baseCommit: string \| null;
1191	combinedCommit: string \| null;
1192	error: string \| null;
1193	results: CheckResult[];
1194	/** Username of whoever merged it into the queue: a person, or `g1t`. */
1195	enqueuedBy: string;
1196	/** RFC 3339. */
1197	createdAt: string;
1198	/** RFC 3339. */
1199	finishedAt: string \| null;
1200	};
1201
1202	/** A repository's merge queue: what is in it, in order, and what recently left. */
1203	export type QueueView = {
1204	enabled: boolean;
1205	active: QueueEntry[];
1206	/** Newest first. */
1207	recent: QueueEntry[];
1208	};
1209
1210	export type QueueStackItem = {
1211	number: number;
1212	title: string;
1213	/** The repository holding the change, and its branch. */
1214	source: RepoPath;
1215	branch: string;
1216	commit: string;
1217	};
1218
1219	/** What a sandbox needs to build and check one combined state. */
1220	export type QueueJob = {
1221	entryId: string;
1222	token: string;
1223	repo: RepoPath;
1224	defaultBranch: string;
1225	baseCommit: string;
1226	branch: string;
1227	stack: QueueStackItem[];
1228	/** Always empty: the state is checked by the merge_group workflows run on it. */
1229	checks: string[];
1230	/** Always empty, as `checks`. */
1231	contractChecks: string[];
1232	actor: User;
1233	};
1234
1235	// --- A person's work ---------------------------------------------------------
1236	// Mirrors the `Authored*` types in `crates/contracts/src/work.rs`.
1237
1238	export type AuthoredKind = "issue" \| "pull";
1239	/** `closed` takes in merged pull requests too; `merged` is only those. */
1240	export type AuthoredState = "open" \| "closed" \| "merged";
1241	/** `created` is newest first, `updated` most recently changed, `oldest` oldest first. */
1242	export type AuthoredSort = "created" \| "updated" \| "oldest";
1243
1244	/** The most items one `byAuthor` page holds. */
1245	export const AUTHORED_PAGE = 25;
1246
1247	export type AuthoredFilter = {
1248	kind?: AuthoredKind;
1249	state?: AuthoredState;
1250	/** `namespace/name`. */
1251	repo?: string;
1252	sort?: AuthoredSort;
1253	/** The `next` of the page before. */
1254	before?: string;
1255	limit?: number;
1256	};
1257
1258	export type AuthoredItem = {
1259	kind: AuthoredKind;
1260	repo: RepoPath;
1261	number: number;
1262	title: string;
1263	/** A merged pull request is closed. */
1264	state: State;
1265	/** A pull request's own status; null on an issue. */
1266	status: PullStatus \| null;
1267	/** Why an issue was closed. */
1268	reason: IssueReason \| null;
1269	draft: boolean;
1270	merged: boolean;
1271	/** RFC 3339. */
1272	createdAt: string;
1273	/** RFC 3339. */
1274	updatedAt: string;
1275	/** RFC 3339. */
1276	mergedAt: string \| null;
1277	};
1278
1279	/** Over every repository the viewer may read, whatever the filters. */
1280	export type AuthoredCounts = {
1281	pullsMerged: number;
1282	pullsOpen: number;
1283	pulls: number;
1284	issues: number;
1285	issuesOpen: number;
1286	};
1287
1288	export type Authored = {
1289	items: AuthoredItem[];
1290	/** Pass as `before` for the next page; null on the last. */
1291	next: string \| null;
1292	counts: AuthoredCounts;
1293	/** The repositories they worked in that the viewer may read, most work first. */
1294	repos: { repo: RepoPath; count: number }[];
1295	};
1296
1297	// Mirrors `Contributions` in `crates/contracts/src/work.rs`.
1298
1299	/** How many days `contributions` covers: today and the 364 before it. */
1300	export const CONTRIBUTION_DAYS = 365;
1301
1302	/** One day with something on it; days with nothing are left out. */
1303	export type ContributionDay = { /** `YYYY-MM-DD`, UTC. */ date: string; count: number };
1304
1305	/** A person's year, as far as the viewer may see. */
1306	export type Contributions = {
1307	/** Oldest first. */
1308	days: ContributionDay[];
1309	total: number;
1310	/** The first day counted, `YYYY-MM-DD`; the last is today (UTC). */
1311	from: string;
1312	};