| 1 | /** |
| 2 | * `@g1t`, every workspace's built-in orchestrator |
| 3 | * (docs.g1t.sh/guides/agents/, "g1t, the orchestrator"). Pure, so it is |
| 4 | * tested on its own. |
| 5 | * |
| 6 | * It is an agent row like any other, marked builtin, so it is billed, |
| 7 | * gated, routed and audited the same way. What sets it apart is here: |
| 8 | * the fields nobody may change, the job it always has, the roster of |
| 9 | * specialists it is given, and the rails on how it delegates. |
| 10 | */ |
| 11 | import type { AgentStatus, ModelTier, NewWorkspaceAgent } from "@g1t/contracts"; |
| 12 | |
| 13 | import { BUILTIN_AGENT_HANDLE, ORCHESTRATOR_TEMPLATE } from "../../../packages/contracts/src/workspace-agents.ts"; |
| 14 | import { type Checked, type Definition, DEFAULT_AUTONOMY, DEFAULT_BUDGET, DEFAULT_CAPACITY, DEFAULT_ROUTING } from "./definition.ts"; |
| 15 | import { MAX_HAND_OFFS } from "./tools.ts"; |
| 16 | |
| 17 | export const BUILTIN_ROLE = "Your orchestrator: delegates to the team's agents, or does the work itself"; |
| 18 | |
| 19 | /** What a new workspace's @g1t starts as. `instructions` are the workspace's additions, none at first. */ |
| 20 | export function builtinDefinition(): Definition { |
| 21 | return { |
| 22 | handle: BUILTIN_AGENT_HANDLE, |
| 23 | display_name: "g1t", |
| 24 | role: BUILTIN_ROLE, |
| 25 | instructions: "", |
| 26 | personality_preset: "friendly", |
| 27 | personality: "", |
| 28 | routing: DEFAULT_ROUTING, |
| 29 | budget: DEFAULT_BUDGET, |
| 30 | autonomy: DEFAULT_AUTONOMY, |
| 31 | capacity: DEFAULT_CAPACITY, |
| 32 | template: ORCHESTRATOR_TEMPLATE, |
| 33 | avatar_seed: BUILTIN_AGENT_HANDLE, |
| 34 | title: "Orchestrator", |
| 35 | team: null, |
| 36 | department: "", |
| 37 | responsibilities: [], |
| 38 | subagents: [], |
| 39 | faces: "internal", |
| 40 | reading: [], |
| 41 | }; |
| 42 | } |
| 43 | |
| 44 | /** What nobody may change on the built-in agent: who it is and what its job is. */ |
| 45 | export const PROTECTED: (keyof NewWorkspaceAgent)[] = [ |
| 46 | "handle", |
| 47 | "display_name", |
| 48 | "role", |
| 49 | "title", |
| 50 | "team", |
| 51 | "department", |
| 52 | "responsibilities", |
| 53 | "subagents", |
| 54 | "template", |
| 55 | "faces", |
| 56 | ]; |
| 57 | |
| 58 | /** |
| 59 | * `changes` to the built-in agent with its fixed fields taken out, whatever |
| 60 | * they say: a profile form sends every field (an empty title, no |
| 61 | * responsibilities), and only the editable ones apply. |
| 62 | */ |
| 63 | export function builtinChanges(_current: Definition, changes: Partial<NewWorkspaceAgent>): Checked<Partial<NewWorkspaceAgent>> { |
| 64 | if (!changes || typeof changes !== "object") return { ok: false, message: "Send the agent's fields." }; |
| 65 | const rest: Partial<NewWorkspaceAgent> = { ...changes }; |
| 66 | for (const key of PROTECTED) delete rest[key]; |
| 67 | return { ok: true, value: rest }; |
| 68 | } |
| 69 | |
| 70 | /** One specialist as @g1t sees it. */ |
| 71 | export type Specialist = { |
| 72 | handle: string; |
| 73 | display_name: string; |
| 74 | role: string; |
| 75 | title?: string; |
| 76 | team?: string | null; |
| 77 | department?: string; |
| 78 | responsibilities?: string[]; |
| 79 | status: AgentStatus; |
| 80 | spent_month_micros: number; |
| 81 | /** The monthly cap, or null for none. */ |
| 82 | monthly_micros: number | null; |
| 83 | }; |
| 84 | |
| 85 | const STATUS_WORDS: Record<AgentStatus, string> = { |
| 86 | idle: "idle", |
| 87 | working: "working", |
| 88 | waiting: "waiting on someone", |
| 89 | out_of_budget: "out of budget", |
| 90 | paused: "paused", |
| 91 | }; |
| 92 | |
| 93 | const dollars = (micros: number) => `$${(Math.max(0, micros) / 1_000_000).toFixed(2)}`; |
| 94 | |
| 95 | /** Where a specialist sits: "QA Engineer on the qa team", "QA Engineer, QA", or its role. */ |
| 96 | function placeLine(agent: Specialist): string { |
| 97 | const title = agent.title?.trim(); |
| 98 | if (!title) return agent.role.replace(/\.$/, ""); |
| 99 | if (agent.team) return `${title} on the ${agent.team} team`; |
| 100 | return agent.department?.trim() ? `${title}, ${agent.department.trim()}` : title; |
| 101 | } |
| 102 | |
| 103 | /** |
| 104 | * The roster, one line per specialist, so g1t can route "QA should look" |
| 105 | * to the right one: `- @margo (Margo): QA Engineer, QA. Does: review pull |
| 106 | * requests; write test plans. idle; $1.20 of $20.00 this month.` |
| 107 | */ |
| 108 | export function rosterLines(specialists: Specialist[]): string { |
| 109 | if (!specialists.length) return "There are no specialists in this workspace yet."; |
| 110 | return specialists |
| 111 | .map((agent) => { |
| 112 | const name = agent.display_name && agent.display_name.toLowerCase() !== agent.handle ? ` (${agent.display_name})` : ""; |
| 113 | const spend = agent.monthly_micros ? `${dollars(agent.spent_month_micros)} of ${dollars(agent.monthly_micros)}` : `${dollars(agent.spent_month_micros)}, no cap`; |
| 114 | const duties = agent.responsibilities?.length ? ` Does: ${agent.responsibilities.map((d) => d.replace(/\.$/, "")).join("; ")}.` : ""; |
| 115 | return `- @${agent.handle}${name}: ${placeLine(agent)}.${duties} ${STATUS_WORDS[agent.status] ?? agent.status}; ${spend} this month.`; |
| 116 | }) |
| 117 | .join("\n"); |
| 118 | } |
| 119 | |
| 120 | /** The most colleagues one reply may hand work to (the hand_off tool's rail). */ |
| 121 | export const MAX_DELEGATES = MAX_HAND_OFFS; |
| 122 | |
| 123 | /** @g1t's job: fixed, whatever the workspace adds. */ |
| 124 | export function orchestratorInstructions(specialists: Specialist[], extra: string): string { |
| 125 | const available = specialists.filter((agent) => agent.status !== "out_of_budget" && agent.status !== "paused"); |
| 126 | const job = [ |
| 127 | "You are the workspace's orchestrator. People come to you when they don't know who should do something. You either answer, hand the work to the right specialist, or do it yourself.", |
| 128 | "", |
| 129 | "### The team", |
| 130 | "", |
| 131 | rosterLines(specialists), |
| 132 | "", |
| 133 | "### How you decide", |
| 134 | "", |
| 135 | "1. **Answer directly** when it is a question, a summary or a quick judgment you can give from this conversation.", |
| 136 | "2. **Delegate** when a specialist's role fits the work: call hand_off with their handle and a crisp brief, written to them: what is wanted, why, what done looks like, and any constraint (deadlines, what not to touch). If they are in this conversation the brief is posted here; otherwise a group message opens with the person who asked, you and them, and a card here links to it. Then tell the person in a sentence who has it and where.", |
| 137 | "3. **Do it yourself, or suggest a specialist,** when nobody fits. Say so plainly, offer to take it on yourself, and if this kind of work will recur, suggest setting one up (for example: \"Want me to set up a release manager for this?\").", |
| 138 | "", |
| 139 | "### Rules for delegating", |
| 140 | "", |
| 141 | "- Only hand_off delegates. An @mention in your message wakes no agent and reaches nobody outside this conversation, so writing \"@mike, could you…\" hands nothing over.", |
| 142 | "- Describing the team is not delegating: name specialists without @ (\"Mike, our technical recruiter\") unless they are in this conversation.", |
| 143 | `- Hand off to at most ${MAX_DELEGATES} specialists for one message. Split bigger work into steps and hand off the next step when the first is done.`, |
| 144 | "- Never delegate in a loop: don't hand work back to a specialist who handed it to you, and don't hand the same work to the same specialist twice.", |
| 145 | "- Don't delegate to a specialist who is out of budget or paused; say they are unavailable and why.", |
| 146 | "- The person sees every hand-off, and their access still limits what any agent does for them.", |
| 147 | "- Once you've handed something off, let the specialist answer; speak again when someone asks you.", |
| 148 | "- When asked what everyone is working on, answer from the team list above.", |
| 149 | available.length ? "" : "\nNo specialist is available right now, so do the work yourself or suggest creating one.", |
| 150 | ].join("\n"); |
| 151 | const added = extra.trim(); |
| 152 | return added ? `${job}\n\n### Added by this workspace\n\n${added}` : job; |
| 153 | } |
| 154 | |
| 155 | /** How long a thread is before @g1t's delegation call is worth a larger model. */ |
| 156 | export const LONG_THREAD = 6; |
| 157 | |
| 158 | /** |
| 159 | * Where @g1t's reply starts: the small tier, or the large one for a |
| 160 | * delegation decision in a long thread (more than `LONG_THREAD` messages, |
| 161 | * with specialists to choose from). Its floor and ceiling apply after. |
| 162 | */ |
| 163 | export function orchestratorTier(messages: number, specialists: number): ModelTier { |
| 164 | return messages > LONG_THREAD && specialists > 0 ? "large" : "small"; |
| 165 | } |
| 166 | |
| 167 | /** The friendly notice when @g1t has no model to run on. */ |
| 168 | export const BUILTIN_NO_MODEL = |
| 169 | "Hi, I'm g1t. I'd love to help, but this workspace doesn't have a model I can use yet. An owner can add AI credit under Billing, or connect the workspace's own model provider under Integrations, and I'll be ready."; |