Skip to content
Sign up

flagon-io/g1t

public
0
231 linesCodeBlameRaw
1import type { AgentRun } from "./agents";
2import type { Trial } from "./billing";
3import type { User, Viewer } from "./identity";
4import type { Result } from "./result";
5import type { RepoPath } from "./repos";
6import type { DelegateInput, Delegated, Plan, Pull } from "./work";
7
8export type RunHostedInput = {
9 /** Extra guidance given to the agent along with the issue. */
10 instructions?: string;
11};
12
13/**
14 * Sandboxes on g1t: agents that work on an issue, reviews, and the merge queue.
15 *
16 * Nobody who assigns a g1t agent picks a model. g1t routes each kind of
17 * work itself, and says in the session which model ran.
18 */
19/**
20 * How a workspace's agents reach a model. The workspace decides: its own
21 * provider (`own` names it), or g1t's hosted models paid from its credit.
22 */
23export type ModelAccess = {
24 /** The workspace's own model connection, by name, if it has one. */
25 own: string | null;
26 /** Whether g1t's hosted models are open to it, on its free allowance or otherwise. */
27 hosted: boolean;
28 /** Its free allowance, when that is how it reaches g1t's hosted models; null when it needs none. */
29 trial: Trial | null;
30 /**
31 * True when hosted models are closed to it because billing takes no real
32 * money yet: until then they are open only to the workspaces g1t lists,
33 * and every other workspace uses its own provider.
34 */
35 preview: boolean;
36};
37
38/**
39 * The files every g1t agent run in a repository reads as the repository's
40 * instructions, as they are on its default branch.
41 */
42export type RepoInstructions = {
43 branch: string;
44 /** Null when the repository has no commits yet. */
45 commit: string | null;
46 files: {
47 path: string;
48 /** `root` is read by every run, `directory` by runs that touch files under it, `review` by reviews. */
49 role: "root" | "directory" | "review";
50 text: string;
51 /** Longer than agents are given; they get the start of it. */
52 truncated: boolean;
53 lastChanged: { commit: string; message: string; author: string; at: string } | null;
54 }[];
55 /** How much of each file, and of all of them, an agent is given. */
56 limits: { fileChars: number; totalChars: number };
57};
58
59// ── An agent's own computer ────────────────────────────────────────────────
60
61/**
62 * What an agent's computer is doing (docs.g1t.sh/guides/agents/, "Its
63 * computer"): asleep with its home saved, waking (the container starting
64 * and the home restored), awake and metered, or sleeping (the home being
65 * saved, then the container stopped).
66 */
67export type AgentComputerState = "asleep" | "waking" | "awake" | "sleeping";
68
69/** How much the home may hold in v1: a hard cap, with no disk charge. */
70export const COMPUTER_DISK_CAP_BYTES = 5_000_000_000;
71/** How long a computer stays awake with nothing running before it sleeps. */
72export const COMPUTER_IDLE_MINUTES = 10;
73/** Where an archived agent's disk is kept before it is deleted. */
74export const COMPUTER_KEEP_DAYS = 30;
75/** How many of the most recent commands a computer keeps for its page. */
76export const COMPUTER_TRANSCRIPTS_KEPT = 50;
77/** How much of one command's output a kept transcript holds. */
78export const COMPUTER_TRANSCRIPT_BYTES = 64 * 1024;
79
80/** The computer as the runner reports it. Wire shape: snake_case. */
81export type AgentComputerStatus = {
82 agent_id: string;
83 state: AgentComputerState;
84 /** RFC 3339: when it entered this state. */
85 since: string;
86 /** What the home holds, as last measured (live while awake; the snapshot's size while asleep). */
87 disk_used_bytes: number;
88 disk_cap_bytes: number;
89 last_woke_at: string | null;
90 last_slept_at: string | null;
91 /** The saved home's size and when it was saved; null while there is none. */
92 snapshot_bytes: number | null;
93 snapshot_at: string | null;
94 /** Where it runs. Pinning to a self-hosted runner group comes later. */
95 where: "g1t_cloud";
96 /** False when this installation has no object storage for homes yet: the computer works, and forgets its home when it sleeps. */
97 disk_attached: boolean;
98 /** Something the owner should know: the home is over its cap and could not be saved, say. */
99 problem: string | null;
100 /** When the disk will be deleted, after its agent was archived. */
101 delete_after: string | null;
102};
103
104/** One command a computer ran, as kept for its page and the session's. */
105export type AgentComputerCommand = {
106 id: string;
107 session_id: string | null;
108 asked_by: string | null;
109 started_at: string;
110 cmd: string;
111 cwd: string;
112 exit_code: number;
113 duration_ms: number;
114 /** stdout and stderr lines in order, cut to `COMPUTER_TRANSCRIPT_BYTES`. */
115 output: string;
116 truncated: boolean;
117 timed_out: boolean;
118};
119
120export type ComputerWakeArgs = {
121 agent_id: string;
122 workspace: string;
123 /** The agent's handle, which its sandbox time is attributed to on the ledger. */
124 agent_handle: string;
125 /** Who asked for the session that woke it, by username; null for a routine's. */
126 asked_by: string | null;
127};
128
129export type ComputerExecArgs = ComputerWakeArgs & {
130 cmd: string;
131 /** Under the home; the home itself when absent. */
132 cwd?: string | null;
133 timeout_seconds?: number | null;
134 session_id?: string | null;
135};
136
137/** What `computer_exec` returns: the command as kept, in full (up to the transcript cap). */
138export type ComputerExecResult = { command: AgentComputerCommand; status: AgentComputerStatus };
139
140/** What `computer_wake` and the others return. */
141export type ComputerResult<T> = Result<T>;
142
143/**
144 * The runner's side of an agent's computer, which the agents service calls
145 * through its RUNNER binding (`POST /rpc/computer_*`, snake_case). One
146 * Durable Object per agent, named `computer:<agent_id>`.
147 */
148export interface RunnerComputerApi {
149 computerStatus(agentId: string): Promise<Result<AgentComputerStatus>>;
150 /** Starts it (restoring the saved home) and begins the meter; `payment_required` when the workspace's plan refuses. */
151 computerWake(args: ComputerWakeArgs): Promise<Result<AgentComputerStatus>>;
152 /** Runs a command, waking it first if asleep. */
153 computerExec(args: ComputerExecArgs): Promise<Result<ComputerExecResult>>;
154 /** Reads a small file of the home as text. */
155 computerReadFile(args: ComputerWakeArgs & { path: string; session_id?: string | null }): Promise<Result<{ path: string; text: string; bytes: number }>>;
156 /** Writes a small file into the home. */
157 computerWriteFile(args: ComputerWakeArgs & { path: string; text: string; session_id?: string | null }): Promise<Result<{ path: string; bytes: number }>>;
158 /** Saves the home and stops the container; the sandbox time goes on the ledger. */
159 computerSleep(agentId: string): Promise<Result<AgentComputerStatus>>;
160 /** Stops it if awake, deletes the saved home and its commands. Memory and artifacts are untouched. */
161 computerReset(agentId: string): Promise<Result<AgentComputerStatus>>;
162 /** An archived agent's: stopped now, its disk deleted after `COMPUTER_KEEP_DAYS`. */
163 computerForget(agentId: string): Promise<Result<AgentComputerStatus>>;
164 /** The most recent commands, newest first; `session_id` narrows them to one session's. */
165 computerCommands(agentId: string, sessionId?: string | null): Promise<Result<AgentComputerCommand[]>>;
166}
167
168export interface RunnerApi {
169 /**
170 * The repository's instructions for agents (`AGENTS.md`, `CLAUDE.md`,
171 * `.g1t/review.md`), as they are on its default branch: what every g1t
172 * agent run there reads. Whoever can see the repository may ask.
173 */
174 instructions(viewer: Viewer, repo: RepoPath): Promise<Result<RepoInstructions>>;
175 /** How `workspace`'s agents would reach a model now. */
176 modelAccess(workspace: string): Promise<ModelAccess>;
177 /**
178 * Whether `viewer` may put g1t's agents to work: in `repo`'s workspace,
179 * or with none named, in any of theirs.
180 */
181 enabled(viewer: Viewer, repo?: RepoPath): Promise<boolean>;
182 /**
183 * Assigns the issue to a g1t agent: opens a draft pull request for it,
184 * made by an agent in a sandbox of its own. Returns as soon as the
185 * sandbox is starting; progress shows up in the pull request's session.
186 * Scale comes from assigning many issues, each to its own agent.
187 */
188 run(actor: User, repo: RepoPath, issue: number, input?: RunHostedInput): Promise<Result<Pull>>;
189 /**
190 * Puts an agent on something in one step: opens an issue and assigns it
191 * to g1t. Refused, with nothing opened, unless `actor` may put
192 * agents to work in `repo` (Write). Once opened, the issue stays whatever
193 * becomes of the agent: `agent` says whether it started, waits for a
194 * free slot, or did not start, why and where to fix it.
195 */
196 delegate(actor: User, repo: RepoPath, input: DelegateInput): Promise<Result<Delegated>>;
197 /**
198 * Has an agent read the repository and turn an outcome into a plan: the
199 * issues that would get there and the order they have to land in. Returns
200 * the plan's id as soon as the sandbox is starting; the plan fills in when
201 * the agent has written it. Members of the repository's workspace only.
202 */
203 plan(actor: User, repo: RepoPath, brief: string): Promise<Result<{ planId: string }>>;
204 /**
205 * Opens a plan's issues. With `assign`, a g1t agent starts on each that
206 * depends on nothing, and on the others as what they depend on merges.
207 */
208 applyPlan(
209 actor: User,
210 repo: RepoPath,
211 planId: string,
212 options?: { assign?: boolean; keep?: number[] },
213 ): Promise<Result<Plan>>;
214 /**
215 * Brings a pull request up to date with the branch it would merge into,
216 * in a sandbox. A clean merge is pushed as it is; a conflict is resolved
217 * by a g1t agent. Whoever can push to the pull request's source may ask:
218 * its author, or for one from a branch, a workspace member.
219 */
220 update(actor: User, repo: RepoPath, number: number): Promise<Result<boolean>>;
221 /**
222 * Has a g1t agent review a pull request: line comments, a summary and a
223 * verdict, posted as `g1t`.
224 */
225 review(actor: User, repo: RepoPath, number: number): Promise<Result<boolean>>;
226 /**
227 * Stops an agent run: marks it stopped, destroys its sandbox, and leaves
228 * the pull request it was on for a person. Members of the workspace only.
229 */
230 stopRun(actor: User, repo: RepoPath, runId: string): Promise<Result<AgentRun>>;
231}