@intentic/sandbox-contract 1.245.0 → 1.247.0

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

@@ -1,5 +1,6 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
+import { LimitResetClaimSchema, LimitResetStatusSchema } from "../schemas/plan-limits.js";
 import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas/usage.js";
 
 // The one control over the headroom readings a person has: measure again, now, every connection. `force`
@@ -38,4 +39,34 @@ export const usageContract = {
         })
         .input(RefreshPlanLimitsSchema)
         .output(z.object({ ok: z.literal(true) })),
+    /* THE WAY PAST A SPENT SESSION WINDOW THAT ISN'T WAITING (LimitResetStatusSchema has what it costs).
+     *
+     * ASKED, NOT POLLED, and that is the whole reason it is a route of its own rather than another field on the
+     * account list. The provider only evaluates it when told the account is at the wall, so asking is a claim
+     * about the account's state; asking on every headroom sweep, for every connection, would be that claim made
+     * continuously and falsely. It is asked at the one moment it is true — a refused turn, with its strip on
+     * screen — and the answer is worth nothing a moment later, so nothing caches it.
+     *
+     * Answers `available: false` rather than failing for an account with no such mechanism, so a caller can ask
+     * about any account it holds without first knowing which provider grants one. */
+    limitReset: oc
+        .route({
+            method: "GET",
+            path: "/usage/limit-reset/{account}",
+            summary: "Whether this account's session window can be reopened now",
+            description:
+                "Asks the provider whether it will reopen this account's spent session window immediately, which some plans grant once a week. Only worth asking about an account that has actually been refused: the answer is the provider's judgement at this moment, it is not cached, and an account with no such grant answers plainly that it has none.",
+        })
+        .input(z.object({ account: z.string().min(1).describe("Which account.") }))
+        .output(LimitResetStatusSchema),
+    claimLimitReset: oc
+        .route({
+            method: "POST",
+            path: "/usage/limit-reset/{account}/claim",
+            summary: "Reopen this account's session window now",
+            description:
+                "Spends one of the account's weekly resets to reopen its session window immediately. The weekly allowance is untouched and still binds. Answers with what the provider actually did: only `reset` changed anything, and it is the cue to send the refused turn again.",
+        })
+        .input(z.object({ account: z.string().min(1).describe("Which account.") }))
+        .output(LimitResetClaimSchema),
 };

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.
@@ -1269,7 +1279,7 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // was stopped, or died under the card), which is not a decision and must not replay as one.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
     /* There was a `permission_note` frame here: a late sentence raced onto a command card that had already gone
-     * out, because the explanation was optional and the card must not wait for a quick-model rung that might
+     * out, because the explanation was optional and the card must not wait for a one-shot helper rung that might
      * take tens of seconds. It is gone with the setting that made it optional. The judge now decides the
      * verdict, so the sentence is not a decoration arriving afterwards — it is the REASON THE CARD EXISTS, and
      * a card cannot be raised before it is known. Nothing races, and `PermissionAsk.explain` is populated at
@@ -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/fast-tier.test.ts

@@ -61,7 +61,7 @@ test("a pin on this provider wins over the catalog's own cheap end", () => {
 });
 
 test("takes a pinned id verbatim, so a model the static catalog has not caught up with is still pinnable", () => {
-    // The same call resolveQuickModels makes, and for the same reason: the picker offers a custom-id escape
+    // The same call resolveRoleModels makes, and for the same reason: the picker offers a custom-id escape
     // hatch, and second-guessing the id here would run a different model than the settings row names.
     expect(fastFor(`claude-opus-5`, { pinned: [`claude:claude-haiku-9`] })).toBe(`claude-haiku-9`);
 });

package/src/fast-tier.ts

@@ -1,5 +1,5 @@
 import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
-import { parsePinned } from "./quick-model.js";
+import { parsePinned } from "./model-pins.js";
 import type { AgentProvider } from "./schemas/agent.js";
 
 /* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
@@ -21,7 +21,7 @@ import type { AgentProvider } from "./schemas/agent.js";
  * follow-up cheap to answer. So a cross-provider pin here is dropped rather than honoured: saving a fraction of
  * a cent by starting the conversation over is not a saving.
  *
- * THE ORDER IS A LADDER, for the reason quick-model.ts is one, but a shorter one: the caller spends the head
+ * THE ORDER IS A LADDER, for the reason model-pins.ts is one, but a shorter one: the caller spends the head
  * and falls back to the user's own pick, rather than walking rungs. A downgrade that cannot be started is not
  * worth a second attempt when the honest answer (their model) is sitting right there. */
 
@@ -34,14 +34,14 @@ export interface FastTierInput {
     // That provider's catalog as the caller can see it. Empty is a real state (a catalog that has not loaded),
     // and it resolves to no downgrade rather than to a guess.
     readonly models: readonly string[];
-    // settings.autoFastModels: an ordered list of `${provider}:${modelId}` keys (quickModelKey), or empty for
+    // settings.autoFastModels: an ordered list of `${provider}:${modelId}` keys (modelPinKey), or empty for
     // Auto. Entries naming another provider are dropped, not honoured.
     readonly pinned: readonly string[];
 }
 
 /* THE CHEAPER MODEL TO RUN THIS TURN ON, or undefined for "there isn't one, use their pick".
  *
- * A PIN IS TAKEN VERBATIM against the catalog, the same call resolveQuickModels makes and for the same reason:
+ * A PIN IS TAKEN VERBATIM against the catalog, the same call resolveRoleModels makes and for the same reason:
  * the model picker offers a custom-id escape hatch for a model the static catalog has not caught up with, and
  * second-guessing the id here would run a different model than the settings row names. It is still checked for
  * being CHEAPER, because that is not a fact about the catalog, it is a fact about the id, and a pin that is not
@@ -49,7 +49,7 @@ export interface FastTierInput {
  *
  * AUTO IS THE CHEAPEST ROW THE PROVIDER PUBLISHES, read through the same cheap-end order the quick model uses,
  * so the two features cannot disagree about which rung is the cheap one. Derived, never stored: connect an
- * account tomorrow and the answer improves by itself, exactly as quickModel's empty default does.
+ * account tomorrow and the answer improves by itself, exactly as a one-shot role's empty list does.
  *
  * NOTHING CHEAPER THAN THE PICK ⇒ UNDEFINED, and that is the common case worth being exact about rather than
  * the edge case: a user already working on the cheap rung has nowhere to be sent, and a user on a model whose

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" },