Skip to content
Sign up

flagon-io/g1t

public
00

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

g1t.sh
gitagentscloudflarerustforgemcp
1,012 linesCodeBlameRaw

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.

Chat has sounds. A short warm cue plays for a message in a conversation you have open but aren't looking at, a direct message, a mention of you and an agent finishing something for you, with a soft tick for sending that is off until you turn it on; never for your own messages, a muted conversation, a conversation you are looking at in a window that has the front, or while you have paused notifications, and never twice for one message or more than once in a second and a half. The cues are made by the browser itself in two sets, Soft and Bright, so nothing is downloaded; the Sounds and notifications section of your notification settings turns them on and off, picks the set and the volume, plays each one, and offers desktop notifications for when the window is behind; Do not disturb is the one pause everyone sees, set from the chat sidebar's bell, the settings, or your avatar menu, now with a two-hour choice, and the top bar's bell shows a dot while it's on. Your choices are kept with your account. The sound layer sits behind one small interface so the desktop app can play them natively later. The chat and notifications guides say the rules.1import type { SoundSettings, SoundSettingsChange } from "./sounds";
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged2import type { AccessClient, BasePermission, RepoGrant } from "./access";
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers3import type { Permissions, ScopeLevel, ScopeResource } from "./scopes";
Merge main (membership, two-factor, GitHub repo roles) into tokens4import type { MemberPrivileges, OrgRole, PolicyHold } from "./members";
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged5import type { Acting, CreateRunCredentialInput, RunBinding } from "./audit";
6import type { RepoPath } from "./repos";
7import type { Result } from "./result";
Merge branch 'worktree-agent-ad7c6d88d93adc817'8import type { TeamCreation, TeamsClient } from "./teams";
People and teams are front and centre: one directory of people and agents with presence, local time, titles, teams and what each owns; profiles with manager and reports and the agents they work with; an org chart with each team's agents beside the person who leads it; and teams of any mix, with a lead, a channel, a budget agents keep to and the agents on them. Every agent is told its teams each turn (who leads, who owns what, who's around and who to page), and the team page shows exactly what. Member management is Members and invites; the people and teams guide says how.9import type { PeopleClient } from "./people";
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca10import type { DeployKeysClient } from "./deploy-keys";
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)11import type { EmailConfirmed } from "./accounts";
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged12
13export type User = {
14 id: string;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers15 /** Lowercased: what the person is found, linked and mentioned by. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged16 username: string;
17 /**
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers18 * The username as its owner wrote it (`Ana`), when that differs from
19 * `username`: what pages show (`shownUsername`). Set on the signed-in
20 * person and on people looked up by name.
21 */
22 display_username?: string;
23 /**
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged24 * `workspace` when a workspace is acting through one of its own access
25 * tokens: `id` is then the workspace's and `username` its slug. `system`
26 * is g1t itself doing platform work, such as a security update
27 * (`username` `g1t`). Absent means `user`.
28 */
29 kind?: "user" | "workspace" | "agent" | "system";
30 /**
31 * Whether the account's email address is confirmed. Only set on users
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)32 * resolved from credentials. An account that has not confirmed it can
33 * only confirm it: see `awaitsConfirmation`.
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged34 */
35 verified?: boolean;
36 /**
37 * The workspaces this user belongs to. Set on users resolved from
38 * credentials, so any service can authorize from it.
39 */
40 workspaces?: Membership[];
41 /**
42 * The person's uploaded avatar: the SHA-256 of its bytes, served at
43 * `/avatars/<avatar>`. Only set on the signed-in person; absent means
44 * the generated letter avatar.
45 */
46 avatar?: string;
47 /**
The contracts no longer describe g1t's own agents, and workspaces can keep their AI providers. Every consumer had already stopped using them, so the TypeScript and Rust contracts drop the workspace-agent, ability, look, skill-library, context, runner-agent and mention modules, the chat and docs RPCs agents posted and read through, the folio agent methods, the agent_waiting notification, agent.asked and memory.changed events, AI credit, token and gateway billing types, model routes and sessions, team agents, agent tokens, plan, review, message and confidence types, command rules, cost caps and confidence rules. The agents:run and models:* scopes are no longer offered by any preset, OAuth default or permission form, but a stored token or grant that names them still reads; and the removed operations are gone from the scope table, so the API's check that every operation has exactly one scope is strict again. What stored data needs in order to parse (old run and credential kinds, an agent team lead, retired rules and webhook events, old guardrail and integration settings) still parses, and a run's token is still PrincipalKind::Agent, which now means a run's token and the @g1t rows written before. The customize, marketplace, skills and claude-plugin contracts stay only until the mobile app drops its Customize screens.48 * Set on a run credential resolved from its token: who it acts for,
49 * with which credential, and what it may do. Older rows written by
50 * g1t's retired hosted agents carry it too ("g1t on behalf of syntaqx").
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged51 */
52 acting?: Acting;
53 /**
54 * The repositories this user has a role on directly, whether or not they
55 * belong to its workspace. Set with `workspaces`; see `access.ts`.
56 */
57 grants?: RepoGrant[];
58 /**
59 * Set on a user resolved from an access token: its scopes (null for full
60 * access) and the workspaces or repositories it reaches. See scopes.ts.
61 */
62 token?: {
63 token_id: string;
64 scopes?: string[] | null;
65 legacy?: boolean;
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens66 /** The token's name, as its owner gave it. */
67 name?: string;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers68 /**
69 * A token narrowed to one workspace (or none): its workspace and
70 * repositories. The key is kept from before tokens were one kind.
71 */
TS access mirrors the workspace token cap and fine-grained reach72 fine_grained?: {
73 workspace?: string | null;
74 repositories?: "all" | "selected" | "public";
75 repo_ids?: string[];
76 };
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers77 /** A workspace's own token with Repositories: admin. */
TS access mirrors the workspace token cap and fine-grained reach78 admin?: boolean;
79 /** Set on what a deploy key resolves to. */
80 deploy_key?: string;
81 /** The one repository a job's token or a deploy key reaches. */
82 repo?: string;
Merge Actions: cross-repo workflows and actions, release and deployment triggers, step timeouts83 /** Set on a workflow job's token (`G1T_TOKEN`): the run and job it was made for. */
84 job?: { run_id: string; job_id: string; pull_requests?: boolean };
Merge main into Artifacts Phase 285 /**
86 * A person's token whose owner let it use the website as them, sent as
87 * `Authorization: Bearer` (apps/web, lib/website-token.ts). Not a scope.
88 */
89 website?: boolean;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged90 };
Merge main (membership, two-factor, GitHub repo roles) into tokens91 /**
92 * Workspaces the person belongs to but cannot use until they meet its
93 * policy, such as turning on two-factor authentication. Left out of
94 * `workspaces` and `grants` meanwhile.
95 */
96 held?: PolicyHold[];
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged97};
98
99/** What a member may do: an owner also manages the workspace's members. */
100export type Role = "owner" | "member";
101
102export type Membership = {
103 /** The workspace's name in URLs: `g1t.sh/<slug>`. */
104 slug: string;
105 role: Role;
106 /** Its display name. Set on users resolved from credentials. */
107 name?: string;
108 /** Its uploaded icon, as `Workspace.avatar`. */
109 avatar?: string;
110 /** The workspace's base permission: what members get on every repository. Absent means `write`. */
111 base_permission?: BasePermission;
Merge branch 'worktree-agent-ad7c6d88d93adc817'112 /** Who may create its teams. Absent means any member. */
113 team_creation?: TeamCreation;
Merge main (membership, two-factor, GitHub repo roles) into tokens114 /** The roles held besides owner or member. */
115 org_roles?: OrgRole[];
116 /** What the workspace lets its members do. Absent means the defaults. */
117 privileges?: MemberPrivileges;
Chat and workspace agents: channels, DMs and named agents you talk to118 /**
119 * Whether this member uses Code: repositories, issues, pull requests,
120 * checks, deploys. False for people who only use Chat, Docs and agents
121 * (support, sales, finance): they see no repository, whatever the base
122 * permission, and agents treat them as unable to change code. Absent
123 * means true.
124 */
125 code_access?: boolean;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged126};
127
Chat and workspace agents: channels, DMs and named agents you talk to128/** Whether a member uses Code. See `Membership.code_access`. */
129export function hasCodeAccess(membership: Pick<Membership, "code_access"> | null | undefined): boolean {
130 return membership?.code_access !== false;
131}
132
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged133/** How long an old workspace slug redirects, and stays reserved for it, after a rename. */
134export const SLUG_HOLD_DAYS = 90;
135
136/** How long a workspace must wait between renames. */
137export const RENAME_COOLDOWN_HOURS = 24;
138
139/** The largest avatar that can be uploaded, in bytes. */
140export const MAX_AVATAR_BYTES = 1024 * 1024;
141
142/**
Merge branch 'worktree-agent-a2013627e5ea4ab13'143 * Where a workspace keeps its repositories' git data: anywhere g1t stores
144 * it (the default), or in the EU only. It applies to repositories made
145 * after it is set.
146 */
147export type DataResidency = "anywhere" | "eu";
148
149/**
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged150 * A workspace: the owner of repositories, and the first segment of their
151 * URLs. A person's own space and a team's are the same thing.
152 */
153export type Workspace = {
154 id: string;
155 slug: string;
156 name: string;
157 /** One line saying what the workspace is for. */
158 description: string | null;
159 /** RFC 3339. */
160 createdAt: string;
161 memberCount: number;
162 /**
163 * The workspace's uploaded icon: the SHA-256 of its bytes, served at
164 * `/avatars/<avatar>`. Null means the generated letter avatar.
165 */
166 avatar: string | null;
167 /** What every member gets on each repository; owners have Admin. */
168 basePermission?: BasePermission;
Merge branch 'worktree-agent-ad7c6d88d93adc817'169 /** Who may create its teams. Absent means any member. */
170 teamCreation?: TeamCreation;
Merge main (membership, two-factor, GitHub repo roles) into tokens171 /** Whether members and outside collaborators need two-factor authentication. */
172 twoFactorRequirementEnabled?: boolean;
173} & Partial<MemberPrivileges>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged174
175export type Member = {
176 username: string;
Cards you act on in chat; agents comment and review as themselves; names shown cleanly; commits on the calendar177 /** The username as its owner wrote it (`Ana`), when that differs from `username`. */
178 display_username?: string;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged179 role: Role;
Merge main (membership, two-factor, GitHub repo roles) into tokens180 /** The roles they hold besides `role`. */
181 org_roles?: OrgRole[];
182 /** Whether two-factor authentication is on; owners only, null for anyone else. */
183 two_factor?: boolean | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged184 /** Their display name, when they set one. */
185 name?: string | null;
186 /** Their uploaded avatar's hash, served at `/avatars/<avatar>`; null for the generated letter avatar. */
187 avatar?: string | null;
188};
189
190/** An owner of a workspace, as staff see them. */
191export type AdminOwner = { username: string; email: string | null };
192
193/** A workspace as staff see it. Mirrors `AdminWorkspace` in `crates/contracts/src/identity.rs`. */
194export type AdminWorkspace = {
195 slug: string;
196 name: string;
197 /** RFC 3339. */
198 createdAt: string;
199 owners: AdminOwner[];
200 memberCount: number;
201};
202
203/** A member of a workspace, as staff see them. */
204export type AdminMember = { username: string; email: string | null; role: Role; /** RFC 3339. */ joined: string };
205
206export type AdminWorkspaceDetail = {
207 slug: string;
208 name: string;
209 description: string | null;
210 /** RFC 3339. */
211 createdAt: string;
212 /** Owners first, then by username. */
213 members: AdminMember[];
214 /** It can never be deleted, by anyone (identity's `PROTECTED_WORKSPACES`). */
215 protected: boolean;
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.216 /** Set while staff have it suspended. */
217 suspended?: Suspension | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged218};
219
220/** The most workspaces one `workspaces` call returns. */
221export const ADMIN_WORKSPACES_LIMIT = 500;
222
223/** How long an invite works, unless identity's `INVITE_TTL_DAYS` says otherwise. */
224export const INVITE_TTL_DAYS = 30;
Workspace is the workspace's settings, in one place. Its sidebar is grouped, General, Access, Money, Compute, Code, Agents, Chat, Artifacts, Security and Integrations, every page one click away with no settings inside settings, the groups folding and the owner-only pages hidden from members; what is not here yet is marked Soon with a hint. Members is a list with search and filters for role, two-factor and team, and Invite opens a dialog: who, by username, name or email, their role and a note that goes into the invitation; nothing is filled in inline any more. Invitations is its own page with All, Pending, Accepted, Declined, Expired and Revoked filters that say how many, and each row's menu can copy the link, send it again or revoke it; identity learned to send an invitation again and to carry the note. Permissions gathers every rule about who may do what, by part: Code's base permission and member privileges, who creates teams, who creates channels, and, marked Soon with what applies today, forking private repositories, adding agents to conversations, messaging agents directly, creating spaces and default sharing, creating workspace agents and raising budgets, deploying to production and publishing packages. General lost what moved. The permissions guide is new, and the workspaces, people and teams, access, chat, teams, authentication and billing guides say where things are now.225/** The most characters an invitation's note keeps (`invite_member`'s `message`). */
226export const MAX_INVITE_MESSAGE = 500;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged227
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.228/** Only a pending invite can be used or revoked. */
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)229/**
230 * `awaiting_confirmation`: used to make an account that has not confirmed its
231 * email address yet; what it gives is joined when the address is confirmed,
232 * unless it is revoked first.
233 */
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)234/**
235 * `awaiting_answer`: the account it made is confirmed, and the workspace it
236 * names waits for the person to accept or decline. `declined`: they said no.
237 */
238export type InviteStatus =
239 | "pending"
240 | "awaiting_confirmation"
241 | "awaiting_answer"
242 | "redeemed"
243 | "declined"
244 | "expired"
245 | "revoked";
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged246
247/** One invite. Mirrors `Invite` in `crates/contracts/src/identity.rs`. */
248export type Invite = {
249 id: string;
250 /** `g1t-k7m2-…`: returned when it is made, and to its maker while pending. */
251 code: string | null;
252 /** The code's first group, such as `g1t-k7m2`. */
253 hint: string;
254 /** Only this address can use it. */
255 email: string | null;
256 /** `account` makes an account; `workspace` joins an existing one to `workspace`. */
257 kind: "account" | "workspace";
258 /** The workspace using it joins. */
259 workspace: string | null;
260 status: InviteStatus;
261 /** Its maker's username; null when g1t staff made it. */
262 invitedBy: string | null;
263 /** The account that used it. */
264 redeemedBy: string | null;
265 /** RFC 3339. */
266 createdAt: string;
267 /** RFC 3339. */
268 expiresAt: string;
269 redeemedAt: string | null;
270 revokedAt: string | null;
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)271 /** The account a workspace invitation is for, by username: someone invited by username, or the account the invite made. */
272 invitee?: string | null;
273 /** The role `workspace` is joined with; null when it names none. */
274 role?: Role | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged275 /** The staff member who minted it; only in staff views. */
276 staff?: string | null;
277};
278
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)279/**
280 * A workspace invitation waiting for its person's answer, as they see it.
281 * Mirrors `WorkspaceInvitation` in `crates/contracts/src/identity.rs`.
282 */
283export type WorkspaceInvitation = {
284 id: string;
285 workspace: ProfileWorkspace;
286 /** The role accepting joins with. */
287 role: Role;
288 /** Null when g1t staff sent it. */
289 invitedBy: { username: string; name: string | null; avatar: string | null } | null;
290 createdAt: string;
291 expiresAt: string;
292};
293
294/** Someone to invite, as `findPeople` finds them: never an email address. */
295export type PersonMatch = { username: string; name: string | null; avatar: string | null };
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged296
297/** What a valid code is for, before it is used. */
298export type InvitePreview = {
299 kind: "account" | "workspace";
300 /** Pending, unless `anyStatus` asked about a code that is spent. */
301 status: InviteStatus;
302 /** Null when g1t staff sent it. */
303 invitedBy: { username: string; name: string | null; avatar: string | null } | null;
304 workspace: ProfileWorkspace | null;
305 /** The repository it accepts an invitation to, such as `{ name: "flagon-io/g1t", role: "write" }`. */
306 repository: { name: string; role: string } | null;
307 /** Partly hidden, such as `a•••@example.com`. */
308 email: string | null;
309 /** The bound address in full, while the invite is pending: it fills in and locks the sign-up form. */
310 address: string | null;
311 /** Whether the bound address has a g1t account already: sign in to accept. */
312 hasAccount: boolean;
313 /** With a viewer: whether it is theirs (for one of their confirmed addresses, or used by them). */
314 forViewer: boolean | null;
315 expiresAt: string;
Merge invite emails that confirm the address: the emailed link carries a proof only that email has, so signing up from it needs no code; shared links and typed codes still confirm316 /**
317 * Whether the page was opened from this pending invite's own email (its
318 * `proof` checked out): the account made with it starts with `address`
319 * confirmed. False without a proof, with a wrong one, or for an invite
320 * bound to no address.
321 */
322 emailProven: boolean;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged323};
324
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.325/**
326 * The shared invite link an account was made with. Before registration
327 * opened, staff handed groups shared links; none are made or used any more.
328 */
Merge shared invite links: label, uses, expiry, domains; joined through recorded (identity 0038)329export type SharedInviteSource = { id: string; label: string };
330
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.331/** Why and since when staff suspended an account or a workspace. */
332export type Suspension = { reason: string; at: string; by: string };
Merge shared invite links: label, uses, expiry, domains; joined through recorded (identity 0038)333
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.334/** An email domain no new account may sign up with; its subdomains too. */
335export type BlockedDomain = { domain: string; reason: string; blockedBy: string; createdAt: string };
Merge shared invite links: label, uses, expiry, domains; joined through recorded (identity 0038)336
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.337/** The most rows one staff listing of invites returns. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged338export const ADMIN_INVITES_LIMIT = 500;
339
340/**
341 * Staff-only identity, for sudo.g1t.sh. It takes no viewer and checks no
342 * membership: only sudo calls it, over its service binding, once Cloudflare
343 * Access and its staff list have let someone in. Never call it on behalf of
344 * a customer.
345 */
346export interface IdentityAdminApi {
347 /** Every workspace, newest first, at most 500; `query` matches slug, name, or an owner's username or email. */
348 workspaces(query?: string): Promise<AdminWorkspace[]>;
349 /** One workspace with all its members, or null. */
350 workspace(slug: string): Promise<AdminWorkspaceDetail | null>;
351
352 /** Invites, newest first; `query` is a code's start, or part of an email, inviter or redeemer. */
353 invites(query?: string | null): Promise<Invite[]>;
354 revokeInvite(id: string, staff: string): Promise<Result<Invite>>;
355
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.356 /**
357 * Suspends an account (by username): it cannot sign in, and its sessions
358 * and tokens stop at once. `suspend: false` lifts it. A reason is required
359 * to suspend.
360 */
361 suspendUser(username: string, suspend: boolean, reason: string, staff: string): Promise<Result<Suspension | null>>;
362 /** Suspends a workspace (by slug): its own tokens stop. Sudo also holds its compute in billing. */
363 suspendWorkspace(slug: string, suspend: boolean, reason: string, staff: string): Promise<Result<Suspension | null>>;
364 /** Email domains no new account may sign up with. */
365 blockedDomains(): Promise<BlockedDomain[]>;
366 /** Blocks (or with `block: false` unblocks) an email domain; returns the list now. */
367 blockDomain(domain: string, block: boolean, reason: string, staff: string): Promise<Result<BlockedDomain[]>>;
368
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged369 /** Workspaces owners deleted that are not purged yet, newest first. */
370 deletedWorkspaces(): Promise<DeletedWorkspace[]>;
371 /**
372 * Brings a deleted workspace back, with its members, tokens and what went
373 * with it, while it is still restorable. Publishes `workspace.restored`.
374 */
375 restoreWorkspace(workspaceId: string, staff: string): Promise<Result<boolean>>;
376 /**
377 * Purges a deleted workspace now rather than at `purgeAfter`. `confirm` is
378 * its slug, typed out. Refused for a protected workspace. Publishes
379 * `workspace.deleted`.
380 */
381 purgeWorkspace(workspaceId: string, staff: string, confirm: string): Promise<Result<boolean>>;
Merge branch 'worktree-agent-a8385d293d42c913a'382
383 /** Every workspace alias, by name. */
384 aliases(): Promise<WorkspaceAlias[]>;
385 /**
386 * Points `alias` at the workspace whose slug is `workspace`. Refused for
387 * one of the site's routes, anyone's username, a workspace's slug (deleted
388 * or held after a rename) and an existing alias. `note` says why.
389 */
390 setAlias(alias: string, workspace: string, note: string, staff: string): Promise<Result<WorkspaceAlias>>;
391 /** Removes an alias; `reason` goes in sudo's audit log. */
392 removeAlias(alias: string, reason: string, staff: string): Promise<Result<boolean>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged393}
394
Merge branch 'worktree-agent-a8385d293d42c913a'395/**
396 * A name g1t's staff point at a workspace, so its addresses lead there under
397 * the workspace's own name: `g1t`, the product, leads to `flagon-io`, Flagon,
398 * Inc. Staff-managed only; it follows the workspace through renames.
399 */
400export type WorkspaceAlias = {
401 alias: string;
402 workspaceId: string;
403 /** The workspace's slug and name now. */
404 workspace: string;
405 workspaceName: string;
406 /** Why it exists. */
407 note: string;
408 /** The staff member who set it, or `migration`. */
409 createdBy: string;
410 /** RFC 3339. */
411 createdAt: string;
412};
413
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged414/** Who is asking. Every read and write in every service takes one. */
415export type Viewer = User | null;
416
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)417/**
418 * Whether this is a person whose account has not confirmed its email
419 * address. Such an account can only confirm it, change it, or sign out.
420 */
421export function awaitsConfirmation(user: Pick<User, "kind" | "verified"> | null | undefined): boolean {
422 return !!user && (user.kind ?? "user") === "user" && !user.verified;
423}
424
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged425export type SshKey = {
426 id: string;
427 title: string;
428 fingerprint: string;
429 /** RFC 3339. */
430 createdAt: string;
Merge branch 'worktree-agent-a5a5de74d8863d554' into worktree-agent-a16631325aecf58ca431 /** When it last signed in over SSH, RFC 3339, to within 5 minutes; null when it never has. */
432 lastUsedAt: string | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged433};
434
435export type AccessToken = {
436 id: string;
437 name: string;
438 /** RFC 3339. */
439 createdAt: string;
440 /** RFC 3339, to within a few minutes. Null until it is first used. */
441 lastUsedAt: string | null;
442 /**
443 * For a workspace's token, the username of the member who made it. Null
444 * once that account is gone, and on personal tokens.
445 */
446 createdBy: string | null;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers447 /** Its scopes, as `resource:level`, the highest of each resource. Null: full access. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged448 scopes: string[] | null;
449 /** Made before tokens had scopes: full access until someone narrows it. */
450 legacy: boolean;
451 /** RFC 3339. Null: it does not expire. */
452 expiresAt: string | null;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers453 /** Its scopes as permissions: each resource it may use, at the highest level. */
454 permissions?: Permissions;
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules455 /** What it is for, as its owner wrote it. */
456 description?: string | null;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers457 /**
458 * A personal token's reach: the workspace it is made for; null for every
459 * workspace you belong to (or, with `repositorySelection` public, none).
460 * Null on a workspace's own token, which reaches its workspace.
461 */
462 workspace?: string | null;
463 /** Which repositories of that workspace it reaches. */
464 repositorySelection?: RepositorySelection;
465 /** With `selected`: the repositories, as `owner/name`, that you can see. */
466 repositories?: string[];
467 /** Whether a token made for a workspace that approves tokens may be used there yet. */
468 status?: TokenStatus;
469 /** Why an owner denied or revoked it. */
470 reviewReason?: string | null;
471 /** A workspace's own token, acting as the workspace. */
472 workspaceOwned?: boolean;
473 /** A workspace's own token with Repositories: admin, an admin of its repositories. */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules474 admin?: boolean;
Merge main into Artifacts Phase 2475 /** A personal token its owner let use the website as them. */
476 website?: boolean;
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules477};
478
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers479/** Which repositories a token reaches in its workspace: all, the selected ones, or public ones only. */
480export type RepositorySelection = "all" | "selected" | "public";
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules481
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers482/** Whether a token made for a workspace may be used there yet. */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules483export type TokenStatus = "active" | "pending" | "denied" | "revoked";
484
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers485/** A new access token: a person's, or (with `owner`) a workspace's. */
486export type TokenInput = {
487 /** A workspace's slug to make that workspace's token; null for your own. */
488 owner?: string | null;
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules489 name: string;
490 description?: string | null;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers491 /** 1 to 366 days; null for no expiry, where the workspaces it reaches allow that. */
492 ttlSeconds: number | null;
493 /**
494 * A personal token's reach: a workspace's slug, or null for every
495 * workspace you belong to (with `repositorySelection` public: none).
496 */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules497 workspace: string | null;
498 repositorySelection: RepositorySelection;
499 /** With `selected`: `owner/name` or names in the workspace. */
500 repositories: string[];
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers501 /** Each resource's level; left out is no access. */
502 permissions: Partial<Record<ScopeResource, ScopeLevel>>;
Merge main into Artifacts Phase 2503 /** A personal token: whether it may use the website as you. Off unless set. */
504 website?: boolean;
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules505};
506
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers507/** A change to a token; what is left out stays. */
Merge main into Artifacts Phase 2508export type TokenChange = Partial<Pick<TokenInput, "name" | "description" | "repositorySelection" | "repositories" | "permissions" | "website">>;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers509
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules510/** A workspace's rules for personal access tokens. */
511export type TokenPolicy = {
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers512 /** A token made for every workspace of its owner reaches this one. */
513 allowTokensForAllWorkspaces: boolean;
514 /** A token may be made for this workspace alone. */
515 allowTokensForThisWorkspace: boolean;
516 /** A token made for this workspace waits for an owner's approval. */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules517 requireApproval: boolean;
518 /** Null: no limit. */
519 maxLifetimeDays: number | null;
520 forbidNoExpiry: boolean;
521 updatedBy?: string | null;
522 updatedAt?: string | null;
523};
524
525/** A member's personal token that reaches a workspace, as its owners see it. */
526export type MemberToken = {
527 owner: string;
528 token: AccessToken;
529 /** Whether it reaches the workspace now. */
530 reaches: boolean;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers531 /** Why not: pending approval, denied, revoked, tokens for all workspaces not allowed, tokens made for this workspace not allowed, lasts too long, never expires. */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules532 blockedBy?: string | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged533};
534
535/** What a new or changed token may do. */
536export type TokenGrant = {
537 /** Null: full access. */
538 scopes: string[] | null;
539};
540
541export type DeviceStart = {
542 /** Secret held by the tool and exchanged for a token once approved. */
543 deviceCode: string;
544 /** Short code shown to the person, e.g. `WDJB-MJHT`. */
545 userCode: string;
546 /** Seconds until both codes stop working. */
547 expiresIn: number;
548 /** Seconds the tool should wait between polls. */
549 interval: number;
550};
551
552export type DeviceRequest = { userCode: string; clientName: string };
553
554export type DeviceClaim =
555 | { status: "pending" | "denied" | "expired" }
556 | { status: "approved"; token: string; user: User };
557
558/** What the site passes on once a person has approved an application. */
559export type OAuthApproval = {
560 clientId: string;
561 /** Shown wherever the application's access is listed. */
562 clientName: string;
563 redirectUri: string;
564 /** PKCE challenge, method S256. */
565 codeChallenge: string;
566 /** What the person granted. Null: full access. */
567 scopes: string[] | null;
568};
569
570export type OAuthTokens = {
571 accessToken: string;
572 /** Works once; using it returns the next one. */
573 refreshToken: string;
574 /** Seconds until the access token stops working. */
575 expiresIn: number;
576 /** The scopes granted, space-separated, or `*` for full access. */
577 scope?: string | null;
578};
579
580/** An application a person has signed in to. */
581export type OAuthGrant = {
582 id: string;
583 clientName: string;
584 /** RFC 3339. */
585 createdAt: string;
586 /** RFC 3339. */
587 lastUsedAt: string;
588 /** What the person granted. Null: full access. */
589 scopes: string[] | null;
590 /** Signed in before applications had scopes: full access until narrowed. */
591 legacy: boolean;
592};
593
594/** Accounts, credentials and sessions. */
595/**
596 * What deleting a workspace takes with it, and what stands in the way:
597 * nothing does while `billing` is null and it is not `protected`.
598 */
599export type WorkspaceDeletion = {
600 /** Its live repositories, deleted with it. */
601 repositories: number;
602 /** Its projects, hidden with it. */
603 projects: number;
604 members: number;
605 /** Why billing cannot close it yet, in words for its owner. */
606 billing: string | null;
607 /** It can never be deleted, by anyone. */
608 protected: boolean;
609};
610
611/** How long a deleted workspace is kept, for g1t's staff to restore, before it is purged. */
612export const WORKSPACE_RESTORE_DAYS = 30;
613
614/**
615 * Workspaces nobody can delete, whatever identity's `PROTECTED_WORKSPACES`
616 * says: Flagon's, which runs g1t. Services that act on `workspace.deleting`
617 * check it too, so one published for it by mistake changes nothing.
618 */
619export const ALWAYS_PROTECTED_WORKSPACES: readonly string[] = ["flagon-io"];
620
621/** Whether `slug` is one of `ALWAYS_PROTECTED_WORKSPACES`, in any case. */
622export function isProtectedWorkspace(slug: string): boolean {
623 return ALWAYS_PROTECTED_WORKSPACES.includes(slug.trim().toLowerCase());
624}
625
626/** A workspace an owner deleted, kept until `purgeAfter` for staff to restore. */
627export type DeletedWorkspace = {
628 workspaceId: string;
629 slug: string;
630 name: string;
631 /** RFC 3339. */
632 deletedAt: string;
Merge sudo: delete an account with the workspaces it alone owns, purge each633 /** The username of the owner who deleted it, or the staff member who deleted it with the account that alone owned it. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged634 deletedBy: string;
635 /** RFC 3339: when it is purged unless restored first. */
636 purgeAfter: string;
637 /** What went with it, counted when it was deleted. */
638 went: WorkspaceDeletion;
639 /** Whether staff can still restore it. */
640 restorable: boolean;
641};
642
People and teams are front and centre: one directory of people and agents with presence, local time, titles, teams and what each owns; profiles with manager and reports and the agents they work with; an org chart with each team's agents beside the person who leads it; and teams of any mix, with a lead, a channel, a budget agents keep to and the agents on them. Every agent is told its teams each turn (who leads, who owns what, who's around and who to page), and the team page shows exactly what. Member management is Members and invites; the people and teams guide says how.643export interface IdentityApi extends AccessClient, TeamsClient, PeopleClient, DeployKeysClient {
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged644 /**
Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them.645 * Creates an account and signs it in. Anyone may register; at most
646 * five accounts an hour per `client`. `inviteCode` is optional: one from an
647 * invitation sent to `email` applies that invitation once the address is
648 * confirmed, and any other code is ignored.
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged649 */
650 register(
651 username: string,
652 email: string,
653 password: string,
654 inviteCode?: string | null,
655 /** Who is asking, such as the visitor's IP address, for rate limits. */
656 client?: string | null,
Merge invite emails that confirm the address: the emailed link carries a proof only that email has, so signing up from it needs no code; shared links and typed codes still confirm657 /**
658 * The `proof` from the invite email's link. When it is the invite's own
659 * and `email` is the address it was sent to, the account starts with that
660 * address confirmed; otherwise it is ignored.
661 */
662 emailProof?: string | null,
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged663 ): Promise<Result<{ user: User; sessionToken: string }>>;
664 /** Verifies a username and password for website sign-in. */
665 /**
666 * Verifies a username, or any confirmed address of the account, and its
667 * password. Wrong passwords are counted against the account and `client`
668 * (the visitor's IP address); past a limit nothing is checked for a while.
669 */
Merge main (membership, two-factor, GitHub repo roles) into tokens670 signIn(
671 username: string,
672 password: string,
673 client?: string | null,
674 ): Promise<Result<{ user: User; sessionToken: string; twoFactorChallenge?: string | null }>>;
675 /**
676 * The second step of signing in, for an account with two-factor
677 * authentication: the challenge `signIn` returned, and a code from the
678 * app or a recovery code.
679 */
680 twoFactorSignIn(challenge: string, code: string, client?: string | null): Promise<Result<{ user: User; sessionToken: string }>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged681 signOut(sessionToken: string): Promise<void>;
682
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)683 /**
684 * Sends a new confirmation code and link to the primary of an account
685 * that has not confirmed it, at most once a minute.
686 */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged687 resendVerification(user: User): Promise<Result<boolean>>;
Merge email confirmation gate: a code and a link, nothing until confirmed (identity 0036)688 /** Confirms the address the emailed link was sent to, signed in or not; ends the code sent with it. */
689 verifyEmail(token: string): Promise<Result<EmailConfirmed>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged690 /** Emails a reset link if the address has an account. Always resolves. */
691 /**
692 * Any confirmed address of an account works; the link goes to it, and the
693 * primary and backup are told. A few an hour per address and per `client`.
694 */
695 requestPasswordReset(email: string, client?: string | null): Promise<boolean>;
696 /** Sets a new password from an emailed token and ends every session. */
697 resetPassword(token: string, password: string): Promise<Result<User>>;
698
699 /**
700 * Device sign-in (RFC 8628). A tool starts a request, a person approves
701 * its short code in a browser, and the tool claims an access token.
702 */
703 deviceStart(clientName: string): Promise<DeviceStart>;
704 /** What a user code is asking for, or null if it is not valid. */
705 deviceLookup(userCode: string): Promise<DeviceRequest | null>;
706 deviceResolve(userCode: string, user: User, approve: boolean): Promise<Result<boolean>>;
707 deviceClaim(deviceCode: string): Promise<DeviceClaim>;
708
709 /**
710 * OAuth 2.1 for applications that sign a person in through the browser.
711 * The caller has checked the client and its redirect address; this
712 * returns the one-time code the application exchanges for tokens.
713 */
714 oauthAuthorize(user: User, approval: OAuthApproval): Promise<{ code: string }>;
715 /** Redeems a code. It works once, for that client, with the PKCE verifier. */
716 oauthExchange(code: string, codeVerifier: string, clientId: string, redirectUri: string): Promise<Result<OAuthTokens>>;
717 /** Trades a refresh token for new tokens; the old ones stop working. */
718 oauthRefresh(refreshToken: string, clientId: string): Promise<Result<OAuthTokens>>;
719 /** Applications the user has signed in to, most recently used first. */
720 listOAuthGrants(user: User): Promise<OAuthGrant[]>;
721 /** Signs an application out. */
722 revokeOAuthGrant(user: User, id: string): Promise<void>;
723 /** Changes what an application may do, at once and when it refreshes. */
724 updateOAuthGrant(user: User, id: string, grant: TokenGrant): Promise<Result<OAuthGrant>>;
725
726 createWorkspace(user: User, slug: string, name: string): Promise<Result<Workspace>>;
727 /** Public details of a workspace, or null. */
728 getWorkspace(slug: string): Promise<Workspace | null>;
Merge branch 'worktree-agent-a2013627e5ea4ab13'729 /** Where a workspace keeps its repositories' git data; null when there is no such workspace. */
730 workspaceResidency(slug: string): Promise<DataResidency | null>;
731 /**
732 * Owners only. Applies to repositories made from then on. Offer `eu`
733 * only when the repos service's `storageOptions()` says it is available.
734 */
735 setWorkspaceResidency(actor: User, slug: string, residency: DataResidency): Promise<Result<DataResidency>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged736 /** Members only. */
737 listMembers(slug: string, viewer: Viewer): Promise<Result<Member[]>>;
738 /** Owners only. */
739 addMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
Merge main (membership, two-factor, GitHub repo roles) into tokens740 /** Owners only; your own username is leaving. Never the last owner. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged741 removeMember(actor: User, slug: string, username: string): Promise<Result<boolean>>;
Merge main (membership, two-factor, GitHub repo roles) into tokens742 /** Owners only: owner or member, and the roles held besides it. Never leaves no owner. */
743 updateMember(actor: User, slug: string, username: string, change: { role?: Role; org_roles?: OrgRole[] }): Promise<Result<Member>>;
744 /** Owners only: `username` becomes an owner, and you a member. */
745 transferOwnership(actor: User, slug: string, username: string): Promise<Result<boolean>>;
746 /** You leave the workspace. Never the last owner. */
747 leaveWorkspace(user: User, slug: string): Promise<Result<boolean>>;
748 /** Owners only: change some member privileges; returns all of them. */
749 setMemberPrivileges(actor: User, slug: string, change: Partial<MemberPrivileges>): Promise<Result<MemberPrivileges>>;
750 /** Owners only, with two-factor on themselves: require it of everyone. */
751 setTwoFactorRequirement(actor: User, slug: string, required: boolean): Promise<Result<boolean>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged752 /** Owners only. An empty name falls back to the slug. */
753 updateWorkspace(actor: User, slug: string, details: { name: string; description: string }): Promise<Result<Workspace>>;
754 /**
755 * Owners only. Changes the slug, the first segment of the workspace's
756 * URLs; the display name is untouched. The old slug redirects to the new
757 * one, and stays reserved for this workspace, for `SLUG_HOLD_DAYS`.
758 * Publishes `workspace.renamed`.
759 */
760 renameWorkspace(actor: User, slug: string, newSlug: string): Promise<Result<Workspace>>;
761 /** Whether `renameWorkspace` would be allowed, changing nothing. */
762 checkWorkspaceRename(actor: User, slug: string, newSlug: string): Promise<Result<boolean>>;
763 /**
764 * The workspace's current slug when `slug` is one it was renamed from
Merge branch 'worktree-agent-a8385d293d42c913a'765 * within `SLUG_HOLD_DAYS`, or when `slug` is an alias staff set for it
766 * (`WorkspaceAlias`); null otherwise, including for a slug in use.
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged767 */
768 resolveSlug(slug: string): Promise<string | null>;
769 /**
770 * Owners only, a person only. `confirm` is the slug, typed out. Refused
771 * for a protected workspace, and while billing cannot settle it. Its
772 * repositories, projects and apps go with it; it is kept for
773 * `WORKSPACE_RESTORE_DAYS`, when g1t's staff can restore it, then purged.
774 * Its slug is never given to anyone else; the person whose username it is
775 * may make it again once it is purged. Publishes `workspace.deleting`.
776 */
777 deleteWorkspace(actor: User, slug: string, confirm: string): Promise<Result<boolean>>;
778 /** What `deleteWorkspace` would take with it, and what stands in its way, changing nothing. */
779 checkWorkspaceDeletion(actor: User, slug: string): Promise<Result<WorkspaceDeletion>>;
780 /**
781 * Owners only. `image` is the file in base64: PNG, JPEG, WebP or GIF, at
782 * most `MAX_AVATAR_BYTES`, checked by its bytes. Null removes the icon.
783 */
784 setWorkspaceAvatar(actor: User, slug: string, image: string | null): Promise<Result<Workspace>>;
785 /** A person's own avatar, as `setWorkspaceAvatar`: the new one, or null. */
786 setUserAvatar(user: User, image: string | null): Promise<Result<string | null>>;
787
788 /**
789 * A workspace's own access tokens. They belong to the workspace, act as
790 * it, and keep working when the member who made one leaves. Members only.
791 */
792 listWorkspaceTokens(slug: string, viewer: Viewer): Promise<Result<AccessToken[]>>;
793 /** Owners only. */
794 removeWorkspaceToken(actor: User, slug: string, id: string): Promise<Result<boolean>>;
795
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules796 /**
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers797 * An access token: yours, or (with `input.owner`, owners only) a
798 * workspace's. People only, signed in. The plaintext token is returned
799 * once and never stored. A personal token made for a workspace that asks
800 * for approval starts pending unless you are an owner there.
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules801 */
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers802 createToken(actor: User, input: TokenInput): Promise<Result<{ token: string; info: AccessToken }>>;
803 /**
804 * Changes a token of yours, or (with `owner`, owners only) a
805 * workspace's; what is left out stays. Widening a token made for a
806 * workspace that approves tokens asks for approval again.
807 */
808 updateToken(actor: User, id: string, change: TokenChange, owner?: string | null): Promise<Result<AccessToken>>;
An access token can be regenerated: a new secret, its name, permissions, repositories and reach kept, and the old secret refused at once. Its page (yours under Settings, a workspace's under its settings for owners) has Regenerate with a new expiry, within the workspace's rules on lifetime, and shows the secret once; identity's regenerate_token logs it to the security log or the workspace's audit log, and refuses a revoked token. The token form's quick permissions have All, every resource at its highest level. A project's Observability settings no longer list the token g1t gives its apps on g1t.page: it is g1t's, and the page says apps there need none.809 /**
810 * A new secret for a token, everything else kept, the old secret refused
811 * from then on: rotating it. `ttlSeconds` is its new lifetime from now
812 * (null: it does not expire), within its workspace's rules. The secret
813 * is shown once.
814 */
815 regenerateToken(actor: User, id: string, ttlSeconds: number | null, owner?: string | null): Promise<Result<{ token: string; info: AccessToken }>>;
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules816 /** A workspace's rules for personal access tokens. Members only. */
817 getTokenPolicy(slug: string, viewer: Viewer): Promise<Result<TokenPolicy>>;
818 /** Owners only, as people. `maxLifetimeDays` of 0 removes the limit. */
819 setTokenPolicy(
820 actor: User,
821 slug: string,
822 change: Partial<Omit<TokenPolicy, "updatedBy" | "updatedAt">>,
823 ): Promise<Result<TokenPolicy>>;
824 /** The members' tokens that can reach a workspace. Owners only. */
825 listMemberTokens(
826 actor: User,
827 slug: string,
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers828 filter?: { status?: TokenStatus },
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules829 ): Promise<Result<MemberToken[]>>;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers830 /** Approve or deny a token waiting for approval. Owners only. */
Settings: fine-grained tokens, workspace token Admin, workspace personal access token rules831 reviewTokenRequest(actor: User, slug: string, id: string, approve: boolean, reason?: string | null): Promise<Result<MemberToken>>;
832 /** Take a member's token out of the workspace. Owners only. */
833 revokeMemberToken(actor: User, slug: string, id: string, reason?: string | null): Promise<Result<boolean>>;
834
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged835 userForSession(sessionToken: string): Promise<Viewer>;
836
837 /**
838 * What a code is for. Unknown, used, revoked and expired codes all get the
839 * same answer, unless `anyStatus`: then a real code that is spent is
Merge invite emails that confirm the address: the emailed link carries a proof only that email has, so signing up from it needs no code; shared links and typed codes still confirm840 * described, with its `status`. `viewer` sets `forViewer`; `emailProof`,
841 * the `proof` from the invite email's link, sets `emailProven`.
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged842 */
843 checkInvite(
844 code: string,
845 client?: string | null,
Merge invite emails that confirm the address: the emailed link carries a proof only that email has, so signing up from it needs no code; shared links and typed codes still confirm846 options?: { viewer?: User | null; anyStatus?: boolean; emailProof?: string | null },
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged847 ): Promise<Result<InvitePreview>>;
848 /**
849 * A signed-in person uses a workspace invite sent to their address, or one
850 * sent with a repository invitation; returns the workspace's slug, or
851 * `workspace/repo`.
852 */
853 acceptInvite(user: User, code: string): Promise<Result<string>>;
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)854 /**
855 * Owners only. Invites someone into a workspace by address (always with an
856 * invite bound to it) or by `username`: a workspace invitation they accept
857 * or decline. Nobody joins without saying yes. `role` is what they join as.
858 */
859 inviteMember(
860 actor: User,
861 slug: string,
Workspace is the workspace's settings, in one place. Its sidebar is grouped, General, Access, Money, Compute, Code, Agents, Chat, Artifacts, Security and Integrations, every page one click away with no settings inside settings, the groups folding and the owner-only pages hidden from members; what is not here yet is marked Soon with a hint. Members is a list with search and filters for role, two-factor and team, and Invite opens a dialog: who, by username, name or email, their role and a note that goes into the invitation; nothing is filled in inline any more. Invitations is its own page with All, Pending, Accepted, Declined, Expired and Revoked filters that say how many, and each row's menu can copy the link, send it again or revoke it; identity learned to send an invitation again and to carry the note. Permissions gathers every rule about who may do what, by part: Code's base permission and member privileges, who creates teams, who creates channels, and, marked Soon with what applies today, forking private repositories, adding agents to conversations, messaging agents directly, creating spaces and default sharing, creating workspace agents and raising budgets, deploying to production and publishing packages. General lost what moved. The permissions guide is new, and the workspaces, people and teams, access, chat, teams, authentication and billing guides say where things are now.862 who: { email?: string | null; username?: string | null; role?: Role | null; message?: string | null },
Merge workspace invitations: nobody joins a workspace without saying yes, people are found by username, your own invites can bring someone in, and nobody is left without a workspace (identity 0040)863 ): Promise<Result<Invite>>;
864 /** The workspace invitations waiting for the person's answer, newest first. */
865 listInvitations(user: User): Promise<WorkspaceInvitation[]>;
866 /** Joins the invitation's workspace with its role; returns the workspace's slug. */
867 acceptInvitation(user: User, id: string): Promise<Result<string>>;
868 /** Declines it; whoever sent it is told in their inbox. */
869 declineInvitation(user: User, id: string): Promise<Result<boolean>>;
870 /** People to invite, by username prefix or name: a username, a name and an avatar each. */
871 findPeople(query: string, limit?: number): Promise<PersonMatch[]>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged872 /** Owners only: the workspace's invites, newest first. */
873 workspaceInvites(slug: string, viewer: Viewer): Promise<Result<Invite[]>>;
874 /** Owners only. */
875 revokeWorkspaceInvite(actor: User, slug: string, id: string): Promise<Result<Invite>>;
Workspace is the workspace's settings, in one place. Its sidebar is grouped, General, Access, Money, Compute, Code, Agents, Chat, Artifacts, Security and Integrations, every page one click away with no settings inside settings, the groups folding and the owner-only pages hidden from members; what is not here yet is marked Soon with a hint. Members is a list with search and filters for role, two-factor and team, and Invite opens a dialog: who, by username, name or email, their role and a note that goes into the invitation; nothing is filled in inline any more. Invitations is its own page with All, Pending, Accepted, Declined, Expired and Revoked filters that say how many, and each row's menu can copy the link, send it again or revoke it; identity learned to send an invitation again and to carry the note. Permissions gathers every rule about who may do what, by part: Code's base permission and member privileges, who creates teams, who creates channels, and, marked Soon with what applies today, forking private repositories, adding agents to conversations, messaging agents directly, creating spaces and default sharing, creating workspace agents and raising budgets, deploying to production and publishing packages. General lost what moved. The permissions guide is new, and the workspaces, people and teams, access, chat, teams, authentication and billing guides say where things are now.876 /** Owners only: sends a pending invitation again, by email and in the invited account's inbox. Unchanged otherwise. */
877 resendWorkspaceInvite(actor: User, slug: string, id: string): Promise<Result<Invite>>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged878
879 /** Verifies git credentials: the account password or an access token. */
880 userForGitCredentials(username: string, secret: string): Promise<Viewer>;
881 /** Resolves a `g1t_…` access token, as sent to the API and MCP server. */
882 userForAccessToken(token: string): Promise<Viewer>;
883 userForSshKey(fingerprint: string): Promise<Viewer>;
884 userByUsername(username: string): Promise<Viewer>;
885 /** The names behind account and workspace ids; unknown ids are left out. */
886 usernames(ids: string[]): Promise<Record<string, string>>;
Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002)887 /**
888 * Internal: the people behind these ids (at most 50) with their
889 * workspaces, roles and repository grants, as a signed-in viewer has
The contracts no longer describe g1t's own agents, and workspaces can keep their AI providers. Every consumer had already stopped using them, so the TypeScript and Rust contracts drop the workspace-agent, ability, look, skill-library, context, runner-agent and mention modules, the chat and docs RPCs agents posted and read through, the folio agent methods, the agent_waiting notification, agent.asked and memory.changed events, AI credit, token and gateway billing types, model routes and sessions, team agents, agent tokens, plan, review, message and confidence types, command rules, cost caps and confidence rules. The agents:run and models:* scopes are no longer offered by any preset, OAuth default or permission form, but a stored token or grant that names them still reads; and the removed operations are gone from the scope table, so the API's check that every operation has exactly one scope is strict again. What stored data needs in order to parse (old run and credential kinds, an agent team lead, retired rules and webhook events, old guardrail and integration settings) still parses, and a run's token is still PrincipalKind::Agent, which now means a run's token and the @g1t rows written before. The customize, marketplace, skills and claude-plugin contracts stay only until the mobile app drops its Customize screens.890 * them. For artifacts' audience checks only. Ids of no live account are
891 * left out.
Merge the workspace shell: navigation and phone shell, g1t as orchestrator, agents in roles with audience-checked reads, reactions and custom emoji, live notifications and browser push, the homepage tour (agents 0002, chat 0002)892 */
893 usersForAudience(ids: string[]): Promise<User[]>;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged894
895 /** A person's public profile, or null if there is no such account. Never an email address. */
896 profile(username: string): Promise<Profile | null>;
897 /** A person changes their own profile. Every field is replaced; an empty one is cleared. */
898 updateProfile(actor: User, fields: ProfileFields): Promise<Result<Profile>>;
899 /**
900 * The workspaces a profile shows `viewer`: those the viewer belongs to
901 * as well, and those of `publicIn` (where the person made a public
902 * project) that the person really belongs to. Nothing else.
903 */
904 profileWorkspaces(username: string, viewer: Viewer, publicIn: string[]): Promise<ProfileWorkspace[]>;
905
The apps you pin to your dock are kept with your account, per workspace and in your order, so the dock is the same on every device: identity keeps them in dock_pins and answers dock_pins and set_dock_pins, the dock reads them with the rest of the page, pins kept only on this device carry over with your first change, this device's copy still draws the dock when identity can't be reached, a pin that can't be saved says so, and they go when you or the workspace do; the workspaces guide says how.906 /**
907 * The apps `user` pinned to their dock in the workspace `workspace` (a
908 * slug), in the order they set; null when they never saved any there or
909 * are not one of its members. Kept with the account, so every device
910 * shows the same dock.
911 */
912 dockPins(user: User, workspace: string): Promise<string[] | null>;
913 /**
914 * Replaces `user`'s dock pins in `workspace` with `apps`, in that order:
915 * keys of lowercase letters, digits and hyphens, repeats dropped, at
916 * most `MAX_DOCK_PINS`. Which keys are real apps is the caller's to check.
917 */
918 setDockPins(user: User, workspace: string, apps: string[]): Promise<Result<string[]>>;
919
Chat has sounds. A short warm cue plays for a message in a conversation you have open but aren't looking at, a direct message, a mention of you and an agent finishing something for you, with a soft tick for sending that is off until you turn it on; never for your own messages, a muted conversation, a conversation you are looking at in a window that has the front, or while you have paused notifications, and never twice for one message or more than once in a second and a half. The cues are made by the browser itself in two sets, Soft and Bright, so nothing is downloaded; the Sounds and notifications section of your notification settings turns them on and off, picks the set and the volume, plays each one, and offers desktop notifications for when the window is behind; Do not disturb is the one pause everyone sees, set from the chat sidebar's bell, the settings, or your avatar menu, now with a two-hour choice, and the top bar's bell shows a dot while it's on. Your choices are kept with your account. The sound layer sits behind one small interface so the desktop app can play them natively later. The chat and notifications guides say the rules.920 /**
921 * How chat sounds and desktop notifications reach `user`, kept with the
922 * account so every device and the desktop app behave the same
923 * (`SoundSettings`). The defaults when they never changed them.
924 */
925 soundSettings(user: User): Promise<SoundSettings>;
926 /**
927 * Changes some of them: only the fields sent change, and `sound_cues`
928 * merges one cue at a time. Returns the settings as kept.
929 */
930 setSoundSettings(user: User, change: SoundSettingsChange): Promise<Result<SoundSettings>>;
931
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged932 listSshKeys(user: User): Promise<SshKey[]>;
933 /** Takes one line in OpenSSH public key format. */
934 addSshKey(user: User, title: string, publicKey: string): Promise<Result<SshKey>>;
935 removeSshKey(user: User, id: string): Promise<void>;
936
937 listAccessTokens(user: User): Promise<AccessToken[]>;
938 /**
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers939 * A credential minted for a person or workspace by another service. The
940 * plaintext token is returned once and never stored. With `ttlSeconds`
The contracts no longer describe g1t's own agents, and workspaces can keep their AI providers. Every consumer had already stopped using them, so the TypeScript and Rust contracts drop the workspace-agent, ability, look, skill-library, context, runner-agent and mention modules, the chat and docs RPCs agents posted and read through, the folio agent methods, the agent_waiting notification, agent.asked and memory.changed events, AI credit, token and gateway billing types, model routes and sessions, team agents, agent tokens, plan, review, message and confidence types, command rules, cost caps and confidence rules. The agents:run and models:* scopes are no longer offered by any preset, OAuth default or permission form, but a stored token or grant that names them still reads; and the removed operations are gone from the scope table, so the API's check that every operation has exactly one scope is strict again. What stored data needs in order to parse (old run and credential kinds, an agent team lead, retired rules and webhook events, old guardrail and integration settings) still parses, and a run's token is still PrincipalKind::Agent, which now means a run's token and the @g1t rows written before. The customize, marketplace, skills and claude-plugin contracts stay only until the mobile app drops its Customize screens.941 * the token expires and is left out of token lists. Tokens people make
942 * use `createToken`.
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged943 */
944 createAccessToken(
945 user: User,
946 name: string,
947 ttlSeconds?: number,
948 grant?: TokenGrant & { listed?: boolean },
949 ): Promise<{ token: string; info: AccessToken }>;
950 removeAccessToken(user: User, id: string): Promise<void>;
951 /**
952 * A token for one sandbox run: it acts as the agent on behalf of
953 * `onBehalfOf`, can do only what the run's kind needs in `repo`, and
954 * expires after `ttlSeconds`. See `audit.ts`.
955 */
956 createRunCredential(input: CreateRunCredentialInput): Promise<{ token: string; info: AccessToken }>;
957 /** Ties tokens, by the SHA-256 of their text in hex, to the agent run their sandbox recorded. */
958 bindRunCredentials(tokenHashes: string[], runId: string): Promise<boolean>;
959 /** Ends a sandbox's run credentials, by hash or by run. Never touches another token. */
960 revokeRunCredentials(target: { tokenHashes?: string[]; runId?: string | null }): Promise<boolean>;
961}
962
963
The contracts no longer describe g1t's own agents, and workspaces can keep their AI providers. Every consumer had already stopped using them, so the TypeScript and Rust contracts drop the workspace-agent, ability, look, skill-library, context, runner-agent and mention modules, the chat and docs RPCs agents posted and read through, the folio agent methods, the agent_waiting notification, agent.asked and memory.changed events, AI credit, token and gateway billing types, model routes and sessions, team agents, agent tokens, plan, review, message and confidence types, command rules, cost caps and confidence rules. The agents:run and models:* scopes are no longer offered by any preset, OAuth default or permission form, but a stored token or grant that names them still reads; and the removed operations are gone from the scope table, so the API's check that every operation has exactly one scope is strict again. What stored data needs in order to parse (old run and credential kinds, an agent team lead, retired rules and webhook events, old guardrail and integration settings) still parses, and a run's token is still PrincipalKind::Agent, which now means a run's token and the @g1t rows written before. The customize, marketplace, skills and claude-plugin contracts stay only until the mobile app drops its Customize screens.964/**
965 * What a scoped token may do: these operations, in this repository. Run
966 * credentials carry one today; tokens g1t's retired hosted agents were
967 * issued carry one too and still parse, so their rows and the `@g1t`
968 * history they wrote read as before.
969 */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged970export type AgentScope = { repo: RepoPath; operations: string[]; run?: RunBinding };
971
The apps you pin to your dock are kept with your account, per workspace and in your order, so the dock is the same on every device: identity keeps them in dock_pins and answers dock_pins and set_dock_pins, the dock reads them with the rest of the page, pins kept only on this device carry over with your first change, this device's copy still draws the dock when identity can't be reached, a pin that can't be saved says so, and they go when you or the workspace do; the workspaces guide says how.972/** The most apps a person pins in one workspace. Mirrors `MAX_DOCK_PINS` in `crates/contracts/src/identity.rs`. */
973export const MAX_DOCK_PINS = 24;
974
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged975/** The most characters each profile field takes. Mirrors `crates/contracts/src/identity.rs`. */
Merge leftovers: plan activity filtered in the query, pushes counted by account, ghost during the deletion window, profile time zones (identity 0039)976export const PROFILE_LIMITS = { name: 80, bio: 160, location: 80, website: 200, pronouns: 40, timezone: 64 } as const;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged977
978/** What anyone may see about a person, at `g1t.sh/u/<username>`. */
979export type Profile = {
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers980 /** Lowercased: what the profile is found and linked by. */
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged981 username: string;
One kind of access token; presence and status; usernames keep their case; the tour is a miniature of the real app; icons for password managers982 /** The username as its owner wrote it (`Ana`), when that differs: what the page shows. */
983 displayUsername?: string | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged984 /** The name they go by, if they gave one. */
985 name: string | null;
986 bio: string | null;
987 location: string | null;
988 /** Always an `https://` address. */
989 website: string | null;
990 pronouns: string | null;
Merge leftovers: plan activity filtered in the query, pushes counted by account, ghost during the deletion window, profile time zones (identity 0039)991 /** The time zone they are in, an IANA name such as `America/Denver`. */
992 timezone: string | null;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged993 /** The uploaded avatar's hash, served at `/avatars/<avatar>`. */
994 avatar: string | null;
995 /** When the account was made. RFC 3339. */
996 createdAt: string;
997};
998
999/** What a person may change on their profile. Empty clears a field. */
1000export type ProfileFields = {
1001 name: string;
1002 bio: string;
1003 location: string;
1004 /** `https://…`; a bare `example.com` is taken as `https://example.com`. */
1005 website: string;
1006 pronouns: string;
Merge leftovers: plan activity filtered in the query, pushes counted by account, ghost during the deletion window, profile time zones (identity 0039)1007 /** An IANA time zone name, such as `America/Denver`; empty clears it. */
1008 timezone: string;
Billing and Usage reconcile: own-provider runs leave Billing's at-price total, and Usage's not-charged part is at price less charged1009};
1010
1011/** A workspace on a person's profile. */
1012export type ProfileWorkspace = { slug: string; name: string; avatar: string | null };

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