@intentic/sandbox-contract 1.225.0 → 1.226.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.225.0",
+  "version": "1.226.1",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -89,9 +89,9 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/constants": "1.225.0",
-    "@intentic/registry": "1.225.0",
-    "@intentic/extension-manifest": "1.225.0"
+    "@intentic/constants": "1.226.1",
+    "@intentic/extension-manifest": "1.226.1",
+    "@intentic/registry": "1.226.1"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/agent-catalog.test.ts

@@ -49,6 +49,15 @@ describe("every provider/harness pair declares what it can do", () => {
         }
         expect(["namespace", "cwd"]).toContain(capabilities.isolation);
         expect(["replace", "append", "none"]).toContain(capabilities.instructions);
+        expect(["hooks", "approval", "refuse-only", "none"]).toContain(capabilities.rulebook);
+        expect(["masked", "none"]).toContain(capabilities.secrets);
+        /* Masking is a PostToolUse hook and nothing else can edit what a model reads, so a record claiming
+         * masked without hooks would be claiming a seam that does not exist (see the axis doc). The one
+         * direction that IS legal is hooks without masking, which is why this is an implication and not
+         * equality. */
+        if (capabilities.secrets === "masked") {
+            expect(capabilities.rulebook).toBe("hooks");
+        }
         // 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));
@@ -176,16 +185,52 @@ test("every axis a record can lack has words for it", () => {
         terminals: false,
         recovery: false,
         instructions: "none",
+        rulebook: "none",
+        secrets: "none",
     };
 
-    // Eleven DISCLOSABLE axes, eleven sentences: an axis added to the interface without one would silently
-    // never be disclosed. fastMode is the deliberate twelfth: a record alone can't tell the truth about it (a
+    // Thirteen DISCLOSABLE axes, thirteen sentences: an axis added to the interface without one would silently
+    // never be disclosed. fastMode is the deliberate exception: a record alone can't tell the truth about it (a
     // translator-routed turn reads true here and still can't go fast), so it is answered by fastAllowed
     // instead. Anything else added to the interface has to move this number.
-    expect(limitationsOf(nothing)).toHaveLength(11);
+    expect(limitationsOf(nothing)).toHaveLength(13);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });
 
+/* The two safety axes, checked the same way the instruction axis is below and for the same reason: `rulebook`
+ * has a middle value, and disclosing the floor's words for it would tell a Codex user their rules are ignored
+ * when they are in fact being applied to everything Codex asks about. */
+test("the safety axes disclose the middle answer differently from the floor", () => {
+    const claude = limitationsOf(capabilitiesOf("claude", "native")).join(" ");
+    const codex = limitationsOf(capabilitiesOf("codex", "native")).join(" ");
+    const pi = limitationsOf(capabilitiesOf("pi", "native")).join(" ");
+
+    // The ceiling says nothing about either axis.
+    expect(claude).not.toContain("command rules");
+    expect(claude).not.toContain("stored secrets");
+
+    // The middle: rules DO apply, to what the vendor raises. Never the floor's flat "aren't applied".
+    expect(codex).toContain("only to calls this agent asks about");
+    expect(codex).not.toContain("aren't applied");
+
+    // The floor: no seam at all, said plainly.
+    expect(pi).toContain("your command rules aren't applied");
+
+    /* The third answer, which exists because OpenCode's watchdog aborts a turn that pauses. Its sentence must
+     * say the rules DO bite (unlike Pi's) and that a hold cannot ask (unlike Codex's). */
+    const grok = limitationsOf(capabilitiesOf("grok", "native")).join(" ");
+    expect(grok).toContain("a rule set to hold refuses instead");
+    expect(grok).not.toContain("aren't applied");
+    expect(grok).not.toContain("only to calls this agent asks about");
+    // Gemini rides the same loop, so it must read the same way.
+    expect(limitationsOf(capabilitiesOf("gemini", "native")).join(" ")).toBe(grok);
+
+    // Masking is binary and structural, so every non-Claude runtime says the same thing.
+    for (const provider of ["codex", "grok", "gemini", "pi", "some-installed-agent"] as const) {
+        expect(limitationsOf(capabilitiesOf(provider, "native")).join(" ")).toContain("stored secrets reach the model unmasked");
+    }
+});
+
 /* The instruction axis has THREE values and only two of them are worth a sentence, which is the one shape the
  * count above cannot check: a middle value that discloses the same words as the floor would tell a Grok user
  * their prompt is ignored when it is in fact being sent. */

package/src/agent-catalog.ts

@@ -286,6 +286,49 @@ export interface AgentCapabilities {
      * only the Claude Code loop's: Codex's own base describes Codex's own tools, so swapping it for a prompt
      * written about another harness is the owner's deliberate act (their custom text), never ours. */
     readonly instructions: "replace" | "append" | "none";
+    /* WHETHER THE OWNER'S COMMAND RULEBOOK REACHES THIS RUNTIME (SandboxSettings.commandRules, decided by
+     * guard/actions.ts commandRun, delivered by guard/command-gate.ts).
+     *
+     * It exists because the rulebook was silently a Claude Code rulebook. The gate is a PreToolUse hook, which
+     * is an Agent SDK seam, so an owner who set `files.destructive: hold` was asked on a Claude turn and never
+     * on a Codex, Grok, Gemini, Pi or ACP one, with nothing on screen saying so. Same failure mode as the
+     * `instructions` axis above, and the same fix: name it once, let every surface read it.
+     *
+     *   "hooks"      , the runtime's own pre-execution hook carries the verdict and a HOLD can park the call.
+     *                  The Claude Code loop, whose PreToolUse hook fires even under bypassPermissions.
+     *   "approval"   , the vendor publishes a per-call approval channel the daemon answers from the same
+     *                  rulebook, and a hold parks on a card because the vendor is blocked on the answer
+     *                  (Codex's `item/commandExecution/requestApproval`, ACP's `session/request_permission`).
+     *                  Weaker than "hooks" in one stated way: the vendor decides WHICH calls it asks about, so a
+     *                  class it never raises is a class the rulebook cannot see. What it does raise is judged by
+     *                  the same decide fn.
+     *   "refuse-only", the same channel, but the vendor puts a CLOCK on the wait, so a hold cannot park and
+     *                  arrives as a refusal instead. OpenCode's turn has an inactivity watchdog that reads a
+     *                  paused approval as a stalled turn; a card there would break the turn rather than gate it.
+     *                  `deny` rules work fully; `hold` rules stop the command and say they could not ask.
+     *   "none"       , the runtime publishes no seam before it runs a command, so no rule can apply. Pi runs its
+     *                  bash in-process with no approval channel at all.
+     *
+     * The taint floor rides this axis too: a runtime with no consult has no place to apply it, which is why
+     * `conversationTainted` must read a "none" runtime as tainted rather than as clean (guard/turn-taint.ts). */
+    readonly rulebook: "hooks" | "approval" | "refuse-only" | "none";
+    /* WHETHER A STORED CREDENTIAL IS MASKED IN WHAT THIS RUNTIME'S MODEL READS (secrets/secret-registry.ts and
+     * the two seams around it).
+     *
+     * "masked" is the full round trip: every stored value is replaced by its `{{secret:name}}` reference on the
+     * way into the model's context, and the same reference resolves back to the value at the two exits that
+     * spend it (a shell command, a script). The Claude Code loop, via PostToolUse and PreToolUse.
+     *
+     * "none" is a STRUCTURAL limit, not an unfinished wire, and it is the reason this axis is honest rather
+     * than aspirational. On every other runtime the tool runs inside the VENDOR'S own loop: the model has read
+     * the result before the daemon sees any frame about it, so there is no seam left to rewrite. A PostToolUse
+     * hook is the only thing that can edit what a model reads, and only the Claude Code loop has one. Nothing
+     * about wiring more transports changes that, which is why the answer here is a disclosure and the real fix
+     * is to stop putting credentials where a vendor's tool can read them at all.
+     *
+     * Read by limitationsOf, and by agent/system-prompt.ts, which must not teach the reference language to a
+     * runtime that has no exit for it. */
+    readonly secrets: "masked" | "none";
 }
 
 // The Claude Code Agent SDK loop, the ceiling every other runtime is measured against, and the only one that
@@ -307,6 +350,10 @@ const CLAUDE_CODE: AgentCapabilities = {
     terminals: true,
     recovery: true,
     instructions: "replace",
+    // The only runtime with a pre-execution hook of its own, which is why it is the only one where a HOLD can
+    // park the call and wait for a card rather than having to refuse it.
+    rulebook: "hooks",
+    secrets: "masked",
 };
 
 /* Codex app-server: item-level events, process-backed MCP servers, and the four interactive seams its protocol
@@ -336,6 +383,13 @@ const CODEX: AgentCapabilities = {
      * message ahead of its skills and team blocks. Verified against codex-cli 0.147 by reading what actually
      * reached the wire, the keys are undocumented, and a strings dump proves only that they parse. */
     instructions: "replace",
+    /* App-server publishes `item/commandExecution/requestApproval`, whose params carry the command text, and
+     * takes `accept`/`decline` back (codex-cli 0.147's own generated JSON Schema, read with
+     * `codex app-server generate-json-schema`). The daemon only asks Codex to raise those requests when the
+     * owner has written command rules, so an unconfigured workspace keeps `approvalPolicy: "never"` and pays
+     * nothing (codex/codex-agent.ts threadOptions). */
+    rulebook: "approval",
+    secrets: "none",
 };
 
 // OpenCode (the Grok runtime): its own agentic loop, its own tools, allow-all permissions. It takes a model id,
@@ -357,6 +411,16 @@ const OPENCODE: AgentCapabilities = {
     // replacing that, so a custom prompt lands here as extra instructions, and the settings page says so
     // rather than letting "replaces everything" quietly mean something else on two providers.
     instructions: "append",
+    /* OpenCode asks over its own permission channel (`permission.updated`, replied on
+     * `/session/{id}/permissions/{permissionID}`, vocabulary once/always/reject), and the daemon judges what it
+     * raises with the same decide fn every other runtime uses.
+     *
+     * REFUSE-ONLY because of its watchdog, not because of its protocol. A Grok/Gemini turn is aborted after two
+     * minutes without an event for its session (grok/grok-agent.ts GROK_INACTIVITY_MS), and a permission paused
+     * on a person is exactly that silence, so a parked card would turn "ask me" into a broken turn. A `deny`
+     * rule is enforced in full; a `hold` stops the command and tells the agent it could not be asked about. */
+    rulebook: "refuse-only",
+    secrets: "none",
 };
 
 /* The same OpenCode loop, serving Gemini instead of xAI, identical abilities, which is the point of giving it
@@ -396,6 +460,12 @@ const ACP: AgentCapabilities = {
     // ACP's `session/new` and `session/prompt` carry no system field: the agent owns its own instructions the
     // same way it owns its model and its permission posture. The persona note takes the user message instead.
     instructions: "none",
+    /* `session/request_permission` is in the protocol floor, so every conforming agent has the channel and the
+     * daemon answers it from the rulebook (acp/acp-permissions.ts). The caveat the "approval" value already
+     * carries is at its widest here: WHICH calls an agent asks about is entirely the agent's choice, and one
+     * that never asks is one no rule can reach. */
+    rulebook: "approval",
+    secrets: "none",
 };
 
 /* THE PI CAPABILITY ID IS RESERVED, the same way the five native ids are: an `agent`-kind capability installed
@@ -426,6 +496,12 @@ const PI: AgentCapabilities = {
     // Pi's RPC opens a session with a prompt and steers it; nothing in that protocol sets standing
     // instructions, so like ACP it hears the persona note through the user message.
     instructions: "none",
+    /* THE ONE RUNTIME WITH NO SEAM AT ALL. Pi runs bash in-process and its RPC publishes no approval request,
+     * so there is nothing to consult before a command runs and no rule the owner writes can apply here. Said
+     * out loud rather than left to be discovered: limitationsOf renders it, and the taint floor treats a "none"
+     * runtime as permanently tainted, because a bit nobody can act on is worse than no bit. */
+    rulebook: "none",
+    secrets: "none",
 };
 
 // The pair → its record. An `endpoint/<id>` provider is a model API the user configured, driven BY the Claude
@@ -501,6 +577,18 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
      * mechanism, because that is the thing they wrote and the thing that will or will not be in force. */
     ...(capabilities.instructions === "append" ? ["your system prompt is added to theirs, not replacing it"] : []),
     ...(capabilities.instructions === "none" ? ["your system prompt isn't applied"] : []),
+    /* THE TWO SAFETY AXES, phrased as what the OWNER loses rather than as which seam is missing, because both
+     * describe something they configured on a settings page and would otherwise assume was in force everywhere.
+     *
+     * "hooks" and "masked" are the ceiling and disclose nothing. The "approval" middle answer discloses the one
+     * thing that genuinely differs from a hook: the vendor picks which calls it asks about, so a rule can only
+     * reach what it chose to raise. */
+    ...(capabilities.rulebook === "approval" ? ["your command rules apply only to calls this agent asks about"] : []),
+    ...(capabilities.rulebook === "refuse-only"
+        ? ["your command rules can stop a command here but not pause to ask: a rule set to hold refuses instead"]
+        : []),
+    ...(capabilities.rulebook === "none" ? ["your command rules aren't applied"] : []),
+    ...(capabilities.secrets === "none" ? ["stored secrets reach the model unmasked, and `{{secret:name}}` isn't substituted"] : []),
 ];
 
 // Claude's compile-time model floor, shared by the daemon's catalog (claude-models.ts, its last rung, reached

package/src/capability-ledger.test.ts

@@ -57,6 +57,11 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // turn-plan.ts (honoured) plans the JS backend only where "js" is declared, so a runtime without it is
     // handed no `jsExecution` and mounts no Code tool: the same drop-what-you-can't-honour rule as `effort`.
     execution: "enforced",
+    /* turn-plan.ts (honoured) carries this onto every request and guard/turn-gate.ts DERIVES the gate's shape
+     * from it: "none" gets no consult and a permanently-set taint bit, "refuse-only" cannot park so a hold
+     * refuses, the other two park on a card. So a row that lies about itself changes how its turns behave.
+     * It also decides whether Codex is asked to raise approvals at all (codex-agent.ts threadOptions). */
+    rulebook: "enforced",
 
     /* DESCRIPTIVE: true of the runtime, and nothing consults them. Each describes behaviour that is emergent
      * rather than gated: an agent that never emits `question` frames simply never asks, one that publishes no
@@ -68,6 +73,14 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     commands: "descriptive",
     terminals: "descriptive",
     recovery: "descriptive",
+    /* DESCRIPTIVE, and the one entry here whose gap cannot be closed by wiring. Masking a stored credential in
+     * what the model READS needs a seam that edits a tool result before the model sees it, and only the Claude
+     * Code loop has one (a PostToolUse hook). Every other runtime runs its tools inside the VENDOR'S loop: the
+     * model has read the result before the daemon sees any frame about it. So nothing consults this field, and
+     * nothing can: it exists so limitationsOf can say out loud what is true, instead of letting an owner who
+     * stored a credential assume it is hidden everywhere. Moving it to ENFORCED would take a runtime that
+     * publishes a result-rewriting seam, not a change here. */
+    secrets: "descriptive",
 };
 
 // The full ceiling: every ability real, so `limitationsOf` has nothing to say about it. Read from the catalog
@@ -92,10 +105,16 @@ describe("a descriptive claim reaches the user", () => {
         expect(limitationsOf(CEILING)).toEqual([]);
     });
 
+    /* What "lacking this axis" MEANS for a field that is not a boolean. A boolean diminishes to false; anything
+     * else has to name its own floor here, because only the axis knows which of its values is the weak one.
+     * Adding a non-boolean descriptive field without an entry fails below rather than silently testing nothing. */
+    const DIMINISHED: Partial<Record<keyof AgentCapabilities, unknown>> = { secrets: "none" };
+
     it.each(fieldsWhere("descriptive"))("%s puts its own sentence in the picker when the runtime lacks it", (field) => {
-        expect(typeof CEILING[field], `${field} is descriptive but not a boolean — teach the flip below how to diminish it`).toBe("boolean");
+        const floor = typeof CEILING[field] === "boolean" ? false : DIMINISHED[field];
+        expect(floor, `${field} is descriptive and not a boolean: add its weakest value to DIMINISHED above`).toBeDefined();
 
-        const lacking: AgentCapabilities = { ...CEILING, [field]: false };
+        const lacking: AgentCapabilities = { ...CEILING, [field]: floor };
 
         expect(limitationsOf(lacking)).toHaveLength(1);
     });

package/src/contracts/activity.contract.ts

@@ -4,6 +4,22 @@ import { ActivityListSchema, ActivityQuerySchema, ActivityStatusSchema } from ".
 // The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design,
 // events are appended daemon-side only, so the log stays a trustworthy record of what the agent did.
 export const activityContract = {
-    list: oc.route({ method: "GET", path: "/activity" }).input(ActivityQuerySchema).output(ActivityListSchema),
-    status: oc.route({ method: "GET", path: "/activity/status" }).output(ActivityStatusSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/activity",
+            summary: "What the agent has done out in the world",
+            description:
+                "The audit trail of actions taken on outside services. Read-only on purpose: entries are written by the sandbox alone, which is what makes it a record worth trusting.",
+        })
+        .input(ActivityQuerySchema)
+        .output(ActivityListSchema),
+    status: oc
+        .route({
+            method: "GET",
+            path: "/activity/status",
+            summary: "Whether the audit trail is being kept",
+            description: "Which sources are feeding the record and whether each is working.",
+        })
+        .output(ActivityStatusSchema),
 };

package/src/contracts/agent.contract.ts

@@ -19,20 +19,90 @@ import {
 // turn waiting on any interactive card (plan approval, clarifying questions, a per-tool permission prompt);
 // steer injects a user message into the running turn; stop hard-cancels it daemon-side.
 export const agentContract = {
-    run: oc.route({ method: "POST", path: "/agent" }).input(AgentTurnSchema).output(StartedTurnSchema),
-    attach: oc.route({ method: "POST", path: "/agent/attach" }).input(AttachTurnSchema).output(eventIterator(AttachFrameSchema)),
-    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),
+    run: oc
+        .route({
+            method: "POST",
+            path: "/agent",
+            summary: "Say something to an agent",
+            description:
+                "Starts a turn and answers immediately with its id; the work runs inside the sandbox whether or not anybody stays connected. Watch it by attaching. Naming a conversation that does not exist yet opens it.",
+        })
+        .input(AgentTurnSchema)
+        .output(StartedTurnSchema),
+    attach: oc
+        .route({
+            method: "POST",
+            path: "/agent/attach",
+            summary: "Watch a turn happen",
+            description:
+                "Streams everything the agent does: its words, the tools it reaches for, and the answers it gets. Give it the point you have already seen and it replays from there before going live, so a reload loses nothing. The window that started the turn holds no special claim, and any number of watchers on any number of devices see the same thing.",
+        })
+        .input(AttachTurnSchema)
+        .output(eventIterator(AttachFrameSchema)),
+    reply: oc
+        .route({
+            method: "POST",
+            path: "/agent/reply",
+            summary: "Answer a question the agent asked",
+            description:
+                "Un-parks a turn that is waiting on you: approving a plan, choosing between options, or permitting a tool. The turn picks up where it stopped.",
+        })
+        .input(AgentReplySchema)
+        .output(OkSchema),
+    steer: oc
+        .route({
+            method: "POST",
+            path: "/agent/steer",
+            summary: "Interrupt a running turn",
+            description:
+                "Slips a message into a turn already under way, without stopping it. This is how you redirect an agent mid-thought rather than waiting for it to finish being wrong.",
+        })
+        .input(SteerSchema)
+        .output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/agent/stop",
+            summary: "Stop a turn now",
+            description: "Cancels the running turn inside the sandbox. Whatever it had already written to disk stays written.",
+        })
+        .input(StopTurnSchema)
+        .output(OkSchema),
     // Go back to a message: restore the workspace to that turn's checkpoint, drop the messages after it, and
     // forget the provider session. CONFLICT while a turn is running, a restore cannot overwrite files an
     // agent is editing. NOT_FOUND when that message has no checkpoint to go back to.
-    rewind: oc.route({ method: "POST", path: "/agent/rewind" }).input(RewindTurnSchema).output(RewindResultSchema),
+    rewind: oc
+        .route({
+            method: "POST",
+            path: "/agent/rewind",
+            summary: "Go back to an earlier message",
+            description:
+                "Puts the files back as they stood at that point, drops every message after it, and forgets what the model remembered, so the next thing you say starts from there cleanly. Refused while a turn is running, because a restore cannot overwrite files an agent is editing, and refused for a message with no saved state to return to.",
+        })
+        .input(RewindTurnSchema)
+        .output(RewindResultSchema),
     // 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),
+    commands: oc
+        .route({
+            method: "GET",
+            path: "/agent/commands",
+            summary: "Shortcut commands the agent knows",
+            description:
+                "The commands a provider published the last time one of its turns ran, so a composer can offer them before this conversation has run anything. A running turn's own list wins over this one.",
+        })
+        .input(AgentCommandsQuerySchema)
+        .output(AgentCommandsSchema),
     // The last refusal per provider, as reported by whichever turn was refused (ProviderRefusalSchema). Read
     // alongside the account listings by the surfaces that draw plan limits: the snapshot on an account row says
     // how full its pools were when last polled, and this says whether one of them has since said no.
-    refusals: oc.route({ method: "GET", path: "/agent/refusals" }).output(ProviderRefusalsSchema),
+    refusals: oc
+        .route({
+            method: "GET",
+            path: "/agent/refusals",
+            summary: "The last time each provider said no",
+            description:
+                "What each model provider most recently refused and why. Read this alongside an account's usage: the usage says how full it was when last checked, this says whether it has since started turning work away.",
+        })
+        .output(ProviderRefusalsSchema),
 };

package/src/contracts/agents.contract.ts

@@ -47,27 +47,96 @@ import {
 // own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
 // agent's repo leaves that one behind rather than taking the batch down with it.
 export const agentsContract = {
-    list: oc.route({ method: "GET", path: "/agents" }).output(AgentsListSchema),
-    archived: oc.route({ method: "GET", path: "/agents/archived" }).output(AgentsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/agents",
+            summary: "Every live conversation",
+            description:
+                "The fleet as the board draws it: each conversation with its title, what it is doing, when it last moved and whether anybody has read it since. Archived conversations are not in here.",
+        })
+        .output(AgentsListSchema),
+    archived: oc
+        .route({
+            method: "GET",
+            path: "/agents/archived",
+            summary: "Conversations put away",
+            description:
+                "The same shape as the live fleet, for the conversations somebody has decided are finished. Their work is kept, and any one of them can be brought back.",
+        })
+        .output(AgentsListSchema),
     // The board's filter. Answers over BOTH halves of the fleet, the live roster and the archive, because
     // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
     // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
     // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
-    search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
-    get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
-    transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).output(AgentTranscriptSchema),
+    search: oc
+        .route({
+            method: "GET",
+            path: "/agents/search",
+            summary: "Find a conversation",
+            description:
+                "Searches the live fleet and the archive together. Both halves on purpose: the board hides finished work by design, and a filter that says it found nothing while the answer sits one click away is simply wrong.",
+        })
+        .input(AgentSearchQuerySchema)
+        .output(AgentSearchResultSchema),
+    get: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}",
+            summary: "One conversation's card",
+            description: "Everything the board shows for a single conversation: its title, state, working branch, unread marker and timestamps.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    transcript: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/transcript",
+            summary: "The full conversation record",
+            description:
+                "Every message in one conversation, in order, including the tool calls and their results. This is the record the chat replays and the next turn is seeded from.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentTranscriptSchema),
     /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
      * turn behind them and no reply. The row is marked `placed` for human readers (RestoredMessageSchema); the
      * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
      * runtime session seeded from the record, where the placed line reads as the agent's own words, because
      * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
      * established between turns, and a concurrent turn would resume the very session this exists to retire. */
-    place: oc.route({ method: "POST", path: "/agents/{id}/place" }).input(AgentPlaceSchema).output(OkSchema),
-    rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).input(AgentRenameSchema).output(AgentSummarySchema),
+    place: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/place",
+            summary: "Put words in the agent's mouth",
+            description:
+                "Writes a line into the record as though the agent had said it, with no turn behind it and no reply. Human readers see it marked as placed. The next real turn starts fresh from the record, where the line reads as the agent's own. Refused while a turn is running.",
+        })
+        .input(AgentPlaceSchema)
+        .output(OkSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/rename",
+            summary: "Retitle a conversation",
+            description:
+                "Sets the title a person chose, replacing the one that was generated. Allowed while the conversation is working, and it does not count as activity.",
+        })
+        .input(AgentRenameSchema)
+        .output(AgentSummarySchema),
     // This agent's own land-at-completion posture, an override of the sandbox-wide `autoLand` setting; null
     // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
     // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
-    autoLand: oc.route({ method: "POST", path: "/agents/{id}/auto-land" }).input(AgentAutoLandSchema).output(AgentSummarySchema),
+    autoLand: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/auto-land",
+            summary: "Whether this conversation merges its work automatically",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to go back to following the default. Deliberately allowed mid-turn, because the setting is read when the turn finishes, so flipping it while the agent works means exactly hold this piece of work for review.",
+        })
+        .input(AgentAutoLandSchema)
+        .output(AgentSummarySchema),
     /* THIS conversation's answer to a provider outage, an override of the sandbox-wide `resumeAfterOutage`
      * setting; null clears it back to "inherit". The chat's offer at the moment a turn dies writes this and
      * never the global: the press happens inside one conversation and means "finish this piece of work", so
@@ -76,20 +145,112 @@ export const agentsContract = {
      * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too, an outage kills a
      * main-tree chat exactly as readily as an isolated one, and there is no branch involved either way. */
     resumeAfterOutage: oc
-        .route({ method: "POST", path: "/agents/{id}/resume-after-outage" })
+        .route({
+            method: "POST",
+            path: "/agents/{id}/resume-after-outage",
+            summary: "Whether this conversation retries after a provider outage",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. This is what the offer shown when a turn dies writes, because the press happens inside one conversation and honestly means finish this piece of work.",
+        })
         .input(AgentResumeAfterOutageSchema)
         .output(AgentSummarySchema),
-    seen: oc.route({ method: "POST", path: "/agents/{id}/seen" }).input(AgentIdSchema).output(AgentSummarySchema),
-    seenAll: oc.route({ method: "POST", path: "/agents/seen" }).output(AgentsListSchema),
-    diff: oc.route({ method: "GET", path: "/agents/{id}/diff" }).input(AgentIdSchema).output(AgentChangesSchema),
-    fileDiff: oc.route({ method: "GET", path: "/agents/{id}/{repo}/file-diff" }).input(AgentFileDiffQuerySchema).output(FileDiffSchema),
-    land: oc.route({ method: "POST", path: "/agents/{id}/land" }).input(AgentLandSchema).output(LandResultSchema),
+    seen: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/seen",
+            summary: "Mark a conversation read",
+            description:
+                "Stamps the read marker behind the unread badge on one card. Allowed while the conversation is working, and reading never counts as activity.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    seenAll: oc
+        .route({
+            method: "POST",
+            path: "/agents/seen",
+            summary: "Mark every conversation read",
+            description: "Clears the unread badge across the whole fleet at once, and hands the refreshed list back.",
+        })
+        .output(AgentsListSchema),
+    diff: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/diff",
+            summary: "Everything a conversation has changed",
+            description:
+                "One flat set of changed files per repo, measured against where each repo stood when the conversation started, with every file flagged as already merged or not. Not the staged-and-unstaged shape a working copy has, because nobody ever checks this branch out to stage into it.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentChangesSchema),
+    fileDiff: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/{repo}/file-diff",
+            summary: "One file's before and after in a conversation's work",
+            description: "Both sides of a single file: what it held when the conversation started and what it holds on its branch now.",
+        })
+        .input(AgentFileDiffQuerySchema)
+        .output(FileDiffSchema),
+    land: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/land",
+            summary: "Merge a conversation's work into the workspace",
+            description:
+                "Brings the conversation's branches into the main tree, one repo at a time. A conflict is reported rather than raised and nothing is lost when it fails. Refused while a turn is running, and refused for a conversation that works directly in the shared tree, which has nothing to merge.",
+        })
+        .input(AgentLandSchema)
+        .output(LandResultSchema),
     // A collaborator's ask for the land they may not perform themselves (role floors put `land`/`discard` at
     // maintainer). Stamps AgentSummarySchema.landRequested with the caller's identity and re-frames the fleet,
     // so every maintainer's board carries the request; the land or discard that answers it clears the stamp.
-    requestLand: oc.route({ method: "POST", path: "/agents/{id}/request-land" }).input(AgentIdSchema).output(AgentSummarySchema),
-    discard: oc.route({ method: "POST", path: "/agents/{id}/discard" }).input(AgentIdSchema).output(OkSchema),
-    archive: oc.route({ method: "POST", path: "/agents/archive" }).input(AgentArchiveSchema).output(AgentsMovedSchema),
-    unarchive: oc.route({ method: "POST", path: "/agents/unarchive" }).input(AgentIdsSchema).output(AgentsMovedSchema),
-    purge: oc.route({ method: "POST", path: "/agents/purge" }).output(AgentsRemovedSchema),
+    requestLand: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/request-land",
+            summary: "Ask a maintainer to merge this work",
+            description:
+                "For a collaborator who is not allowed to merge: marks the conversation as waiting for review, with who asked. The request shows on every maintainer's board and clears when somebody merges or discards it.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    discard: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/discard",
+            summary: "Throw a conversation's work away",
+            description:
+                "Deletes the conversation's working copies, its branches and its entry. Nothing is kept. Refused while a turn is running, and refused for a conversation working in the shared tree.",
+        })
+        .input(AgentIdSchema)
+        .output(OkSchema),
+    archive: oc
+        .route({
+            method: "POST",
+            path: "/agents/archive",
+            summary: "Put conversations away",
+            description:
+                "The gentle counterpart to discarding. Commits whatever the conversation still has in progress onto its own branch, releases its working copy, and keeps the entry and the record. It leaves the live fleet and joins the archive. Refused for a conversation that is running.",
+        })
+        .input(AgentArchiveSchema)
+        .output(AgentsMovedSchema),
+    unarchive: oc
+        .route({
+            method: "POST",
+            path: "/agents/unarchive",
+            summary: "Bring conversations back",
+            description:
+                "Returns archived conversations to the live fleet. The next turn picks up a fresh working copy from the branch that was kept.",
+        })
+        .input(AgentIdsSchema)
+        .output(AgentsMovedSchema),
+    purge: oc
+        .route({
+            method: "POST",
+            path: "/agents/purge",
+            summary: "Empty the archive for good",
+            description:
+                "Discards every conversation already in the archive: working copies, branches and entries. The whole archive rather than a chosen few, because the archive is the pile somebody has already decided is over. A teardown that fails on one conversation leaves that one behind instead of taking the rest down with it.",
+        })
+        .output(AgentsRemovedSchema),
 };