Skip to content
Sign in

flagon-io/g1t

public
0

g1t/packages/contracts/src/work.ts

1,268 lines45,087 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Merge checks: statuses and check runs on every commit1import type { ChecksApi } from "./checks";
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar2import type { CodeownersReport, PullCodeOwners } from "./codeowners";
Initial g1t: services, event bus, intents and attempts3import type { User, Viewer } from "./identity";
Catching up with main takes seconds when the two sides touched different files4import type { PullBranchUpdate, RepoPath } from "./repos";
Initial g1t: services, event bus, intents and attempts5import type { Result } from "./result";
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge6import type { MergeRules, RulesApi } from "./rules";
Initial g1t: services, event bus, intents and attempts7
Issues and pull requests replace intents and attempts8/**
9 * The filter on lists of issues and pull requests. An open pull request is
10 * a draft or one ready for review; a closed one was merged or closed
11 * without merging.
12 */
13export type State = "open" | "closed";
14
15/** Why an issue was closed. */
16export type IssueReason = "completed" | "not_planned";
Initial g1t: services, event bus, intents and attempts17
Issues and pull requests replace intents and attempts18/**
19 * Something that should change in a repository: a bug, a feature, a
20 * question. Opened by a person, an agent or an integration. Pull requests
21 * are made against it; the one that is merged resolves it.
22 *
23 * Issues and pull requests share one sequence of numbers per repository.
24 */
25export type Issue = {
Initial g1t: services, event bus, intents and attempts26 id: string;
27 repoId: string;
Issues and pull requests replace intents and attempts28 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts29 number: number;
30 title: string;
Issues and pull requests replace intents and attempts31 /** Markdown. Also what an agent is given to work from. */
32 body: string;
33 labels: string[];
34 state: State;
35 /** Set when closed. */
36 reason: IssueReason | null;
37 /** The number of the pull request whose merge closed this issue. */
38 resolvedBy: number | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights39 /** Who opened it: a person, an integration, or g1t (`kind` `agent`) for one its agent filed while at work. */
Initial g1t: services, event bus, intents and attempts40 author: User;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights41 /**
42 * For an issue g1t's agent filed: the person it was working for. They may
43 * manage it as its author could. See `workOwner`.
44 */
45 requestedBy: User | null;
Work service in Rust, with RFC 3339 timestamps46 /** RFC 3339. */
47 createdAt: string;
Issues and pull requests replace intents and attempts48 /** RFC 3339. */
49 updatedAt: string;
50 /** RFC 3339. */
51 closedAt: string | null;
52 /** Pull requests made against this issue, in any state. */
53 pullCount: number;
54 commentCount: number;
Agents as a team: lifecycle, merge queue, billing and a new shell55 /** Usernames of the people it is assigned to. */
56 assignees: string[];
57 /** The numbers of the issues that have to be merged before this one is worked on. */
58 blockedBy: number[];
59 /**
60 * Whether a g1t agent takes it as soon as it can: at once, or when what it
61 * is blocked by has merged.
62 */
63 queued: boolean;
64 /**
65 * The agent working on it now: the one behind its newest pull request
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent66 * that is still in progress in a fork, such as `g1t`.
Agents as a team: lifecycle, merge queue, billing and a new shell67 */
68 agent: string | null;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar69 /** The milestone it is in, if any. */
70 milestone?: MilestoneRef | null;
Initial g1t: services, event bus, intents and attempts71};
72
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights73/**
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar74 * A label of a repository: a name, a color and what it means. Issues and
75 * pull requests carry labels by name; names are lowercase.
76 */
77export type Label = {
78 name: string;
79 /** Six hex digits, without `#`. */
80 color: string;
81 description: string;
82 /** How many issues carry it, open or closed. */
83 issues: number;
84 /** How many pull requests carry it, in any state. */
85 pulls: number;
86};
87
88/** A milestone, as an issue or pull request names it. */
89export type MilestoneRef = { number: number; title: string };
90
91/**
92 * A goal, with an optional due date, that issues and pull requests are
93 * gathered under. Its progress is how many of them are closed.
94 */
95export type Milestone = {
96 /** Numbered from 1 in each repository, apart from issues. */
97 number: number;
98 title: string;
99 /** Markdown. */
100 description: string;
101 /** `YYYY-MM-DD`. */
102 dueOn: string | null;
103 state: State;
104 /** Open issues and pull requests in it. */
105 openItems: number;
106 /** Closed issues, and merged or closed pull requests, in it. */
107 closedItems: number;
108 createdAt: string;
109 updatedAt: string;
110 closedAt: string | null;
111};
112
113/** One milestone and what is in it, newest first. */
114export type MilestoneDetail = { milestone: Milestone; issues: Issue[]; pulls: Pull[] };
115
116/** How `setLabels` changes an item's labels. */
117export type LabelChange = "set" | "add" | "remove";
118
119/**
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights120 * Whose an issue or a pull request is to answer for: whoever asked g1t for
121 * it, or its author. They may change, close and steer it, are never asked to
122 * review it and cannot approve it, and see it as theirs. Mirrors
123 * `Pull::owner` in the Rust contracts.
124 */
125export function workOwner(item: Pick<Pull, "author" | "requestedBy">): User {
126 return item.requestedBy ?? item.author;
127}
128
Issues and pull requests replace intents and attempts129/** `draft` is still being worked on; `open` is ready for review. */
130export type PullStatus = "draft" | "open" | "merged" | "closed";
Initial g1t: services, event bus, intents and attempts131
132/** Where the agent runs: on g1t's sandboxes, or in someone's own session. */
Issues and pull requests replace intents and attempts133export type Runtime = "hosted" | "external";
Initial g1t: services, event bus, intents and attempts134
Pull requests from branches135/**
136 * A proposed change. It is made either in a fork created for it, which is
137 * how agents work, or on a branch pushed to the repository itself.
138 */
Issues and pull requests replace intents and attempts139export type Pull = {
Initial g1t: services, event bus, intents and attempts140 id: string;
141 repoId: string;
Issues and pull requests replace intents and attempts142 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts143 number: number;
Issues and pull requests replace intents and attempts144 /** The number of the issue this is for, if any. */
145 issue: number | null;
146 title: string;
147 /** Markdown: what changed and why. Set when marked ready. */
148 body: string | null;
Initial g1t: services, event bus, intents and attempts149 /** A label for the agent doing the work, e.g. `claude-code`. */
150 agent: string;
Issues and pull requests replace intents and attempts151 runtime: Runtime;
152 status: PullStatus;
Pull requests from branches153 /** The fork holding the change, unless it is on a branch. */
154 fork: RepoPath | null;
Diffs on attempts; hosted agent presented as the g1t agent155 /** The fork's repository id. */
Pull requests from branches156 forkRepoId: string | null;
157 /** The branch of the repository holding the change, unless it is in a fork. */
158 branch: string | null;
Initial g1t: services, event bus, intents and attempts159 headCommit: string | null;
Diffs on attempts; hosted agent presented as the g1t agent160 /**
Issues and pull requests replace intents and attempts161 * For a merged pull request, what the branch pointed to before the merge.
162 * Comparing against it shows what the pull request changed.
163 */
164 mergeBase: string | null;
165 /** Username of whoever merged it. */
166 mergedBy: string | null;
167 /** RFC 3339. */
168 mergedAt: string | null;
169 /**
170 * Set on a pull request closed because another one for the same issue was
171 * merged: that one's number.
Diffs on attempts; hosted agent presented as the g1t agent172 */
Issues and pull requests replace intents and attempts173 supersededBy: number | null;
Acceptance checks in sandboxes, line comments and review verdicts174 /**
175 * Where the latest run of the issue's acceptance checks stands, if there
176 * has been one against the current head.
177 */
178 checkStatus: CheckStatus | null;
Agents as a team: lifecycle, merge queue, billing and a new shell179 /** The files it changes, as of its latest push. */
180 files: ChangedFile[];
181 /** Usernames of the people it is assigned to. */
182 assignees: string[];
183 /**
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent184 * Those whose review was asked for: usernames, and `g1t` when a g1t
Agents as a team: lifecycle, merge queue, billing and a new shell185 * agent was asked.
186 */
187 reviewers: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar188 /**
189 * Teams whose review was asked for, as `workspace/slug`. A team stays here
190 * after review assignment picks people from it, who are in `reviewers`.
191 */
192 teamReviewers?: string[];
193 /** The labels it carries, by name. */
194 labels?: string[];
195 /** The milestone it is in, if any. */
196 milestone?: MilestoneRef | null;
197 /**
198 * The branch it merges into. Lists and `getPull` name it; null only in
199 * what services pass between themselves, for the default branch.
200 */
201 base?: string | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights202 /** Who opened it: a person, or g1t (`kind` `agent`, username `g1t`) for a change g1t made. */
Issues and pull requests replace intents and attempts203 author: User;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights204 /**
205 * For a change g1t made: the person who asked for it, by assigning an issue
206 * or handing g1t the work. They answer for it as its author would. See
207 * `workOwner`.
208 */
209 requestedBy: User | null;
Work service in Rust, with RFC 3339 timestamps210 /** RFC 3339. */
211 createdAt: string;
212 /** RFC 3339. */
213 updatedAt: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step214 /**
215 * How sure g1t is of a g1t agent's change, from what it can observe, once
216 * the agent has finished it. Absent before then, and on changes g1t is
217 * not seeing through.
218 */
219 confidence?: Confidence | null;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge220 /** Who last moved its head (a user id), and when; absent until a push after rulesets arrived. */
221 headPushedBy?: string;
222 headPushedAt?: string;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step223};
224
225/** How sure g1t is that an agent's change is right. */
226export type ConfidenceLevel = "low" | "medium" | "high";
227
228/**
229 * How sure g1t is of a change an agent made, worked out from what can be
230 * observed: its checks, how often it was sent back, the reviewer agent's
231 * verdict, whether it touched tests, its size, where it reached, how close
232 * it came to its guardrails, and what it asked without an answer. The
233 * agent's own word can only lower it.
234 */
235export type Confidence = {
236 level: ConfidenceLevel;
237 /** A few words each, most telling first: what lowered it, or for `high`, what it rests on. */
238 reasons: string[];
239 /** What the agent said of its own change, if it said. */
240 selfReported: ConfidenceLevel | null;
241 /** What the agent said it was unsure about. */
242 uncertainAbout: string[];
243 /** The agent run it was worked out after. */
244 runId: string | null;
245 /** RFC 3339. */
246 assessedAt: string;
247};
248
249/** What became of the agent when an issue was opened and handed to it in one step. */
250export type AgentStartStatus = "started" | "queued" | "not_started";
251
252/** Whether the agent started, and if not, why and what fixes it. */
253export type AgentStart = {
254 status: AgentStartStatus;
255 /**
256 * Why it did not start: `not_paid`, `trial_used`, `limit`, `paused`,
257 * `issue_cap`, `billing_unavailable` or `no_model`; `waiting` when queued.
258 */
259 code: string | null;
260 /** What happened, in a sentence or two, with what to do. */
261 message: string | null;
262 /** Where the fix is: the workspace's billing or model settings. */
263 fixUrl: string | null;
Initial g1t: services, event bus, intents and attempts264};
265
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent266/** An issue opened and handed to g1t in one step. The issue exists whatever became of the agent. */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step267export type Delegated = {
268 issue: Issue;
269 /** The pull request the agent opened, when it started. */
270 pull: Pull | null;
271 agent: AgentStart;
272};
273
Fast pages, required checks on the branch, self-hosted runners, honest incidents274/**
275 * What to put an agent on: an issue's title, and what to do in plain words,
276 * with what done means if you like (a "Definition of done" section). What
277 * has to pass before it merges is the branch's required checks.
278 */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step279export type DelegateInput = {
280 title: string;
281 body: string;
282 labels?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents283 /** Deprecated: commands, added to the body under "Definition of done". */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step284 checks?: string[];
285};
286
Agents as a team: lifecycle, merge queue, billing and a new shell287/** One file a pull request changes, and by how much. */
288export type ChangedFile = { path: string; additions: number; deletions: number };
289
290/**
291 * Another pull request in progress that changes some of the same files. Two
292 * for the same issue are alternatives; two for different issues are heading
293 * for a conflict.
294 */
295export type Overlap = {
296 number: number;
297 title: string;
298 /** The number of the issue the other pull request is for. */
299 issue: number | null;
300 /** The files both change. */
301 paths: string[];
302};
303
Fast pages, required checks on the branch, self-hosted runners, honest incidents304/**
305 * On a pull request, `failed` means the merge queue took it out, until its
306 * head moves. The other states are from runs of commands written on issues,
307 * which g1t no longer runs.
308 */
Acceptance checks in sandboxes, line comments and review verdicts309export type CheckStatus = "queued" | "running" | "passed" | "failed" | "errored";
310
Fast pages, required checks on the branch, self-hosted runners, honest incidents311/** How one command went, in a run recorded before checks were workflows. */
Acceptance checks in sandboxes, line comments and review verdicts312export type CheckResult = {
313 command: string;
314 passed: boolean;
315 /** Null when the command was stopped for taking too long. */
316 exitCode: number | null;
317 /** What the command printed; the end of it, when there was a lot. */
318 output: string;
319 durationMs: number;
320};
321
322/**
Fast pages, required checks on the branch, self-hosted runners, honest incidents323 * A record against a pull request's head: the merge queue taking it out,
324 * with why, or an earlier run of commands written on its issue.
Acceptance checks in sandboxes, line comments and review verdicts325 */
326export type CheckRun = {
327 id: string;
328 /** The commit that was checked. */
329 headCommit: string;
330 status: CheckStatus;
331 results: CheckResult[];
332 /** Why the checks could not be run, when `status` is `errored`. */
333 error: string | null;
334 /** RFC 3339. */
335 createdAt: string;
336 /** RFC 3339. */
337 finishedAt: string | null;
338};
339
340/** A reviewer's decision on a pull request. */
341export type Verdict = "approve" | "request_changes";
342
343/**
344 * A comment on an issue or a pull request. On a pull request it can sit on
345 * one line of the change, and it can carry a reviewer's verdict.
346 */
Issues and pull requests replace intents and attempts347export type Comment = {
348 id: string;
Agents as a team: lifecycle, merge queue, billing and a new shell349 /**
350 * Something a person or an agent wrote, or something that happened: an
351 * assignment, a review asked for, a close.
352 */
353 kind: "comment" | "event";
Issues and pull requests replace intents and attempts354 author: User;
Agents as a team: lifecycle, merge queue, billing and a new shell355 /**
356 * Markdown. For an event, what its author did, as the rest of a sentence
357 * that starts with their name: "assigned ana".
358 */
Issues and pull requests replace intents and attempts359 body: string;
Acceptance checks in sandboxes, line comments and review verdicts360 /** The file commented on, for a comment on a line. */
361 path: string | null;
362 /** The line of that file, as numbered after the change. */
363 line: number | null;
364 verdict: Verdict | null;
Issues and pull requests replace intents and attempts365 /** RFC 3339. */
366 createdAt: string;
367};
368
Acceptance checks in sandboxes, line comments and review verdicts369export type NewComment = {
370 /** May be empty when approving. */
371 body: string;
372 path?: string;
373 line?: number;
374 verdict?: Verdict;
375};
376
377/** What a sandbox needs to carry out a check run. */
378export type CheckJob = {
379 runId: string;
380 /** Lets the sandbox, and nothing else, report this run's results. */
381 token: string;
382 commands: string[];
383 /** The repository holding the commit: the fork, or the repository itself. */
384 source: RepoPath;
385 commit: string;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights386 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Acceptance checks in sandboxes, line comments and review verdicts387 author: User;
388 /** Username of whoever wrote the checks: the issue's author. */
389 requestedBy: string;
390 repo: RepoPath;
391 number: number;
392};
393
394export type CheckReport = { results?: CheckResult[]; error?: string; skip?: boolean };
395
Initial g1t: services, event bus, intents and attempts396export type SessionEntryKind = "prompt" | "message" | "tool_call" | "tool_result" | "note";
397
Issues and pull requests replace intents and attempts398/** One step of an agent's session: the "why" behind a pull request's commits. */
Initial g1t: services, event bus, intents and attempts399export type SessionEntry = {
400 seq: number;
401 kind: SessionEntryKind;
402 text: string;
403 /** For tool calls and results. */
404 tool: string | null;
405 /** The fork's head commit when this entry was recorded, if known. */
406 commit: string | null;
Work service in Rust, with RFC 3339 timestamps407 /** RFC 3339. */
408 at: string;
Initial g1t: services, event bus, intents and attempts409};
410
411export type NewSessionEntry = Pick<SessionEntry, "kind" | "text"> &
Work service in Rust, with RFC 3339 timestamps412 Partial<Pick<SessionEntry, "tool" | "commit">>;
Initial g1t: services, event bus, intents and attempts413
Issues and pull requests replace intents and attempts414export type IssueDetail = {
415 issue: Issue;
416 /** Every pull request made against it, oldest first. */
417 pulls: Pull[];
418 comments: Comment[];
419};
Initial g1t: services, event bus, intents and attempts420
Issues and pull requests replace intents and attempts421export type PullDetail = {
422 pull: Pull;
423 /** The issue it is for, if any. */
424 issue: Issue | null;
425 comments: Comment[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents426 /** The latest record against its head: the merge queue taking it out. */
Acceptance checks in sandboxes, line comments and review verdicts427 checks: CheckRun | null;
Agents as a team: lifecycle, merge queue, billing and a new shell428 /** Other pull requests in progress that change the same files. */
429 overlaps: Overlap[];
430 /**
431 * Whether the branch it would merge into has moved on without it, so that
432 * it has to catch up before it can merge.
433 */
434 behind: boolean;
435 /** Whether a g1t agent is reviewing it right now. */
436 reviewPending: boolean;
437 /**
438 * Where it stands on its way to being merged, for a pull request g1t is
439 * seeing through. Null on anyone else's.
440 */
441 lifecycle: Lifecycle | null;
442 /**
443 * A merge was asked for while it was behind: g1t is bringing it up to
444 * date and will then land it.
445 */
446 landing: boolean;
447 /** Why g1t stopped working on it, if it did. */
448 stalled: string | null;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request449 /** Messages people sent the agent while it worked, oldest first. */
450 messages: AgentMessage[];
GitHub Actions on g1t, part three: .g1t/workflows, the pages, the docs451 /** What workflow runs said about its head commit, one per workflow. */
452 statuses?: CommitStatus[];
Agents and memory, checks and conflicts, profiles, slug renames, custom domains453 /**
454 * Whether it merges cleanly into the branch it targets, worked out ahead
455 * of time whenever either side moves.
456 */
457 mergeable?: Mergeable;
458 /** When `mergeable` is `conflicting`: the files that conflict. */
459 conflicts?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents460 /** Earlier records like `checks`, newest first, without their output. */
Agents and memory, checks and conflicts, profiles, slug renames, custom domains461 earlierChecks?: CheckRun[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents462 /**
463 * The checks the default branch's protection requires, each as it stands
464 * on the head commit. Empty when none are required.
465 */
466 requiredChecks?: RequiredCheck[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar467 /**
468 * Who owns the files it changes (the CODEOWNERS file of the branch it
469 * merges into) and whose approval is still needed. Absent without one.
470 */
471 codeOwners?: PullCodeOwners | null;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge472 /**
473 * The rules of the branch it merges into it does not meet yet, for whoever
474 * is looking: what refuses the merge, what they may bypass, and what rulesets
475 * in evaluate would refuse. Absent once it is closed or merged.
476 */
477 rules?: MergeRules | null;
Fast pages, required checks on the branch, self-hosted runners, honest incidents478};
479
480/** Where a required check stands on a commit; `expected` when nothing has reported it yet. */
481export type RequiredState = "success" | "failure" | "pending" | "expected";
482
483/** One check a branch's protection requires, as it stands on a commit. */
484export type RequiredCheck = {
485 /** A workflow's name, such as `CI`, or another status's context. */
486 name: string;
487 state: RequiredState;
488 description: string | null;
489 /** Where to see more: the workflow run, for one a workflow reported. */
490 targetUrl: string | null;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains491};
492
Fast pages, required checks on the branch, self-hosted runners, honest incidents493/** A check name reported on a repository's commits lately, for choosing required checks. */
494export type SeenCheck = {
495 name: string;
496 /** The events it was reported for, such as `pull_request`; empty for a status that names none. */
497 events: string[];
498 /** RFC 3339. */
499 lastSeen: string;
500};
501
Agents and memory, checks and conflicts, profiles, slug renames, custom domains502/**
Fast pages, required checks on the branch, self-hosted runners, honest incidents503 * A status context's check name: `CI / pull_request` is the `CI` check,
504 * reported for a `pull_request` event. A context that does not end in an
505 * event, such as `g1t / deploy`, is its own name. As the work service reads it.
506 */
507export function checkName(context: string): string {
508 const at = context.lastIndexOf(" / ");
509 if (at <= 0) return context;
510 return STATUS_EVENTS.has(context.slice(at + 3)) ? context.slice(0, at) : context;
511}
512
513const STATUS_EVENTS = new Set([
514 "push",
515 "pull_request",
516 "pull_request_target",
517 "pull_request_review",
518 "merge_group",
519 "workflow_dispatch",
520 "workflow_run",
521 "workflow_call",
522 "schedule",
523 "release",
524 "issues",
525 "issue_comment",
526 "repository_dispatch",
527]);
528
529/**
Agents and memory, checks and conflicts, profiles, slug renames, custom domains530 * Whether a pull request merges cleanly into the branch it targets:
531 * `unknown` when it was never worked out or could not be, `checking` while
532 * a probe merges the two.
533 */
534export type Mergeable = "clean" | "conflicting" | "unknown" | "checking";
535
536/** What a sandbox needs to find out whether a pull request merges cleanly. */
537export type MergecheckJob = {
538 pullId: string;
539 /** Lets the sandbox, and nothing else, report this probe. */
540 token: string;
541 repo: RepoPath;
542 number: number;
543 defaultBranch: string;
544 /** The default branch's commit to merge into. */
545 base: string;
546 /** The repository holding the change: its fork, or the repository. */
547 source: RepoPath;
548 /** The branch of `source` holding it. */
549 branch: string;
550 /** The change's commit. */
551 head: string;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights552 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Agents and memory, checks and conflicts, profiles, slug renames, custom domains553 author: User;
GitHub Actions on g1t, part three: .g1t/workflows, the pages, the docs554};
555
556/** What a workflow run (or another tool) says about a commit. */
557export type CommitStatus = {
558 /** What reported it, such as `CI / push`. */
559 context: string;
560 state: "pending" | "success" | "failure" | "error";
561 description: string | null;
562 targetUrl: string | null;
563 updatedAt: string;
Merge checks: statuses and check runs on every commit564 /** The integration that reported it: `actions`, `deployments`, `security`, `g1t` or `api`. */
565 source?: string;
566 /** Set on the status a check run stands as: the check run's id. */
567 checkRunId?: string;
Agents as a team: lifecycle, merge queue, billing and a new shell568};
569
570/**
571 * A step on the way from an assigned issue to a pull request that is ready
572 * to merge. g1t takes each one without being asked: `working` (the agent is
573 * making the change), `checking`, `reviewing`, `revising` (the agent is
574 * addressing failed checks or a review), `catching_up` (merging in the
Agents asked while not at work are woken to answer575 * branch it would land on), `answering` (woken to answer another agent),
576 * then `ready` for a person to merge. `needs_you`
Agents as a team: lifecycle, merge queue, billing and a new shell577 * means g1t has stopped and a person decides what happens next.
578 */
579export type Stage =
580 | "working"
581 | "checking"
582 | "reviewing"
583 | "revising"
584 | "catching_up"
Agents asked while not at work are woken to answer585 | "answering"
Agents as a team: lifecycle, merge queue, billing and a new shell586 | "queued"
587 | "ready"
588 | "needs_you";
589
590export type Lifecycle = {
591 stage: Stage;
592 /** One sentence saying what is happening, or why it stopped. */
593 detail: string;
594 /** How many times the agent has been sent back to revise it. */
595 revisions: number;
596};
597
598/** What the runner needs to carry out a step of a pull request's lifecycle. */
599export type LifecycleJob = {
600 pullId: string;
601 repo: RepoPath;
602 number: number;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights603 /** Who the pull request belongs to (`workOwner`: whoever asked g1t for it, or its author). Sandboxes act as them. */
Agents as a team: lifecycle, merge queue, billing and a new shell604 author: User;
605 /** The repository holding the change: its fork, or the repository itself. */
606 source: RepoPath;
607 /** The branch of the source holding the change; its default branch when null. */
608 branch: string | null;
609 defaultBranch: string;
610 title: string;
611 description: string;
612 issue: Issue | null;
613 /** For a revision: the failed checks or the review to address. */
614 feedback: string;
615 /** For a revision: which one this is, from 1. */
616 round: number;
617};
618
Agents asked while not at work are woken to answer619/** An agent woken to answer what other agents sent it while it was not at work. */
620export type Wake = { job: LifecycleJob; messages: AgentMessage[] };
621
Agents as a team: lifecycle, merge queue, billing and a new shell622/**
623 * `planning` while an agent reads the repository and writes it; `ready` for
624 * a person to read and apply; `failed` if it could not be written;
625 * `applied` once its issues are open.
626 */
627export type PlanStatus = "planning" | "ready" | "failed" | "applied";
628
629/** One issue a plan proposes. */
630export type PlannedIssue = {
631 title: string;
632 /** Markdown: what to change, where, and why. */
633 body: string;
634 labels: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents635 /** What is true once it is done, in plain words; added to the issue's body under "Definition of done". */
636 done: string[];
Agents as a team: lifecycle, merge queue, billing and a new shell637 /** The files it will most likely change. */
638 files: string[];
639 /**
640 * The positions, counting from 1, of earlier issues in the plan that have
641 * to be merged first.
642 */
643 dependsOn: number[];
644 /** Its number, once the plan has been applied and it was kept. */
645 number: number | null;
646};
647
648/** An outcome someone wrote, and the issues an agent proposes to get there. */
649export type Plan = {
650 id: string;
651 repoId: string;
652 /** The outcome wanted, as written. */
653 brief: string;
654 status: PlanStatus;
655 /** The agent's account of how it split the work. */
656 summary: string;
657 issues: PlannedIssue[];
658 /** Why it could not be written, when `status` is `failed`. */
659 error: string | null;
660 author: User;
661 /** RFC 3339. */
662 createdAt: string;
663 /** RFC 3339. */
664 finishedAt: string | null;
Dark gray base with lavender as an accent, and a live outcome view for plans665 /** Once applied: where each issue it opened stands now, in plan order. */
666 progress: IssueProgress[];
Agents ask each other, hand each other work, and answer667 /** Questions and handoffs between its pull requests' agents, newest first. */
668 exchanges: AgentMessage[];
Agents as a team: lifecycle, merge queue, billing and a new shell669};
670
671/** What a sandbox needs to write a plan. */
672export type PlanJob = {
673 planId: string;
674 /** Lets the sandbox, and nothing else, report this plan. */
675 token: string;
676 brief: string;
677 repo: RepoPath;
Issues and pull requests replace intents and attempts678};
Initial g1t: services, event bus, intents and attempts679
Agents as a team: lifecycle, merge queue, billing and a new shell680/** An issue waiting for a g1t agent that can be given one now. */
681export type ReadyIssue = {
682 repo: RepoPath;
683 number: number;
684 /** Who queued it, on whose say-so the agent works. */
685 actor: User;
686};
687
688/**
689 * How a repository wants its pull requests handled. A repository that has
690 * changed nothing has the defaults.
691 */
692export type RepoSettings = {
693 /**
694 * Land a g1t agent's pull request without a person once it is ready:
695 * checks passed and approved as the settings below require.
696 */
697 autoMerge: boolean;
698 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents699 * The checks that must pass on a pull request's head before it may merge
700 * into the default branch, by name: a workflow's name (`CI`) or another
701 * status's context (`g1t / deploy`). The same for people and agents, and
702 * for the merge queue.
703 */
704 requiredChecks: string[];
705 /**
Agents as a team: lifecycle, merge queue, billing and a new shell706 * Refuse to merge a pull request that does not contain the default
707 * branch's latest commits, so that what merges is what was checked. When
708 * off, merging one that is behind brings it up to date first.
709 */
710 requireUpToDate: boolean;
711 /**
712 * How many approving reviews a pull request needs before it may merge. A
713 * reviewer who has since asked for changes blocks it.
714 */
715 requiredApprovals: number;
716 /** Whether a g1t agent's approval counts towards `requiredApprovals`. */
717 countAgentApprovals: boolean;
Fast pages, required checks on the branch, self-hosted runners, honest incidents718 /** Whether someone who may merge can bypass required checks that have not passed. */
Agents as a team: lifecycle, merge queue, billing and a new shell719 allowIgnoringChecks: boolean;
720 /** Whether a g1t agent's pull request is reviewed by a second agent unasked. */
721 agentReview: boolean;
722 /**
723 * How many times a g1t agent is sent back to its pull request before a
724 * person is asked instead.
725 */
726 maxRevisions: number;
727 /**
728 * Merge through a queue: pull requests are tested together with those
729 * ahead of them, and only a combination that passed reaches the default
730 * branch.
731 */
732 mergeQueue: boolean;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step733 /**
734 * Ask a person before merging a g1t agent's change whose confidence is
735 * low: auto-merge and the merge queue leave it until a person approves it.
736 */
737 holdLowConfidence: boolean;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar738 /**
739 * Refuse to merge until the code owners of every file it changes have
740 * approved, as many as each section asks. People only; `g1t` only where
741 * the file names `@g1t`.
742 */
743 requireCodeOwnerReview?: boolean;
Agents as a team: lifecycle, merge queue, billing and a new shell744 /** Username of the member who last changed the settings, if anyone has. */
745 updatedBy: string | null;
746 /** RFC 3339. */
747 updatedAt: string | null;
748};
749
750/** The settings a member can change. */
751export type RepoSettingsInput = Omit<RepoSettings, "updatedBy" | "updatedAt">;
752
753/** The next step for a pull request g1t is seeing through, already claimed. */
754export type Advance =
755 | { action: "none" }
756 | { action: "review" | "revise" | "catch_up"; job: LifecycleJob };
757
758/** What a sandbox needs to review a pull request. */
759export type ReviewJob = {
760 runId: string;
761 /** Lets the sandbox, and nothing else, report this review. */
762 token: string;
763 /** The repository holding the commit: the fork, or the repository itself. */
764 source: RepoPath;
765 commit: string;
766 repo: RepoPath;
767 defaultBranch: string;
768 number: number;
769 title: string;
770 description: string;
771 /** The issue the pull request is for, which says what it should achieve. */
772 issue: Issue | null;
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights773 /** Who the pull request is for (`workOwner`: whoever asked g1t for it, or its author), and so can read its source. */
Agents as a team: lifecycle, merge queue, billing and a new shell774 author: User;
Auto model routing: the cheapest tier that can do each piece of work, a retry goes up a tier, and each run records its tier775 /**
776 * The files it changes, as of its latest push: how large the change is,
777 * which decides the model that reviews it.
778 */
779 files: ChangedFile[];
780 /**
781 * What among them runs, configures or guards things (CI workflows,
782 * secrets, infrastructure), once each. Any sends the review to the
783 * larger model.
784 */
785 sensitive: string[];
Agents as a team: lifecycle, merge queue, billing and a new shell786};
787
Issues and pull requests replace intents and attempts788export type OpenIssueInput = {
789 title: string;
790 body: string;
791 labels?: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents792 /** Deprecated: commands, added to the body under "Definition of done". */
Issues and pull requests replace intents and attempts793 checks?: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar794 /** The number of the milestone to put it in. Needs the Triage role. */
795 milestone?: number;
Issues and pull requests replace intents and attempts796};
797
Agents as a team: lifecycle, merge queue, billing and a new shell798export type UpdateIssueInput = {
799 title?: string;
800 body?: string;
801 labels?: string[];
802 /** Usernames of the people it is assigned to; replaces the whole set. */
803 assignees?: string[];
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar804 /** The number of the milestone to put it in; 0 takes it out. */
805 milestone?: number;
Agents as a team: lifecycle, merge queue, billing and a new shell806};
Issues and pull requests replace intents and attempts807
808export type OpenPullInput = {
809 /** The number of the issue this is for. */
810 issue?: number;
811 /** Defaults to the issue's title; required without an issue. */
812 title?: string;
Pull requests from branches813 /** What changed and why. Usually set later, when a draft is marked ready. */
814 body?: string;
815 /**
816 * A branch of the repository that already holds the change. The pull
817 * request is then ready for review at once and has no fork.
818 */
819 branch?: string;
Issues and pull requests replace intents and attempts820 agent: string;
821 runtime: Runtime;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar822 /** The branch to merge into: the default branch when left out. */
823 base?: string;
Issues and pull requests replace intents and attempts824};
Initial g1t: services, event bus, intents and attempts825
Fast pages, required checks on the branch, self-hosted runners, honest incidents826/** One repository's pull requests from `pullsForRepos`, newest first. */
827export type RepoPulls = {
828 repoId: string;
829 /** Draft and open. */
830 open: Pull[];
831 /** Merged and closed. */
832 closed: Pull[];
833};
834
Issues and pull requests replace intents and attempts835/** Issues, pull requests, comments and sessions. */
Merge checks: statuses and check runs on every commit836export interface WorkApi extends RulesApi, ChecksApi {
Issues and pull requests replace intents and attempts837 openIssue(actor: User, repo: RepoPath, input: OpenIssueInput): Promise<Result<Issue>>;
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step838 /**
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent839 * Opens an issue to put g1t on at once: refused, with nothing
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step840 * opened, unless `actor` may put agents to work in `repo`. The runner's
841 * `delegate` calls it, then starts the agent.
842 */
843 delegateIssue(actor: User, repo: RepoPath, input: DelegateInput): Promise<Result<Issue>>;
Issues and pull requests replace intents and attempts844 /** Newest first. */
845 listIssues(
846 repo: RepoPath,
847 viewer: Viewer,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar848 filter?: { state?: State; label?: string; milestone?: number },
Issues and pull requests replace intents and attempts849 ): Promise<Result<Issue[]>>;
850 getIssue(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<IssueDetail>>;
851 /** The author or a member of the workspace may. */
852 updateIssue(actor: User, repo: RepoPath, number: number, input: UpdateIssueInput): Promise<Result<Issue>>;
853 closeIssue(actor: User, repo: RepoPath, number: number, reason?: IssueReason): Promise<Result<Issue>>;
854 reopenIssue(actor: User, repo: RepoPath, number: number): Promise<Result<Issue>>;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar855 /** A repository's labels, by name, each with how many issues and pull requests carry it. */
856 listLabels(repo: RepoPath, viewer: Viewer): Promise<Result<Label[]>>;
857 /**
858 * Creates a label, or with `name` changes one; renaming it renames it on
859 * everything that carries it. Needs the Triage role.
860 */
861 saveLabel(
862 actor: User,
863 repo: RepoPath,
864 label: { name?: string; newName?: string; color?: string; description?: string },
865 ): Promise<Result<Label>>;
866 /** Removes a label from the repository and everything carrying it. */
867 deleteLabel(actor: User, repo: RepoPath, name: string): Promise<Result<boolean>>;
868 /** Adds the default labels the repository does not have yet; returns them all. */
869 addDefaultLabels(actor: User, repo: RepoPath): Promise<Result<Label[]>>;
870 /**
871 * The labels of an issue or a pull request, replaced, added to or taken
872 * from. Labels the repository lacks are created for someone with the
873 * Triage role. Returns its labels now.
874 */
875 setLabels(
876 actor: User,
877 repo: RepoPath,
878 number: number,
879 labels: string[],
880 change?: LabelChange,
881 ): Promise<Result<string[]>>;
882 /** Open ones by due date, then closed ones; both unless `state` says. */
883 listMilestones(repo: RepoPath, viewer: Viewer, state?: State): Promise<Result<Milestone[]>>;
884 getMilestone(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<MilestoneDetail>>;
885 /** Creates a milestone, or with `number` changes the fields given. Needs the Triage role. */
886 saveMilestone(
887 actor: User,
888 repo: RepoPath,
889 milestone: { number?: number; title?: string; description?: string; dueOn?: string; state?: State },
890 ): Promise<Result<Milestone>>;
891 deleteMilestone(actor: User, repo: RepoPath, number: number): Promise<Result<boolean>>;
Issues and pull requests replace intents and attempts892 /** How many issues and pull requests are open. */
893 counts(repo: RepoPath, viewer: Viewer): Promise<Result<{ issues: number; pulls: number }>>;
Initial g1t: services, event bus, intents and attempts894
Acceptance checks in sandboxes, line comments and review verdicts895 /**
896 * On an issue or a pull request. On a pull request it may name a line of
897 * the change and carry a verdict; nobody can give a verdict on their own.
898 */
899 addComment(actor: User, repo: RepoPath, number: number, comment: NewComment): Promise<Result<Comment>>;
900
901 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents902 * Always refused now: a pull request's checks are the workflows run on
903 * it. Kept for a runner from before.
Acceptance checks in sandboxes, line comments and review verdicts904 */
905 startChecks(pullId: string): Promise<Result<CheckJob>>;
906 /**
Fast pages, required checks on the branch, self-hosted runners, honest incidents907 * What a sandbox says about a run from before checks were workflows: so
908 * one still finishing is recorded.
Acceptance checks in sandboxes, line comments and review verdicts909 */
910 reportChecks(runId: string, token: string, report: CheckReport): Promise<Result<CheckRun>>;
Agents as a team: lifecycle, merge queue, billing and a new shell911 /** Begins a review by a g1t agent. For the runner service. */
912 startReview(pullId: string): Promise<Result<ReviewJob>>;
913 /** Records that a review could not be written. For the runner service. */
914 failReview(runId: string, token: string, error: string): Promise<Result<boolean>>;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains915 /**
916 * Claims the probe of whether a pull request merges cleanly that a
917 * `pull.mergecheck` event asked for. Refused when it is no longer wanted
918 * or the repository has as many running as it may. For the runner service.
919 */
920 startMergecheck(pullId: string): Promise<Result<MergecheckJob>>;
921 /** Records that a probe could not be carried out. For the runner service. */
922 failMergecheck(pullId: string, token: string, error: string): Promise<Result<Mergeable>>;
Agents as a team: lifecycle, merge queue, billing and a new shell923
924 /**
925 * Works out the next step for a pull request g1t is seeing through and,
926 * if there is one to take now, claims it, so that it is taken once
927 * however often this is called. For the runner service.
928 */
929 advance(pullId: string): Promise<Advance>;
930 /** Records that a step could not be carried out, so a person is asked. */
931 stall(pullId: string, reason: string): Promise<boolean>;
932 /** Ids of the open pull requests g1t is seeing through. */
933 managedPulls(repoId?: string): Promise<string[]>;
Issues and pull requests replace intents and attempts934
Agents as a team: lifecycle, merge queue, billing and a new shell935 /** A repository's merge queue: what is in it, in order, and what recently left. */
936 queue(repo: RepoPath, viewer: Viewer): Promise<Result<QueueView>>;
Pull requests from branches937 /**
Agents as a team: lifecycle, merge queue, billing and a new shell938 * The next batch of combined states to test for a repository, one per
939 * entry; empty while a batch is being tested or nothing waits.
940 */
941 queueBuild(repoId: string): Promise<QueueJob[]>;
942 /** Reports that a combined state could not be built or checked. */
943 failQueue(entryId: string, token: string, error: string): Promise<Result<QueueState>>;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request944 /** Sends the agent working on a pull request a message, for its next step. */
945 messageAgent(actor: User, repo: RepoPath, number: number, body: string): Promise<Result<AgentMessage>>;
Agents as a team: lifecycle, merge queue, billing and a new shell946 /** Takes a pull request out of the merge queue. Members only. */
947 removeFromQueue(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
948
949 getSettings(repo: RepoPath, viewer: Viewer): Promise<Result<RepoSettings>>;
Fast pages, required checks on the branch, self-hosted runners, honest incidents950 /** The check names reported on the repository's commits in the last 30 days, most recent first. */
951 seenChecks(repo: RepoPath, viewer: Viewer): Promise<Result<SeenCheck[]>>;
Agents as a team: lifecycle, merge queue, billing and a new shell952 /** Members of the repository's workspace only. */
953 updateSettings(actor: User, repo: RepoPath, settings: RepoSettingsInput): Promise<Result<RepoSettings>>;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar954 /** The CODEOWNERS file at a branch (the default when left out), checked. Needs Read. */
955 codeownersErrors(repo: RepoPath, viewer: Viewer, ref?: string | null): Promise<Result<CodeownersReport>>;
Agents as a team: lifecycle, merge queue, billing and a new shell956 /**
957 * What the runner needs to bring a pull request up to date because a
958 * merge of it was asked for. Null if none was.
959 */
960 catchUpJob(pullId: string): Promise<LifecycleJob | null>;
Agents asked while not at work are woken to answer961 /**
962 * Claims a short step for the agent on a pull request to answer the
963 * questions and handoffs it was sent while not at work, and hands them
964 * over, marked read. Null when there is nothing waiting or it cannot
965 * take a step now.
966 */
967 wakeForMessages(pullId: string): Promise<Wake | null>;
Agents as a team: lifecycle, merge queue, billing and a new shell968
969 /**
Pull requests from branches970 * Opens a pull request: a draft with a fork to push to, or, given a
971 * branch, one ready for review.
972 */
Issues and pull requests replace intents and attempts973 openPull(actor: User, repo: RepoPath, input: OpenPullInput): Promise<Result<Pull>>;
974 /** Newest first. */
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar975 listPulls(
976 repo: RepoPath,
977 viewer: Viewer,
978 state?: State,
979 filter?: { label?: string; milestone?: number; base?: string },
980 ): Promise<Result<Pull[]>>;
Fast pages, required checks on the branch, self-hosted runners, honest incidents981 /**
982 * The newest `limit` open and closed pull requests of each repository,
983 * in one call. Repositories the viewer cannot read, and forks, are left
984 * out: ask those with `listPulls`.
985 */
986 pullsForRepos(repoIds: string[], viewer: Viewer, limit: number): Promise<RepoPulls[]>;
Issues and pull requests replace intents and attempts987 getPull(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<PullDetail>>;
Agents as a team: lifecycle, merge queue, billing and a new shell988 /**
989 * Changes who a pull request is assigned to and whose review is asked
g1t is one name: its agent's work, commits and comments show as @g1t, and nobody can claim g1t or g1t-agent990 * for; each list given replaces the whole set. Asking for `g1t`'s
Agents as a team: lifecycle, merge queue, billing and a new shell991 * review does not by itself start one: the runner's `review` does.
992 */
993 updatePull(
994 actor: User,
995 repo: RepoPath,
996 number: number,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar997 changes: {
998 assignees?: string[];
999 reviewers?: string[];
1000 labels?: string[];
1001 /** 0 takes it out of its milestone. */
1002 milestone?: number;
1003 /** The branch it merges into. Needs the Write role. */
1004 base?: string;
1005 },
Agents as a team: lifecycle, merge queue, billing and a new shell1006 ): Promise<Result<Pull>>;
Catching up with main takes seconds when the two sides touched different files1007 /**
1008 * Brings a pull request up to date with the default branch in seconds,
1009 * without a sandbox, when the two changed different files: the merge
1010 * commit is pushed to its branch as `actor`, who must be whoever opened
1011 * it (for a fork) or a member (for a branch). Otherwise `needs_agent`, and
1012 * nothing is pushed: the runner's `update` is the way on.
1013 */
1014 catchUpPull(actor: User, repo: RepoPath, number: number): Promise<Result<PullBranchUpdate>>;
Issues and pull requests replace intents and attempts1015 /** Marks a draft ready for review and sets its description. */
1016 readyPull(actor: User, repo: RepoPath, number: number, summary: string): Promise<Result<Pull>>;
1017 closePull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
Rust repos service with shipping; pull requests kept in the model1018 /**
Issues and pull requests replace intents and attempts1019 * Lands the pull request on the repository's default branch. Unless
1020 * `keepIssueOpen`, that resolves the issue it was for: the issue closes
1021 * naming this pull request, and the others still in progress for it close
1022 * as superseded. Only members of the repository's workspace may merge.
Agents as a team: lifecycle, merge queue, billing and a new shell1023 *
1024 * If the default branch has moved, the pull request is brought up to date
1025 * first and lands when that is done; it comes back still open, and
1026 * `PullDetail.landing` is true meanwhile. A repository that requires pull
1027 * requests to be up to date refuses instead.
Rust repos service with shipping; pull requests kept in the model1028 */
Acceptance checks in sandboxes, line comments and review verdicts1029 mergePull(
1030 actor: User,
1031 repo: RepoPath,
1032 number: number,
1033 options?: {
1034 keepIssueOpen?: boolean;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge1035 /** Merge although required checks have not passed, where the rule requiring them allows it. */
Acceptance checks in sandboxes, line comments and review verdicts1036 ignoreChecks?: boolean;
Merge rulesets: branch and tag rules, agent-first, enforced on push and merge1037 /** Merge past rules a ruleset lets the actor bypass. Recorded as a bypass. */
1038 bypassRules?: boolean;
Acceptance checks in sandboxes, line comments and review verdicts1039 },
1040 ): Promise<Result<Pull>>;
Agents as a team: lifecycle, merge queue, billing and a new shell1041 /**
1042 * Drafts and open pull requests the viewer started, most recently active
1043 * first, each with where it stands if g1t is seeing it through.
1044 */
1045 listActivePulls(
1046 viewer: Viewer,
1047 ): Promise<{ pull: Pull; issue: Issue | null; lifecycle: Lifecycle | null }[]>;
Agents and memory, checks and conflicts, profiles, slug renames, custom domains1048 /**
1049 * The issues and pull requests a person opened, a page at a time, only
1050 * on repositories the viewer may read. Not found for no such account.
1051 */
1052 byAuthor(username: string, viewer: Viewer, filter?: AuthoredFilter): Promise<Result<Authored>>;
Initial g1t: services, event bus, intents and attempts1053
Agents as a team: lifecycle, merge queue, billing and a new shell1054 /**
1055 * Records an outcome to plan for. Members only. For the runner service,
1056 * which starts the sandbox in which an agent writes the plan.
1057 */
1058 startPlan(actor: User, repo: RepoPath, brief: string): Promise<Result<PlanJob>>;
1059 /** Records that a plan could not be written. For the runner service. */
1060 failPlan(planId: string, token: string, error: string): Promise<Result<boolean>>;
1061 /** Members only. */
1062 getPlan(repo: RepoPath, viewer: Viewer, id: string): Promise<Result<Plan>>;
1063 /** Newest first. Members only. */
1064 listPlans(repo: RepoPath, viewer: Viewer): Promise<Result<Plan[]>>;
1065 /**
1066 * Opens a plan's issues, each blocked by the ones it depends on. With
1067 * `assign`, each is queued for a g1t agent. `keep` holds the positions,
1068 * from 1, of the issues to open; all of them when absent. Once.
1069 */
1070 applyPlan(
1071 actor: User,
1072 repo: RepoPath,
1073 id: string,
1074 options?: { assign?: boolean; keep?: number[] },
1075 ): Promise<Result<Plan>>;
1076 /** Asks for a g1t agent to take an issue as soon as it can, or withdraws that. */
1077 queueIssue(actor: User, repo: RepoPath, number: number, queued: boolean): Promise<Result<boolean>>;
1078 /** Issues waiting for a g1t agent that can be given one now. For the runner. */
1079 readyIssues(repoId?: string): Promise<ReadyIssue[]>;
1080
1081 /** Open issues assigned to the viewer, most recently changed first. */
1082 listAssignedIssues(viewer: Viewer): Promise<Issue[]>;
1083
Issues and pull requests replace intents and attempts1084 appendSession(actor: User, repo: RepoPath, number: number, entries: NewSessionEntry[]): Promise<Result<{ count: number }>>;
1085 readSession(repo: RepoPath, number: number, viewer: Viewer, afterSeq?: number): Promise<Result<SessionEntry[]>>;
Initial g1t: services, event bus, intents and attempts1086}
Pull requests from branches1087
1088/**
1089 * What to pass `ReposApi.compare` to see what a pull request changes.
1090 *
1091 * A fork is compared as a whole. A branch is compared by name while the
1092 * pull request is open, and by the commit it was merged or closed at
1093 * afterwards, so later pushes to the branch do not change the record.
1094 */
1095export function pullComparison(pull: Pull): {
1096 repoId: string;
1097 base: string | null;
1098 head: string | null;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1099 /** The branch it merges into, which it is compared from. */
1100 baseBranch: string | null;
Pull requests from branches1101} {
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1102 const baseBranch = pull.base ?? null;
1103 if (pull.forkRepoId) return { repoId: pull.forkRepoId, base: pull.mergeBase, head: null, baseBranch };
Pull requests from branches1104 const settled = pull.status === "merged" || pull.status === "closed";
1105 return {
1106 repoId: pull.repoId,
1107 base: pull.mergeBase,
1108 head: (settled && pull.headCommit) || pull.branch,
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar1109 baseBranch,
Pull requests from branches1110 };
1111}
Agents as a team: lifecycle, merge queue, billing and a new shell1112
1113
1114/** Where a pull request in a merge queue stands. */
Dark gray base with lavender as an accent, and a live outcome view for plans1115/** Where one issue of an applied plan stands. */
1116export type IssueProgress = {
1117 number: number;
1118 title: string;
1119 /**
1120 * `blocked`, `waiting` (for an agent), `open`, a lifecycle stage,
1121 * `landed` or `closed`.
1122 */
1123 state: string;
1124 detail: string;
1125 /** The issues it is waiting on that are still open. */
1126 blockedBy: number[];
1127 pull: number | null;
1128 agent: string | null;
1129};
1130
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request1131/** A message a person sent an agent at work on a pull request. */
1132export type AgentMessage = {
1133 id: string;
1134 author: string;
1135 body: string;
1136 createdAt: string;
1137 /** When the agent received it; null until then. */
1138 deliveredAt: string | null;
Agents ask each other, hand each other work, and answer1139 /** `message` from a person; from an agent a `question`, `handoff` or `answer`. */
1140 kind: "message" | "question" | "handoff" | "answer";
1141 /** The pull request whose agent sent it, when an agent did. */
1142 fromNumber: number | null;
1143 /** The pull request it was sent to. */
1144 toNumber: number;
1145 /** The reply to a question or handoff, once there is one. */
1146 answer: string | null;
1147 declined: boolean;
1148 /** For the sending agent: what to expect when the one it asked is not at work. */
1149 hint?: string;
Usage, like a hosting provider's: what agents cost, per day, task, repository and pull request1150};
1151
Agents as a team: lifecycle, merge queue, billing and a new shell1152export type QueueState = "waiting" | "testing" | "passed" | "failed" | "landed" | "removed";
1153
1154/** One pull request's place in a merge queue. */
1155export type QueueEntry = {
1156 id: string;
1157 number: number;
1158 title: string;
1159 agent: string;
1160 state: QueueState;
1161 /** The pull requests merged ahead of it in the state being tested, in order. */
1162 ahead: number[];
1163 baseCommit: string | null;
1164 combinedCommit: string | null;
1165 error: string | null;
1166 results: CheckResult[];
1167 /** Username of whoever merged it into the queue: a person, or `g1t`. */
1168 enqueuedBy: string;
1169 /** RFC 3339. */
1170 createdAt: string;
1171 /** RFC 3339. */
1172 finishedAt: string | null;
1173};
1174
1175/** A repository's merge queue: what is in it, in order, and what recently left. */
1176export type QueueView = {
1177 enabled: boolean;
1178 active: QueueEntry[];
1179 /** Newest first. */
1180 recent: QueueEntry[];
1181};
1182
1183export type QueueStackItem = {
1184 number: number;
1185 title: string;
1186 /** The repository holding the change, and its branch. */
1187 source: RepoPath;
1188 branch: string;
1189 commit: string;
1190};
1191
1192/** What a sandbox needs to build and check one combined state. */
1193export type QueueJob = {
1194 entryId: string;
1195 token: string;
1196 repo: RepoPath;
1197 defaultBranch: string;
1198 baseCommit: string;
1199 branch: string;
1200 stack: QueueStackItem[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents1201 /** Always empty: the state is checked by the merge_group workflows run on it. */
Agents as a team: lifecycle, merge queue, billing and a new shell1202 checks: string[];
Fast pages, required checks on the branch, self-hosted runners, honest incidents1203 /** Always empty, as `checks`. */
Agents as a team: lifecycle, merge queue, billing and a new shell1204 contractChecks: string[];
1205 actor: User;
1206};
Agents and memory, checks and conflicts, profiles, slug renames, custom domains1207
1208// --- A person's work ---------------------------------------------------------
1209// Mirrors the `Authored*` types in `crates/contracts/src/work.rs`.
1210
1211export type AuthoredKind = "issue" | "pull";
1212/** `closed` takes in merged pull requests too; `merged` is only those. */
1213export type AuthoredState = "open" | "closed" | "merged";
1214/** `created` is newest first, `updated` most recently changed, `oldest` oldest first. */
1215export type AuthoredSort = "created" | "updated" | "oldest";
1216
1217/** The most items one `byAuthor` page holds. */
1218export const AUTHORED_PAGE = 25;
1219
1220export type AuthoredFilter = {
1221 kind?: AuthoredKind;
1222 state?: AuthoredState;
1223 /** `namespace/name`. */
1224 repo?: string;
1225 sort?: AuthoredSort;
1226 /** The `next` of the page before. */
1227 before?: string;
1228 limit?: number;
1229};
1230
1231export type AuthoredItem = {
1232 kind: AuthoredKind;
1233 repo: RepoPath;
1234 number: number;
1235 title: string;
1236 /** A merged pull request is closed. */
1237 state: State;
1238 /** A pull request's own status; null on an issue. */
1239 status: PullStatus | null;
1240 /** Why an issue was closed. */
1241 reason: IssueReason | null;
1242 draft: boolean;
1243 merged: boolean;
1244 /** RFC 3339. */
1245 createdAt: string;
1246 /** RFC 3339. */
1247 updatedAt: string;
1248 /** RFC 3339. */
1249 mergedAt: string | null;
1250};
1251
1252/** Over every repository the viewer may read, whatever the filters. */
1253export type AuthoredCounts = {
1254 pullsMerged: number;
1255 pullsOpen: number;
1256 pulls: number;
1257 issues: number;
1258 issuesOpen: number;
1259};
1260
1261export type Authored = {
1262 items: AuthoredItem[];
1263 /** Pass as `before` for the next page; null on the last. */
1264 next: string | null;
1265 counts: AuthoredCounts;
1266 /** The repositories they worked in that the viewer may read, most work first. */
1267 repos: { repo: RepoPath; count: number }[];
1268};

This file's history is long; its oldest lines are credited to the oldest commit read.