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/agents.ts

215 lines7,404 bytesCodeBlame
1/**
2 * Agents at work and what they remember, kept by the work service. Mirrors
3 * `g1t_contracts::agents`.
4 */
5import type { ServiceBinding } from "./clients";
6import type { User, Viewer } from "./identity";
7import type { RepoPath } from "./repos";
8import type { Result } from "./result";
9import type { Pull, PullStatus, SessionEntry } from "./work";
10
11/** The work a run does. checks, queue and mergecheck run commands, not a model. */
12export type RunKind =
13 | "implement"
14 | "revise"
15 | "review"
16 | "answer"
17 | "update"
18 | "plan"
19 | "checks"
20 | "queue"
21 | "mergecheck";
22
23export const RUN_KINDS: RunKind[] = ["implement", "revise", "review", "answer", "update", "plan", "checks", "queue", "mergecheck"];
24
25/** How a kind of run reads in a sentence: "is implementing", "a review run". */
26export const RUN_KIND_LABEL: Record<RunKind, string> = {
27 implement: "Implementing",
28 revise: "Revising",
29 review: "Reviewing",
30 answer: "Answering",
31 update: "Catching up",
32 plan: "Planning",
33 checks: "Checks",
34 queue: "Merge queue",
35 mergecheck: "Merge check",
36};
37
38/** Whether a message reaches the agent while it runs, at its next step. */
39export function takesMessages(kind: RunKind): boolean {
40 return kind === "implement" || kind === "revise" || kind === "answer";
41}
42
43export function isAgentKind(kind: RunKind): boolean {
44 return kind !== "checks" && kind !== "queue" && kind !== "mergecheck";
45}
46
47export type AgentRunStatus = "queued" | "running" | "succeeded" | "failed" | "stopped";
48
49export function isActiveRun(status: AgentRunStatus): boolean {
50 return status === "queued" || status === "running";
51}
52
53export type RunStep = { at: string; text: string };
54
55export type AgentRun = {
56 id: string;
57 repo: RepoPath;
58 number: number | null;
59 title: string | null;
60 kind: RunKind;
61 /** `g1t-agent`, or `g1t` for a sandbox that runs commands. */
62 agent: string;
63 /** Members only. */
64 model: string | null;
65 status: AgentRunStatus;
66 step: string | null;
67 /** Oldest first; empty in lists. */
68 steps: RunStep[];
69 stepCount: number;
70 startedBy: string | null;
71 error: string | null;
72 /** Members only. */
73 costUsd: number | null;
74 turns: number | null;
75 createdAt: string;
76 startedAt: string | null;
77 finishedAt: string | null;
78 updatedAt: string;
79};
80
81export type AgentRunTicket = { runId: string; token: string };
82
83export type OpenRunInput = {
84 actor: User;
85 repo: RepoPath;
86 number?: number | null;
87 pullId?: string | null;
88 title?: string | null;
89 kind: RunKind;
90 agent?: string | null;
91 model?: string | null;
92 sandbox: string;
93 startedBy?: string | null;
94};
95
96export type RunFilter = {
97 repo?: RepoPath;
98 workspace?: string;
99 active?: boolean;
100 kind?: RunKind;
101 status?: AgentRunStatus;
102 number?: number;
103 limit?: number;
104};
105
106export type SessionSummary = {
107 number: number;
108 title: string;
109 status: PullStatus;
110 agent: string;
111 entries: number;
112 tools: number;
113 prompt: string | null;
114 kinds: RunKind[];
115 runs: number;
116 costUsd: number | null;
117 active: boolean;
118 startedAt: string;
119 lastAt: string;
120};
121
122export type SessionFilter = { kind?: RunKind; outcome?: PullStatus; number?: number };
123
124export type SessionView = {
125 pull: Pull;
126 entries: SessionEntry[];
127 runs: AgentRun[];
128 costUsd: number | null;
129};
130
131export type MemoryScope = "project" | "workspace";
132export type MemoryKind = "fact" | "convention" | "decision" | "gotcha";
133export const MEMORY_KINDS: MemoryKind[] = ["fact", "convention", "decision", "gotcha"];
134
135export type MemorySource = {
136 /** `person`, `agent` or `run`. */
137 kind: string;
138 runId: string | null;
139 repo: RepoPath | null;
140 number: number | null;
141};
142
143export type Memory = {
144 id: string;
145 scope: MemoryScope;
146 workspace: string;
147 repo: RepoPath | null;
148 text: string;
149 kind: MemoryKind;
150 source: MemorySource;
151 createdBy: string;
152 pinned: boolean;
153 createdAt: string;
154 updatedAt: string;
155 lastUsedAt: string | null;
156};
157
158export type Memories = { project: Memory[]; workspace: Memory[] };
159
160export type NewMemory = {
161 scope: MemoryScope;
162 repo?: RepoPath | null;
163 text: string;
164 kind?: MemoryKind;
165 pinned?: boolean;
166};
167
168export type MemoryChange = { text?: string; kind?: MemoryKind; pinned?: boolean };
169
170export interface AgentsApi {
171 /** For the runner: records a sandbox it is starting. */
172 openRun(input: OpenRunInput): Promise<Result<AgentRunTicket>>;
173 /** For the runner: ends a run when its sandbox stops. Refused once it has ended. */
174 closeRun(runId: string, token: string, outcome: "succeeded" | "failed", error?: string): Promise<Result<AgentRunStatus>>;
175 /** Marks a run stopped and says where its sandbox is. Members only. */
176 stopRun(actor: User, repo: RepoPath, id: string): Promise<Result<{ run: AgentRun; sandbox: string }>>;
177 listRuns(viewer: Viewer, filter: RunFilter): Promise<Result<AgentRun[]>>;
178 getRun(viewer: Viewer, repo: RepoPath, id: string): Promise<Result<AgentRun>>;
179 listSessions(viewer: Viewer, repo: RepoPath, filter?: SessionFilter): Promise<Result<SessionSummary[]>>;
180 getSession(viewer: Viewer, repo: RepoPath, number: number): Promise<Result<SessionView>>;
181 listMemories(viewer: Viewer, workspace: string, repo?: RepoPath | null): Promise<Result<Memories>>;
182 addMemory(actor: User, workspace: string, memory: NewMemory): Promise<Result<Memory>>;
183 updateMemory(actor: User, workspace: string, id: string, change: MemoryChange): Promise<Result<Memory>>;
184 deleteMemory(actor: User, workspace: string, id: string): Promise<Result<boolean>>;
185 /** For the runner: what to tell an agent starting in `repo`, marked used. */
186 memoryContext(repo: RepoPath, budget?: number): Promise<{ text: string | null; count: number }>;
187}
188
189/** The agents and memory methods of the work service. */
190export function agentsClient(service: ServiceBinding): AgentsApi {
191 const call = async <T>(method: string, args: object): Promise<T> => {
192 const response = await service.fetch(`https://service/rpc/${method}`, {
193 method: "POST",
194 headers: { "content-type": "application/json" },
195 body: JSON.stringify(args),
196 });
197 if (!response.ok) throw new Error(`${method} failed with status ${response.status}`);
198 return (await response.json()) as T;
199 };
200 return {
201 openRun: (input) => call("open_run", input),
202 closeRun: (runId, token, outcome, error) => call("report_run", { runId, token, outcome, error }),
203 stopRun: (actor, repo, id) => call("stop_run", { actor, repo, id }),
204 listRuns: (viewer, filter) => call("list_runs", { viewer, ...filter }),
205 getRun: (viewer, repo, id) => call("get_run", { viewer, repo, id }),
206 listSessions: (viewer, repo, filter = {}) => call("list_sessions", { viewer, repo, ...filter }),
207 getSession: (viewer, repo, number) => call("get_session", { viewer, repo, number }),
208 listMemories: (viewer, workspace, repo) => call("list_memories", { viewer, workspace, repo: repo ?? null }),
209 addMemory: (actor, workspace, memory) =>
210 call("add_memory", { actor, workspace, repo: memory.repo ?? null, scope: memory.scope, text: memory.text, kind: memory.kind ?? "fact", pinned: memory.pinned ?? false }),
211 updateMemory: (actor, workspace, id, change) => call("update_memory", { actor, workspace, id, ...change }),
212 deleteMemory: (actor, workspace, id) => call("delete_memory", { actor, workspace, id }),
213 memoryContext: (repo, budget) => call("memory_context", { repo, budget }),
214 };
215}