Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/work.ts

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