@intentic/sandbox-contract 1.311.0 → 1.313.0

package/src/front/generated/tunnel.json

@@ -0,0 +1,38 @@
+{
+  "close": {
+    "away": 1001,
+    "displaced": 4001,
+    "refused": 4003
+  },
+  "headers": {
+    "bulk": "x-intentic-bulk",
+    "grant": "x-intentic-grant",
+    "lane": "x-intentic-lane",
+    "transports": "x-intentic-transports"
+  },
+  "lanes": [
+    "interactive",
+    "bulk"
+  ],
+  "liveness": {
+    "deadAfterMs": 45000,
+    "pingEveryMs": 15000
+  },
+  "mux": "yamux",
+  "path": "/tunnel/v2",
+  "quic": {
+    "alpn": "intentic-tunnel/1",
+    "hello": {
+      "gone": 2,
+      "held": 0,
+      "refused": 1
+    },
+    "yieldAfterBytes": 1048576
+  },
+  "transports": [
+    "quic",
+    "h3",
+    "webtransport"
+  ],
+  "upgrade": "websocket"
+}

package/src/front/generated/wire.ts

@@ -1,6 +1,10 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
-export type Answer = { "answer": "preview", route: PreviewRoute, };
+export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer": "terminal", plan: TerminalPlan, 
+/**
+ * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
+ */
+member?: string, };
 
 /**
  * A PEM certificate chain and its PEM private key.
@@ -12,7 +16,9 @@ export type Endpoint = { host: string, port: number, };
 /**
  * Everything Node sends the front.
  */
-export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, };
+export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "ask", id: number, question: FrontQuestion, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, } | { "kind": "revoke", member?: string, } | { "kind": "watch", checkout: WatchedCheckout, } | { "kind": "unwatch", dir: string, };
+
+export type FrontAnswer = { "answer": "sync", generations: Array<number | null>, };
 
 /**
  * Request headers only the front sets on what it forwards to Node; it strips them from everything arriving outside.
@@ -20,6 +26,11 @@ export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kin
  */
 export type FrontHeader = "x-intentic-preview" | "x-intentic-preview-unreachable";
 
+/**
+ * A question Node asks the front.
+ */
+export type FrontQuestion = { "question": "sync", dirs: Array<string>, };
+
 /**
  * Every port the front binds, as Node's config names them; an absent one is not bound.
  */
@@ -38,26 +49,37 @@ frameAncestors: Array<string>,
 previewProbePath: string, };
 
 /**
- * Where a preview host's requests go, as Node resolved it.
+ * An answer Node renders whole when asked, for the front to write as it stands: a refusal page, or the probe's report.
  */
-export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "node" };
+export type Page = { status: number, headers: { [key in string]: string }, body: string, };
 
 /**
- * A question the front asks Node; the answer carries the same id.
+ * What becomes of a preview host's request, decided by Node once, when asked.
  */
-export type Question = { "question": "preview", host: string, };
+export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "page", page: Page, } | { "to": "outbox" };
+
+/**
+ * A question the front asks Node.
+ */
+export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, };
 
 export type Scheme = "http" | "https";
 
+/**
+ * What a terminal socket opens onto, as Node decided from its ticket, session name and working directory.
+ */
+export type TerminalPlan = { "plan": "session", name: string, createIn?: string, } | { "plan": "tail", path: string, } | { "plan": "exit", code: number, reason: string, } | { "plan": "refused", code: number, reason: string, };
+
 /**
  * Everything the front sends Node.
  */
-export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "tunnel", connected: boolean, };
+export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "answer", id: number, answer: FrontAnswer, } | { "kind": "refused", id: number, message: string, } | { "kind": "tunnel", connected: boolean, };
 
 /**
- * The ingress tunnel's door and the reachability grant it presents there.
+ * The ingress tunnel's door, the reachability grant it presents there, and the daemon's transfer routes it announces
+ * (`METHOD /path` each, as the daemon names them), which the edge sends down the bulk socket.
  */
-export type TunnelConfig = { url: string, grant: string, };
+export type TunnelConfig = { url: string, grant: string, bulk: Array<string>, };
 
 /**
  * A local upstream a preview host relays to.
@@ -71,3 +93,9 @@ localhost: boolean,
  * Framed by the editor: `frame-ancestors` is set and `x-frame-options` dropped.
  */
 frameable: boolean, };
+
+/**
+ * A checkout whose changes the front counts: its working tree, the git dir holding its index and HEAD, and the common
+ * dir holding refs and excludes (the git dir itself for a repository's main checkout).
+ */
+export type WatchedCheckout = { dir: string, gitDir: string, commonDir: string, };

package/src/front/wire-manifests.test.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import { EDGE_VERDICT_HEADER, edgeVerdictOf } from "../protocol/edge-verdict.js";
+import { INGRESS_GRANT_HEADER, INGRESS_TUNNEL_PATH } from "../protocol/ingress-contract.js";
+import { EDGE_TRANSPORTS, TERMINAL_PATH, WEBTRANSPORT_PATH } from "./browser-wire.js";
+import { ASK_PATIENCE_MS, FRAME_LENGTH_BYTES, FRONT_SOCKET_ENV, NODE_SOCKET_ENV } from "./front-wire.js";
+
+// The manifests `cargo test` writes from the Rust crates that define this wire: every value TypeScript restates is read
+// back against them, so the two languages cannot drift and contract.lock.json pins what both agree on.
+const manifest = (name: string): Record<string, unknown> =>
+    JSON.parse(readFileSync(new URL(`./generated/${name}.json`, import.meta.url), "utf8")) as Record<string, unknown>;
+
+const tunnel = manifest("tunnel") as {
+    path: string;
+    headers: { grant: string; transports: string };
+    transports: string[];
+};
+// SAFETY: front-wire's own test writes this manifest with exactly these keys, and the lock pins them.
+const socket = manifest("front-wire") as {
+    env: { frontSocket: string; nodeSocket: string };
+    askPatienceMs: number;
+    frame: { lengthBytes: number };
+};
+const browser = manifest("browser-wire") as {
+    edge: { verdictHeader: string; verdicts: { oneOf: { const: string }[] } };
+    terminal: { path: string; upgrade: string };
+    webTransport: { path: string };
+};
+
+describe("the wire outside oRPC, as the Rust crates define it", () => {
+    it("names the tunnel door and its headers as the tunnel crate does", () => {
+        expect({ path: INGRESS_TUNNEL_PATH, grant: INGRESS_GRANT_HEADER }).toEqual({
+            path: tunnel.path,
+            grant: tunnel.headers.grant,
+        });
+    });
+
+    it("names the control socket's env vars, its patience and its framing as front-wire does", () => {
+        expect({ front: FRONT_SOCKET_ENV, node: NODE_SOCKET_ENV, patience: ASK_PATIENCE_MS, length: FRAME_LENGTH_BYTES }).toEqual({
+            front: socket.env.frontSocket,
+            node: socket.env.nodeSocket,
+            patience: socket.askPatienceMs,
+            length: socket.frame.lengthBytes,
+        });
+    });
+
+    it("declares exactly the transports an edge may", () => {
+        expect<readonly string[]>(EDGE_TRANSPORTS).toEqual(tunnel.transports);
+    });
+
+    it("reads the edge's verdicts and the browser's paths as browser-wire writes them", () => {
+        const verdicts = browser.edge.verdicts.oneOf.map((verdict) => verdict.const);
+        expect(verdicts).toEqual(["no-tunnel", "unknown-sandbox", "dropped"]);
+        expect<readonly (string | undefined)[]>(verdicts.map((verdict) => edgeVerdictOf(verdict))).toEqual(verdicts);
+        expect({ header: EDGE_VERDICT_HEADER, terminal: TERMINAL_PATH, session: WEBTRANSPORT_PATH, upgrade: "websocket" }).toEqual({
+            header: browser.edge.verdictHeader,
+            terminal: browser.terminal.path,
+            session: browser.webTransport.path,
+            upgrade: browser.terminal.upgrade,
+        });
+    });
+});

package/src/ids/conversation-ids.ts

@@ -160,15 +160,16 @@ const repoSlug = (repo: string): string =>
         .replace(/^-+|-+$/g, "") || "repo";
 export const ciFixConversationId = (repo: string, runId: number): string => `${CI_FIX_PREFIX}${repoSlug(repo)}-${runId}`;
 
-// Keyed by which gates failed (fixSignature), not a run id (a push has none); the same gates red again is the same
-// failure. Hashed rather than spelled into the branch name; the fix agent's first message names the gates.
+// Keyed by when the project's push red began (pushFixBase, `red:<since>`), not a run id (a push has none): a refused push
+// is owed by that red too (push-checks-store.ts). Hashed rather than spelled into the branch name; the fix agent's first
+// message names what it is for.
 export const PUSH_FIX_PREFIX = "push-fix-";
 
 // FNV-1a, not a cryptographic hash: nothing here is secret, the only requirement is the same failure yields the same
-// seven characters in every browser and in node.
+// seven characters in every browser and in node. The one spelling: a push finding's id (push-checks-store.ts) is this too.
 const FNV_OFFSET = 0x811c_9dc5;
 const FNV_PRIME = 0x0100_0193;
-const digest = (text: string): string => {
+export const fnvDigest = (text: string): string => {
     let hash = FNV_OFFSET;
     for (let index = 0; index < text.length; index += 1) {
         hash = Math.imul(hash ^ text.charCodeAt(index), FNV_PRIME);
@@ -176,7 +177,14 @@ const digest = (text: string): string => {
     return (hash >>> 0).toString(36).padStart(7, "0");
 };
 
-export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${digest(signature)}`;
+export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${fnvDigest(signature)}`;
+
+// A red main-line check that no conversation still holding the work could take: keyed by the project and the moment its
+// red streak began, so every attempt at one streak shares a base and a later streak in the same project starts over.
+// Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.
+export const LAND_FIX_PREFIX = "land-fix-";
+export const landFixConversationId = (project: string, redSince: number): string =>
+    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(redSince / 1000).toString(36)}`;
 
 // ONE FAILURE, MANY ATTEMPTS, ONE LIVE ANSWER. The derived id above names the FAILURE; an attempt at it is a
 // conversation of its own, so starting over (another model, a clean worktree) never rewrites a record some other window

package/src/ids/session-names.ts

@@ -6,6 +6,8 @@ export const WEB_SESSION_PREFIX = "web-";
 export const AGENT_SESSION_PREFIX = "agent-";
 export const JOB_SESSION_PREFIX = "job-";
 export const BROWSER_SESSION_PREFIX = "browser-";
+// A panel's session, one per managed process; the browser string-builds these names too, so never rename it.
+export const PANEL_SESSION_PREFIX = "panel-";
 
 // Eight characters of the SDK session UUID, sanitized to the name-guard charset; groups a turn's work, including its
 // subagents', under one name. Undefined when it sanitizes to empty.
@@ -21,6 +23,11 @@ export const agentSessionName = (sessionId: string): string | undefined => {
     return suffix === undefined ? undefined : `${AGENT_SESSION_PREFIX}${suffix}`;
 };
 
+// The session a panel keyed `key` runs in, and back; undefined for a name that isn't a panel session at all.
+export const panelSession = (key: string): string => `${PANEL_SESSION_PREFIX}${key}`;
+export const panelKeyOf = (session: string | undefined): string | undefined =>
+    session?.startsWith(PANEL_SESSION_PREFIX) === true ? session.slice(PANEL_SESSION_PREFIX.length) : undefined;
+
 // The browser session one SDK session drives. Shares the suffix with agentSessionName on purpose: a conversation's
 // shell and its browser read as the pair they are.
 export const browserSessionName = (sessionId: string): string | undefined => {

package/src/index.ts

@@ -40,6 +40,7 @@ import { skillsContract } from "./contracts/skills.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
 import { usageContract } from "./contracts/usage.contract.js";
+import { offloadContract } from "./contracts/offload.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
 import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
@@ -100,6 +101,7 @@ export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
 export { type PlanLimitsHeld, type PlanLimitsRefreshed, PlanLimitsRefreshedSchema, usageContract } from "./contracts/usage.contract.js";
 export { netdiskContract } from "./contracts/netdisk.contract.js";
+export { offloadContract } from "./contracts/offload.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
@@ -110,15 +112,19 @@ export * from "./events/resume.js";
 export * from "./events/system-events.js";
 export * from "./events/transcript.js";
 export * from "./events/land-breakage.js";
+export * from "./events/land-conflict.js";
 export * from "./events/verify-nudge.js";
+export * from "./events/errands.js";
 export * from "./events/watch-wake.js";
 export * from "./policy/request-status.js";
+export * from "./events/child-run.js";
 export * from "./policy/turned-away.js";
 export * from "./text/mentions.js";
 export * from "./protocol/sse.js";
 export * from "./protocol/routes.js";
-export type { ControlReach, RouteMeta } from "./protocol/route-meta.js";
+export { type ControlReach, defaultFloor, type RouteAccess, type RouteMeta, routeAccess } from "./protocol/route-meta.js";
 export { RAW_ROUTE_LIST, RAW_ROUTES, type RawRouteKey, rawRoutePath } from "./protocol/raw-routes.js";
+export { tunnelBulkRoutes } from "./protocol/tunnel-bulk.js";
 export type { SandboxCallInput, SandboxGroup, SandboxHandlerInput, SandboxHandlerOutput, SandboxProcedure } from "./protocol/procedure-types.js";
 export * from "./policy/control-scopes.js";
 // The container's directory layout, re-exported since extensions can't import @intentic/constants directly.
@@ -130,6 +136,7 @@ export * from "./state/history-state.js";
 export * from "./state/fix-stance.js";
 export * from "./state/landed-commit.js";
 export * from "./state/fix-attempt-plan.js";
+export * from "./state/red-streak.js";
 // Provider vocabulary bottom-up: agent-runtimes, provider-specs, agent-catalog; three modules since the dependency
 // points one way.
 export * from "./models/agent-runtimes.js";
@@ -170,6 +177,7 @@ export * from "./schemas/areas.js";
 export * from "./policy/fence-paths.js";
 export * from "./policy/persona-home.js";
 export * from "./schemas/agents.js";
+export * from "./schemas/speaker.js";
 export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
 export * from "./schemas/capabilities.js";
@@ -210,29 +218,33 @@ export * from "./schemas/secrets.js";
 export * from "./schemas/netdisk.js";
 export * from "./schemas/sessions.js";
 export * from "./schemas/settings.js";
+export * from "./schemas/settings-history.js";
 export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
+export * from "./schemas/state-plan.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
 export * from "./schemas/keep-warm.js";
 export * from "./schemas/providers/usage.js";
 export * from "./schemas/vpn.js";
+export * from "./schemas/offload.js";
 export * from "./schemas/webext.js";
 export * from "./schemas/workflows.js";
 export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
+export * from "./schemas/workspace/mainline.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";
 export * from "./state/starter.js";
-export * from "./protocol/terminal-protocol.js";
 export * from "./text/title.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
+export * from "./text/shell-regions.js";
 export * from "./text/whisper.js";
 export * from "./text/workflow-faults.js";
 export * from "./text/emoji.js";
@@ -278,6 +290,7 @@ export const sandboxContract = {
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    offload: offloadContract,
     exit: exitContract,
     netdisk: netdiskContract,
     workflows: workflowsContract,

package/src/models/agent-catalog.test.ts

@@ -31,7 +31,7 @@ describe("every provider/harness pair declares what it can do", () => {
 
         expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
-        expect(["full", "tools", "browser", "http", "none"]).toContain(capabilities.mcp);
+        expect(["full", "tools", "http", "none"]).toContain(capabilities.mcp);
         expect(capabilities.execution).toContain("shell");
         for (const backend of capabilities.execution) {
             expect(["shell", "js"]).toContain(backend);
@@ -135,8 +135,8 @@ test("the ceiling has nothing to disclose; a floor names what it lacks", () => {
     expect(acpCaps.terminals).toBe(true);
 
     const codexCaps = capabilitiesOf("codex", "native");
-    expect(codexCaps.mcp).toBe("browser");
-    expect(limitationsOf(codexCaps).some((line) => line.includes("browser"))).toBe(true);
+    expect(codexCaps.mcp).toBe("http");
+    expect(limitationsOf(codexCaps)).toContain("MCP servers only, none of the daemon's own tools, no plugins");
     expect(limitationsOf(codexCaps).length).toBeLessThan(limitationsOf({ ...grokCaps, mcp: "none" }).length + 5);
 });
 
@@ -154,13 +154,15 @@ test("every axis a record can lack has words for it", () => {
         commands: false,
         terminals: false,
         recovery: false,
+        warm: false,
         instructions: "none",
         skillDiscovery: "prompt",
         rulebook: "none",
         secrets: "none",
     };
 
-    // Thirteen disclosable axes, thirteen sentences; `fastMode` is the exception, disclosed via fastAllowed.
+    // Thirteen disclosable axes, thirteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
+    // default) is no limit on the turn itself.
     expect(limitationsOf(nothing)).toHaveLength(13);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });

package/src/models/agent-catalog.ts

@@ -116,12 +116,10 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.mcp === "none"
         ? ["no MCP tools or plugins"]
         : capabilities.mcp === "http"
-          ? ["MCP tools only, no plugins or browser"]
-          : capabilities.mcp === "browser"
-            ? ["browser tools only, no other MCP"]
-            : capabilities.mcp === "tools"
-              ? ["no plugins"]
-              : []),
+          ? ["MCP servers only, none of the daemon's own tools, no plugins"]
+          : capabilities.mcp === "tools"
+            ? ["no plugins"]
+            : []),
     ...(capabilities.execution.includes("js") ? [] : ["no code runs, shell only"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),

package/src/models/agent-runtimes.ts

@@ -15,8 +15,13 @@ export interface AgentCapabilities {
     readonly permissions: "modes" | "plan";
     // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
     readonly questions: boolean;
-    // Which tools reach the agent, full down to none; never rounded up or down from what a runtime has.
-    readonly mcp: "full" | "tools" | "browser" | "http" | "none";
+    // Which tools reach the agent, full down to none; never rounded up or down from what a runtime has. Every runtime
+    // but `none` takes the turn's whole remote list (TurnTools.remote: the daemon's MCP door's mounts, browsers
+    // included, and the mcp-kind cards), so no granted server reaches one runtime and misses another:
+    // full - that list, the daemon's own in-process servers (ui, secrets, watch, …), and plugin checkouts.
+    // tools - that list, and the daemon's own tools through the runtime's host callbacks; no plugins.
+    // http - that list alone, as http MCP servers.
+    readonly mcp: "full" | "tools" | "http" | "none";
     // Which ways of executing the daemon stands behind here; distinct from `mcp`, which names tools, not execution.
     readonly execution: readonly ExecutionBackend[];
     // Reasoning-effort selection is forwarded to the model.
@@ -31,6 +36,9 @@ export interface AgentCapabilities {
     readonly terminals: boolean;
     // Fails with the coded frames auto-resume keys off, so a turn the provider killed is re-run once it's back.
     readonly recovery: boolean;
+    // Can hold an idle conversation's prompt cache warm: its provider replays the last turn's prefix as one forked,
+    // unsaved request with every tool refused (keep-warm). Only where the provider module also implements `warm`.
+    readonly warm: boolean;
     // How much of the owner's instructions this runtime takes: replace the base, append to it, or no seam at all.
     readonly instructions: "replace" | "append" | "none";
     // How the runtime discovers loaded skills: scans its own filesystem, or the daemon names them in the opener.
@@ -61,6 +69,7 @@ export const CLAUDE_CODE: AgentCapabilities = {
     commands: true,
     terminals: true,
     recovery: true,
+    warm: true,
     instructions: "replace",
     skillDiscovery: "native",
     // The only runtime with its own pre-execution hook, so the only one where a hold can park instead of refusing.
@@ -68,14 +77,15 @@ export const CLAUDE_CODE: AgentCapabilities = {
     secrets: "masked",
 };
 
-// Codex app-server: item-level events, process-backed MCP, and four seams (steer, a question request, the skills list,
-// the shared mount namespace). Daemon-side servers, plugins, server approvals stay unwired.
+// Codex app-server: item-level events, the turn's remote MCP servers over http, and four seams (steer, a question
+// request, the skills list, the shared mount namespace). The daemon's in-process servers, plugins and server approvals
+// stay unwired.
 export const CODEX: AgentCapabilities = {
     runtime: "codex",
     steering: true,
     permissions: "plan",
     questions: true,
-    mcp: "browser",
+    mcp: "http",
     execution: ["shell"],
     effort: true,
     fastMode: false,
@@ -83,6 +93,7 @@ export const CODEX: AgentCapabilities = {
     commands: true,
     terminals: false,
     recovery: false,
+    warm: false,
     // Both ride the per-thread config: one replaces Codex's base prompt, the other adds a developer message.
     instructions: "replace",
     skillDiscovery: "native",
@@ -106,6 +117,7 @@ export const OPENCODE: AgentCapabilities = {
     commands: false,
     terminals: false,
     recovery: false,
+    warm: false,
     // `system` on the prompt body, per message; adds to OpenCode's own prompt, with no seam to replace it.
     instructions: "append",
     skillDiscovery: "prompt",
@@ -122,7 +134,7 @@ export const OPENCODE_GEMINI: AgentCapabilities = {
 };
 
 // Any agent speaking the Agent Client Protocol: a documented floor, not the native ceiling. Publishes commands and
-// terminals, takes http MCP tools when offered, but owns its own model, effort and permission posture.
+// terminals, takes the turn's remote MCP servers when it advertises http MCP, but owns its own model, effort and permission posture.
 export const ACP: AgentCapabilities = {
     runtime: "acp",
     steering: false,
@@ -136,6 +148,7 @@ export const ACP: AgentCapabilities = {
     commands: true,
     terminals: true,
     recovery: false,
+    warm: false,
     // ACP's calls carry no system field: the agent owns its instructions, the persona note rides the message.
     instructions: "none",
     skillDiscovery: "prompt",
@@ -159,6 +172,7 @@ export const PI: AgentCapabilities = {
     commands: true,
     terminals: false,
     recovery: false,
+    warm: false,
     // Pi's RPC sets no standing instructions; like ACP, it hears the persona note through the user message.
     instructions: "none",
     skillDiscovery: "prompt",
@@ -177,7 +191,7 @@ export const CURSOR: AgentCapabilities = {
     permissions: "plan",
     // True since the daemon supplies its own ask tool; Cursor's own can fabricate an answer, so it's disallowed.
     questions: true,
-    // stdio + http/sse MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
+    // The turn's remote MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
     mcp: "tools",
     // The JS backend rides Cursor's custom-tool seam rather than an MCP server, and consults the rulebook in its
     // handler, since the hook file only covers the shell.
@@ -193,6 +207,7 @@ export const CURSOR: AgentCapabilities = {
     terminals: false,
     // The SDK throws typed errors instead of dissolving a refusal into prose, so the adapter files coded frames.
     recovery: true,
+    warm: false,
     // append, reached differently: `beforeSubmitPrompt`'s reply folds the daemon's text onto Cursor's base. The SDK can
     // replace that base outright, but only for an entitled account, so the seam every turn can reach is this one.
     instructions: "append",

package/src/models/capability-ledger.test.ts

@@ -32,6 +32,8 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // - refuse-only: a hold refuses instead of parking
     // - other values: park on a card
     rulebook: "enforced",
+    // agent/run/turn/cache-keepwarm.ts files nothing to keep warm for a turn whose runtime lacks it.
+    warm: "enforced",
 
     // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
     questions: "descriptive",