@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/agent-catalog.ts

@@ -8,7 +8,7 @@ import {
     type PermissionMode,
 } from "./schemas.js";
 
-/* The provider / harness / model catalog every picker shares (the chat menu, the automations dialog) — pure
+/* The provider / harness / model catalog every picker shares (the chat menu, the automations dialog), pure
  * data keyed by the wire vocabulary in schemas.ts, so the surfaces can't drift. Live state stays with the
  * consumer (native Grok's model list is the daemon's own catalog for it, layered on top of modelsFor by the
  * web; ACP providers are merged in from the installed `agent` capabilities). */
@@ -26,13 +26,13 @@ export const PROVIDERS: readonly { label: string; value: NativeProvider }[] = [
     { label: "Codex", value: "codex" },
     { label: "Grok", value: "grok" },
     { label: "Kimi Code", value: "kimi" },
-    // Labelled for the ACCOUNT, not the model family: the `gemini` id names one channel — Google's Antigravity —
+    // Labelled for the ACCOUNT, not the model family: the `gemini` id names one channel. Google's Antigravity,
     // and that channel vends Claude and GPT-OSS models alongside Gemini's own (see gemini-models.ts). A section
     // headed "Gemini" holding Claude Opus would be a lie; "Google" is what the whole list has in common.
     { label: "Google", value: "gemini" },
 ];
 
-// What it COSTS to unlock a provider, and what the user connects to do it — the axis the picker groups on, since
+// What it COSTS to unlock a provider, and what the user connects to do it, the axis the picker groups on, since
 // "can this row actually run" is the first thing a model list has to answer. `free` is not a courtesy tier: the
 // Google channel serves its models on an ordinary Google sign-in, at no subscription, which is the single most
 // useful thing this catalog can tell a user who has connected nothing yet.
@@ -40,7 +40,7 @@ export type AccessKind = "free" | "subscription" | "key";
 
 export interface ProviderAccess {
     readonly kind: AccessKind;
-    // What the user connects, named the way its vendor names it — this is the noun every connect prompt uses.
+    // What the user connects, named the way its vendor names it, this is the noun every connect prompt uses.
     readonly requirement: string;
     // What connecting it lets them run, for the connect gate's one-line pitch.
     readonly runs: string;
@@ -54,7 +54,7 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
     gemini: { kind: "free", requirement: "Google sign-in", runs: "Gemini, Claude and GPT-OSS under Claude Code" },
 };
 
-/* THE PROVIDERS THAT COST NOTHING — derived from the table above rather than named a second time, and read by
+/* THE PROVIDERS THAT COST NOTHING, derived from the table above rather than named a second time, and read by
  * every surface that LEADS with a free option instead of merely labelling one.
  *
  * The distinction is worth the export. `accessBadge` answers "what does this row cost" for a row the user is
@@ -65,7 +65,7 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
 export const FREE_PROVIDERS: readonly NativeProvider[] = NATIVE_PROVIDERS.filter((provider) => PROVIDER_ACCESS[provider].kind === "free");
 export const isFreeProvider = (provider: AgentProvider): boolean => FREE_PROVIDERS.includes(provider as NativeProvider);
 
-/* WHOSE ALLOWANCE A TURN ON THIS PROVIDER SPENDS, as the subject of a sentence — a third naming of the same
+/* WHOSE ALLOWANCE A TURN ON THIS PROVIDER SPENDS, as the subject of a sentence, a third naming of the same
  * five ids, and the third is not redundancy. PROVIDERS names the RUNTIME the user picks ("Claude Code", "Kimi
  * Code") and PROVIDER_ACCESS.requirement names the thing they CONNECT ("Claude subscription", "Google sign-in");
  * neither reads as English in "… usage limit reached", and neither is what a spent quota belongs to.
@@ -73,7 +73,7 @@ export const isFreeProvider = (provider: AgentProvider): boolean => FREE_PROVIDE
  * The routed providers are why this can't be inferred from the harness: a `gemini` turn drives Claude Opus 4.6
  * through Google's Antigravity channel on a plain Google sign-in, so the quota that refuses it is Google's and
  * Anthropic has no part in it. Saying "Claude usage limit reached" there sends the user to check the wrong
- * account — and to a reset that is days out on a pool they never touched. */
+ * account, and to a reset that is days out on a pool they never touched. */
 export const PROVIDER_VENDOR: Record<NativeProvider, string> = {
     claude: "Claude",
     codex: "ChatGPT",
@@ -85,50 +85,50 @@ export const PROVIDER_VENDOR: Record<NativeProvider, string> = {
 // What a turn on this provider costs at the MARGIN, ordering the same three kinds by the only question a
 // helper spending the user's money on their behalf has to answer: free is free; a subscription is already paid
 // but has a quota the user watches; a key is metered, so every call is real money. Deliberately not folded into
-// AccessKind's declaration order — a union's order is not a runtime fact, and this one is load-bearing.
+// AccessKind's declaration order, a union's order is not a runtime fact, and this one is relied on.
 export const ACCESS_COST: Record<AccessKind, number> = { free: 0, subscription: 1, key: 2 };
 
-/* THE PROVIDER ID OF AN `endpoint` CAPABILITY — a model API the user pointed us at, native or not, near or far.
+/* THE PROVIDER ID OF AN `endpoint` CAPABILITY, a model API the user pointed us at, native or not, near or far.
  *
  * Namespaced rather than bare (which is what ACP agents are) because the two kinds mint providers with OPPOSITE
  * ability records: an ACP agent brings its own loop and gets the documented ACP floor, while an endpoint is
  * driven BY the Claude Code loop and gets its full ceiling. capabilitiesOf answers that from the id alone, so
  * the prefix is what keeps it a pure function of (provider, harness) instead of a lookup against the installed
- * manifest — which the contract cannot see and the browser would have to pass in everywhere.
+ * manifest, which the contract cannot see and the browser would have to pass in everywhere.
  *
  * A SLASH, never a colon: `${provider}:${model}` is the picker's own key shape, and quick-model.ts's parsePinned
  * splits a pinned selection on the FIRST colon. `endpoint:ollama:qwen3` would parse as provider "endpoint" with
- * model "ollama:qwen3" — a pin that silently resolves to nothing. The capability id (entryId) excludes both
+ * model "ollama:qwen3", a pin that silently resolves to nothing. The capability id (entryId) excludes both
  * characters, so `endpoint/<id>` stays unambiguous in either direction. */
-/* THE FREE TRIAL'S ENDPOINT ID IS RESERVED, the way `pi` is — an `endpoint`-kind capability like any model API
+/* THE FREE TRIAL'S ENDPOINT ID IS RESERVED, the way `pi` is, an `endpoint`-kind capability like any model API
  * the user configured, except that this one is provisioned by the DAEMON rather than added by a person, and it
  * points at intentic's own pool (see the sandbox's trial/ and the platform's /trial routes).
  *
  * Riding the endpoint kind is the entire reason the trial needed no new turn path, no new provider and no new
  * adapter: the translator already re-serves an OpenAI-compatible upstream to the Claude Code loop, so a trial
- * turn is an endpoint turn and everything downstream — catalog, picker, routing — works unchanged.
+ * turn is an endpoint turn and everything downstream, catalog, picker, routing, works unchanged.
  *
  * What the reserved id buys is the part that must NOT look the same. A trial turn passes through intentic's
  * servers, which no other provider in this product does, and a user cannot consent to something they were not
- * told. So every surface that names a provider asks `isTrialProvider` and says so, and the id is here — beside
- * the vocabulary those surfaces already read — rather than spelled out in each of them. */
+ * told. So every surface that names a provider asks `isTrialProvider` and says so, and the id is here, beside
+ * the vocabulary those surfaces already read, rather than spelled out in each of them. */
 export const TRIAL_ENDPOINT_ID = "free-trial";
 export const TRIAL_PROVIDER = "endpoint/free-trial";
 export const isTrialProvider = (provider: AgentProvider): boolean => provider === TRIAL_PROVIDER;
 
-/* THE ONLY MODEL THE TRIAL PUBLISHES — a synthetic id, not one of Google's, and that is the point.
+/* THE ONLY MODEL THE TRIAL PUBLISHES, a synthetic id, not one of Google's, and that is the point.
  *
  * The trial used to publish whatever the upstream listed. Two things were wrong with that and neither could be
  * fixed by filtering harder. Google lists ~54 models on a fresh key and declares `generateContent` for many that
- * cannot serve an agent turn — deep-research, antigravity, gemma, robotics and computer-use previews all pass a
- * capability check and then fail the first message — so the picker was full of rows whose only outcome was an
+ * cannot serve an agent turn, deep-research, antigravity, gemma, robotics and computer-use previews all pass a
+ * capability check and then fail the first message, so the picker was full of rows whose only outcome was an
  * error. And the list MOVED: the translator's routing table is written at boot and on capability edits, while
  * the picker re-reads the catalog every minute, so a model discovered in between was pickable and unroutable,
  * refused with "unknown provider for model".
  *
  * One id, never changing, ends both. There is nothing to filter because nothing is discovered, and the routing
  * table cannot drift from a list of one constant. WHICH real model answers is decided per message by the
- * platform, which is the only party that can see which of its keys still has quota on which model — the sandbox
+ * platform, which is the only party that can see which of its keys still has quota on which model, the sandbox
  * cannot, and a user choosing blind between rows they know nothing about was never a choice worth offering. */
 export const TRIAL_MODEL_ID = "auto";
 // What the picker calls it, and the sentence the surfaces put underneath. One wording, so the composer's notice
@@ -143,28 +143,28 @@ export const isEndpointProvider = (provider: AgentProvider): boolean => provider
 export const endpointIdOf = (provider: AgentProvider): string | undefined =>
     isEndpointProvider(provider) ? provider.slice(ENDPOINT_PROVIDER_PREFIX.length) : undefined;
 
-// An ACP provider carries its own credentials — installed means runnable — so it has no access requirement at
+// An ACP provider carries its own credentials, installed means runnable, so it has no access requirement at
 // all; `undefined` is that state, and every surface reads it as "nothing to connect". An endpoint is the same
 // answer for a different reason: its credential (if it even needs one) was configured with the endpoint itself,
-// so there is likewise nothing left to connect. What a turn on it COSTS is deliberately not claimed here — a
+// so there is likewise nothing left to connect. What a turn on it COSTS is deliberately not claimed here, a
 // self-hosted model on the user's own GPU and a metered gateway key are the same shape to us, and inventing an
 // AccessKind for them would have the picker assert a price the daemon has no way to know.
 export const accessFor = (provider: AgentProvider): ProviderAccess | undefined => PROVIDER_ACCESS[provider as NativeProvider];
 
-// An ACP provider's label is its capability's display name, which the web layers on top — the raw id is the
+// An ACP provider's label is its capability's display name, which the web layers on top, the raw id is the
 // static fallback.
 export const providerLabel = (provider: AgentProvider): string => PROVIDERS.find((p) => p.value === provider)?.label ?? provider;
 
-/* Whether a plan-limit reading for this provider is OBTAINABLE at all — one fact, on the wire, because both
+/* Whether a plan-limit reading for this provider is OBTAINABLE at all, one fact, on the wire, because both
  * halves need it and they need the same answer. The daemon reads it to decide what to even ask upstream for
  * (usage/translator-usage.ts); the browser reads it to say WHY an account shows no meter, which is the
- * difference between "this plan publishes nothing" and "we haven't measured yet" — two states that look
+ * difference between "this plan publishes nothing" and "we haven't measured yet", two states that look
  * identical as a blank row and mean opposite things.
  *
  * Four can be read, by two mechanisms that stop at the daemon's readers: Claude's rides its own turn (the
  * OAuth usage endpoint, agent.ts), ChatGPT's, Google's and Kimi's are pulled through the translator's
  * credential-scoped api-call. Kimi's endpoint is the platform's own `/coding/v1/usages`, which the Kimi Code
- * subscription's OAuth token reads directly — the bundled translator does not route it, but it does not have
+ * subscription's OAuth token reads directly, the bundled translator does not route it, but it does not have
  * to: the api-call substitutes that token server-side like it does for the other two.
  *
  * Grok is the one absence, because xAI's usable billing data needs a subject id CLIProxyAPI keeps out of its
@@ -176,28 +176,28 @@ export const reportsPlanLimits = (provider: AgentProvider): boolean => PLAN_LIMI
 // The harness (agentic loop) a turn runs on, orthogonal to the provider. `native` = the provider's own runtime;
 // `claude-code` = the Claude Code loop for any provider (codex/grok then route through the translator).
 // Surfaced for codex/grok alone. Claude is always its own Claude Code loop; kimi has no native runtime to switch
-// to (it only exists under this harness); and GEMINI IS THE MIRROR OF KIMI — it only exists under its native
+// to (it only exists under this harness); and GEMINI IS THE MIRROR OF KIMI, it only exists under its native
 // one, because Google refuses Claude Code's traffic outright (capabilitiesOf says why). See AgentHarness in
 // schemas.ts.
 //
 // Gemini's `native` is OpenCode rather than a Google CLI: the image ships no Gemini binary, and OpenCode is
-// already here driving Grok. It spends the same translator accounts a routed turn would have — what Google
+// already here driving Grok. It spends the same translator accounts a routed turn would have, what Google
 // refuses is the loop, never the credential.
 export const HARNESSES: readonly { label: string; value: AgentHarness }[] = [
     { label: "Native", value: "native" },
     { label: "Claude Code", value: "claude-code" },
 ];
 
-/* WHAT A PROVIDER/HARNESS PAIR CAN ACTUALLY DO — one declaration, read by both sides of the wire.
+/* WHAT A PROVIDER/HARNESS PAIR CAN ACTUALLY DO, one declaration, read by both sides of the wire.
  *
  * Five runtimes serve turns behind one seam (AgentRequest in, AgentEvent frames out): the Claude Code Agent SDK
  * loop, Codex app-server, OpenCode, any ACP agent, and Pi's RPC surface. They do NOT do the same things, and for a long time
- * the only thing that said so was a comment inside each adapter — "Ignores the Claude-only request fields" —
+ * the only thing that said so was a comment inside each adapter, "Ignores the Claude-only request fields",
  * which no surface above it could read. So the composer offered "Ask before each file edit" on a runtime whose
  * every tool call is pre-approved, and offered a reasoning-effort scale to a runtime that drops the field.
  *
  * A capability is listed here only if something READS it: the daemon gates a seam on it, the composer hides or
- * clamps a control by it, or `limitationsOf` tells the user about it. That is the whole point — an ability the
+ * clamps a control by it, or `limitationsOf` tells the user about it. That is the whole point, an ability the
  * matrix claims and nothing consults is how the drift started.
  *
  * Adding a provider is a row here, not a hunt for literals; agent-catalog.test.ts walks PROVIDERS × HARNESSES
@@ -205,11 +205,11 @@ export const HARNESSES: readonly { label: string; value: AgentHarness }[] = [
 
 // An execution backend: one way a turn runs work of its own, named for the AgentCapabilities.execution axis
 // and for the persona switch that grants it. Adding a language is a member here and a backend in the daemon's
-// execution/ module — never a new one-off tool wired where nothing else can see it.
+// execution/ module, never a new one-off tool wired where nothing else can see it.
 export type ExecutionBackend = "shell" | "js";
 
 export interface AgentCapabilities {
-    // Which agentic loop actually serves the turn — the question "is the harness `claude-code`" only looks like.
+    // Which agentic loop actually serves the turn, the question "is the harness `claude-code`" only looks like.
     // Claude is always its own Claude Code loop and Kimi has no native runtime, so both run it whatever harness
     // the client sent; codex/grok/gemini each have a native runtime to switch away from. Names the session store
     // a finished conversation's transcript is backfilled from, too.
@@ -222,7 +222,7 @@ export interface AgentCapabilities {
     readonly steering: boolean;
     // How much of the permission-mode axis the runtime honours. "modes" = every PermissionMode, with per-tool
     // permission cards and `mode` frames when the agent moves itself; "plan" = propose-then-approve or run, and
-    // nothing in between — the container is the isolation boundary and every tool call is pre-approved.
+    // nothing in between, the container is the isolation boundary and every tool call is pre-approved.
     readonly permissions: "modes" | "plan";
     // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
     readonly questions: boolean;
@@ -232,14 +232,14 @@ export interface AgentCapabilities {
     // them at all. Keeping the partial answers distinct matters: a runtime that can drive a connected account
     // must not be described as tool-less, and one that cannot host daemon-side SDK servers must not claim full.
     readonly mcp: "full" | "browser" | "http" | "none";
-    /* WHICH EXECUTION BACKENDS THE RUNTIME HOSTS — the ways a turn RUNS things, as opposed to the tools it is
+    /* WHICH EXECUTION BACKENDS THE RUNTIME HOSTS, the ways a turn RUNS things, as opposed to the tools it is
      * handed. "shell" is the runtime's own command tool (Bash on the Claude Code loop, each foreign loop's
      * equivalent); "js" is the sandbox's JavaScript backend (execution/ in the daemon): the model writes a
      * script instead of a command line, and the daemon runs it in a permission-fenced Node subprocess.
      *
      * A first-class axis rather than a corollary of `mcp`, because the two answer different questions: `mcp`
      * says which TOOLS reach the model's context, this says which ways of EXECUTING the daemon can stand
-     * behind for this runtime — with the same guard, secret and persona seams the shell gets. A runtime that
+     * behind for this runtime, with the same guard, secret and persona seams the shell gets. A runtime that
      * cannot host a backend simply never shows it, and the persona switch for it (PersonaPowersSchema.code)
      * then has nothing to grant there. */
     readonly execution: readonly ExecutionBackend[];
@@ -247,14 +247,14 @@ export interface AgentCapabilities {
     readonly effort: boolean;
     /* The runtime can serve a turn at fast speed when asked (AgentTurn.fast). A statement about the LOOP, not
      * about the route: the Claude Code loop knows how to ask for it, which is why every provider this record
-     * hands the loop to reads true here — including the ones served through the translator, whose turns the
+     * hands the loop to reads true here, including the ones served through the translator, whose turns the
      * harness will then refuse fast mode for because a translator endpoint is not first-party. That second
      * question is answered where the endpoint is decided (planHarnessTurn), because it is a fact about the
      * CREDENTIAL rather than about the runtime, and this record is a pure function of (provider, harness). */
     readonly fastMode: boolean;
     // How an isolated conversation's worktree is enforced. "namespace" = the worktree IS /work inside the turn's
     // mount namespace (with the tool-input rewrite as the fallback when the container can't build one); "cwd" =
-    // the turn is merely cwd'd into the worktree, so an absolute /work path still reaches the shared checkout —
+    // the turn is merely cwd'd into the worktree, so an absolute /work path still reaches the shared checkout,
     // which is why those turns are told where their tree is (turn-preamble.ts).
     readonly isolation: "namespace" | "cwd";
     // Publishes its slash commands (`commands` frames) for the composer's `/` popover.
@@ -264,31 +264,31 @@ export interface AgentCapabilities {
     // Fails with the coded frames the daemon's auto-resume keys off (rate_limit, provider-outage), so a turn the
     // provider killed is re-run once the breaker says the provider is back (turn-resume.ts).
     readonly recovery: boolean;
-    /* HOW MUCH OF ITS STANDING INSTRUCTIONS THIS RUNTIME WILL TAKE FROM US — the axis behind the sandbox's
+    /* HOW MUCH OF ITS STANDING INSTRUCTIONS THIS RUNTIME WILL TAKE FROM US, the axis behind the sandbox's
      * system-prompt setting (SandboxSettings.systemPromptMode) and the persona's own override.
      *
      * It exists because that setting was silently a Claude Code setting. The composer offers Codex, Grok and
      * Gemini on their own runtimes, and a turn on any of them ignored the prompt the owner had written without
-     * saying so anywhere — the one failure mode a settings page cannot recover from, because nothing on screen
+     * saying so anywhere, the one failure mode a settings page cannot recover from, because nothing on screen
      * is wrong. Naming it here means every surface reads the same answer and the daemon composes to it
      * (agent/system-prompt.ts), rather than each learning the exception separately.
      *
-     *   "replace" — the whole base prompt can be swapped for the owner's text, and extra guidance appended on
+     *   "replace", the whole base prompt can be swapped for the owner's text, and extra guidance appended on
      *               top of whichever base is in force. The Claude Code loop (SDK `systemPrompt`) and native
      *               Codex (`model_instructions_file` replaces its base; `developer_instructions` adds a
-     *               developer message — both verified on the wire against codex-cli 0.147).
-     *   "append"  — extra system text only; the runtime's own base prompt stands. OpenCode takes one per
+     *               developer message, both verified on the wire against codex-cli 0.147).
+     *   "append" , extra system text only; the runtime's own base prompt stands. OpenCode takes one per
      *               message (`system` on the prompt body), and there is no seam for replacing its base.
-     *   "none"    — no system seam at all. What must still reach the model (the persona note) rides the user
+     *   "none"   , no system seam at all. What must still reach the model (the persona note) rides the user
      *               message instead, which is the door the delegation note already uses.
      *
-     * The BASE CHOICE — Intentic's prompt or Claude Code's — is a "replace" runtime's question and, of those,
+     * The BASE CHOICE. Intentic's prompt or Claude Code's, is a "replace" runtime's question and, of those,
      * only the Claude Code loop's: Codex's own base describes Codex's own tools, so swapping it for a prompt
      * written about another harness is the owner's deliberate act (their custom text), never ours. */
     readonly instructions: "replace" | "append" | "none";
 }
 
-// The Claude Code Agent SDK loop — the ceiling every other runtime is measured against, and the only one that
+// The Claude Code Agent SDK loop, the ceiling every other runtime is measured against, and the only one that
 // owns the whole request: permission callbacks, the ask tool, plugins, hooks, and the spawn seam a mount
 // namespace needs.
 const CLAUDE_CODE: AgentCapabilities = {
@@ -297,7 +297,7 @@ const CLAUDE_CODE: AgentCapabilities = {
     permissions: "modes",
     questions: true,
     mcp: "full",
-    // The one loop with a seam the daemon can put its own backend through — so it hosts the JS backend beside
+    // The one loop with a seam the daemon can put its own backend through, so it hosts the JS backend beside
     // its Bash. Every other runtime below hosts only its own shell.
     execution: ["shell", "js"],
     effort: true,
@@ -310,13 +310,13 @@ const CLAUDE_CODE: AgentCapabilities = {
 };
 
 /* Codex app-server: item-level events, process-backed MCP servers, and the four interactive seams its protocol
- * actually publishes — `turn/steer` for mid-turn injection, the experimental `item/tool/requestUserInput` server
+ * actually publishes, `turn/steer` for mid-turn injection, the experimental `item/tool/requestUserInput` server
  * request behind a question card, `skills/list` for the `/` popover (a picked command rides back as a structured
  * skill input), and the same mount namespace the Claude Code loop gets, because app-server is a child process
  * the adapter spawns and nsenter can put it in the turn's namespace like any other.
  *
  * Browser servers ride the per-thread config; daemon-side SDK servers, plugins and server-initiated APPROVALS
- * stay unwired — the container is the isolation boundary, so approvals are declined by design rather than
+ * stay unwired, the container is the isolation boundary, so approvals are declined by design rather than
  * missing (codex-app-server.ts refuses every server request but the question one). */
 const CODEX: AgentCapabilities = {
     runtime: "codex",
@@ -334,12 +334,12 @@ const CODEX: AgentCapabilities = {
     /* Both halves, through the per-thread `config` block the adapter already sends: `model_instructions_file`
      * takes the place of Codex's own base prompt, `developer_instructions` arrives as an extra developer
      * message ahead of its skills and team blocks. Verified against codex-cli 0.147 by reading what actually
-     * reached the wire — the keys are undocumented, and a strings dump proves only that they parse. */
+     * reached the wire, the keys are undocumented, and a strings dump proves only that they parse. */
     instructions: "replace",
 };
 
 // OpenCode (the Grok runtime): its own agentic loop, its own tools, allow-all permissions. It takes a model id,
-// a prompt and one system message of ours — no effort scale, no tools of ours, no command list.
+// a prompt and one system message of ours, no effort scale, no tools of ours, no command list.
 const OPENCODE: AgentCapabilities = {
     runtime: "opencode",
     steering: false,
@@ -353,19 +353,19 @@ const OPENCODE: AgentCapabilities = {
     commands: false,
     terminals: false,
     recovery: false,
-    // `system` on the prompt body, per message. It ADDS to OpenCode's own prompt — there is no seam for
-    // replacing that — so a custom prompt lands here as extra instructions, and the settings page says so
+    // `system` on the prompt body, per message. It ADDS to OpenCode's own prompt, there is no seam for
+    // replacing that, so a custom prompt lands here as extra instructions, and the settings page says so
     // rather than letting "replaces everything" quietly mean something else on two providers.
     instructions: "append",
 };
 
-/* The same OpenCode loop, serving Gemini instead of xAI — identical abilities, which is the point of giving it
+/* The same OpenCode loop, serving Gemini instead of xAI, identical abilities, which is the point of giving it
  * its own row rather than its own record shape.
  *
  * It exists because the alternative was Gemini's ONLY route being the Claude Code loop, and that loop announces
  * itself to whatever it is pointed at: the CLI prepends its own "You are a Claude agent, built on Anthropic's
  * Claude Agent SDK." to every request, baked into the binary with no option to suppress it. Google's Antigravity
- * channel matches that exact sentence and refuses the request — reported as a quota error, which sent the
+ * channel matches that exact sentence and refuses the request, reported as a quota error, which sent the
  * translator walking all 31 connected accounts looking for one with room, ~60s per attempt, none of which could
  * ever have answered. Under this runtime the request carries OpenCode's own prompt, so the turn is simply not
  * Claude Code traffic and the block has nothing to match.
@@ -379,7 +379,7 @@ const OPENCODE_GEMINI: AgentCapabilities = {
 
 // Any agent speaking the Agent Client Protocol: a documented floor rather than the native ceiling. It publishes
 // commands, runs its terminals in the conversation's tmux session, and takes our http MCP tools when it says it
-// can — but it owns its own model, effort and permission posture.
+// can, but it owns its own model, effort and permission posture.
 const ACP: AgentCapabilities = {
     runtime: "acp",
     steering: false,
@@ -399,7 +399,7 @@ const ACP: AgentCapabilities = {
 };
 
 /* THE PI CAPABILITY ID IS RESERVED, the same way the five native ids are: an `agent`-kind capability installed
- * under it is served over Pi's own RPC protocol rather than ACP — Pi closed ACP support deliberately (its RPC
+ * under it is served over Pi's own RPC protocol rather than ACP. Pi closed ACP support deliberately (its RPC
  * mode is the embedding surface), and the two want different records. A bare id rather than a namespace like
  * `endpoint/`, because there is exactly one Pi runtime to name; capabilitiesOf still answers from the id alone,
  * which is what keeps it a pure function of (provider, harness). */
@@ -408,7 +408,7 @@ export const PI_PROVIDER = "pi";
 // Pi driven over its RPC mode (`pi --mode rpc`, strict-LF JSONL over stdio): above the ACP floor and below the
 // Claude Code ceiling. Its `steer` command is real mid-turn injection; `set_thinking_level` takes the effort
 // tiers; `get_commands` publishes its extension/skill commands. It has no MCP seam (Pi's own extensions are its
-// tool surface), no approval channel (plan is the shared two-phase emulation), and runs bash in-process — no
+// tool surface), no approval channel (plan is the shared two-phase emulation), and runs bash in-process, no
 // tmux session for the terminal panel to attach to.
 const PI: AgentCapabilities = {
     runtime: "pi",
@@ -429,9 +429,9 @@ const PI: AgentCapabilities = {
 };
 
 // The pair → its record. An `endpoint/<id>` provider is a model API the user configured, driven BY the Claude
-// Code loop on either harness — so it gets that loop's full ceiling, which is the entire point of routing a
+// Code loop on either harness, so it gets that loop's full ceiling, which is the entire point of routing a
 // model through it rather than adopting a second runtime. The reserved `pi` id is the Pi coding agent on its
-// own RPC runtime (harness doesn't apply — Pi is its own loop, like ACP). Any other id that names no native
+// own RPC runtime (harness doesn't apply. Pi is its own loop, like ACP). Any other id that names no native
 // provider is an installed `agent`-kind capability, served over ACP.
 export const capabilitiesOf = (provider: AgentProvider, harness: AgentHarness): AgentCapabilities => {
     if (provider === "codex") {
@@ -442,12 +442,12 @@ export const capabilitiesOf = (provider: AgentProvider, harness: AgentHarness):
     }
     /* GEMINI IGNORES THE HARNESS, and it is the only routed provider that does. The Claude Code loop announces
      * itself in every request it sends and Google refuses on that announcement (see OPENCODE_GEMINI), so
-     * "Gemini under Claude Code" was never a slower or poorer option — it was one that could not complete a
+     * "Gemini under Claude Code" was never a slower or poorer option, it was one that could not complete a
      * single turn, on any of the connected accounts, ever.
      *
      * Answering OPENCODE_GEMINI whatever the caller asked for is what makes that structural rather than a rule
-     * each surface has to remember. Everything downstream reads the runtime off this record — the adapter that
-     * serves a turn, the transcript store, the quick helper's choice of loop — so there is exactly one place
+     * each surface has to remember. Everything downstream reads the runtime off this record, the adapter that
+     * serves a turn, the transcript store, the quick helper's choice of loop, so there is exactly one place
      * where Gemini's loop is decided, and no way left to route Claude Code traffic at Google by asking for it. */
     if (provider === "gemini") {
         return OPENCODE_GEMINI;
@@ -466,18 +466,18 @@ export const capabilitiesOf = (provider: AgentProvider, harness: AgentHarness):
 export const modesFor = (capabilities: AgentCapabilities): readonly PermissionMode[] =>
     capabilities.permissions === "modes" ? ["default", "acceptEdits", "plan", "bypassPermissions"] : ["plan", "bypassPermissions"];
 
-// The mode a selection falls back to when the runtime can't hold it — the same shape as clampEffort, and for the
+// The mode a selection falls back to when the runtime can't hold it, the same shape as clampEffort, and for the
 // same reason: a provider switch must not leave the composer showing a posture nothing applies.
 export const clampMode = (mode: PermissionMode, capabilities: AgentCapabilities): PermissionMode =>
     modesFor(capabilities).includes(mode) ? mode : "bypassPermissions";
 
-/* What this pair does NOT do, phrased for the person about to send a message to it — the honest half of the
+/* What this pair does NOT do, phrased for the person about to send a message to it, the honest half of the
  * picker, and the reason the record carries axes the daemon itself never branches on. Empty ⇒ the full ceiling.
  *
  * `fastMode` is deliberately NOT disclosed here, and it is the one axis that can't be: every other axis is fully
  * determined by the record, while fast mode also depends on the route and the model. The record says true for
- * every provider the Claude Code loop serves — including the ones routed through the translator, which can never
- * go fast — so a sentence derived from it would stay silent for exactly the turns that most need to hear it.
+ * every provider the Claude Code loop serves, including the ones routed through the translator, which can never
+ * go fast, so a sentence derived from it would stay silent for exactly the turns that most need to hear it.
  * fastAllowed answers the real question, and the `fast_mode` frame reports what the turn actually got. */
 export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.permissions === "plan" ? ["no per-tool approvals"] : []),
@@ -486,11 +486,11 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.mcp === "none"
         ? ["no MCP tools or plugins"]
         : capabilities.mcp === "http"
-          ? ["MCP tools only — no plugins or browser"]
+          ? ["MCP tools only: no plugins or browser"]
           : capabilities.mcp === "browser"
-            ? ["browser tools only — no plugins or other MCP tools"]
+            ? ["browser tools only: no plugins or other MCP tools"]
             : []),
-    ...(capabilities.execution.includes("js") ? [] : ["no code runs — its shell is the one way to execute"]),
+    ...(capabilities.execution.includes("js") ? [] : ["no code runs, its shell is the one way to execute"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),
     ...(capabilities.terminals ? [] : ["no terminal panel"]),
@@ -503,10 +503,10 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.instructions === "none" ? ["your system prompt isn't applied"] : []),
 ];
 
-// Claude's compile-time model floor, shared by the daemon's catalog (claude-models.ts — its last rung, reached
+// Claude's compile-time model floor, shared by the daemon's catalog (claude-models.ts, its last rung, reached
 // only before either live source has ever answered) and by the web's pre-load list, so the two can't name
 // different models. VERSIONED ids only, never the tier aliases (`opus`, `sonnet`) that used to sit here: an
-// alias names no version, so a turn running on one leaves the user unable to say what answered them — and it
+// alias names no version, so a turn running on one leaves the user unable to say what answered them, and it
 // lags a release besides, resolving to the previous version for as long as the CLI keeps pointing it there.
 // Going stale costs nothing: every rung above replaces the whole list, and a selection the live catalog no
 // longer offers is repointed to its default (loadProviderModels web-side, routedModel daemon-side).
@@ -517,8 +517,8 @@ export const CLAUDE_SEED_MODELS: readonly Model[] = [
 ];
 
 // The STATIC floor of the model catalog, harness-independent: every provider's real list is the daemon's live
-// catalog (/providers/{provider}/models — discovery with a persisted/seed floor, never empty),
-// which consumers layer on top. Codex/grok are empty here (nothing sensible to offer before the live load — and
+// catalog (/providers/{provider}/models, discovery with a persisted/seed floor, never empty),
+// which consumers layer on top. Codex/grok are empty here (nothing sensible to offer before the live load, and
 // under the Claude Code harness they route through the translator, which serves the SAME subscription model ids
 // as the native catalog, so the harness no longer changes the list).
 export const modelsFor = (provider: AgentProvider): CatalogOption[] => {
@@ -532,9 +532,9 @@ export const modelsFor = (provider: AgentProvider): CatalogOption[] => {
 // Whether a reasoning-effort tier is actually sendable for this provider with this thinking setting. 'max' is
 // the only constrained tier and it fails two ways: no non-Claude scale HAS it, and Claude's API rejects it
 // outright when extended thinking is disabled ("effort 'max' is not supported when thinking is disabled on this
-// model" — a 400 that kills the turn before the model sees it, surfacing only as the SDK's `unknown` error
-// category). It is the one rule a MODEL's published tier list can't express — the daemon reports what a model
-// accepts without knowing this turn's thinking setting — so the consumer that assembles the offered scale
+// model", a 400 that kills the turn before the model sees it, surfacing only as the SDK's `unknown` error
+// category). It is the one rule a MODEL's published tier list can't express, the daemon reports what a model
+// accepts without knowing this turn's thinking setting, so the consumer that assembles the offered scale
 // (effortsFor, web-side) filters through here, and the clamp over that scale makes the pair unreachable.
 export const effortAllowed = (effort: string, provider: AgentProvider, thinking: boolean): boolean =>
     effort !== "max" || (provider === "claude" && thinking);
@@ -543,7 +543,7 @@ export const effortAllowed = (effort: string, provider: AgentProvider, thinking:
  *
  * effortAllowed makes the pair unreachable in the picker, and the picker is not the only way a turn is
  * assembled: a route, an extension, a restored tab or a settings-pinned model can all name an effort that no
- * live scale filtered. One did — a session ran `max` with thinking off, and every server-side tool call in it
+ * live scale filtered. One did, a session ran `max` with thinking off, and every server-side tool call in it
  * came back `400 output_config.effort 'max' is not supported when thinking is disabled`, which reads to the
  * model as "web search is broken" and cost it the answer it was sent to find.
  *
@@ -554,18 +554,18 @@ export const effortAllowed = (effort: string, provider: AgentProvider, thinking:
 export const sendableEffort = (effort: string | undefined, thinking: boolean | undefined): string | undefined =>
     effort === "max" && thinking !== true ? "high" : effort;
 
-/* WHETHER FAST SPEED CAN BE OFFERED for a provider/harness/model triple — the picker-side filter, the same
+/* WHETHER FAST SPEED CAN BE OFFERED for a provider/harness/model triple, the picker-side filter, the same
  * shape and the same reason as effortAllowed: the composer must not show a control that does nothing.
  *
- * Three conditions, each answering a different question, and all three are load-bearing:
+ * Three conditions, each answering a different question, and all three are required:
  *
  *   - the RUNTIME has to know how to ask (capabilities.fastMode). Only the Claude Code loop does.
  *   - the ROUTE has to be first-party. Every non-Claude provider the Claude Code loop serves is served through
  *     the sandbox's translator, and the harness refuses fast mode on a non-Anthropic endpoint ("not_first_party")
- *     — so a `grok` turn on the claude-code harness reads true on the capability and still cannot go fast.
+ *    , so a `grok` turn on the claude-code harness reads true on the capability and still cannot go fast.
  *   - the MODEL has to publish it, which is the `fast` badge Anthropic's own catalog reports per model
  *     (claude-models.ts maps supportsFastMode onto it). Curating a list of ids here instead is what this repo
- *     deliberately does not do — a model that gains or loses fast mode moves the badge, and this follows.
+ *     deliberately does not do, a model that gains or loses fast mode moves the badge, and this follows.
  *
  * `badges` absent ⇒ false. That is the honest reading: a catalog row that published no capabilities said
  * nothing about fast mode, and the seed floor a picker shows before its first live load is exactly that row. */

package/src/agent-run-model.test.ts

@@ -3,7 +3,7 @@ import { resolveAgentRunModels } from "./agent-run-model.js";
 import type { QuickModelSource } from "./quick-model.js";
 
 /* Which model a run somebody's BUTTON started opens on. The rule answers the same two surfaces its quick-model
- * sibling does — the daemon walks it, the settings row names it — so what these pin is the pair of properties
+ * sibling does: the daemon walks it, the settings row names it, so what these pin is the pair of properties
  * that separate the two: an account this sandbox cannot reach never sits at the head of the chain, and an empty
  * answer stays empty rather than being filled in with a tier nobody chose. */
 
@@ -13,7 +13,7 @@ const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`ge
 
 const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
 
-test("keeps the user's own order — this list is read, never ranked", () => {
+test("keeps the user's own order, this list is read, never ranked", () => {
     // The opposite of the quick chain, which sorts by tier and cost. Here the order IS the setting: someone who
     // put Opus above GPT wants Opus first, and a resolver that knew better would spend the wrong account.
     expect(resolveAgentRunModels([CLAUDE, CODEX], [`codex:gpt-5.6`, `claude:claude-opus-5`])).toEqual([
@@ -30,7 +30,7 @@ test("steps over a provider this sandbox has no credential for", () => {
     ]);
 });
 
-test("resolves to nothing when no pin is reachable — it does NOT fall back to whatever is connected", () => {
+test("resolves to nothing when no pin is reachable: it does NOT fall back to whatever is connected", () => {
     // The deliberate difference from resolveQuickModels, which lands on its Auto ladder here. An agent run is
     // billed in whole sessions, so an unreachable list hands the choice back to the caller's floor (the user's
     // own composer pick) rather than spending an account they never pointed at.

package/src/agent-run-model.ts

@@ -1,6 +1,6 @@
 import { parsePinned, type QuickModelChoice, quickModelKey, type QuickModelSource } from "./quick-model.js";
 
-/* WHAT A SURFACE-STARTED AGENT RUN OPENS ON — the resolver for `agentRunModels`, sibling to resolveQuickModels
+/* WHAT A SURFACE-STARTED AGENT RUN OPENS ON, the resolver for `agentRunModels`, sibling to resolveQuickModels
  * and deliberately not the same function.
  *
  * BOTH ARE ORDERED LISTS, FOR THE SAME REASON. One connected account whose allowance went on the chat this
@@ -13,33 +13,33 @@ import { parsePinned, type QuickModelChoice, quickModelKey, type QuickModelSourc
  * is connected" is a good answer and quickModel's empty list resolves to a derived Auto ladder. An agent run is
  * a full session with a worktree, billed whole: nothing here can judge whether a job is worth the frontier tier,
  * so an empty list resolves to NOTHING and the caller falls back to the model the user picked for their own
- * chat — a choice they made, rather than one this file guessed for them. For the same reason there is no Auto
+ * chat, a choice they made, rather than one this file guessed for them. For the same reason there is no Auto
  * ladder underneath a list that has been emptied by disconnection: it would spend an account the user never
  * pointed at, on the most expensive kind of run this app starts.
  *
  * WHAT "STEPPED OVER" MEANS HERE IS NARROWER than the quick chain's, and worth being exact about. The quick
  * chain re-asks the next rung when a call comes back refused, because a one-shot that failed has cost nothing
- * and can simply be run again. An agent session cannot be replayed that way — by the time a provider refuses
- * mid-turn the agent may have already edited files — so this list is read ONCE, at the moment the turn is
+ * and can simply be run again. An agent session cannot be replayed that way, by the time a provider refuses
+ * mid-turn the agent may have already edited files, so this list is read ONCE, at the moment the turn is
  * composed, and steps over exactly one thing: an account that is not connected. A model that accepts the turn
  * and fails later is a failed run the user reads on the card, like any other. */
 
 /* The pins that could actually be started right now, in the user's own order.
  *
  * `sources` is the same readiness view resolveQuickModels takes, so both settings rows agree about which
- * accounts this sandbox can send to — a pin greyed as "Not connected" in one row and silently spent by the
+ * accounts this sandbox can send to, a pin greyed as "Not connected" in one row and silently spent by the
  * other would be the worst of both.
  *
  * A pin whose provider is gone is DROPPED rather than held: it would otherwise sit at the head of the chain
- * failing every run, which is exactly what the list exists to prevent. It stays on SCREEN, greyed — the settings
- * row renders the stored list, not this one — because a setting that vanished from view would look like the app
+ * failing every run, which is exactly what the list exists to prevent. It stays on SCREEN, greyed, the settings
+ * row renders the stored list, not this one, because a setting that vanished from view would look like the app
  * had eaten it.
  *
  * Empty out means nobody has pinned anything this sandbox can reach, and the caller's floor takes over. */
 export const resolveAgentRunModels = (sources: readonly QuickModelSource[], pinned: readonly string[]): readonly QuickModelChoice[] => {
     const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
     const requested = pinned.flatMap((key) => {
-        // Verbatim, unvalidated against the catalog — the same call resolveQuickModels makes and for the same
+        // Verbatim, unvalidated against the catalog, the same call resolveQuickModels makes and for the same
         // reason: the picker offers a custom-id escape hatch for a model the static catalog has not caught up
         // with, and second-guessing the id here would run a different model than the settings row names.
         const choice = parsePinned(key);

package/src/capability-env.ts

@@ -1,10 +1,10 @@
-/* HOW A CLI CAPABILITY'S ENV VARS ARE NAMED — the one rule both ends of that wire have to apply.
+/* HOW A CLI CAPABILITY'S ENV VARS ARE NAMED, the one rule both ends of that wire have to apply.
  *
  * The daemon writes the agent's shell env by suffixing every var a cli connector declares with the instance id
  * (cli-env.ts), so two connections of the same provider coexist on one flat environment. A connector's own
- * TOOL then has to read them back, and an extension may not import daemon internals — so without this the
+ * TOOL then has to read them back, and an extension may not import daemon internals, so without this the
  * rule would be spelled twice, and a change to it would silently split the writer from the reader. */
 
 // `analytics` → `POSTGRES_URL_ANALYTICS`; the default-named `github` → `GITHUB_TOKEN_GITHUB`.
-// ponytail: ids differing only by case or `-`/`_` (my-db vs my_db) map to the same suffix — last wins.
+// ponytail: ids differing only by case or `-`/`_` (my-db vs my_db) map to the same suffix, last wins.
 export const envSuffix = (id: string): string => id.toUpperCase().replaceAll("-", "_");