Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/work.ts

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