Sign in

pulls/pr_01m47d15m3e54sn21z27rpy5n9

public

pr_01m47d15m3e54sn21z27rpy5n9/packages/contracts/src/work.ts

234 lines8,135 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.

Initial g1t: services, event bus, intents and attempts1import type { User, Viewer } from "./identity";
2import type { RepoPath } from "./repos";
3import type { Result } from "./result";
4
Issues and pull requests replace intents and attempts5/**
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";
Initial g1t: services, event bus, intents and attempts14
Issues and pull requests replace intents and attempts15/**
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 = {
Initial g1t: services, event bus, intents and attempts23 id: string;
24 repoId: string;
Issues and pull requests replace intents and attempts25 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts26 number: number;
27 title: string;
Issues and pull requests replace intents and attempts28 /** 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. */
Initial g1t: services, event bus, intents and attempts32 checks: string[];
Issues and pull requests replace intents and attempts33 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;
Initial g1t: services, event bus, intents and attempts38 author: User;
Work service in Rust, with RFC 3339 timestamps39 /** RFC 3339. */
40 createdAt: string;
Issues and pull requests replace intents and attempts41 /** 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;
Initial g1t: services, event bus, intents and attempts48};
49
Issues and pull requests replace intents and attempts50/** `draft` is still being worked on; `open` is ready for review. */
51export type PullStatus = "draft" | "open" | "merged" | "closed";
Initial g1t: services, event bus, intents and attempts52
53/** Where the agent runs: on g1t's sandboxes, or in someone's own session. */
Issues and pull requests replace intents and attempts54export type Runtime = "hosted" | "external";
Initial g1t: services, event bus, intents and attempts55
Pull requests from branches56/**
57 * A proposed change. It is made either in a fork created for it, which is
58 * how agents work, or on a branch pushed to the repository itself.
59 */
Issues and pull requests replace intents and attempts60export type Pull = {
Initial g1t: services, event bus, intents and attempts61 id: string;
62 repoId: string;
Issues and pull requests replace intents and attempts63 /** Shown as `#12`. */
Initial g1t: services, event bus, intents and attempts64 number: number;
Issues and pull requests replace intents and attempts65 /** The number of the issue this is for, if any. */
66 issue: number | null;
67 title: string;
68 /** Markdown: what changed and why. Set when marked ready. */
69 body: string | null;
Initial g1t: services, event bus, intents and attempts70 /** A label for the agent doing the work, e.g. `claude-code`. */
71 agent: string;
Issues and pull requests replace intents and attempts72 runtime: Runtime;
73 status: PullStatus;
Pull requests from branches74 /** The fork holding the change, unless it is on a branch. */
75 fork: RepoPath | null;
Diffs on attempts; hosted agent presented as the g1t agent76 /** The fork's repository id. */
Pull requests from branches77 forkRepoId: string | null;
78 /** The branch of the repository holding the change, unless it is in a fork. */
79 branch: string | null;
Initial g1t: services, event bus, intents and attempts80 headCommit: string | null;
Diffs on attempts; hosted agent presented as the g1t agent81 /**
Issues and pull requests replace intents and attempts82 * For a merged pull request, what the branch pointed to before the merge.
83 * Comparing against it shows what the pull request changed.
84 */
85 mergeBase: string | null;
86 /** Username of whoever merged it. */
87 mergedBy: string | null;
88 /** RFC 3339. */
89 mergedAt: string | null;
90 /**
91 * Set on a pull request closed because another one for the same issue was
92 * merged: that one's number.
Diffs on attempts; hosted agent presented as the g1t agent93 */
Issues and pull requests replace intents and attempts94 supersededBy: number | null;
95 author: User;
Work service in Rust, with RFC 3339 timestamps96 /** RFC 3339. */
97 createdAt: string;
98 /** RFC 3339. */
99 updatedAt: string;
Initial g1t: services, event bus, intents and attempts100};
101
Issues and pull requests replace intents and attempts102export type Comment = {
103 id: string;
104 author: User;
105 /** Markdown. */
106 body: string;
107 /** RFC 3339. */
108 createdAt: string;
109};
110
Initial g1t: services, event bus, intents and attempts111export type SessionEntryKind = "prompt" | "message" | "tool_call" | "tool_result" | "note";
112
Issues and pull requests replace intents and attempts113/** One step of an agent's session: the "why" behind a pull request's commits. */
Initial g1t: services, event bus, intents and attempts114export type SessionEntry = {
115 seq: number;
116 kind: SessionEntryKind;
117 text: string;
118 /** For tool calls and results. */
119 tool: string | null;
120 /** The fork's head commit when this entry was recorded, if known. */
121 commit: string | null;
Work service in Rust, with RFC 3339 timestamps122 /** RFC 3339. */
123 at: string;
Initial g1t: services, event bus, intents and attempts124};
125
126export type NewSessionEntry = Pick<SessionEntry, "kind" | "text"> &
Work service in Rust, with RFC 3339 timestamps127 Partial<Pick<SessionEntry, "tool" | "commit">>;
Initial g1t: services, event bus, intents and attempts128
Issues and pull requests replace intents and attempts129export type IssueDetail = {
130 issue: Issue;
131 /** Every pull request made against it, oldest first. */
132 pulls: Pull[];
133 comments: Comment[];
134};
Initial g1t: services, event bus, intents and attempts135
Issues and pull requests replace intents and attempts136export type PullDetail = {
137 pull: Pull;
138 /** The issue it is for, if any. */
139 issue: Issue | null;
140 comments: Comment[];
141};
Initial g1t: services, event bus, intents and attempts142
Issues and pull requests replace intents and attempts143export type OpenIssueInput = {
144 title: string;
145 body: string;
146 labels?: string[];
147 checks?: string[];
148};
149
150export type UpdateIssueInput = { title?: string; body?: string; labels?: string[] };
151
152export type OpenPullInput = {
153 /** The number of the issue this is for. */
154 issue?: number;
155 /** Defaults to the issue's title; required without an issue. */
156 title?: string;
Pull requests from branches157 /** What changed and why. Usually set later, when a draft is marked ready. */
158 body?: string;
159 /**
160 * A branch of the repository that already holds the change. The pull
161 * request is then ready for review at once and has no fork.
162 */
163 branch?: string;
Issues and pull requests replace intents and attempts164 agent: string;
165 runtime: Runtime;
166};
Initial g1t: services, event bus, intents and attempts167
Issues and pull requests replace intents and attempts168/** Issues, pull requests, comments and sessions. */
Work service in Rust, with RFC 3339 timestamps169export interface WorkApi {
Issues and pull requests replace intents and attempts170 openIssue(actor: User, repo: RepoPath, input: OpenIssueInput): Promise<Result<Issue>>;
171 /** Newest first. */
172 listIssues(
173 repo: RepoPath,
174 viewer: Viewer,
175 filter?: { state?: State; label?: string },
176 ): Promise<Result<Issue[]>>;
177 getIssue(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<IssueDetail>>;
178 /** The author or a member of the workspace may. */
179 updateIssue(actor: User, repo: RepoPath, number: number, input: UpdateIssueInput): Promise<Result<Issue>>;
180 closeIssue(actor: User, repo: RepoPath, number: number, reason?: IssueReason): Promise<Result<Issue>>;
181 reopenIssue(actor: User, repo: RepoPath, number: number): Promise<Result<Issue>>;
182 /** The default labels, then every other label in use on the repository. */
183 listLabels(repo: RepoPath, viewer: Viewer): Promise<Result<string[]>>;
184 /** How many issues and pull requests are open. */
185 counts(repo: RepoPath, viewer: Viewer): Promise<Result<{ issues: number; pulls: number }>>;
Initial g1t: services, event bus, intents and attempts186
Issues and pull requests replace intents and attempts187 /** On an issue or a pull request. */
188 addComment(actor: User, repo: RepoPath, number: number, body: string): Promise<Result<Comment>>;
189
Pull requests from branches190 /**
191 * Opens a pull request: a draft with a fork to push to, or, given a
192 * branch, one ready for review.
193 */
Issues and pull requests replace intents and attempts194 openPull(actor: User, repo: RepoPath, input: OpenPullInput): Promise<Result<Pull>>;
195 /** Newest first. */
196 listPulls(repo: RepoPath, viewer: Viewer, state?: State): Promise<Result<Pull[]>>;
197 getPull(repo: RepoPath, number: number, viewer: Viewer): Promise<Result<PullDetail>>;
198 /** Marks a draft ready for review and sets its description. */
199 readyPull(actor: User, repo: RepoPath, number: number, summary: string): Promise<Result<Pull>>;
200 closePull(actor: User, repo: RepoPath, number: number): Promise<Result<Pull>>;
Rust repos service with shipping; pull requests kept in the model201 /**
Issues and pull requests replace intents and attempts202 * Lands the pull request on the repository's default branch. Unless
203 * `keepIssueOpen`, that resolves the issue it was for: the issue closes
204 * naming this pull request, and the others still in progress for it close
205 * as superseded. Only members of the repository's workspace may merge.
Rust repos service with shipping; pull requests kept in the model206 */
Issues and pull requests replace intents and attempts207 mergePull(actor: User, repo: RepoPath, number: number, keepIssueOpen?: boolean): Promise<Result<Pull>>;
208 /** Drafts and open pull requests the viewer started, most recently active first. */
209 listActivePulls(viewer: Viewer): Promise<{ pull: Pull; issue: Issue | null }[]>;
Initial g1t: services, event bus, intents and attempts210
Issues and pull requests replace intents and attempts211 appendSession(actor: User, repo: RepoPath, number: number, entries: NewSessionEntry[]): Promise<Result<{ count: number }>>;
212 readSession(repo: RepoPath, number: number, viewer: Viewer, afterSeq?: number): Promise<Result<SessionEntry[]>>;
Initial g1t: services, event bus, intents and attempts213}
Pull requests from branches214
215/**
216 * What to pass `ReposApi.compare` to see what a pull request changes.
217 *
218 * A fork is compared as a whole. A branch is compared by name while the
219 * pull request is open, and by the commit it was merged or closed at
220 * afterwards, so later pushes to the branch do not change the record.
221 */
222export function pullComparison(pull: Pull): {
223 repoId: string;
224 base: string | null;
225 head: string | null;
226} {
227 if (pull.forkRepoId) return { repoId: pull.forkRepoId, base: pull.mergeBase, head: null };
228 const settled = pull.status === "merged" || pull.status === "closed";
229 return {
230 repoId: pull.repoId,
231 base: pull.mergeBase,
232 head: (settled && pull.headCommit) || pull.branch,
233 };
234}