Sign in

flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

g1t/packages/contracts/src/work.ts

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