@intentic/sandbox-contract 1.167.0 → 1.169.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.167.0",
+  "version": "1.169.0",
   "description": "oRPC wire contract for the intentic sandbox daemon — shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -56,7 +56,7 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/extension-api": "1.167.0"
+    "@intentic/extension-api": "1.169.0"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/agent-catalog.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, test } from "vitest";
+import { type AgentCapabilities, capabilitiesOf, clampMode, HARNESSES, limitationsOf, modesFor, PROVIDERS } from "./agent-catalog.js";
+import type { AgentHarness, AgentProvider, PermissionMode } from "./schemas.js";
+
+/* THE MATRIX GUARD.
+ *
+ * Four runtimes serve turns behind one seam, and for a long time the only record of what each could do was a
+ * comment inside its own adapter. The surfaces above them could not read those, so they offered the same
+ * controls to all four: a permission mode to a runtime with no approval channel, an effort scale to one that
+ * drops the field. The record is what fixed that, and this is what keeps it honest.
+ *
+ * By SHAPE, not by a list: PROVIDERS × HARNESSES comes from the catalog itself, so a provider added tomorrow is
+ * covered the day it is added. If a pair fails here, the answer is a row in capabilitiesOf — never a special
+ * case in the surface that asked. */
+
+const pairs: { provider: AgentProvider; harness: AgentHarness }[] = PROVIDERS.flatMap((provider) =>
+    HARNESSES.map((harness) => ({ provider: provider.value as AgentProvider, harness: harness.value })),
+);
+
+describe("every provider/harness pair declares what it can do", () => {
+    it.each(pairs)("$provider on the $harness harness", ({ provider, harness }) => {
+        const capabilities = capabilitiesOf(provider, harness);
+
+        // Nothing may be left to inference: a `permissions` a surface can't read, or a runtime nobody serves,
+        // is the drift this record exists to end.
+        expect(["claude-code", "codex", "opencode", "acp"]).toContain(capabilities.runtime);
+        expect(["modes", "plan"]).toContain(capabilities.permissions);
+        expect(["full", "http", "none"]).toContain(capabilities.mcp);
+        expect(["namespace", "cwd"]).toContain(capabilities.isolation);
+        // The permission modes offered must include the mode a clamp falls back to — a floor that isn't in the
+        // list would leave the composer showing a posture the runtime can't hold.
+        expect(modesFor(capabilities)).toContain(clampMode("default", capabilities));
+    });
+});
+
+// An ACP provider is an installed capability's id — any string that isn't a native provider. It gets the ACP
+// floor whatever harness the client happened to send, because the agent IS its own loop.
+test("an unknown provider id is an ACP agent, on either harness", () => {
+    for (const harness of HARNESSES) {
+        expect(capabilitiesOf("some-installed-agent", harness.value).runtime).toBe("acp");
+    }
+});
+
+/* The harness axis is real for exactly two providers. 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 the client sent — which is why "is the harness claude-code" was
+ * never the question worth asking. */
+test("only codex and grok change runtime with the harness", () => {
+    const switched = PROVIDERS.filter((provider) => capabilitiesOf(provider.value, "native") !== capabilitiesOf(provider.value, "claude-code"));
+
+    expect(switched.map((provider) => provider.value)).toEqual(["codex", "grok"]);
+});
+
+test("codex and grok under the Claude Code harness get the full ceiling — it is the same loop", () => {
+    for (const provider of ["codex", "grok"] as const) {
+        expect(capabilitiesOf(provider, "claude-code")).toEqual(capabilitiesOf("claude", "native"));
+    }
+});
+
+// The composer's four modes describe behaviours the Claude Code loop actually has. A runtime whose every tool
+// call is pre-approved has two postures, so it is offered two names — not four names for two behaviours.
+test("a plan-only runtime offers the two postures it has", () => {
+    expect(modesFor(capabilitiesOf("codex", "native"))).toEqual(["plan", "bypassPermissions"]);
+    expect(modesFor(capabilitiesOf("claude", "native"))).toEqual(["default", "acceptEdits", "plan", "bypassPermissions"]);
+});
+
+test("a mode the runtime can't hold falls back to the one it runs; one it can holds", () => {
+    const codex = capabilitiesOf("codex", "native");
+
+    expect(clampMode("acceptEdits", codex)).toBe("bypassPermissions");
+    expect(clampMode("plan", codex)).toBe("plan");
+    expect(clampMode("acceptEdits", capabilitiesOf("claude", "native"))).toBe("acceptEdits");
+});
+
+/* The user-facing half. The full ceiling says nothing — an empty list is what hides the picker's block — and
+ * every axis the record carries has a sentence here, because a capability nobody can read is how this started. */
+test("the ceiling has nothing to disclose; a floor names what it lacks", () => {
+    expect(limitationsOf(capabilitiesOf("claude", "native"))).toEqual([]);
+
+    const grok = limitationsOf(capabilitiesOf("grok", "native"));
+    expect(grok).toContain("no per-tool approvals");
+    expect(grok).toContain("no mid-turn steering");
+    expect(grok).toContain("no effort control");
+    expect(grok).toContain("worktree by working directory only");
+
+    // ACP takes our http MCP tools when it advertises them, so its line is a narrowing rather than an absence —
+    // and it publishes commands and terminals, which must NOT be listed as missing.
+    const acp = limitationsOf(capabilitiesOf("some-installed-agent", "native"));
+    expect(acp).toContain("MCP tools only — no plugins or browser");
+    expect(acp).not.toContain("no slash commands");
+    expect(acp).not.toContain("no terminal panel");
+});
+
+test("every axis a record can lack has words for it", () => {
+    const nothing: AgentCapabilities = {
+        runtime: "acp",
+        steering: false,
+        permissions: "plan",
+        questions: false,
+        mcp: "none",
+        effort: false,
+        isolation: "cwd",
+        commands: false,
+        terminals: false,
+        recovery: false,
+    };
+
+    // Nine axes, nine sentences: an axis added to the interface without one would silently never be disclosed.
+    expect(limitationsOf(nothing)).toHaveLength(9);
+});
+
+// The mode vocabulary is the contract's own PermissionMode, so a mode added to the wire can't be quietly absent
+// from the runtime that owns them all.
+test("the Claude Code loop offers every PermissionMode the wire has", () => {
+    const wire: PermissionMode[] = ["default", "acceptEdits", "plan", "bypassPermissions"];
+
+    expect([...modesFor(capabilitiesOf("claude", "native"))].toSorted()).toEqual(wire.toSorted());
+});

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
@@ -46,6 +46,23 @@ export const PROVIDER_ACCESS: Record<NativeProvider, ProviderAccess> = {
     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 (both are 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

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/prepush.contract.ts

@@ -0,0 +1,16 @@
+import { oc } from "@orpc/contract";
+import { OkSchema, PrepushRunSchema } from "../schemas.js";
+
+// The pre-push check — the command the workspace runs when the user pushes, before anything leaves the machine
+// (see PrepushRunSchema for where this sits and why). Three verbs about ONE run: the check answers about the
+// main working tree, of which there is exactly one, so nothing here is addressed by id.
+//
+// `run` starts the check and returns immediately — a suite takes minutes, and an oRPC call held open for one
+// would die on the first proxy timeout with the work still going. The dialog that started it polls `state`,
+// which carries the live output tail while `status` is `running`. `cancel` kills the child's whole process
+// group; the run settles as `cancelled` and the push it was gating does not go.
+export const prepushContract = {
+    state: oc.route({ method: "GET", path: "/prepush/state" }).output(PrepushRunSchema),
+    run: oc.route({ method: "POST", path: "/prepush/run" }).output(OkSchema),
+    cancel: oc.route({ method: "POST", path: "/prepush/cancel" }).output(OkSchema),
+};

package/src/contracts/system.contract.ts

@@ -1,6 +1,6 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { SystemEventSchema } from "../events.js";
+import { SessionTranscriptSchema, SystemEventSchema } from "../events.js";
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
@@ -10,6 +10,8 @@ import {
     InfoSchema,
     OkSchema,
     PresenceReportSchema,
+    SubagentIdParamSchema,
+    SubagentsListSchema,
     TerminalNameParamSchema,
     TerminalsListSchema,
     UsageSummarySchema,
@@ -47,4 +49,16 @@ export const systemContract = {
     // 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/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);
+});