@intentic/sandbox-contract 1.167.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
@@ -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/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);
+});

package/src/events.ts

@@ -6,6 +6,8 @@ import {
     LandConflictSchema,
     PermissionModeSchema,
     RateLimitInfoSchema,
+    SubagentKindSchema,
+    SubagentStatusSchema,
     UsageWindowSchema,
 } from "./schemas.js";
 
@@ -125,19 +127,36 @@ export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
 // tool_use/tool_result blocks, so a restored card carries everything the live `tool_call` frame did except
 // the streaming-only correlation fields.
 //
-// One restored tool card. Subagent (Task) calls do NOT nest here: the SDK stores a delegation's own calls in a
-// separate per-subagent file, so a Task card restores as a leaf and its children stay collapsed — the live
-// stream still nests them (see ChatTool.children).
-export const RestoredToolCallSchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    category: ToolKindSchema,
-    status: ToolCallStatusSchema,
-    target: z.string().optional(),
-    locations: z.array(ToolCallLocationSchema).optional(),
-    content: z.array(ToolCallContentSchema).optional(),
-});
-export type RestoredToolCall = z.infer<typeof RestoredToolCallSchema>;
+// One restored tool card. A subagent's own calls and its thinking nest under the Agent card that spawned them,
+// the same two fields (and the same recursion) the live ChatTool carries — so a reopened chat redraws the
+// delegation it was showing instead of a leaf card with the whole child collapsed into its result text.
+// z.lazy because the shape refers to itself: a subagent that delegates nests one level deeper.
+export const RestoredToolCallSchema: z.ZodType<RestoredToolCall> = z.lazy(() =>
+    z.object({
+        id: z.string(),
+        name: z.string(),
+        category: ToolKindSchema,
+        status: ToolCallStatusSchema,
+        target: z.string().optional(),
+        locations: z.array(ToolCallLocationSchema).optional(),
+        content: z.array(ToolCallContentSchema).optional(),
+        children: z.array(RestoredToolCallSchema).optional(),
+        thinking: z.string().optional(),
+    }),
+);
+// Mutable, unlike most of this file: both builders settle a card IN PLACE when its result arrives turns later
+// (restoredTurn's `cards` map, readWorkspaceSession's `awaiting`), which is what saves them a second pass.
+export interface RestoredToolCall {
+    id: string;
+    name: string;
+    category: ToolKind;
+    status: ToolCallStatus;
+    target?: string | undefined;
+    locations?: ToolCallLocation[] | undefined;
+    content?: ToolCallContent[] | undefined;
+    children?: RestoredToolCall[] | undefined;
+    thinking?: string | undefined;
+}
 
 // One restored bubble. Each stored assistant message becomes its own, which is what reproduces the live
 // interleaving — prose, the tool cards that prose introduced, then the next block of prose — rather than
@@ -162,7 +181,8 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId:
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
 // `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
 // permission posture as the agent changes it.
-// `parentToolUseId` tags frames produced inside a subagent (Task tool).
+// `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
+// subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("session"), sessionId: z.string() }),
     /* First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
@@ -229,6 +249,40 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // `browser-<id>` session, and the client surfaces it in the same panel as the terminals. One per turn, for
     // the same reason: one browser serves every browser call the turn makes.
     z.object({ kind: z.literal("browser"), session: z.string() }),
+    /* THE AGENT STARTED ANOTHER AGENT — an Agent/Task subagent, or a Codex/Grok CLI it drove from its own Bash
+     * (see SubagentSessionSchema). One `subagent` frame per child, then `subagent_update` as it works: the same
+     * call/update pair `tool_call`/`tool_call_update` uses, and for the same reason — the fields that move
+     * (status, spend, what it is doing) arrive many times and must REPLACE, while the fields that identify it are
+     * said once.
+     *
+     * `id` is the SPAWNING TOOL CALL's id — the same id the client already nests the child's inner frames under
+     * (`parentToolUseId`), so both frames land on the card that spawned the child by the lookup that is already
+     * there (mapToolAnywhere). No second correlation, and nothing to get wrong.
+     *
+     * These exist because the SDK's task messages were dropped. A BACKGROUNDED child (the Agent tool's default)
+     * emits its tool_use and then nothing until its result lands, which for a long child is minutes of a spinner
+     * that cannot say whether anything is happening. */
+    z.object({
+        kind: z.literal("subagent"),
+        id: z.string(),
+        subagentKind: SubagentKindSchema,
+        agentType: z.string().optional(),
+        description: z.string().optional(),
+        model: z.string().optional(),
+        background: z.boolean().optional(),
+        // A delegation's tmux session — the one live view a subagent doesn't have (SubagentSessionSchema).
+        terminal: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("subagent_update"),
+        id: z.string(),
+        status: SubagentStatusSchema.optional(),
+        tokens: z.number().optional(),
+        toolUses: z.number().optional(),
+        lastTool: z.string().optional(),
+        summary: z.string().optional(),
+        error: z.string().optional(),
+    }),
     z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
     // The provider's own slash commands (ACP available_commands_update), replaced whole each time — the
     // composer's `/` popover lists them; invoking one is plain `/name …` prompt text (the ACP convention).
@@ -322,9 +376,11 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "claude-reauth",
                 // The API refused this turn's token MID-FLIGHT — nearly always one superseded by a rotation,
                 // which Anthropic retires the moment its successor is minted. Distinct from claude-reauth: the
-                // account is fine and the daemon re-mints on the spot, so this frame is a notice about a turn
-                // that resumed itself, not a request for the user to do anything. It only reaches the client
-                // when the resume could NOT start, which is when reconnecting really is the fix.
+                // account is fine and the daemon re-mints on the spot, so this is usually a notice about a turn
+                // that is coming back rather than a request for the user to do anything. `autoResume` says
+                // which of the two: "scheduled" means the re-mint-and-re-run is armed, and its absence means
+                // nothing is coming (the turn was already a resume, or it ran on a credential with nothing to
+                // re-mint from) — that is the case where reconnecting really is the fix.
                 "claude-token-refused",
                 // The model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
                 // socket — and the harness's own in-turn retries did not outlast it. Nothing about the workspace
@@ -346,12 +402,12 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // rate_limit_event or the account's persisted usage windows). Absent when the reset instant is unknown
         // (nothing to schedule against).
         resetsAt: z.number().optional(),
-        // Where the daemon's resume of THIS turn stands — the same two states for a spent allowance and for a
-        // provider outage, because the client's reading of them is the same: "scheduled" = the resume is armed
-        // and this turn comes back by itself; "available" = the daemon remembered the failed turn and turning
-        // the setting on (autoResumeOnLimit / resumeAfterOutage) arms that same resume, which is what the
-        // chat's offer banner hangs off. Absent normally means there is nothing automatic to resume; the
-        // usage-limit feature gate also leaves it absent while preserving the explicit account-switch path.
+        // Where the daemon's resume of THIS turn stands, for the two codes that have one (provider-outage,
+        // claude-token-refused). "scheduled" = the resume is armed and this turn comes back by itself;
+        // "available" = the daemon remembered the failed turn and turning resumeAfterOutage on arms that same
+        // resume, which is what the chat's offer banner hangs off — outage only, since a renewal is never gated
+        // on a setting. Absent means there is nothing automatic to resume: a spent usage limit never has one,
+        // and a refused credential has none once re-minting it has already been tried and failed.
         autoResume: z.enum(["scheduled", "available"]).optional(),
         /* provider-outage only: the shape of the wait. `retryAt` (epoch seconds) is when the next attempt is
          * due — not a fixed cadence, because an outage has no reset instant to aim at and hammering a provider
@@ -362,10 +418,6 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
          * on-by-default retry that gives no account of how long it will keep going is the kind users switch off
          * defensively; one that says "attempt 2 of 6" is one they leave on. */
         outage: z.object({ retryAt: z.number(), attempt: z.number(), maxAttempts: z.number() }).optional(),
-        // rate_limit only: the account whose allowance is spent, as the DAEMON resolved it (the client's own
-        // selection can be empty, which means "the provider's first"). It is what lets the chat offer the
-        // provider's OTHER accounts as a resume-now instead of a wait — see /agent/resume-limit.
-        account: z.string().optional(),
     }),
     z.object({ kind: z.literal("done") }),
 ]);
@@ -384,6 +436,32 @@ export const AttachFrameSchema = z.discriminatedUnion("kind", [
 ]);
 export type AttachFrame = z.infer<typeof AttachFrameSchema>;
 
+/* WHAT A RESUMED TURN'S PROMPT SAYS IT IS. The daemon re-runs a turn something underneath it killed (turn-resume.ts)
+ * by sending the original prompt again behind one of these sentences, so the model knows what interrupted it.
+ *
+ * They live on the wire rather than in the daemon because the CLIENT has to recognise them too: an attach head
+ * carries the run's prompt verbatim, and a window joining a resumed run would otherwise render the note as a
+ * message the USER wrote — the same words the user already said one run up, with a machine's preamble on them.
+ * Recognising the prefix is what lets that window reuse the bubble that is already there instead. */
+export const RESUME_NOTES = {
+    auth: "The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically.",
+    outage: "The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically.",
+    restart: "The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back.",
+} as const;
+
+// The prompt a resume actually sends: the note, then why the words below are being repeated, then them.
+export const withResumeNote = (prompt: string, note: string): string =>
+    Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known))
+        ? prompt
+        : `${note} The interrupted request is repeated below — where part of it was already completed in this session, continue from that point instead of starting over.\n\n${prompt}`;
+
+// The user's own words inside a resumed prompt — the note and its explanation stripped back off. Returns the
+// prompt unchanged when it is not a resume, so a caller can hand every attach head through it.
+export const withoutResumeNote = (prompt: string): string => {
+    const note = Object.values(RESUME_NOTES).find((known) => prompt.startsWith(known));
+    return note === undefined ? prompt : prompt.slice(prompt.indexOf("\n\n") + 2);
+};
+
 // One parsed line from `intentic … --output ndjson` (engine events, provider `log`, the terminal `result`).
 // Open-ended by design — the sandbox consumes the wire shape, not @intentic/engine's types — so a string
 // `kind` plus arbitrary extra fields pass through. The apply-events tail (intentic.contract `applyEvents`) rides

package/src/index.ts

@@ -67,6 +67,7 @@ export * from "./effects.js";
 export * from "./events.js";
 export * from "./sse.js";
 export * from "./routes.js";
+export * from "./workspace-state.js";
 export * from "./agent-catalog.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";

package/src/schemas.test.ts

@@ -29,7 +29,6 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         quickModel: "",
         agentRetentionDays: 3,
         autoLand: true,
-        autoResumeOnLimit: false,
         resumeAfterOutage: true,
         autoResumeOnRestart: true,
         gateCommand: "",
@@ -68,9 +67,8 @@ test("an empty object is the full default settings object", () => {
         // On because it is the historical behaviour — defaulting off would silently hold every existing
         // sandbox's finished work on branches nobody is watching.
         autoLand: true,
-        autoResumeOnLimit: false,
-        // On, unlike the limit resume beside it: an outage resume spends nothing the dead turn hadn't already
-        // committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
+        // On, where a spent usage limit re-runs nothing: an outage resume spends nothing the dead turn hadn't
+        // already committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
         resumeAfterOutage: true,
         // On: a daemon restart is usually intentic's own doing (an image update, an approved environment
         // change), not the user's decision, so the turn it interrupted resumes rather than staying stuck.
@@ -90,7 +88,3 @@ test("a key of the wrong type is still a parse failure — tolerance is for abse
     // The prompt cap is a real bound, not advice: the text IS the system prompt, and every turn pays for it.
     expect(SandboxSettingsSchema.safeParse({ systemPrompt: "x".repeat(20001) }).success).toBe(false);
 });
-
-test("usage-limit auto-resume stays off while the feature is disabled, including for an older saved true value", () => {
-    expect(SandboxSettingsSchema.parse({ autoResumeOnLimit: true }).autoResumeOnLimit).toBe(false);
-});