Skip to content
Sign in

flagon-io/g1t

public
0

g1t/packages/contracts/src/events.ts

392 lines16,557 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 attempts1/**
2 * Every state change in g1t is published as an event. Services react to
3 * each other through events rather than direct calls, and the same stream
Sidebar: the panels really slide4 * feeds timelines, webhooks and workflows.
Initial g1t: services, event bus, intents and attempts5 *
6 * The envelope follows CloudEvents: `type` says what happened, `subject`
7 * says to what, `data` is the type-specific payload.
8 */
Agents as a team: lifecycle, merge queue, billing and a new shell9
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look10import type { RepoRole } from "./access";
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar11import type { TeamRole, TeamVisibility } from "./teams";
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step12import type { Confidence, Verdict } from "./work";
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look13
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member14/** What every `package.*` event names. */
15export type PackageEventData = {
16 packageId: string;
17 workspace: string;
18 ecosystem: string;
19 name: string;
20 repoId: string | null;
21};
22
Events: review requests, assignments, stops and deployments are published23/** What `deployment.succeeded` and `deployment.failed` carry. */
24export type DeploymentEventData = {
25 deploymentId: string;
26 projectId: string;
27 repoId: string;
28 workspace: string;
29 project: string;
30 kind: "production" | "preview";
31 branch: string | null;
32 number: number | null;
33 commit: string;
34 path: string;
35 error: string | null;
36 recovered: boolean;
37 /** A username, or `g1t`. */
38 triggeredBy: string;
39};
40
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look41/** The payload of the `repo.collaborator_*` events. */
42export type RepoCollaboratorData = {
43 repoId: string;
44 namespace: string;
45 name: string;
46 username: string;
47 role: RepoRole | null;
48 previousRole: RepoRole | null;
49};
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar50/** A team asked to review a pull request. */
51export type TeamRequested = { team: string; notified: string[]; assigned: string[] };
52
53/** The payload of the `team.*` events; each sets the fields that apply. */
54export type TeamChangedData = {
55 workspace: string;
56 teamId: string;
57 team: string;
58 name: string;
59 visibility: TeamVisibility | null;
60 parent?: string;
61 changes?: string[];
62 username?: string;
63 role?: TeamRole;
64 previousRole?: TeamRole;
65 repoId?: string;
66 repo?: string;
67 repoRole?: RepoRole;
68 previousRepoRole?: RepoRole;
69};
70
Initial g1t: services, event bus, intents and attempts71export type EventPayloads = {
72 "repo.created": { repoId: string; namespace: string; name: string; isPrivate: boolean };
Issues and pull requests replace intents and attempts73 "repo.forked": { repoId: string; sourceRepoId: string; pullId: string };
Events service in Rust, with RFC 3339 times and accurate push events74 /**
Search across all of g1t, Explore, and a command palette75 * A repository's description, topics or visibility changed.
76 * `visibilityChanged` says whether it went public or private, which
77 * `repo.visibility_changed` also announces on its own.
78 */
79 "repo.updated": { repoId: string; namespace: string; name: string; isPrivate: boolean; visibilityChanged: boolean };
80 "repo.visibility_changed": { repoId: string; isPrivate: boolean };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look81 /**
82 * A repository's name changed within its workspace `namespace`, from
83 * `from` to `to`, keeping its id. A path change like `repo.transferred`:
84 * services move rows kept under its path to its *current* path (see
85 * `repoMove`, `currentMovedPath`).
86 */
87 "repo.renamed": { repoId: string; namespace: string; from: string; to: string };
88 /**
89 * A repository was deleted. It is hidden and git refuses it, but it can
90 * be restored until `purgeAfter`: services stop what runs for it and hide
91 * it, and keep their rows until `repo.purged`.
92 */
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member93 "repo.deleted": {
94 repoId: string;
95 namespace: string;
96 name: string;
97 isPrivate: boolean;
98 purgeAfter: string;
99 /** It went with its workspace (`workspace.deleting`); deployments leaves it to that. */
100 withWorkspace?: boolean;
101 };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look102 /** A deleted repository is back, as it was. Services start again what they stopped. */
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member103 "repo.restored": {
104 repoId: string;
105 namespace: string;
106 name: string;
107 isPrivate: boolean;
108 /** It came back with its workspace (`workspace.restored`). */
109 withWorkspace?: boolean;
110 };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look111 /**
112 * A deleted repository is gone for good, its git data with it. Services
113 * drop every row they keep for it, except a workspace's history (ledgers,
114 * invoices, the audit log).
115 */
116 "repo.purged": { repoId: string; namespace: string; name: string };
117 /**
118 * A repository was archived (read-only: pushes, merges, agents and
119 * workflows refused; issues and pull requests locked; deployments keep
120 * serving), or unarchived.
121 */
122 "repo.archived": { repoId: string; namespace: string; name: string; archived: true };
123 "repo.unarchived": { repoId: string; namespace: string; name: string; archived: false };
124 /** The default branch is now `to`; `renamed` when `from` was renamed to it. */
125 "repo.default_branch_changed": { repoId: string; from: string; to: string; renamed: boolean };
126 /** A branch was renamed. Pull requests from it follow. */
127 "branch.renamed": { repoId: string; from: string; to: string; defaultBranch: boolean };
Search across all of g1t, Explore, and a command palette128 /** An account was made, or changed what its profile shows. Ask identity for the profile. */
129 "user.updated": { username: string };
130 /** A workspace was made, or its name, description or icon changed. */
131 "workspace.updated": { workspaceId: string; slug: string };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look132 /** Someone, or g1t staff, made an invite. Never the code or the address. */
133 "invite.created": { inviteId: string; inviterId: string | null; workspaceId: string | null; bound: boolean };
134 /** An invite was used: by a new account, or by an account joining a workspace. */
135 "invite.redeemed": {
136 inviteId: string;
137 userId: string;
138 inviterId: string | null;
139 workspaceId: string | null;
140 createdAccount: boolean;
141 };
142 /** Someone asked for access while registration is invite-only. The address is not in the event. */
143 "waitlist.requested": { entryId: string };
Search across all of g1t, Explore, and a command palette144 /**
Events service in Rust, with RFC 3339 times and accurate push events145 * One branch moved by a push. `ref` is the full ref, `after` the commit it
146 * points to now, and `defaultBranch` whether it is the default branch.
147 */
Mission control counts people's direct pushes to the default branch148 /** `before` is where the ref pointed before; absent for a new branch or tag. */
149 "git.push": { repoId: string; ref: string; before?: string; after: string; defaultBranch: boolean };
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights150 /**
151 * `author` is who opened it: g1t, for one its agent filed while at work,
152 * with `requestedBy` the person it was working for. Every issue and pull
153 * request event carries both.
154 */
155 "issue.opened": {
156 issueId: string;
157 repoId: string;
158 number: number;
159 title: string;
160 author?: { id: string; username: string };
161 requestedBy?: { id: string; username: string };
162 };
Issues and pull requests replace intents and attempts163 "issue.updated": { issueId: string; repoId: string; number: number };
Events: review requests, assignments, stops and deployments are published164 /** The people an issue is assigned to changed; `assignees` is the new set, `added` those newly assigned. */
165 "issue.assigned": { issueId: string; repoId: string; number: number; assignees: string[]; added?: string[] };
Issues and pull requests replace intents and attempts166 /** `resolvedBy` is the number of the pull request whose merge closed it. */
167 "issue.closed": {
168 issueId: string;
169 repoId: string;
170 number: number;
171 reason: "completed" | "not_planned";
172 resolvedBy?: number;
173 };
174 "issue.reopened": { issueId: string; repoId: string; number: number };
g1t is the stored author of what it opens; the person who asked is requested_by and keeps the author's rights175 /**
176 * `issue` is the number of the issue the pull request is for. `author` is
177 * who opened it: g1t, for a change g1t made, with `requestedBy` the person
178 * who asked for it.
179 */
180 "pull.opened": {
181 pullId: string;
182 repoId: string;
183 number: number;
184 issue?: number;
185 agent: string;
186 author?: { id: string; username: string };
187 requestedBy?: { id: string; username: string };
188 };
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step189 /** `confidence`, on a g1t agent's change once g1t has worked it out, is on every pull request event. */
190 "pull.ready": { pullId: string; repoId: string; number: number; issue?: number; confidence?: Confidence };
Acceptance checks in sandboxes, line comments and review verdicts191 /** A push moved the head of a pull request that is ready for review. */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step192 "pull.updated": { pullId: string; repoId: string; number: number; issue?: number; commit: string; confidence?: Confidence };
Agents as a team: lifecycle, merge queue, billing and a new shell193 /** A merge was asked for while the pull request was behind; it has to catch up first. */
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step194 "pull.merge_requested": { pullId: string; repoId: string; number: number; issue?: number; confidence?: Confidence };
195 "pull.closed": { pullId: string; repoId: string; number: number; issue?: number; confidence?: Confidence };
Events: review requests, assignments, stops and deployments are published196 /** People were assigned to a pull request: `assignees` is the new set, `added` those newly assigned. */
197 "pull.assigned": { pullId: string; repoId: string; number: number; issue?: number; assignees: string[]; added: string[] };
198 /** Reviewers were asked for a pull request (`reviewers`), or no longer are. */
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar199 "pull.review_requested": {
200 pullId: string;
201 repoId: string;
202 number: number;
203 issue?: number;
204 reviewers?: string[];
205 /** Teams asked: `team` is `workspace/slug`, `notified` who is told, `assigned` who review assignment picked. */
206 teams?: TeamRequested[];
207 /** Asked because they own files it changes (its CODEOWNERS file). */
208 codeOwners?: boolean;
209 };
210 "pull.review_request_removed": {
211 pullId: string;
212 repoId: string;
213 number: number;
214 issue?: number;
215 reviewers?: string[];
216 teams?: TeamRequested[];
217 };
Events: review requests, assignments, stops and deployments are published218 /** g1t stopped seeing a pull request through until a person steps in; `detail` says why. */
219 "pull.stalled": { pullId: string; repoId: string; number: number; issue?: number; detail: string };
220 /** A pull request g1t had stopped on is going again. */
221 "pull.resumed": { pullId: string; repoId: string; number: number; issue?: number };
Agents and memory, checks and conflicts, profiles, slug renames, custom domains222 /**
223 * The pull request's head or its target moved and the files both changed
224 * overlap: a sandbox should find out whether it still merges cleanly.
225 * `commit` is its head.
226 */
227 "pull.mergecheck": { pullId: string; repoId: string; number: number; issue?: number; commit: string };
228 /** Whether the pull request merges cleanly was settled. */
229 "pull.mergeability": { pullId: string; repoId: string; number: number; issue?: number };
Agents asked while not at work are woken to answer230 /** Another agent asked the agent on a pull request, which was not at work, a question or handed it work. */
231 "agent.asked": { pullId: string; repoId: string; number: number; issue?: number };
Thirteen MCP tools and classic token scopes; agents rate their confidence and can be put on an issue in one step232 "pull.merged": { pullId: string; repoId: string; number: number; issue?: number; commit: string; confidence?: Confidence };
Acceptance checks in sandboxes, line comments and review verdicts233 /** A run of the acceptance checks finished. `commit` is what was checked. */
234 "checks.completed": {
235 pullId: string;
236 repoId: string;
237 number: number;
238 status: "passed" | "failed" | "errored";
239 commit: string;
240 };
Agents as a team: lifecycle, merge queue, billing and a new shell241 /** A g1t agent finished reviewing a pull request; no verdict if it could not. */
242 "review.completed": {
243 pullId: string;
244 repoId: string;
245 number: number;
246 verdict?: "approve" | "request_changes";
247 };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look248 /** A person was given a role on one repository directly, had it changed, or lost it. `role` is null once removed. */
249 "repo.collaborator_added": RepoCollaboratorData;
250 "repo.collaborator_removed": RepoCollaboratorData;
251 "repo.collaborator_role_changed": RepoCollaboratorData;
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar252 /** A team of a workspace was created, changed (`changes` says what) or deleted. */
253 "team.created": TeamChangedData;
254 "team.edited": TeamChangedData;
255 "team.deleted": TeamChangedData;
256 /** Someone joined a team, had their role in it changed, or left it. */
257 "team.member_added": TeamChangedData;
258 "team.member_role_changed": TeamChangedData;
259 "team.member_removed": TeamChangedData;
260 /** A team was given a role on a repository, had it changed, or lost it. */
261 "team.repo_added": TeamChangedData;
262 "team.repo_role_changed": TeamChangedData;
263 "team.repo_removed": TeamChangedData;
Agents as a team: lifecycle, merge queue, billing and a new shell264 /** A repository's merge queue gained, lost or settled an entry. */
265 "queue.changed": { repoId: string };
What happened across an outcome, as a feed beside its graph266 /** `number` is the issue or pull request commented on. */
Agents as a team: lifecycle, merge queue, billing and a new shell267 "comment.created": {
268 commentId: string;
269 repoId: string;
270 number: number;
271 /** Set when the comment is on a pull request. */
272 pullId?: string;
273 /** Set when the comment is a review. */
274 verdict?: Verdict;
275 };
Issues and pull requests replace intents and attempts276 "session.appended": { pullId: string; repoId: string; number: number; count: number };
Agents and memory, checks and conflicts, profiles, slug renames, custom domains277 /**
Events: review requests, assignments, stops and deployments are published278 * A build of a project finished, for production or one pull request's
279 * preview (`number`). `path` is the deployment's page on the site;
280 * `recovered`, on a success, says the build before it failed.
281 */
282 "deployment.succeeded": DeploymentEventData;
283 "deployment.failed": DeploymentEventData;
284 /**
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member285 * A package version was published, such as an image pushed by
286 * `docker push`. `tags` are the tags that now point to it; `repoId` (and
287 * the event's) is the repository the package is linked to, if any.
288 */
289 "package.published": PackageEventData & { version: string; digest: string; size: number; tags: string[] };
290 /** One version of a package was deleted, with the tags that pointed to it. */
291 "package.version_deleted": PackageEventData & { version: string; digest: string };
292 /** A package was deleted with every version it had. */
293 "package.deleted": PackageEventData;
294 /** A package became public or private. */
295 "package.visibility_changed": PackageEventData & { visibility: "public" | "private" };
296 /**
Agents and memory, checks and conflicts, profiles, slug renames, custom domains297 * A workspace's slug changed from `from` to `to`. Services that store a
298 * slug move their rows to the workspace's *current* slug (see
299 * `currentWorkspaceSlug`), so a repeated or late delivery after a second
300 * rename still lands in the right place.
301 */
302 "workspace.renamed": { workspaceId: string; from: string; to: string };
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API303 /**
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look304 * A repository moved from workspace `from` to `to`, keeping its id and
305 * name. Services that store its path or its workspace's slug move those
306 * rows to its *current* path (ask repos `path_by_id`), so a repeated or
307 * late delivery after a second transfer still lands in the right place.
308 */
309 "repo.transferred": { repoId: string; name: string; from: string; to: string };
310 /**
311 * A workspace is gone. Services drop what they keep for it alone; ledgers,
312 * invoices and the audit log stay under its slug, which is never reused.
313 */
314 "workspace.deleted": { workspaceId: string; slug: string };
315 /**
Packages, with a container registry on g1t.sh; workspaces deleted whole and kept 30 days; Members for every member316 * An owner deleted a workspace; staff can restore it until `purgeAfter`,
317 * and nobody can reach it meanwhile. Services hide what they keep for it
318 * and stop what runs for it, keeping their rows: repos deletes its
319 * repositories softly (`repo.deleted` with `withWorkspace`), deployments
320 * pauses its apps, search drops it. `workspace.restored` undoes exactly
321 * that; `workspace.deleted` follows once `purgeAfter` passes. `by` is the
322 * owner's username.
323 */
324 "workspace.deleting": { workspaceId: string; slug: string; by: string; purgeAfter: string };
325 /**
326 * Staff brought a deleted workspace back with its members and tokens.
327 * Services undo what they did on `workspace.deleting`, and only that.
328 */
329 "workspace.restored": { workspaceId: string; slug: string };
330 /**
Agents get guardrails, run credentials, an audit log, a context hub, repository instructions and mentions; security upkeep; snake_case API331 * A memory was added, changed, reviewed or forgotten. No text: ask the
332 * work service for it by id. `repoId` is the project's, or null for the
333 * workspace's memory. `status` is `deleted` once forgotten.
334 */
335 "memory.changed": { memoryId: string; workspace: string; status: "candidate" | "kept" | "dismissed" | "deleted" };
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look336 /**
337 * A sandbox was stopped because it looked like it was mining: CPU pinned
338 * with little I/O and no progress, or a miner seen by name. For g1t's
339 * staff, in sudo; published with no `repoId` so it never reaches a
340 * repository's timeline or webhooks. `metrics` is what the sandbox
341 * measured (`Verdict` in crates/runner abuse.rs), or null if it could
342 * not say.
343 */
344 "abuse.flagged": {
345 workspace: string;
346 repo: string | null;
347 /** The agent run, when the sandbox had one. */
348 run: string | null;
349 /** What the sandbox was for: agent, checks, queue, actions, deploy... */
350 kind: string;
351 sandbox: string;
352 metrics: Record<string, unknown> | null;
353 };
Initial g1t: services, event bus, intents and attempts354};
355
356export type EventType = keyof EventPayloads;
357
358export type G1tEvent<T extends EventType = EventType> = {
359 [K in T]: {
360 id: string;
361 type: K;
362 /** The service that published it. */
363 source: string;
Events service in Rust, with RFC 3339 times and accurate push events364 /** RFC 3339. */
365 time: string;
Initial g1t: services, event bus, intents and attempts366 /** The repo the event concerns, used to scope timelines and deliveries. */
367 repoId: string | null;
368 /** The user or agent that caused it, if any. */
369 actor: string | null;
370 data: EventPayloads[K];
371 };
372}[T];
373
374/** What a publisher supplies; the bus fills in `id` and `time`. */
375export type NewEvent<T extends EventType = EventType> = {
376 [K in T]: Omit<G1tEvent<K>, "id" | "time">;
377}[T];
378
379export type EventQuery = {
380 repoId?: string;
381 types?: EventType[];
382 /** Return events older than this event id. */
383 before?: string;
384 limit?: number;
385};
386
387/** The event bus and its durable log. */
388export interface EventsApi {
389 publish(events: NewEvent[]): Promise<void>;
390 /** Newest first. */
391 list(query: EventQuery): Promise<G1tEvent[]>;
392}