@intentic/sandbox-contract 1.166.0 → 1.168.0

package/src/agent-catalog.ts

@@ -1,4 +1,4 @@
-import type { AgentHarness, AgentProvider, Model, NativeProvider } from "./schemas.js";
+import { type AgentHarness, type AgentProvider, type Model, NATIVE_PROVIDERS, type NativeProvider, type PermissionMode } from "./schemas.js";
 
 /* 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
@@ -42,10 +42,27 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
     claude: { kind: "subscription", requirement: "Claude subscription", runs: "Claude Code" },
     codex: { kind: "subscription", requirement: "ChatGPT subscription", runs: "Codex" },
     grok: { kind: "subscription", requirement: "SuperGrok subscription", runs: "Grok" },
-    kimi: { kind: "key", requirement: "Moonshot API key", runs: "Kimi Code" },
+    kimi: { kind: "subscription", requirement: "Kimi Code subscription", runs: "Kimi Code" },
     gemini: { kind: "free", requirement: "Google sign-in", runs: "Gemini, Claude and GPT-OSS under Claude Code" },
 };
 
+/* 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.
+ *
+ * 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. */
+export const PROVIDER_VENDOR: Record<NativeProvider, string> = {
+    claude: "Claude",
+    codex: "ChatGPT",
+    grok: "xAI",
+    kimi: "Kimi Code",
+    gemini: "Google",
+};
+
 // 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
@@ -60,6 +77,21 @@ export const accessFor = (provider: AgentProvider): ProviderAccess | undefined =
 // 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
+ * 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
+ * identical as a blank row and mean opposite things.
+ *
+ * Three 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 and Google's are pulled through the translator's
+ * credential-scoped api-call. Grok is absent because xAI's usable billing data needs a subject id CLIProxyAPI
+ * keeps out of its auth-file listing, and the fallback probe spends a token to answer. Kimi is absent because
+ * it publishes no quota endpoint — the bundled translator knows only its chat and OAuth routes. Adding either
+ * is adding a reader and its name here, and nothing else. */
+export const PLAN_LIMIT_PROVIDERS: readonly NativeProvider[] = ["claude", "codex", "gemini"];
+export const reportsPlanLimits = (provider: AgentProvider): boolean => PLAN_LIMIT_PROVIDERS.includes(provider as NativeProvider);
+
 // 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). Only
 // surfaced for codex/grok — claude is always its own Claude Code loop, and kimi/gemini have no native runtime
@@ -69,20 +101,152 @@ export const HARNESSES: readonly { label: string; value: AgentHarness }[] = [
     { label: "Claude Code", value: "claude-code" },
 ];
 
-// Whether a turn on this provider/harness pair ACTUALLY runs the Claude Code Agent SDK loop — which is not the
-// same question as `harness === "claude-code"`. Claude is always its own Claude Code loop, and kimi/gemini have
-// no native runtime at all (Moonshot speaks the Anthropic protocol directly; Google is re-served through the
-// translator), so all three run it whatever harness the client happened to send; only codex/grok have a native
-// runtime to switch away from. An ACP agent runs its own loop and is never one of these.
-//
-// Everything the SDK loop owns keys off this: the SteeringQueue that makes mid-turn injection possible, and the
-// session store `/sessions/:id` reads a finished conversation's transcript back out of. Both sides of the wire
-// answer it here so a provider that gains (or loses) a native runtime is one edit, not a hunt for the literals.
-export const runsClaudeCode = (provider: AgentProvider, harness: AgentHarness): boolean =>
-    provider === "claude" ||
-    provider === "kimi" ||
-    provider === "gemini" ||
-    ((provider === "codex" || provider === "grok") && harness === "claude-code");
+/* WHAT A PROVIDER/HARNESS PAIR CAN ACTUALLY DO — one declaration, read by both sides of the wire.
+ *
+ * Four runtimes serve turns behind one seam (AgentRequest in, AgentEvent frames out): the Claude Code Agent SDK
+ * loop, Codex's exec surface, OpenCode, and any ACP agent. 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" —
+ * 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
+ * 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
+ * and demands one, so a pair can never be silently absent. */
+export interface AgentCapabilities {
+    // 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/gemini have no native runtime at all (both are
+    // re-served through the translator), so all three run it whatever harness the client sent; only codex/grok
+    // have a native runtime to switch away from. Names the session store a finished conversation's transcript is
+    // backfilled from, too.
+    readonly runtime: "claude-code" | "codex" | "opencode" | "acp";
+    // Mid-turn injection (the SteeringQueue behind /agent/steer). Needs the SDK's streaming-input mode.
+    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.
+    readonly permissions: "modes" | "plan";
+    // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
+    readonly questions: boolean;
+    // Which of the turn's tools reach the agent. "full" = http MCP tools + in-process SDK servers + plugin
+    // checkouts + the browser servers; "http" = the http MCP tools alone, and only if the agent advertises http
+    // MCP support; "none" = the runtime has no seam for them at all.
+    readonly mcp: "full" | "http" | "none";
+    // Reasoning-effort selection is forwarded to the model.
+    readonly effort: 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 —
+    // 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.
+    readonly commands: boolean;
+    // Runs its shell in a tmux session the terminal panel can attach to (`terminal` frames).
+    readonly terminals: boolean;
+    // 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;
+}
+
+// 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 = {
+    runtime: "claude-code",
+    steering: true,
+    permissions: "modes",
+    questions: true,
+    mcp: "full",
+    effort: true,
+    isolation: "namespace",
+    commands: true,
+    terminals: true,
+    recovery: true,
+};
+
+// Codex's exec surface: item-level events, no approval channel, no MCP seam through the SDK constructor we use.
+// Reasoning effort IS forwarded (modelReasoningEffort). `codex app-server` is the upgrade path for the first two.
+const CODEX: AgentCapabilities = {
+    runtime: "codex",
+    steering: false,
+    permissions: "plan",
+    questions: false,
+    mcp: "none",
+    effort: true,
+    isolation: "cwd",
+    commands: false,
+    terminals: false,
+    recovery: false,
+};
+
+// OpenCode (the Grok runtime): its own agentic loop, its own tools, allow-all permissions. It takes a model id
+// and a prompt — no effort scale, no tools of ours, no command list.
+const OPENCODE: AgentCapabilities = {
+    runtime: "opencode",
+    steering: false,
+    permissions: "plan",
+    questions: false,
+    mcp: "none",
+    effort: false,
+    isolation: "cwd",
+    commands: false,
+    terminals: false,
+    recovery: false,
+};
+
+// 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.
+const ACP: AgentCapabilities = {
+    runtime: "acp",
+    steering: false,
+    permissions: "plan",
+    questions: false,
+    mcp: "http",
+    effort: false,
+    isolation: "cwd",
+    commands: true,
+    terminals: true,
+    recovery: false,
+};
+
+// The pair → its record. An 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") {
+        return harness === "claude-code" ? CLAUDE_CODE : CODEX;
+    }
+    if (provider === "grok") {
+        return harness === "claude-code" ? CLAUDE_CODE : OPENCODE;
+    }
+    return (NATIVE_PROVIDERS as readonly string[]).includes(provider) ? CLAUDE_CODE : ACP;
+};
+
+// Which permission modes a runtime can actually be put in. Under "plan" every other mode collapses onto the
+// autonomous posture the runtime already runs, so offering them would be offering four names for two behaviours.
+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
+// 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
+// picker, and the reason the record carries axes the daemon itself never branches on. Empty ⇒ the full ceiling.
+export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
+    ...(capabilities.permissions === "plan" ? ["no per-tool approvals"] : []),
+    ...(capabilities.questions ? [] : ["no clarifying questions"]),
+    ...(capabilities.steering ? [] : ["no mid-turn steering"]),
+    ...(capabilities.mcp === "none" ? ["no MCP tools or plugins"] : capabilities.mcp === "http" ? ["MCP tools only — no plugins or browser"] : []),
+    ...(capabilities.effort ? [] : ["no effort control"]),
+    ...(capabilities.commands ? [] : ["no slash commands"]),
+    ...(capabilities.terminals ? [] : ["no terminal panel"]),
+    ...(capabilities.isolation === "namespace" ? [] : ["worktree by working directory only"]),
+    ...(capabilities.recovery ? [] : ["no auto-resume after an outage"]),
+];
 
 // 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
@@ -114,13 +278,8 @@ export const modelsFor = (provider: AgentProvider): CatalogOption[] => {
 // 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). Every point where a selection can land on an invalid pair — restore from storage, provider switch,
-// thinking toggle, the picker's own option list — runs the pair through here, so the combination is unreachable
-// rather than merely discouraged.
+// 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);
-
-// The tier a selection falls back to when effortAllowed rejects it — one rung down from 'max', the top of every
-// scale that excludes it.
-export const clampEffort = (effort: string, provider: AgentProvider, thinking: boolean): string =>
-    effortAllowed(effort, provider, thinking) ? effort : "xhigh";

package/src/contracts/agent.contract.ts

@@ -1,15 +1,6 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { AgentCommandsQuerySchema, AgentCommandsSchema, AttachFrameSchema } from "../events.js";
-import {
-    AgentReplySchema,
-    AgentTurnSchema,
-    AttachTurnSchema,
-    OkSchema,
-    ResumeLimitSchema,
-    StartedTurnSchema,
-    SteerSchema,
-    StopTurnSchema,
-} from "../schemas.js";
+import { AgentReplySchema, AgentTurnSchema, AttachTurnSchema, OkSchema, StartedTurnSchema, SteerSchema, StopTurnSchema } from "../schemas.js";
 
 // A turn EXECUTES as a detached daemon-side run: `run` starts it and acks with the run id; any number of
 // clients render it via `attach` (replay from a seq cursor, then live) — the initiating window holds no
@@ -22,10 +13,6 @@ export const agentContract = {
     reply: oc.route({ method: "POST", path: "/agent/reply" }).input(AgentReplySchema).output(OkSchema),
     steer: oc.route({ method: "POST", path: "/agent/steer" }).input(SteerSchema).output(OkSchema),
     stop: oc.route({ method: "POST", path: "/agent/stop" }).input(StopTurnSchema).output(OkSchema),
-    // Fire the conversation's pending usage-limit resume immediately, optionally on another account — the
-    // chat's "resume on another account" action. Acks with the run id, exactly like `run`; the resumed turn
-    // is an ordinary detached run any window attaches to.
-    resumeLimit: oc.route({ method: "POST", path: "/agent/resume-limit" }).input(ResumeLimitSchema).output(StartedTurnSchema),
     // The provider's slash commands as last published by one of its turns, so a conversation's `/` popover is
     // populated before it has run one. The live `commands` frame stays authoritative for a running turn.
     commands: oc.route({ method: "GET", path: "/agent/commands" }).input(AgentCommandsQuerySchema).output(AgentCommandsSchema),

package/src/contracts/agents.contract.ts

@@ -20,19 +20,21 @@ import {
     OkSchema,
 } from "../schemas.js";
 
-// The fleet: every registered conversation-agent (see AgentSummarySchema). `diff` is the conversation
-// worktree's CUMULATIVE multi-repo delta vs its recorded per-repo bases — one flat change set per repo
+// The fleet: every registered conversation-agent (see AgentSummarySchema). Registry-level actions (read,
+// rename, seen, archive) apply uniformly. For branch-backed conversations, `diff` is the worktree's CUMULATIVE
+// multi-repo delta vs its recorded per-repo bases — one flat change set per repo
 // (AgentChanges), each file flagged `landed` or not, deliberately not the working tree's staged/unstaged
 // shape: a worktree the user never checks out has no index they could stage into. `land` merges the worktree
 // branches into the main tree (per-repo, conflicts reported, nothing lost on failure); `discard` removes
-// worktrees + branches + registry entry. An unknown {id} is NOT_FOUND; land/discard while the turn runs is CONFLICT.
+// worktrees + branches + registry entry. Those branch actions reject workspace conversations explicitly. An
+// unknown {id} is NOT_FOUND; land/discard while the turn runs is CONFLICT.
 // `rename` sets the user-chosen display title — legal mid-turn (it touches no worktree state).
 // `seen`/`seenAll` stamp the read marker behind the cards' unread badge (AgentSummarySchema.seenAt) — also
 // legal mid-turn, and like `rename` they never bump `updatedAt` (reading is not activity).
 //
-// ARCHIVE is the non-destructive counterpart to discard, and the one the board leans on: `archive` commits
-// whatever the worktree still holds onto agent/<id>, drops the CHECKOUT (the expensive part — one file tree
-// per repo per agent) and keeps the branch, the entry, and the transcript. `list` then stops carrying it and
+// ARCHIVE is the non-destructive counterpart to discard, and the one the board leans on: for an isolated
+// conversation, `archive` commits whatever the worktree still holds onto agent/<id> and drops the CHECKOUT;
+// for a workspace conversation it has no git teardown. Both keep the entry and transcript. `list` stops carrying it and
 // `archived` does; `unarchive` puts it back, and either way the next turn re-attaches a worktree from the
 // surviving branch. Archiving a running agent is CONFLICT, same as land/discard.
 //

package/src/contracts/gate.contract.ts

@@ -9,8 +9,8 @@ import { GateVerdictSchema, OkSchema } from "../schemas.js";
 // claiming a green light the moment the tree moves under it. The three writes answer `ok` and nothing else —
 // each starts work that outlives the request, so there is no result to return and the poll is what reports.
 // `run` arms nothing and waits for nothing: it starts the check now, the user's own "I'm about to commit, check
-// this". `fix` opens the seeded main-tree turn for a red verdict, the same shape /ci/fix opens for a red
-// pipeline, minus the worktree it must not have.
+// this". `fix` opens a seeded workspace conversation for a red verdict; it has the same registry lifecycle as
+// /ci/fix, minus the isolated worktree it must not have.
 export const gateContract = {
     verdict: oc.route({ method: "GET", path: "/gate/verdict" }).output(GateVerdictSchema),
     run: oc.route({ method: "POST", path: "/gate/run" }).output(OkSchema),

package/src/contracts/kimi.contract.ts

@@ -1,26 +1,9 @@
 import { oc } from "@orpc/contract";
-import {
-    AccountIdSchema,
-    AccountRenameSchema,
-    KimiConnectSchema,
-    ModelsSchema,
-    OauthAccountListSchema,
-    OauthAccountSchema,
-    OkSchema,
-} from "../schemas.js";
+import { ModelsSchema } from "../schemas.js";
 
-// Kimi Code (Moonshot) — the sandbox owns the credential, an API key rather than an OAuth grant. Kimi speaks the
-// Anthropic Messages protocol, so a Kimi turn runs on the SAME Claude Code harness as Claude, with the harness
-// pointed at Moonshot's Anthropic-compatible endpoint and authenticated with the stored key (see agent.routes).
-// `connect` stores a pasted key as a new account and returns it; `models` is the live catalog for the picker;
-// `accounts` lists connected keys (tokens never ride back); `rename` renames one (a pasted key carries no
-// identity to derive a name from, so this is the ONLY way a Kimi row gets a distinguishing name);
-// `disconnect` clears the one named by id.
+// Kimi Code's picker catalog. Authentication and accounts belong to the bundled translator just like the other
+// routed subscriptions (translator.contract.ts); this provider-specific route only projects CLIProxyAPI's Kimi
+// model definitions into the shared picker shape.
 export const kimiContract = {
-    connect: oc.route({ method: "POST", path: "/kimi/account/connect" }).input(KimiConnectSchema).output(OauthAccountSchema),
-    // Kimi/Moonshot's live models for the picker — the source of valid ids (see kimi-models.ts).
     models: oc.route({ method: "GET", path: "/kimi/models" }).output(ModelsSchema),
-    accounts: oc.route({ method: "GET", path: "/kimi/accounts" }).output(OauthAccountListSchema),
-    rename: oc.route({ method: "POST", path: "/kimi/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
-    disconnect: oc.route({ method: "POST", path: "/kimi/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
 };

package/src/contracts/system.contract.ts

@@ -1,13 +1,17 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { SystemEventSchema } from "../events.js";
+import { SessionTranscriptSchema, SystemEventSchema } from "../events.js";
 import {
+    BrowserNameParamSchema,
+    BrowsersListSchema,
     DaemonSessionSchema,
     HostTunnelInputSchema,
     HostTunnelSchema,
     InfoSchema,
     OkSchema,
     PresenceReportSchema,
+    SubagentIdParamSchema,
+    SubagentsListSchema,
     TerminalNameParamSchema,
     TerminalsListSchema,
     UsageSummarySchema,
@@ -38,4 +42,23 @@ export const systemContract = {
     // (browser fetch sends the header), unlike the header-less WS route which app.ts exempts.
     terminals: oc.route({ method: "GET", path: "/system/terminals" }).output(TerminalsListSchema),
     killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }).input(TerminalNameParamSchema).output(OkSchema),
+    // The agent's live Chromiums and the pages each has open — the Browsers view's roster, polled while it is on
+    // screen and by the rail so its tile can appear the moment a turn starts browsing. The frames are the
+    // separate /system/browser-view WebSocket; this is the control plane, exactly as `terminals` is for tmux.
+    // `closeBrowser` shuts one Chromium down: the agent's next browser tool call then fails as if it had crashed,
+    // which is the honest account of the owner pulling the plug.
+    browsers: oc.route({ method: "GET", path: "/system/browsers" }).output(BrowsersListSchema),
+    closeBrowser: oc.route({ method: "DELETE", path: "/system/browsers/{name}" }).input(BrowserNameParamSchema).output(OkSchema),
+    // The agents this sandbox's agents started — SDK subagents and delegated Codex/Grok runs alike (see
+    // SubagentSessionSchema). Same two-route shape as the browsers above, and same division of labour: the list
+    // is polled by the Subagents area while it is on screen and loosely by the rail, so its tile can appear the
+    // moment a turn delegates. There is no third WebSocket here, because a subagent has no byte stream to watch —
+    // what you watch it through is its TRANSCRIPT, which `subagentTranscript` serves in the one shape every
+    // other transcript route already answers in: live from the parent turn's frame log while it runs, off the
+    // provider's own store once it has finished.
+    subagents: oc.route({ method: "GET", path: "/system/subagents" }).output(SubagentsListSchema),
+    subagentTranscript: oc
+        .route({ method: "GET", path: "/system/subagents/{id}/transcript" })
+        .input(SubagentIdParamSchema)
+        .output(SessionTranscriptSchema),
 };

package/src/contracts/translator.contract.ts

@@ -7,12 +7,10 @@ import { KeyedProviderSchema, OkSchema, TranslatorAccountsSchema, TranslatorComp
 // than an API key. A provider can hold several accounts side by side (the translator balances across them);
 // `accounts` lists what's connected per provider and `disconnect` clears ONE account by its auth-file `name`.
 //
-// Two login shapes ride one pair of routes. Codex and Grok mint a one-time device `code`: the user enters it at
-// the provider's site and the translator polls to completion in the background, so the UI just polls `accounts`
-// and `complete` is never called. Google has no device flow — it redirects the browser to a loopback URL this
-// sandbox can't receive — so its `connect` returns an EMPTY code, the card asks the user to paste the URL they
-// landed on, and `complete` hands it to the translator to finish the exchange. The card branches on that empty
-// code rather than on the provider id, so a provider that later gains a device flow needs no UI change.
+// Two login shapes ride one pair of routes. Codex, Grok and Kimi use device authorization: the translator polls
+// to completion in the background, so the UI only polls `accounts`. Google redirects the browser to a loopback
+// URL this sandbox can't receive, so `complete` hands the landing URL to the translator. `connect.flow` tells the
+// card which mechanic it received without inferring it from whether an optional device code happened to exist.
 export const translatorContract = {
     accounts: oc.route({ method: "GET", path: "/translator/accounts" }).output(TranslatorAccountsSchema),
     connect: oc

package/src/events.test.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "vitest";
+import { RESUME_NOTES, withResumeNote, withoutResumeNote } from "./events.js";
+
+/* The resume note is a round trip across the wire: the daemon wraps a prompt to tell the model what interrupted
+ * it, and the client unwraps the SAME prompt off an attach head to tell whether it already has that bubble. A
+ * mismatch between the two halves fails silently and cosmetically — a paragraph of machine prose rendered as
+ * something the user typed — which is exactly the kind of drift that stays broken. */
+test("a resume note round-trips back to the user's own words", () => {
+    for (const note of Object.values(RESUME_NOTES)) {
+        expect(withoutResumeNote(withResumeNote("ship the parser", note))).toBe("ship the parser");
+    }
+});
+
+// A prompt with blank lines of its own: only the note's own separator comes off, never the user's paragraphs.
+test("stripping takes the note and nothing of the prompt", () => {
+    const prompt = "step one\n\nstep two\n\nstep three";
+    expect(withoutResumeNote(withResumeNote(prompt, RESUME_NOTES.outage))).toBe(prompt);
+});
+
+// An ordinary prompt passes through untouched, so every attach head can be handed through it.
+test("a prompt that is not a resume is left alone", () => {
+    expect(withoutResumeNote("just a question")).toBe("just a question");
+    expect(withoutResumeNote("")).toBe("");
+});
+
+// Wrapping is idempotent: a resume that dies the same way again is re-recorded from its own input, and a second
+// note stacked on the first would grow the prompt on every attempt.
+test("wrapping an already-wrapped prompt adds nothing", () => {
+    const once = withResumeNote("retry me", RESUME_NOTES.restart);
+    expect(withResumeNote(once, RESUME_NOTES.restart)).toBe(once);
+    expect(withResumeNote(once, RESUME_NOTES.auth)).toBe(once);
+});