| 1 | /** |
| 2 | * A workspace's own agents: named members with a job, a personality, |
| 3 | * routing limits and a budget, kept by the agents service |
| 4 | * (`services/agents`). Every workspace also has `@g1t`, its built-in |
| 5 | * orchestrator, kept the same way (`builtin`). |
| 6 | * |
| 7 | * Wire shapes are snake_case end to end. |
| 8 | */ |
| 9 | import type { ServiceBinding } from "./clients"; |
| 10 | import type { Role, User } from "./identity"; |
| 11 | import type { Result } from "./result"; |
| 12 | import type { CardActionResult } from "./chat"; |
| 13 | |
| 14 | // Model tiers (`ModelTier`, `MODEL_TIERS`) are integrations.ts's, the |
| 15 | // same ones runs are routed between. |
| 16 | import type { ModelTier } from "./integrations"; |
| 17 | |
| 18 | /** The built-in orchestrator's handle; nobody else's agent may take it. */ |
| 19 | export const BUILTIN_AGENT_HANDLE = "g1t"; |
| 20 | |
| 21 | /** The built-in orchestrator's template id: not one a workspace can adopt. */ |
| 22 | export const ORCHESTRATOR_TEMPLATE = "orchestrator"; |
| 23 | |
| 24 | /** Voice presets; free text in `personality` refines them. */ |
| 25 | export type PersonalityPreset = "crisp" | "friendly" | "socratic" | "terse"; |
| 26 | |
| 27 | export type AgentRouting = { |
| 28 | /** Never route below this tier. Null: no floor. */ |
| 29 | floor: ModelTier | null; |
| 30 | /** Never route above this tier. Null: no ceiling. */ |
| 31 | ceiling: ModelTier | null; |
| 32 | /** |
| 33 | * Where its model calls may go. Empty: anything the workspace allows. |
| 34 | * `g1t`: g1t's hosted models. `workspace`: the workspace's own providers |
| 35 | * (Integrations), whichever they are. Any other entry: one of the |
| 36 | * workspace's own providers by integration id. Entries combine, so |
| 37 | * `["g1t", "workspace"]` is both. |
| 38 | */ |
| 39 | providers: string[]; |
| 40 | /** Advanced: a fixed `provider/model`, for own endpoints. Usually null. */ |
| 41 | pinned: string | null; |
| 42 | }; |
| 43 | |
| 44 | export type AgentBudget = { |
| 45 | /** Monthly cap in micro-dollars. Null: only the workspace limit applies. */ |
| 46 | monthly_micros: number | null; |
| 47 | daily_micros: number | null; |
| 48 | /** Default cap for one task. */ |
| 49 | task_micros: number | null; |
| 50 | }; |
| 51 | |
| 52 | export type AgentAutonomy = { |
| 53 | open_pull_requests: "alone" | "approval"; |
| 54 | merge: "alone" | "approval" | "never"; |
| 55 | deploy_production: "approval" | "never"; |
| 56 | edit_docs: "alone" | "suggest"; |
| 57 | }; |
| 58 | |
| 59 | export type AgentStatus = "idle" | "working" | "waiting" | "out_of_budget" | "paused"; |
| 60 | |
| 61 | export type WorkspaceAgent = { |
| 62 | id: string; |
| 63 | workspace_id: string; |
| 64 | /** Lowercase, unique in the workspace, never `g1t`. Mentioned as `@handle`. */ |
| 65 | handle: string; |
| 66 | display_name: string; |
| 67 | /** Uploaded avatar hash, or null for the generated mark. */ |
| 68 | avatar: string | null; |
| 69 | /** |
| 70 | * What its generated avatar is drawn from: a little pixel creature, the |
| 71 | * same for the same seed everywhere. Set from the handle when it is |
| 72 | * made; changing it gives the agent a new face. |
| 73 | */ |
| 74 | avatar_seed: string; |
| 75 | /** |
| 76 | * One line, as lists show it: "QA Engineer on the QA team". Made from |
| 77 | * the title and team (or department) when not written. |
| 78 | */ |
| 79 | role: string; |
| 80 | /** |
| 81 | * Agents are hired into roles, not tasks: a title, a team, and broad |
| 82 | * responsibilities. |
| 83 | */ |
| 84 | title: string; |
| 85 | /** The team it is on, by slug, from the workspace's teams; null for none. */ |
| 86 | team: string | null; |
| 87 | /** A label for where it works when it is on no team: "QA", "Sales". */ |
| 88 | department: string; |
| 89 | /** What it is responsible for: 2 to 8 short duties, or none yet. */ |
| 90 | responsibilities: string[]; |
| 91 | /** |
| 92 | * Specialised help it will use inside its own work. Never members, never |
| 93 | * wider than their agent. Stored now; they run with tasks and sessions. |
| 94 | */ |
| 95 | subagents: SubagentDef[]; |
| 96 | /** |
| 97 | * Its required reading: Docs spaces (by id) it checks first, every time |
| 98 | * it answers or works. It still reads only what the person it acts for, |
| 99 | * and everyone reading its answer, can read. |
| 100 | */ |
| 101 | reading: string[]; |
| 102 | /** |
| 103 | * Who it works with: `internal`, the workspace's own people (back |
| 104 | * office), or `customers` (front office). Only `internal` for now. |
| 105 | */ |
| 106 | faces: AgentFaces; |
| 107 | /** The job: what it is responsible for and how it works. */ |
| 108 | instructions: string; |
| 109 | personality_preset: PersonalityPreset; |
| 110 | /** Free text refining the voice. Never changes what it may do. */ |
| 111 | personality: string; |
| 112 | routing: AgentRouting; |
| 113 | budget: AgentBudget; |
| 114 | autonomy: AgentAutonomy; |
| 115 | /** Tasks it works at once; more queue on its desk. */ |
| 116 | capacity: number; |
| 117 | /** The template it was made from, if any. */ |
| 118 | template: string | null; |
| 119 | /** |
| 120 | * The workspace's built-in orchestrator, `@g1t`: every workspace has one, |
| 121 | * made the first time its agents are asked for. It cannot be archived, |
| 122 | * and its handle, name, role and job are fixed; its `instructions` are |
| 123 | * added to that job. Listed first. |
| 124 | */ |
| 125 | builtin: boolean; |
| 126 | version: number; |
| 127 | status: AgentStatus; |
| 128 | /** Spend this calendar month, in micro-dollars. */ |
| 129 | spent_month_micros: number; |
| 130 | created_by: string; |
| 131 | created_at: string; |
| 132 | updated_at: string; |
| 133 | archived_at: string | null; |
| 134 | }; |
| 135 | |
| 136 | /** |
| 137 | * Back office or front office (docs.g1t.sh/guides/agents/, "Back office |
| 138 | * and front office"). Customer-facing agents are not available yet. |
| 139 | */ |
| 140 | export type AgentFaces = "internal" | "customers"; |
| 141 | |
| 142 | /** |
| 143 | * A subagent: help an agent keeps for its own work, such as Margo's |
| 144 | * `flake-hunter`. Its routing limits sit within its agent's: a floor below |
| 145 | * the agent's is raised to it, a ceiling above is lowered to it. |
| 146 | */ |
| 147 | export type SubagentDef = { |
| 148 | /** Lowercase letters, digits and hyphens: `flake-hunter`. Unique on the agent. */ |
| 149 | name: string; |
| 150 | /** One line: what it is for. */ |
| 151 | description: string; |
| 152 | instructions: string; |
| 153 | routing: { floor: ModelTier | null; ceiling: ModelTier | null }; |
| 154 | /** How many of it may run at once inside one task, 1 to 8. */ |
| 155 | max_parallel: number; |
| 156 | }; |
| 157 | |
| 158 | export type NewWorkspaceAgent = { |
| 159 | handle: string; |
| 160 | display_name: string; |
| 161 | /** Left out or empty: made from the title and team. */ |
| 162 | role?: string; |
| 163 | title?: string; |
| 164 | team?: string | null; |
| 165 | department?: string; |
| 166 | responsibilities?: string[]; |
| 167 | subagents?: SubagentDef[]; |
| 168 | /** Docs spaces (by id) it reads first; at most 10. */ |
| 169 | reading?: string[]; |
| 170 | /** Only `internal` for now; `customers` is refused. */ |
| 171 | faces?: AgentFaces; |
| 172 | instructions: string; |
| 173 | personality_preset?: PersonalityPreset; |
| 174 | personality?: string; |
| 175 | routing?: Partial<AgentRouting>; |
| 176 | budget?: Partial<AgentBudget>; |
| 177 | autonomy?: Partial<AgentAutonomy>; |
| 178 | capacity?: number; |
| 179 | template?: string | null; |
| 180 | /** Its avatar's seed; left out, the handle. */ |
| 181 | avatar_seed?: string; |
| 182 | }; |
| 183 | |
| 184 | /** |
| 185 | * A role to hire an agent into, by department. Agents get names, not job |
| 186 | * titles ("Margo", the QA Engineer). |
| 187 | */ |
| 188 | export type AgentTemplate = { |
| 189 | id: string; |
| 190 | /** The name it suggests first. */ |
| 191 | display_name: string; |
| 192 | handle: string; |
| 193 | /** Other names that suit it, for the form's shuffle. Each is also a valid handle, lowercased. */ |
| 194 | name_ideas: string[]; |
| 195 | role: string; |
| 196 | title: string; |
| 197 | department: string; |
| 198 | responsibilities: string[]; |
| 199 | subagents: SubagentDef[]; |
| 200 | instructions: string; |
| 201 | personality_preset: PersonalityPreset; |
| 202 | routing: AgentRouting; |
| 203 | }; |
| 204 | |
| 205 | /** What the chat service hands an agent: a message it should answer. */ |
| 206 | export type AgentDelivery = { |
| 207 | workspace: string; |
| 208 | workspace_id: string; |
| 209 | channel_id: string; |
| 210 | channel_kind: "channel" | "dm"; |
| 211 | channel_name: string | null; |
| 212 | agent_id: string; |
| 213 | /** The message that woke it. */ |
| 214 | message_id: string; |
| 215 | thread_root: string | null; |
| 216 | /** Who asked: the person's user id. */ |
| 217 | asked_by: string; |
| 218 | /** Agent-to-agent hops so far in this chain. */ |
| 219 | hops: number; |
| 220 | /** |
| 221 | * What the person who asked may do, from the viewer the chat service |
| 222 | * already holds when the message is posted (`askerAccess`). An agent |
| 223 | * never does more for someone than they could do themselves. Absent |
| 224 | * from an older chat service: the agent then treats the asker as unable |
| 225 | * to change code. |
| 226 | */ |
| 227 | asker?: AskerAccess | null; |
| 228 | /** |
| 229 | * The agents that handled this request before this one, by id, oldest |
| 230 | * first; the last sent the work here. An agent never hands back or |
| 231 | * consults the one that sent it work, and the hop limit counts every |
| 232 | * hand-off and consult along the chain. Absent: none (a person asked). |
| 233 | */ |
| 234 | chain?: string[]; |
| 235 | /** |
| 236 | * Where the conversation is: g1t's own chat, or later another chat app |
| 237 | * the workspace connected. The agent reads and replies through that |
| 238 | * surface; its definition, budget and replies are the same everywhere. |
| 239 | * Absent: `g1t`. |
| 240 | */ |
| 241 | surface?: AgentSurface; |
| 242 | }; |
| 243 | |
| 244 | /** The chat surfaces an agent answers on. Only g1t's own today. */ |
| 245 | export type AgentSurface = "g1t"; |
| 246 | |
| 247 | /** Who asked an agent, as far as its reply needs to know. */ |
| 248 | export type AskerAccess = { |
| 249 | username: string; |
| 250 | /** Their role in the workspace; `outside` for someone who is not a member. */ |
| 251 | role: Role | "outside"; |
| 252 | /** |
| 253 | * Whether they can change code in the workspace: Code is on for them |
| 254 | * and they hold write access (or more) on at least one of its |
| 255 | * repositories, through the base permission or a grant. |
| 256 | */ |
| 257 | can_write: boolean; |
| 258 | }; |
| 259 | |
| 260 | const WRITING_ROLES = new Set(["write", "maintain", "admin"]); |
| 261 | |
| 262 | /** |
| 263 | * `user`'s access in `workspace`, for `AgentDelivery.asker`. Pure, with no |
| 264 | * imports, so the chat service computes it from its viewer for free. |
| 265 | */ |
| 266 | export function askerAccess(user: User, workspace: string): AskerAccess { |
| 267 | const slug = workspace.toLowerCase(); |
| 268 | const membership = user.workspaces?.find((m) => m.slug.toLowerCase() === slug); |
| 269 | // Someone who uses only Chat, Docs and agents sees no repository at all. |
| 270 | const code = membership?.code_access !== false; |
| 271 | const base = membership ? membership.role === "owner" || WRITING_ROLES.has(membership.base_permission ?? "write") : false; |
| 272 | const granted = (user.grants ?? []).some((grant) => grant.workspace.toLowerCase() === slug && WRITING_ROLES.has(grant.role)); |
| 273 | return { |
| 274 | username: user.username, |
| 275 | role: membership?.role ?? "outside", |
| 276 | can_write: code && (base || granted), |
| 277 | }; |
| 278 | } |
| 279 | |
| 280 | /** |
| 281 | * A session: one bounded piece of work an agent took on |
| 282 | * (docs.g1t.sh/guides/agent-sessions/). A conversation with an agent is |
| 283 | * not a session: talking stays cheap and quick, and when a request needs |
| 284 | * real work the agent spins off a session for it, with its own context, transcript, budget and live card in |
| 285 | * the conversation. Sessions start other sessions (one of the agent's |
| 286 | * subagents, or a colleague brought in), and everything a tree of sessions |
| 287 | * spends is charged to the agent at its root, so a chain never escapes the |
| 288 | * budget that started it. |
| 289 | */ |
| 290 | export type AgentSessionKind = |
| 291 | /** Spun off from a conversation: someone asked for work. */ |
| 292 | | "chat" |
| 293 | /** A routine's run. */ |
| 294 | | "routine" |
| 295 | /** A colleague brought in by another session. */ |
| 296 | | "helper" |
| 297 | /** One of the agent's own subagents, inside another session. */ |
| 298 | | "subagent"; |
| 299 | |
| 300 | export type AgentSessionStatus = |
| 301 | | "queued" |
| 302 | | "working" |
| 303 | /** Waiting on sessions it started. */ |
| 304 | | "waiting" |
| 305 | /** Stopped at its spend cap: someone who may raise it decides. */ |
| 306 | | "needs_approval" |
| 307 | | "done" |
| 308 | | "failed" |
| 309 | | "stopped"; |
| 310 | |
| 311 | /** The statuses of a session that is not over. */ |
| 312 | export const SESSION_LIVE: readonly AgentSessionStatus[] = ["queued", "working", "waiting", "needs_approval"]; |
| 313 | |
| 314 | export type AgentSession = { |
| 315 | id: string; |
| 316 | workspace_id: string; |
| 317 | agent_id: string; |
| 318 | /** The agent's handle, name and face, for lists. */ |
| 319 | agent_handle: string; |
| 320 | agent_name: string; |
| 321 | agent_avatar_seed: string; |
| 322 | /** The subagent running it, by name, when kind is `subagent`. */ |
| 323 | subagent: string | null; |
| 324 | kind: AgentSessionKind; |
| 325 | /** The session that started it, and the root of its tree. */ |
| 326 | parent_id: string | null; |
| 327 | root_id: string; |
| 328 | /** Whose budget pays for it: the agent at the root of its tree. */ |
| 329 | payer_agent_id: string; |
| 330 | title: string; |
| 331 | goal: string; |
| 332 | status: AgentSessionStatus; |
| 333 | /** Why it is waiting, stopped or failed, in a line. */ |
| 334 | status_note: string | null; |
| 335 | /** What it found or did, once done: its report. */ |
| 336 | summary: string | null; |
| 337 | /** Where it reports: the conversation it was started from. */ |
| 338 | channel_id: string; |
| 339 | channel_kind: "channel" | "dm"; |
| 340 | channel_name: string | null; |
| 341 | /** Its live card in that conversation; its updates go in the card's thread. */ |
| 342 | card_message_id: string | null; |
| 343 | asked_by: string | null; |
| 344 | asked_by_username: string | null; |
| 345 | routine_id: string | null; |
| 346 | steps: number; |
| 347 | tool_calls: number; |
| 348 | input_tokens: number; |
| 349 | output_tokens: number; |
| 350 | /** At list price, what it counts against budgets. */ |
| 351 | charged_micros: number; |
| 352 | /** The most it may spend before someone approves more. */ |
| 353 | cap_micros: number | null; |
| 354 | model: string | null; |
| 355 | /** What it produced: issues filed, sessions started. */ |
| 356 | outputs: SessionOutput[]; |
| 357 | created_at: string; |
| 358 | updated_at: string; |
| 359 | finished_at: string | null; |
| 360 | /** |
| 361 | * False when the viewer is not among the people of the conversation it |
| 362 | * came from: they see that it ran and what it cost, never its title, |
| 363 | * goal, report or transcript. |
| 364 | */ |
| 365 | visible: boolean; |
| 366 | }; |
| 367 | |
| 368 | export type SessionOutput = |
| 369 | | { kind: "issue"; repo: string; number: number; title: string } |
| 370 | | { kind: "session"; id: string; agent_handle: string; title: string } |
| 371 | | { kind: "memory"; id: string; body: string }; |
| 372 | |
| 373 | /** One entry of a session's transcript, as its page shows it. */ |
| 374 | export type SessionEvent = { |
| 375 | seq: number; |
| 376 | kind: "goal" | "text" | "tool" | "steer" | "update" | "child" | "result" | "note"; |
| 377 | /** Who: the agent's handle, a person's username (steering), or null for g1t's notes. */ |
| 378 | by: string | null; |
| 379 | body: string; |
| 380 | /** For `tool`: the tool, and whether it read, was withheld, refused or failed. */ |
| 381 | tool: string | null; |
| 382 | outcome: string | null; |
| 383 | created_at: string; |
| 384 | }; |
| 385 | |
| 386 | export type AgentSessionDetail = { |
| 387 | session: AgentSession; |
| 388 | events: SessionEvent[]; |
| 389 | /** Every session in its tree, root first. */ |
| 390 | tree: AgentSession[]; |
| 391 | /** Whether the viewer may stop it, steer it, or approve more spend. */ |
| 392 | can_stop: boolean; |
| 393 | can_steer: boolean; |
| 394 | can_approve: boolean; |
| 395 | }; |
| 396 | |
| 397 | /** |
| 398 | * What an agent remembers (docs.g1t.sh/guides/agent-memory/). Every fact |
| 399 | * carries where it came from, and its scope decides, in code, where it may |
| 400 | * be recalled and who may see it: |
| 401 | * |
| 402 | * - `workspace`: anywhere in the workspace. Owners write these, or an agent |
| 403 | * from a public channel, which every member can read already. |
| 404 | * - `channel`: only in that channel and its threads. |
| 405 | * - `person`: only in a direct message with that one person. |
| 406 | */ |
| 407 | export type AgentMemoryScope = "workspace" | "channel" | "person"; |
| 408 | |
| 409 | export type AgentMemory = { |
| 410 | id: string; |
| 411 | agent_id: string; |
| 412 | scope: AgentMemoryScope; |
| 413 | /** The channel's id or the person's user id; empty for `workspace`. */ |
| 414 | scope_ref: string; |
| 415 | /** The channel's name or the person's username, for display. */ |
| 416 | scope_label: string | null; |
| 417 | body: string; |
| 418 | source_kind: "message" | "session" | "person"; |
| 419 | /** A message id, a session id, or the username of who wrote it. */ |
| 420 | source_ref: string | null; |
| 421 | source_label: string | null; |
| 422 | /** The channel the source is in, for a link. */ |
| 423 | source_channel_id: string | null; |
| 424 | created_by: string; |
| 425 | created_by_kind: "agent" | "user"; |
| 426 | pinned: boolean; |
| 427 | created_at: string; |
| 428 | updated_at: string; |
| 429 | }; |
| 430 | |
| 431 | /** When a routine runs, in UTC. */ |
| 432 | export type RoutineSchedule = { |
| 433 | every: "hour" | "day" | "weekday" | "week"; |
| 434 | /** Minute of the hour, 0 to 59. */ |
| 435 | minute: number; |
| 436 | /** Hour of the day (UTC), 0 to 23; not used for `hour`. */ |
| 437 | hour: number; |
| 438 | /** Day of the week for `week`, 0 (Sunday) to 6. */ |
| 439 | weekday: number; |
| 440 | }; |
| 441 | |
| 442 | /** |
| 443 | * Things that happen in the workspace a routine can run on |
| 444 | * (docs.g1t.sh/guides/agent-routines/). Each run is one session about the one |
| 445 | * thing that happened, in a repository its sponsor can read. |
| 446 | */ |
| 447 | export const ROUTINE_EVENTS = [ |
| 448 | { key: "pull_ready", label: "A pull request is ready for review", hint: "Opened ready, or moved out of draft." }, |
| 449 | { key: "pull_merged", label: "A pull request is merged", hint: "On any branch it targets." }, |
| 450 | { key: "checks_failed", label: "Checks fail on a pull request", hint: "Its required checks failed or errored." }, |
| 451 | { key: "issue_opened", label: "An issue is opened", hint: "By a person or an agent." }, |
| 452 | { key: "deploy_failed", label: "A deploy fails", hint: "A production or preview deploy." }, |
| 453 | ] as const; |
| 454 | |
| 455 | export type RoutineEvent = (typeof ROUTINE_EVENTS)[number]["key"]; |
| 456 | |
| 457 | /** |
| 458 | * A routine: work an agent does on a schedule or when something happens, such as Sam's Monday digest |
| 459 | * of support themes. Each run is a session posted in the routine's channel, |
| 460 | * paid from the agent's budget, and run with the access of the person who |
| 461 | * set it up (its sponsor), never more. |
| 462 | */ |
| 463 | export type AgentRoutine = { |
| 464 | id: string; |
| 465 | agent_id: string; |
| 466 | name: string; |
| 467 | instructions: string; |
| 468 | /** When it runs on a clock; null when it runs only on events. */ |
| 469 | schedule: RoutineSchedule | null; |
| 470 | /** What it runs on; empty when it runs only on its schedule. */ |
| 471 | events: RoutineEvent[]; |
| 472 | /** Which repositories its events come from, by `workspace/name`; empty: every one its sponsor can read. */ |
| 473 | repos: string[]; |
| 474 | channel_id: string; |
| 475 | channel_name: string | null; |
| 476 | sponsor: string; |
| 477 | sponsor_username: string | null; |
| 478 | enabled: boolean; |
| 479 | /** Why g1t paused it, when it did. */ |
| 480 | paused_note: string | null; |
| 481 | next_run_at: string | null; |
| 482 | last_run_at: string | null; |
| 483 | last_session_id: string | null; |
| 484 | runs: number; |
| 485 | created_at: string; |
| 486 | updated_at: string; |
| 487 | }; |
| 488 | |
| 489 | /** A routine suggested from an agent's responsibilities, for an owner to add in one step. */ |
| 490 | export type RoutineSuggestion = { responsibility: string; routine: Omit<NewRoutine, "channel_id"> }; |
| 491 | |
| 492 | export type NewRoutine = { |
| 493 | name: string; |
| 494 | instructions: string; |
| 495 | /** A schedule, events, or both; at least one. */ |
| 496 | schedule: RoutineSchedule | null; |
| 497 | events?: RoutineEvent[]; |
| 498 | repos?: string[]; |
| 499 | /** A channel the agent is in, by id. */ |
| 500 | channel_id: string; |
| 501 | enabled?: boolean; |
| 502 | }; |
| 503 | |
| 504 | /** |
| 505 | * The workspace's say over all its agents together, set by owners: one |
| 506 | * monthly budget across every agent, the budget a new agent starts with, |
| 507 | * and the cap a session starts with. The workspace's spend limit and AI |
| 508 | * credit (billing) sit above all of it. |
| 509 | */ |
| 510 | export type AgentPolicy = { |
| 511 | /** Every agent's spend together in a month. Null: only the workspace's spend limit. */ |
| 512 | monthly_micros: number | null; |
| 513 | /** The monthly budget a new agent gets. Null: none. */ |
| 514 | default_agent_monthly_micros: number | null; |
| 515 | /** The cap one session starts with, unless its agent's per-task cap is lower. */ |
| 516 | default_session_micros: number; |
| 517 | }; |
| 518 | |
| 519 | export type SpendSlice = { key: string; label: string; micros: number; count: number }; |
| 520 | |
| 521 | /** Where an agent's (or every agent's) month went. */ |
| 522 | export type AgentSpendBreakdown = { |
| 523 | period: string; |
| 524 | total_micros: number; |
| 525 | /** Chat replies, sessions, routines, helping colleagues. */ |
| 526 | by_kind: SpendSlice[]; |
| 527 | by_model: SpendSlice[]; |
| 528 | /** Who asked: the work done for each person. */ |
| 529 | by_person: SpendSlice[]; |
| 530 | by_agent: SpendSlice[]; |
| 531 | by_team: SpendSlice[]; |
| 532 | /** The costliest sessions this month. */ |
| 533 | top_sessions: AgentSession[]; |
| 534 | /** Spend by day this month. */ |
| 535 | days: { day: string; micros: number }[]; |
| 536 | }; |
| 537 | |
| 538 | /** Agents mode's front page. */ |
| 539 | export type AgentsOverview = { |
| 540 | policy: AgentPolicy; |
| 541 | /** Every agent's spend this month, against the policy's budget. */ |
| 542 | spent_month_micros: number; |
| 543 | /** The highest alert this month: 75, 90 or 100 (% of the workspace's agent budget). */ |
| 544 | alert: number | null; |
| 545 | agents: WorkspaceAgent[]; |
| 546 | /** Live sessions, counted by agent id, for the roster. */ |
| 547 | live_by_agent: Record<string, number>; |
| 548 | /** Sessions live now that the viewer can see. */ |
| 549 | live: AgentSession[]; |
| 550 | /** Sessions waiting on the viewer: spend they may approve. */ |
| 551 | waiting_on_you: AgentSession[]; |
| 552 | /** Recently finished sessions the viewer can see. */ |
| 553 | recent: AgentSession[]; |
| 554 | /** The next routines to run on a schedule. */ |
| 555 | upcoming: (AgentRoutine & { agent_handle: string; agent_name: string })[]; |
| 556 | spend: AgentSpendBreakdown; |
| 557 | can_manage: boolean; |
| 558 | }; |
| 559 | |
| 560 | /** One thing an agent did, for its Activity tab. */ |
| 561 | export type AgentActivity = { |
| 562 | id: string; |
| 563 | kind: "reply" | "session"; |
| 564 | status: string; |
| 565 | channel_id: string; |
| 566 | channel_name: string | null; |
| 567 | /** The session's title; null for a reply or one the viewer can't see. */ |
| 568 | title: string | null; |
| 569 | asked_by_username: string | null; |
| 570 | model: string | null; |
| 571 | tools: number; |
| 572 | charged_micros: number; |
| 573 | created_at: string; |
| 574 | visible: boolean; |
| 575 | /** For a reply, the message it posted; for a session, its id. */ |
| 576 | ref: string | null; |
| 577 | }; |
| 578 | |
| 579 | export type AgentVersion = { version: number; changed_by: string; created_at: string; definition: Partial<NewWorkspaceAgent> }; |
| 580 | |
| 581 | /** A card action, as chat hands it to agents. */ |
| 582 | export type AgentCardAction = { |
| 583 | workspace: string; |
| 584 | channel_id: string; |
| 585 | message_id: string; |
| 586 | viewer: User; |
| 587 | card: { kind: string; ref: string | null }; |
| 588 | action_id: string; |
| 589 | input: string | null; |
| 590 | }; |
| 591 | |
| 592 | export type WorkspaceAgentsApi = { |
| 593 | list(workspace: string, viewer: User): Promise<Result<WorkspaceAgent[]>>; |
| 594 | get(workspace: string, handle: string, viewer: User): Promise<Result<WorkspaceAgent>>; |
| 595 | /** Internal: by id, for the chat service resolving members. */ |
| 596 | byIds(ids: string[]): Promise<WorkspaceAgent[]>; |
| 597 | create(workspace: string, viewer: User, input: NewWorkspaceAgent): Promise<Result<WorkspaceAgent>>; |
| 598 | update( |
| 599 | workspace: string, |
| 600 | handle: string, |
| 601 | viewer: User, |
| 602 | changes: Partial<NewWorkspaceAgent>, |
| 603 | ): Promise<Result<WorkspaceAgent>>; |
| 604 | archive(workspace: string, handle: string, viewer: User): Promise<Result<null>>; |
| 605 | templates(): Promise<AgentTemplate[]>; |
| 606 | /** |
| 607 | * Internal: the workspace's built-in `@g1t` agent, made if it does not |
| 608 | * exist yet. The chat service asks for it when someone mentions @g1t in |
| 609 | * a channel it is not in yet. |
| 610 | */ |
| 611 | builtin(workspace: string, workspaceId: string): Promise<Result<WorkspaceAgent>>; |
| 612 | /** The chat service hands over a message for an agent to answer. Returns at once. */ |
| 613 | deliver(delivery: AgentDelivery): Promise<Result<null>>; |
| 614 | overview(workspace: string, viewer: User): Promise<Result<AgentsOverview>>; |
| 615 | sessions( |
| 616 | workspace: string, |
| 617 | viewer: User, |
| 618 | filter?: { handle?: string | null; status?: "live" | "done" | null; limit?: number | null }, |
| 619 | ): Promise<Result<AgentSession[]>>; |
| 620 | session(workspace: string, id: string, viewer: User): Promise<Result<AgentSessionDetail>>; |
| 621 | /** Stops a session and every session under it. */ |
| 622 | stopSession(workspace: string, id: string, viewer: User): Promise<Result<AgentSession>>; |
| 623 | /** Raises a stopped session's cap and lets it go on. Owners only. */ |
| 624 | approveSession(workspace: string, id: string, viewer: User, capMicros: number): Promise<Result<AgentSession>>; |
| 625 | /** A person's message to a session, running or finished: it reads it and goes on. */ |
| 626 | steerSession(workspace: string, id: string, viewer: User, body: string): Promise<Result<AgentSession>>; |
| 627 | memories(workspace: string, handle: string, viewer: User): Promise<Result<AgentMemory[]>>; |
| 628 | remember( |
| 629 | workspace: string, |
| 630 | handle: string, |
| 631 | viewer: User, |
| 632 | input: { body: string; scope: AgentMemoryScope; scope_ref?: string | null }, |
| 633 | ): Promise<Result<AgentMemory>>; |
| 634 | updateMemory( |
| 635 | workspace: string, |
| 636 | handle: string, |
| 637 | viewer: User, |
| 638 | id: string, |
| 639 | changes: { body?: string; pinned?: boolean }, |
| 640 | ): Promise<Result<AgentMemory>>; |
| 641 | forget(workspace: string, handle: string, viewer: User, id: string): Promise<Result<null>>; |
| 642 | routines(workspace: string, handle: string, viewer: User): Promise<Result<{ routines: AgentRoutine[]; suggestions: RoutineSuggestion[] }>>; |
| 643 | saveRoutine(workspace: string, handle: string, viewer: User, input: NewRoutine, id?: string | null): Promise<Result<AgentRoutine>>; |
| 644 | deleteRoutine(workspace: string, handle: string, viewer: User, id: string): Promise<Result<null>>; |
| 645 | /** Runs a routine now, as a session. */ |
| 646 | runRoutine(workspace: string, handle: string, viewer: User, id: string): Promise<Result<AgentSession>>; |
| 647 | /** Where the month went: one agent's, or every agent's. */ |
| 648 | spend(workspace: string, viewer: User, handle?: string | null): Promise<Result<AgentSpendBreakdown>>; |
| 649 | activity(workspace: string, handle: string, viewer: User): Promise<Result<AgentActivity[]>>; |
| 650 | versions(workspace: string, handle: string, viewer: User): Promise<Result<AgentVersion[]>>; |
| 651 | /** |
| 652 | * Internal, from chat: a person pressed an action on one of agents' |
| 653 | * cards. Agents checks they may, acts, and updates the card. |
| 654 | */ |
| 655 | cardAction(input: AgentCardAction): Promise<Result<CardActionResult>>; |
| 656 | policy(workspace: string, viewer: User): Promise<Result<AgentPolicy>>; |
| 657 | setPolicy(workspace: string, viewer: User, policy: Partial<AgentPolicy>): Promise<Result<AgentPolicy>>; |
| 658 | }; |
| 659 | |
| 660 | async function rpc<T>(service: ServiceBinding, method: string, args: object): Promise<T> { |
| 661 | const response = await service.fetch(`https://service/rpc/${method}`, { |
| 662 | method: "POST", |
| 663 | headers: { "content-type": "application/json" }, |
| 664 | body: JSON.stringify(args), |
| 665 | }); |
| 666 | if (!response.ok) { |
| 667 | throw new Error(`${method} failed with status ${response.status}`); |
| 668 | } |
| 669 | return (await response.json()) as T; |
| 670 | } |
| 671 | |
| 672 | export function workspaceAgentsClient(service: ServiceBinding): WorkspaceAgentsApi { |
| 673 | const call = <T>(method: string, args: object) => rpc<T>(service, method, args); |
| 674 | return { |
| 675 | list: (workspace, viewer) => call("list", { workspace, viewer }), |
| 676 | get: (workspace, handle, viewer) => call("get", { workspace, handle, viewer }), |
| 677 | byIds: (ids) => call("by_ids", { ids }), |
| 678 | create: (workspace, viewer, input) => call("create", { workspace, viewer, input }), |
| 679 | update: (workspace, handle, viewer, changes) => call("update", { workspace, handle, viewer, changes }), |
| 680 | archive: (workspace, handle, viewer) => call("archive", { workspace, handle, viewer }), |
| 681 | templates: () => call("templates", {}), |
| 682 | builtin: (workspace, workspaceId) => call("builtin", { workspace, workspace_id: workspaceId }), |
| 683 | deliver: (delivery) => call("deliver", delivery), |
| 684 | overview: (workspace, viewer) => call("overview", { workspace, viewer }), |
| 685 | sessions: (workspace, viewer, filter) => call("sessions", { workspace, viewer, ...(filter ?? {}) }), |
| 686 | session: (workspace, id, viewer) => call("session", { workspace, id, viewer }), |
| 687 | stopSession: (workspace, id, viewer) => call("stop_session", { workspace, id, viewer }), |
| 688 | approveSession: (workspace, id, viewer, capMicros) => call("approve_session", { workspace, id, viewer, cap_micros: capMicros }), |
| 689 | steerSession: (workspace, id, viewer, body) => call("steer_session", { workspace, id, viewer, body }), |
| 690 | memories: (workspace, handle, viewer) => call("memories", { workspace, handle, viewer }), |
| 691 | remember: (workspace, handle, viewer, input) => call("remember", { workspace, handle, viewer, input }), |
| 692 | updateMemory: (workspace, handle, viewer, id, changes) => call("update_memory", { workspace, handle, viewer, id, changes }), |
| 693 | forget: (workspace, handle, viewer, id) => call("forget", { workspace, handle, viewer, id }), |
| 694 | routines: (workspace, handle, viewer) => call("routines", { workspace, handle, viewer }), |
| 695 | saveRoutine: (workspace, handle, viewer, input, id) => call("save_routine", { workspace, handle, viewer, input, id: id ?? null }), |
| 696 | deleteRoutine: (workspace, handle, viewer, id) => call("delete_routine", { workspace, handle, viewer, id }), |
| 697 | runRoutine: (workspace, handle, viewer, id) => call("run_routine", { workspace, handle, viewer, id }), |
| 698 | spend: (workspace, viewer, handle) => call("spend", { workspace, viewer, handle: handle ?? null }), |
| 699 | activity: (workspace, handle, viewer) => call("activity", { workspace, handle, viewer }), |
| 700 | versions: (workspace, handle, viewer) => call("versions", { workspace, handle, viewer }), |
| 701 | cardAction: (input) => call("card_action", input), |
| 702 | policy: (workspace, viewer) => call("policy", { workspace, viewer }), |
| 703 | setPolicy: (workspace, viewer, policy) => call("set_policy", { workspace, viewer, policy }), |
| 704 | }; |
| 705 | } |