@intentic/sandbox-contract 1.244.0 → 1.246.1

package/src/contracts/system.contract.ts

@@ -2,11 +2,12 @@ import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
 import { SessionTranscriptSchema, SystemEventSchema } from "../events.js";
 import {
-    MachineCommandInputSchema,
-    MachineCommandResultSchema,
-    MachineFlowLineSchema,
-    MachineSandboxFlowInputSchema,
-} from "../schemas/computers.js";
+    DeviceAgentFlowInputSchema,
+    DeviceCommandInputSchema,
+    DeviceCommandResultSchema,
+    DeviceFlowLineSchema,
+    DeviceSandboxFlowInputSchema,
+} from "../schemas/devices.js";
 import { PresenceReportSchema } from "../schemas/logs.js";
 import { OkSchema } from "../schemas/shared.js";
 import { DaemonSessionSchema, InfoSchema, ManifestProblemsSchema } from "../schemas/system.js";
@@ -160,52 +161,70 @@ export const systemContract = {
         .route({
             method: "GET",
             path: "/system/subagents",
-            summary: "Helpers the agents have started",
+            summary: "Subagents the agents have started",
             description:
-                "Every helper agent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
+                "Every subagent and child agent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
         })
         .output(SubagentsListSchema),
     subagentTranscript: oc
         .route({
             method: "GET",
             path: "/system/subagents/{id}/transcript",
-            summary: "A helper agent's record",
+            summary: "A subagent's record",
             description:
-                "The full record of one delegated helper, in the same shape as any other conversation. It comes live from the parent turn while the helper works, and from stored history once it has finished.",
+                "The full record of one delegated subagent, in the same shape as any other conversation. It comes live from the parent turn while it works, and from stored history once it has finished.",
         })
         .input(SubagentIdParamSchema)
         .output(SessionTranscriptSchema),
-    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own computers,
-     * the Computers view's buttons, relayed to the machine over the socket it holds open to us.
+    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own devices,
+     * the Devices view's buttons, relayed to the machine over the socket it holds open to us.
      *
      * Streamed because the slowest of these takes minutes, and it is the same stream whatever the op: one door
      * for one decision, so the view has one shape to render rather than one per duration. The daemon adds no
      * judgement, the machine enforces its own switches and its refusal arrives as the terminal `error` line,
      * in its own words, naming the control to flip. */
-    manageMachineSandbox: oc
+    manageDeviceSandbox: oc
         .route({
             method: "POST",
-            path: "/system/computers/{id}/sandboxes/{slug}",
-            summary: "Drive a sandbox on one of your own computers",
+            path: "/system/devices/{id}/sandboxes/{slug}",
+            summary: "Drive a sandbox on one of your own devices",
             description:
-                "Start, stop, restart, update, rebuild, roll back or remove a sandbox running on a machine you own, relayed over the connection that machine holds open. The answer is a stream because the slowest of these takes minutes, and it is the same stream whichever you ask for. The daemon adds no opinion: the machine enforces its own permissions and a refusal arrives as the last line, in the machine's words, naming the switch to flip.",
+                "Start, stop, restart, update, rebuild, roll back, reshape (its memory and CPU caps, privileged, GPU) or remove a sandbox running on a machine you own, relayed over the connection that machine holds open. The answer is a stream because the slowest of these takes minutes, and it is the same stream whichever you ask for. The daemon adds no opinion: the machine enforces its own permissions and a refusal arrives as the last line, in the machine's words, naming the switch to flip.",
         })
-        .input(MachineSandboxFlowInputSchema)
-        .output(eventIterator(MachineFlowLineSchema)),
-    /* Run one of this product's own CLI actions on a connected computer, from a button rather than through an
+        .input(DeviceSandboxFlowInputSchema)
+        .output(eventIterator(DeviceFlowLineSchema)),
+    /* Run one of this product's own CLI actions on a connected device, from a button rather than through an
      * agent. A closed set of names, and the daemon builds the command line from the name (see the schema): the
      * browser never sends one, because the socket underneath also carries `run_command`.
      *
      * Not a stream, unlike the sandbox ops beside it: these are seconds-long CLI calls whose whole answer is the
      * sentence they print at the end, and a stream for that is a shape with nothing to put in it. */
-    runMachineCommand: oc
+    runDeviceCommand: oc
         .route({
             method: "POST",
-            path: "/system/computers/{id}/commands/{command}",
-            summary: "Run one of your computer's own CLI actions",
+            path: "/system/devices/{id}/commands/{command}",
+            summary: "Run one of your device's own CLI actions",
             description:
-                "Performs a named action on a machine you own by running its own intentic-machine command there — turning that computer's port mirroring off, say — over the connection it holds open. The set of actions is fixed and the command line is built here from the name, never sent by the caller. The machine enforces its own permissions and a refusal comes back as its own sentence, naming the switch to flip.",
+                "Performs a named action on a machine you own by running its own intentic-machine command there — turning that device's port mirroring off, say — over the connection it holds open. The set of actions is fixed and the command line is built here from the name, never sent by the caller. The machine enforces its own permissions and a refusal comes back as its own sentence, naming the switch to flip.",
         })
-        .input(MachineCommandInputSchema)
-        .output(MachineCommandResultSchema),
+        .input(DeviceCommandInputSchema)
+        .output(DeviceCommandResultSchema),
+    /* Update or restart the agent on one of the user's own devices — the remedy the Devices view used to print
+     * as a command to go and type, on the view built to replace that terminal.
+     *
+     * Streamed like the sandbox ops, and for a reason of its own: this is the one call whose transport the work
+     * destroys. Both ops stop the resident process holding the socket, so the stream ends WITHOUT a terminal
+     * frame in the ordinary, successful case, and callers must read that as "it started" rather than as a
+     * failure (DeviceAgentFlowSchema has the whole argument). The confirmation is the device's agent version
+     * moving on the next read of the fleet. */
+    runDeviceAgentFlow: oc
+        .route({
+            method: "POST",
+            path: "/system/devices/{id}/agent/{op}",
+            summary: "Update or restart the agent on one of your own devices",
+            description:
+                "Updates a machine you own to the current intentic-machine agent, or restarts the loop it is running, over the connection that machine holds open. The answer is a stream of the run's own output — and it normally stops mid-run, because the agent's loop is what carries this connection: the work is detached from it first, so it finishes regardless, and the device's reported version is what confirms it. Takes the machine's \"Run commands\" permission, the same one a command typed there would.",
+        })
+        .input(DeviceAgentFlowInputSchema)
+        .output(eventIterator(DeviceFlowLineSchema)),
 };

package/src/contracts/vpn.contract.ts

@@ -5,14 +5,14 @@ import { ForticlientImportInputSchema, ForticlientImportSchema, VpnConnectInputS
 
 // The live VPN surface. A VPN is ADDED as a `vpn` capability (credentials, autoConnect, capabilities.contract);
 // it is DIALLED here. The split is deliberate: connecting is a runtime operation that both the operator (the
-// Sandbox ▸ Status card) and the agent (`vpn` on its PATH, which calls these very routes) perform many times
+// VPN capability card) and the agent (`vpn` on its PATH, which calls these very routes) perform many times
 // over one stored connection, so it cannot be a capability re-add, and its result is richer than a
 // CapabilityStatus, which is why `list` returns VpnLinks instead of {state, detail}.
 //
 // Every route reads tunnel state back from the OS rather than from daemon memory, so the agent dropping a
 // tunnel from a shell and the UI dropping it are the same event, and a daemon restart observes the truth.
 export const vpnContract = {
-    // Every configured VPN with its live link state, the Status card, the rail indicator, and `vpn list`.
+    // Every configured VPN with its live link state, the VPN card, the rail indicator, and `vpn list`.
     list: oc
         .route({
             method: "GET",

package/src/documents.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
-import { documentOf, documentTitle, isDocumentPath, isPlanDocumentPath, PLAN_DOCUMENTS_DIR } from "./documents.js";
+import { documentOf, documentTitle, isDocumentPath, isPlanDocumentPath } from "./documents.js";
+import { PLAN_DOCUMENTS_DIR } from "./workspace-state.js";
 
 const write = (path: string, newText: string, extra: { oldText?: string; truncated?: boolean } = {}) => [
     { type: "diff" as const, path, newText, ...extra },

package/src/documents.ts

@@ -1,6 +1,6 @@
-import { STATE_DIR } from "@intentic/constants";
 import type { CardDocument, ToolCallContent } from "./events.js";
 import { planParts } from "./title.js";
+import { PLAN_DOCUMENTS_DIR } from "./workspace-state.js";
 
 /* A DOCUMENT A TURN WROTE FOR A PERSON TO READ, told apart from the files it changed for the machine.
  *
@@ -18,14 +18,6 @@ import { planParts } from "./title.js";
  * prose it is a mid-sentence slice with no heading, and the DIFF is what a reader wants from an edit anyway. So
  * a Write of a markdown file is a document, and an edit to one stays a diff. */
 
-/* WHERE THE CLI'S PLAN FILES LAND, workspace-relative.
- *
- * `~/.claude/plans` is a symlink onto this directory (sessions/session-store.ts links the SDK's conversation
- * state onto the workspace volume), which makes a plan file the one document with a HARNESS-OWNED address: no
- * guessing whether prose is a plan, no threshold on length, the path says so. That is why plan documents get
- * their own treatment while everything else rides the general markdown rule above. */
-export const PLAN_DOCUMENTS_DIR = `${STATE_DIR}/records/sessions/claude/plans`;
-
 // Prose, by extension. Deliberately short: a document is something the chat can RENDER, and markdown is what
 // the chat's prose pipeline speaks. A `.txt` report would render as an unstyled wall and reads better as the
 // plain text box it already gets.
@@ -36,8 +28,12 @@ export const isDocumentPath = (path: string): boolean => {
     return DOCUMENT_EXTENSIONS.some((extension) => lower.endsWith(extension));
 };
 
-// Whether a path is one of the CLI's plan files. Matched on the directory rather than on the name, which is a
-// mint-fresh three-word phrase (`map-of-this-wiggly-spring.md`) carrying no signal at all.
+/* Whether a path is one of the CLI's plan files, which is what earns a document the plan treatment here rather
+ * than the general markdown rule above: the harness owns that address, so there is no guessing whether prose is
+ * a plan and no threshold on length. Matched on the DIRECTORY rather than on the name, which is a mint-fresh
+ * three-word phrase (`map-of-this-wiggly-spring.md`) carrying no signal at all.
+ *
+ * The directory itself is declared in workspace-state.ts, beside the lock it is the one exception to. */
 export const isPlanDocumentPath = (path: string): boolean => path.startsWith(`${PLAN_DOCUMENTS_DIR}/`);
 
 /* What a document is CALLED. Its opening heading when it has one, which is the line the author wrote to name

package/src/embed.test.ts

@@ -0,0 +1,68 @@
+import { webcrypto } from "node:crypto";
+import { beforeAll, expect, test, vi } from "vitest";
+import { EmbedError, embedFailure, embedUrl, fetchEmbedJson, solveProofOfWork } from "./embed.js";
+
+/* The wire every embed speaks before it speaks its own, against a fake fetch and the real WebCrypto. */
+
+// jsdom ships no SubtleCrypto; node's is the same WebCrypto the browser exposes, so the solver is exercised
+// against the real digest rather than a stub.
+beforeAll(() => {
+    Object.defineProperty(globalThis, "crypto", { value: webcrypto, configurable: true });
+});
+
+// The daemon verifies exactly this: hash the whole answer string and count the leading zero bits.
+const leadingZeroBits = async (answer: string): Promise<number> => {
+    const digest = new Uint8Array(await webcrypto.subtle.digest("SHA-256", new TextEncoder().encode(answer)));
+    let bits = 0;
+    for (const byte of digest) {
+        if (byte !== 0) {
+            return bits + Math.clz32(byte) - 24;
+        }
+        bits += 8;
+    }
+    return bits;
+};
+
+test("a door's route is spelled the daemon's way, with the automation id encoded", () => {
+    expect(embedUrl({ base: "https://sandbox.example", automationId: "a b" }, "webchat", "config")).toBe("https://sandbox.example/webchat/a%20b/config");
+});
+
+test("a refusal carries the server's own sentence and status, and a bodyless one says what it can", async () => {
+    const said = await embedFailure(new Response(JSON.stringify({ error: "origin not allowed" }), { status: 403 }));
+    expect(said).toBeInstanceOf(EmbedError);
+    expect(said).toMatchObject({ message: "origin not allowed", status: 403 });
+    expect(await embedFailure(new Response("nope", { status: 502 }))).toMatchObject({ message: "request failed (502)", status: 502 });
+});
+
+test("a JSON fetch answers the body or throws the refusal", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ ok: true }), { status: 200 })));
+    expect(await fetchEmbedJson<{ ok: boolean }>("https://x/y")).toEqual({ ok: true });
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ error: "rate limited" }), { status: 429 })));
+    await expect(fetchEmbedJson("https://x/y")).rejects.toMatchObject({ message: "rate limited", status: 429 });
+    vi.unstubAllGlobals();
+});
+
+/* The one test that pays for real work: 12 bits is ~900 awaited digests, which is what carries the solver past
+ * its 512-nonce batch and through the yield the page needs to keep painting. Every digest is a round trip to
+ * the platform's crypto, so what that costs is set by how loaded the machine is and never by this code: hence
+ * a budget that bounds a hang instead of the suite's 5s hang detector for in-memory work, which a busy runner
+ * beat. The other two prove things that need no work at all, and are cheap on purpose. */
+test("the answer really clears the difficulty, and carries the salt back for the daemon to re-derive", async () => {
+    const answer = await solveProofOfWork({ salt: "abc123", difficulty: 12 }, "needs https");
+    expect(answer.startsWith("abc123:")).toBe(true);
+    expect(await leadingZeroBits(answer)).toBeGreaterThanOrEqual(12);
+}, 20_000);
+
+test("a different salt yields a different answer: a solution cannot be replayed across callers", async () => {
+    const [one, two] = await Promise.all([
+        solveProofOfWork({ salt: "salt-one", difficulty: 6 }, "needs https"),
+        solveProofOfWork({ salt: "salt-two", difficulty: 6 }, "needs https"),
+    ]);
+    expect(one).not.toBe(two);
+});
+
+test("an http:// page is told the truth, in the embed's own words, instead of hanging on a missing SubtleCrypto", async () => {
+    Object.defineProperty(globalThis, "crypto", { value: { randomUUID: webcrypto.randomUUID }, configurable: true });
+    await expect(solveProofOfWork({ salt: "abc", difficulty: 8 }, "This page must be served over HTTPS to start a chat.")).rejects.toThrow(/HTTPS to start a chat/);
+    Object.defineProperty(globalThis, "crypto", { value: webcrypto, configurable: true });
+});

package/src/embed.ts

@@ -0,0 +1,164 @@
+/* THE ZOD-FREE HALF OF AN EMBED'S WIRE: what every script a customer drops on their own page does before it
+ * does anything of its own. Two embeds exist, the Front Desk chat bubble (_sandbox/webchat-widget) and the bug
+ * reporter (_sandbox/issue-widget), and each used to carry its own copy of this: the same three requests
+ * against a public door, the same proof-of-work solver, the same localStorage-backed id, the same
+ * read-my-own-script-tag boot. The daemon's side of the same doors is one module too (automations/public-door.ts).
+ *
+ * THE RULE FOR WHAT MAY LIVE HERE: no imports, ever. This module is bundled INTO a page that belongs to someone
+ * else, so it must cost that page nothing it did not ask for; the contract's barrel would bring zod with it
+ * (webext-links.ts measured that at 1.1 MB for two strings). Types are declared here for the same reason. */
+
+// Where an embed talks to: the daemon it came from, and the automation it is the public face of.
+export interface EmbedEndpoint {
+    readonly base: string;
+    readonly automationId: string;
+}
+
+// What the server said when it refused. The daemon answers every refusal as {"error": "..."}, and that sentence
+// is shown verbatim where a person can see it: "origin not allowed" tells a site owner exactly what to fix and
+// anything invented here would not.
+export class EmbedError extends Error {
+    constructor(
+        message: string,
+        readonly status: number,
+    ) {
+        super(message);
+        this.name = "EmbedError";
+    }
+}
+
+export const embedFailure = async (response: Response): Promise<EmbedError> => {
+    const body = (await response.json().catch(() => undefined)) as { error?: unknown } | undefined;
+    return new EmbedError(typeof body?.error === "string" ? body.error : `request failed (${response.status})`, response.status);
+};
+
+// One route of a public door: `<base>/<slug>/<automation>/<path>`, the daemon's own spelling.
+export const embedUrl = ({ base, automationId }: EmbedEndpoint, slug: string, path: string): string =>
+    `${base}/${slug}/${encodeURIComponent(automationId)}/${path}`;
+
+// One GET against a public door, answered as JSON or refused with the server's own sentence.
+export const fetchEmbedJson = async <T>(url: string): Promise<T> => {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw await embedFailure(response);
+    }
+    return (await response.json()) as T;
+};
+
+/* ---- proof of work ----
+ *
+ * The daemon issues a challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` begins with `difficulty` zero
+ * BITS. It costs the person a second or so and costs a script the same per identity it wants to burn, with no
+ * third-party account anywhere. The challenge is minted FOR one caller (the daemon signs the caller's own id
+ * into the salt), so a solution cannot be carried to another thread or another reporter; hence the id in the
+ * challenge request rather than a bare GET.
+ *
+ * Solved on the main thread in yielding batches rather than in a Worker: a Worker would have to come from a
+ * blob: URL, which a host page's Content-Security-Policy is entitled to forbid, and being unable to chat or send
+ * feedback because of the SITE's CSP is a worse failure than a busy second. */
+export interface PowChallenge {
+    readonly salt: string;
+    readonly difficulty: number;
+}
+
+export const fetchEmbedChallenge = (endpoint: EmbedEndpoint, slug: string, param: string, id: string): Promise<PowChallenge> =>
+    fetchEmbedJson<PowChallenge>(`${embedUrl(endpoint, slug, "challenge")}?${param}=${encodeURIComponent(id)}`);
+
+const BATCH = 512;
+
+// Leading zero bits of a digest, up to `wanted`. Stops at the first non-zero byte, so a miss costs one byte.
+const leadingZeroBits = (digest: Uint8Array, wanted: number): number => {
+    let bits = 0;
+    for (const byte of digest) {
+        if (byte !== 0) {
+            // Math.clz32 counts 32-bit leading zeros; the byte sits in the low 8, so 24 of them are structural.
+            return bits + Math.clz32(byte) - 24;
+        }
+        bits += 8;
+        if (bits >= wanted) {
+            return bits;
+        }
+    }
+    return bits;
+};
+
+/* Resolves to the ANSWER the daemon expects, `<salt>:<nonce>`, carrying back the salt it signed so it can
+ * re-derive the challenge it issued without having stored one. `insecure` is what to say on an http:// page:
+ * `crypto.subtle` is only available in a secure context, and the fix is the site's TLS, not anything the
+ * person can do, so the sentence names the thing they were trying to do. */
+export const solveProofOfWork = async (challenge: PowChallenge, insecure: string, onProgress?: (attempts: number) => void): Promise<string> => {
+    if (crypto.subtle === undefined) {
+        throw new Error(insecure);
+    }
+    const encoder = new TextEncoder();
+    for (let nonce = 0; ; nonce += 1) {
+        const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(`${challenge.salt}:${nonce}`)));
+        if (leadingZeroBits(digest, challenge.difficulty) >= challenge.difficulty) {
+            return `${challenge.salt}:${nonce}`;
+        }
+        if (nonce % BATCH === BATCH - 1) {
+            onProgress?.(nonce + 1);
+            // Hand the main thread back so the page (and the embed's own "checking…" line) keeps painting.
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+};
+
+/* ---- what an embed keeps in the visitor's browser ----
+ *
+ * localStorage throws in Safari's private mode and anywhere the site blocks storage. An embed with no storage
+ * still works; it just mints a fresh id per page load, which costs only a slightly less useful thread or
+ * rate-limit key. Silence here is deliberate: an embed must never be the thing that puts an error in the
+ * console. */
+export const readStored = (name: string): string | undefined => {
+    try {
+        return window.localStorage.getItem(name) ?? undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+export const writeStored = (name: string, value: string): void => {
+    try {
+        window.localStorage.setItem(name, value);
+    } catch {
+        /* no storage: this page load keeps the value in memory and the next one mints another */
+    }
+};
+
+/* A per-browser id under `name`, minted once and kept. NOT identity and NOT a secret: anyone can mint one, and
+ * the daemon treats it as exactly what it is, the key that threads a visitor's messages into one conversation,
+ * or that a rate window counts against so one runaway tab cannot spend the whole day's budget. */
+export const storedId = (name: string): string => {
+    const existing = readStored(name);
+    if (existing !== undefined && existing !== "") {
+        return existing;
+    }
+    const minted = crypto.randomUUID();
+    writeStored(name, minted);
+    return minted;
+};
+
+/* ---- the <script> tag an embed boots from ----
+ *
+ *   <script src="https://sandbox-<id>.<zone>/<slug>/…js" data-automation="support" defer></script>
+ *
+ * Everything else is derived: the daemon to talk to is the ORIGIN THIS SCRIPT CAME FROM, which is the one thing
+ * a copy-pasted snippet can't get wrong. `data-base` overrides it for a site fronting the sandbox behind its
+ * own proxy, the only case where the two legitimately differ.
+ *
+ * `document.currentScript` is only valid while the script body is executing, so it is read at module scope by
+ * the caller rather than inside an async boot. The querySelector is the fallback for a bundler or tag manager
+ * that re-executes the entry in a context where currentScript is null. */
+export const embedScript = (srcMatch: string): HTMLScriptElement | null =>
+    (document.currentScript as HTMLScriptElement | null) ?? document.querySelector<HTMLScriptElement>(`script[src*="${srcMatch}"]`);
+
+// The endpoint a script tag names, or undefined when it carries no automation id, the one mistake worth a
+// console line: without it the embed is silently absent and the site owner has nothing to go on.
+export const embedEndpointOf = (script: HTMLScriptElement): EmbedEndpoint | undefined => {
+    const automationId = script.dataset["automation"];
+    if (automationId === undefined || automationId === "") {
+        return undefined;
+    }
+    return { automationId, base: (script.dataset["base"] ?? new URL(script.src, window.location.href).origin).replace(/\/$/, "") };
+};

package/src/events.ts

@@ -93,7 +93,7 @@ export const PermissionAskSchema = z.object({
      * the title (the judge read the owner's policy and the program, and its account of why this needs asking is
      * the only account there is), so this is left off rather than printing the same words twice. It carries the
      * sentence on the two cards whose title says something the sentence cannot: the hard rule's, which names the
-     * consequence that stopped it, and a machine command's, which names the computer.
+     * consequence that stopped it, and a machine command's, which names the device.
      *
      * Written by the quick model from the program text and the policy, never by the agent being gated — a card
      * whose persuasive half was authored by the thing it is stopping argues for its own approval, and the turns
@@ -557,7 +557,7 @@ export const TranscriptToolSchema: z.ZodType<TranscriptTool> = z.lazy(() =>
             .array(TranscriptToolSchema)
             .optional()
             .describe(
-                "Calls a delegated helper made, nested under the call that started it, so a reopened conversation redraws the delegation rather than collapsing it into one result.",
+                "Calls a delegated subagent made, nested under the call that started it, so a reopened conversation redraws the delegation rather than collapsing it into one result.",
             ),
         thinking: z.string().optional().describe("What the agent was reasoning about around this call."),
         subagent: TranscriptSubagentSchema.optional().describe(
@@ -772,7 +772,7 @@ export const TranscriptPatchSchema = z.discriminatedUnion("op", [
         op: z.literal("tool").describe("A tool card, whole: new, or the latest state of one already there, matched by id wherever it nests."),
         index: z.number().int().nonnegative(),
         tool: TranscriptToolSchema,
-        parent: z.string().optional().describe("The card this one nests under, when it is a delegated helper's own call."),
+        parent: z.string().optional().describe("The card this one nests under, when it is a delegated subagent's own call."),
     }),
 ]);
 export type TranscriptPatch = z.infer<typeof TranscriptPatchSchema>;
@@ -857,6 +857,16 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
     ending: TurnEndingSchema.optional().describe(
         "How the last turn ended, when it left work behind that one press finishes. Absent for a conversation whose last turn ended on its own, and for the failures that name something to repair first.",
     ),
+    /* WHERE THIS PAGE SITS IN THE CONVERSATION. `messages` is the tail, not the whole record: a conversation
+     * that ran all week used to be served entire to every tab that opened it and to every card the board warms
+     * behind it, which is megabytes over a tunnel to redraw a screenful.
+     *
+     * `from` is the position of the first message in the WHOLE record, which makes it two things at once: the
+     * offset every `rewindIndex` in this page is counted against, and the `before` that asks for the page above
+     * it. `more` says whether there is one, so a client can offer to go back without spending a round trip
+     * finding out. */
+    from: z.number().int().nonnegative().describe("Where the first message sits in the whole record, and the `before` that asks for the page above this one."),
+    more: z.boolean().describe("Whether older messages precede this page."),
 });
 
 /* WHAT A PUBLISHED CONVERSATION'S PAGE IS HANDED, the whole of it, baked into the page as one JSON block.
@@ -1334,6 +1344,23 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 "unknown-command",
                 "grok-model-invalid",
                 "codex-model-invalid",
+                /* THE MODEL IS REAL, LISTED, AND NOT THIS PLAN'S TO RUN. A routed provider's catalog is the set
+                 * the vendor publishes, not the set the connected subscription pays for, so a picker row can be
+                 * a model the upstream refuses on sight ("Your current subscription does not have access to
+                 * kimi-for-coding-highspeed. Upgrade to higher-tier Kimi Code plans.").
+                 *
+                 * Its own code because every neighbour's recovery is wrong for it. It is not `provider-outage`,
+                 * though that is what it wore: the translator answers a refused model with a 503, the harness
+                 * reads a 5xx as an outage, and rides it out for the whole in-turn retry budget — two minutes of
+                 * a spinner for a request that was refused in five milliseconds and will be refused identically
+                 * forever, followed by an auto-resume schedule for a turn that cannot come back. It is not
+                 * `*-model-invalid` either: nothing is misspelled and reloading the catalog re-offers the same
+                 * row, because the vendor really does serve it — to somebody else.
+                 *
+                 * What changes the outcome is picking another model or buying the plan, so the sentence is the
+                 * upstream's own (it names the tier), the client holds the words, and the daemon files the model
+                 * as refused so the picker stops offering it (usage/model-refusals.ts). */
+                "model-unavailable",
                 /* THE MODEL CANNOT HOLD A TURN OF THIS AGENT LOOP, so the daemon refused before sending
                  * (agent/context-budget.ts). Its own code because none of the neighbours describes it: nothing is
                  * disconnected, nothing is spent, nothing comes back on a clock, and re-sending the same request

package/src/history-state.ts

@@ -67,6 +67,12 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "usage.jsonl", portability: "carry" },
     { path: "account-usage.json", portability: "carry" },
     { path: "provider-refusals.json", portability: "carry" },
+    /* Which MODELS this sandbox's credentials were refused (usage/model-refusals.ts), the per-model half of the
+     * entry above and carried for the same reason: a bundle is this owner's sandbox on another machine, signing
+     * the same subscriptions back in, so a plan that does not cover a model there does not cover it here
+     * either, and the picker should arrive already clean. Cheap to be wrong about in the one case it can be
+     * (the target signs in a bigger plan): every entry is forgotten a day after it was written. */
+    { path: "model-refusals.json", portability: "carry" },
     // Explicit first-time dependency setup requests. Carrying the worklist preserves the owner's decision when
     // an export interrupts the queue before its terminal starts; fulfilled entries remove themselves.
     { path: "dependency-requests.json", portability: "carry" },
@@ -146,15 +152,18 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },
     { path: "host-enrollments.json", portability: "identity" },
-    /* A connected BROWSER's enrollment (webext/webext-store.ts). Identity for the hosts file's reason and one
+    /* A connected BROWSER's enrollment (webext/webext-peer.ts). Identity for the hosts file's reason and one
      * more of its own: the token admits a socket into somebody's signed-in browser, and that browser was paired
      * with THIS sandbox — carried into another one it would either be dead weight or, worse, a second sandbox
      * holding a live key to a browser its owner never connected it to. Re-pairing is a code and one click. */
     { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
-    // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
+    // The browser door's burn list: every peer door keeps one (peers/peer-store.ts), and a browser pairing
+    // redeemed here must not read as fresh in a sandbox this file travelled to. Identity, hosts' reason.
+    { path: "webext-pair-consumed.json", portability: "identity" },
+    // The burn list for setup-time device pairings. Identity, like sync's beside it, and for a sharper reason:
     // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
     { path: "host-pair-consumed.json", portability: "identity" },
-    // A runner's enrollment names THIS sandbox as its parent (runners/runners-store.ts): in another sandbox the
+    // A runner's enrollment names THIS sandbox as its parent (runners/runner-peer.ts): in another sandbox the
     // digest would admit a socket whose runner still dials the old parent. Identity, both files, hosts' reasons.
     { path: "runner-enrollments.json", portability: "identity" },
     { path: "runner-pair-consumed.json", portability: "identity" },

package/src/host-protocol.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 
 /* The handshake on /system/hosts/connect, the ONE message that is not oRPC.
  *
- * Everything a connected computer is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
+ * Everything a connected device is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
  * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
  * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
  * oRPC call, the daemon has nothing to call yet, and would be attaching a link to a stranger.
@@ -12,7 +12,7 @@ import { z } from "zod";
  * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
 
 // The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
-// handshake ITSELF when the machine is asleep (hosts/host.routes.ts), two spellings of this would mean an
+// handshake ITSELF when the machine is asleep (the daemon's peer bridge), two spellings of this would mean an
 // offline machine negotiating a different protocol than the same machine awake.
 export const MCP_PROTOCOL_VERSION = "2025-06-18";