@intentic/sandbox-contract 1.303.0 → 1.305.0

package/src/protocol/peer-dial.ts

@@ -1,6 +1,12 @@
 // The one outbound socket a peer (machine agent, webext, runner) holds to its sandbox: hello carries the enrollment
 // token in the frame, then the link is pure oRPC. Reconnects on backoff after any drop except a revoked enrollment
 // (code 1008), which never retries.
+//
+// THE RULE BOTH ENDS ARE HELD TO: 1008 means the sandbox READ its enrollment store and does not hold this token. It
+// costs the far end its pairing — someone has to walk to that machine and paste a command — so it is the one refusal
+// that may never stand in for a moment the sandbox was having. A manifest mid-write, a capability card not yet
+// restored after a recreate, a hello that arrived late: all of those are PEER_TRY_AGAIN, and all of them used to be
+// 1008.
 
 // Reconnect backoff: fast floor for a restart, low cap so a reopened laptop is back within a minute.
 export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_000 } as const;
@@ -9,12 +15,24 @@ export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_0
 const LOUD_ATTEMPTS = 3;
 const QUIET_LOG_MS = 10 * 60_000;
 
+/* HOW OFTEN A LINK NOBODY IS ANSWERING MAY TRY, once "the sandbox is restarting" has stopped being a plausible
+   reading of the silence. The ladder above caps at 30s and stays there forever, which is right for the first minutes
+   and absurd after the first week: a machine holding a link to a sandbox that no longer exists spent 2,880 attempts a
+   day on it, and most of a 7 MB log saying so. The link is never given up — a laptop closed for a fortnight must find
+   its sandboxes again — it just stops asking every half minute. Reaching the far end once resets it (`failures = 0`),
+   so an outage that ends is back on the fast ladder immediately. */
+export const LONG_OUTAGE_ATTEMPTS = 20;
+export const LONG_OUTAGE_MS = 15 * 60_000;
+
 /* HOW LONG A SOCKET MAY SAY NOTHING before this side calls the link dead, as a multiple of the door's own heartbeat. */
 export const PEER_LINK_SILENCE_HEARTBEATS = 3;
 export const peerLinkSilenceMs = (heartbeatMs: number): number => heartbeatMs * PEER_LINK_SILENCE_HEARTBEATS;
 
 // The sandbox closes with this when the token is not enrolled: a decision, not a fault, and one that never heals.
-const UNAUTHORIZED = 1008;
+export const PEER_UNAUTHORIZED = 1008;
+// Refused, but not about this peer's credential: the sandbox could not decide right now. Retried on the ordinary
+// ladder, which is the whole difference between the two.
+export const PEER_TRY_AGAIN = 1013;
 
 // WebSocket spec's readyState value for open, named so a fake socket need not import the real class.
 const OPEN = 1;
@@ -50,11 +68,20 @@ export interface PeerDialSpec<S extends SocketLike> {
 // it for `status`, which otherwise has only the link list on disk and no idea whether any of it is up).
 export type PeerLinkState = "open" | "connecting" | "closed";
 
+// How long this link has been failing and how many attempts it has spent, for the readers that are not this process.
+// Absent while the socket is open, so "is anything wrong here" is answerable without publishing a healthy link's
+// history. `since` is the first failure of THIS outage: one answer resets it.
+export interface PeerOutage {
+    readonly failures: number;
+    readonly since: number;
+}
+
 export interface PeerLink {
     // Resolves when the loop is asked to stop or refused for good; never rejects, a connection error is a retry.
     readonly done: Promise<void>;
     readonly stop: (reason?: string) => void;
     readonly state: () => PeerLinkState;
+    readonly outage: () => PeerOutage | undefined;
 }
 
 export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
@@ -73,6 +100,8 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
     // loud: between them they are the whole of the quiet rule above.
     let failures = 0;
     let quietSince = 0;
+    // When the CURRENT outage began, as opposed to when this link was last complained about.
+    let failingSince: number | undefined;
 
 /* What ONE failed attempt is allowed to say. */
     const complain = (said: string, delay: number): void => {
@@ -135,9 +164,11 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
                 resolveDone();
                 return;
             }
-            const delay = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
+            const rung = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
             openedAt = undefined;
             failures += 1;
+            failingSince ??= Date.now();
+            const delay = failures >= LONG_OUTAGE_ATTEMPTS ? Math.max(rung, LONG_OUTAGE_MS) : rung;
             complain(said, delay);
             waiting = true;
             setTimeout(() => void open(), delay);
@@ -166,6 +197,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             // "connected to …" line this open is about to log is what reports the recovery.
             failures = 0;
             quietSince = 0;
+            failingSince = undefined;
             arm();
             spec.attach(ws);
             const send = (hello: Record<string, unknown>): void => {
@@ -185,7 +217,7 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
 
         ws.addEventListener("close", (event) => {
             /* A revocation is answered here rather than through `drop`: it is the one close that ends the loop. */
-            if (event.code === UNAUTHORIZED) {
+            if (event.code === PEER_UNAUTHORIZED) {
                 dropped = true;
                 disarm();
                 if (socket === ws) {
@@ -196,7 +228,9 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
                 spec.revoked();
                 return;
             }
-            drop(`disconnected (${event.code ?? "no code"})`);
+            // Named rather than numbered, because this is the code a reader most needs not to mistake for the one
+            // above it: the sandbox is up and talking, it just would not admit this socket this time.
+            drop(event.code === PEER_TRY_AGAIN ? "the sandbox is not ready to admit this connection yet" : `disconnected (${event.code ?? "no code"})`);
         });
 
         /* Socket errors record a cause; the close event owns retry scheduling. */
@@ -222,5 +256,6 @@ export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink
             resolveDone();
         },
         state: () => (socket?.readyState === OPEN ? "open" : socket !== undefined || waiting ? "connecting" : "closed"),
+        outage: () => (failingSince === undefined ? undefined : { failures, since: failingSince }),
     };
 };

package/src/protocol/peer-mcp-server.test.ts

@@ -1,4 +1,4 @@
-import { expect, test } from "vitest";
+import { test, expect } from "bun:test";
 import { z } from "zod";
 import { createMcpServer, type McpAuditEntry, textResult, tool } from "./peer-mcp-server.js";
 
@@ -37,7 +37,8 @@ const build = () => {
     return { handle, audits };
 };
 
-const call = (name: string, args: Record<string, unknown>, allowed = true) => build().handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, { allowed });
+const call = (name: string, args: Record<string, unknown>, allowed = true) =>
+    build().handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, { allowed });
 
 test("initialize names the peer and its build; ping answers empty; an unknown method is a JSON-RPC error", async () => {
     const { handle } = build();
@@ -52,14 +53,38 @@ test("initialize names the peer and its build; ping answers empty; an unknown me
 
 test("tools/list publishes each tool's schema as JSON Schema, without the dialect line", async () => {
     const { handle } = build();
-    const listed = (await handle({ jsonrpc: "2.0", id: 1, method: "tools/list" }, { allowed: true })) as { result: { tools: { name: string; inputSchema: Record<string, unknown> }[] } };
+    const listed = (await handle({ jsonrpc: "2.0", id: 1, method: "tools/list" }, { allowed: true })) as {
+        result: { tools: { name: string; inputSchema: Record<string, unknown> }[] };
+    };
     expect(listed.result.tools.map((entry) => entry.name)).toEqual(["echo", "fail"]);
     expect(listed.result.tools[0]?.inputSchema).toMatchObject({ type: "object", properties: { text: { type: "string" } } });
     expect(listed.result.tools[0]?.inputSchema).not.toHaveProperty("$schema");
 });
 
+test("a tuple is published without the boolean `items` llama.cpp's grammar converter refuses, and still checks its length", async () => {
+    const listed = tool({
+        name: "point",
+        description: "A point.",
+        input: z.object({ at: z.tuple([z.number(), z.number()]), path: z.array(z.tuple([z.number(), z.number()])) }),
+        run: async () => textResult("ok"),
+    });
+    expect(JSON.stringify(listed.inputSchema)).not.toContain("false");
+    expect(listed.inputSchema).toMatchObject({
+        properties: {
+            at: { type: "array", prefixItems: [{ type: "number" }, { type: "number" }], minItems: 2, maxItems: 2 },
+            path: { items: { type: "array", prefixItems: [{ type: "number" }, { type: "number" }], maxItems: 2 } },
+        },
+    });
+    const parsed = (await listed.call({ at: [1, 2, 3], path: [] }, undefined)) as { isError: boolean };
+    expect(parsed.isError).toBe(true);
+});
+
 test("a call is checked against the same schema, and a bad argument is a readable result, not a fault", async () => {
-    expect(await call("echo", { text: "hi" })).toEqual({ jsonrpc: "2.0", id: 1, result: { content: [{ type: "text", text: "hi" }], isError: false } });
+    expect(await call("echo", { text: "hi" })).toEqual({
+        jsonrpc: "2.0",
+        id: 1,
+        result: { content: [{ type: "text", text: "hi" }], isError: false },
+    });
     const bad = (await call("echo", { text: "" })) as { result: { content: { text: string }[]; isError: boolean } };
     expect(bad.result.isError).toBe(true);
     expect(bad.result.content[0]?.text).toContain("text");
@@ -75,8 +100,11 @@ test("a tool this peer does not have answers in the peer's own words", async ()
 
 test("a thrown refusal and a thrown failure are both results, and the audit line says which", async () => {
     const { handle, audits } = build();
-    const refused = (await handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "echo", arguments: { text: "hi" } } }, { allowed: false })) as {
-        result: { content: { text: string }[]; isError: boolean };
+    const refused = (await handle(
+        { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "echo", arguments: { text: "hi" } } },
+        { allowed: false },
+    )) as {
+        result: { content: { type: string; text: string }[]; isError: boolean };
     };
     expect(refused.result).toEqual({ content: [{ type: "text", text: "the switch is off" }], isError: true });
     await handle({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "fail", arguments: {} } }, { allowed: true });
@@ -99,5 +127,7 @@ test("an audit log that cannot be written never fails the answer", async () => {
             throw new Error("disk full");
         },
     });
-    expect(await handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "hi", arguments: {} } }, undefined)).toMatchObject({ result: { isError: false } });
+    expect(await handle({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "hi", arguments: {} } }, undefined)).toMatchObject({
+        result: { isError: false },
+    });
 });

package/src/protocol/peer-mcp-server.ts

@@ -22,6 +22,27 @@ export interface McpTool<Ctx> {
 
 export const textResult = (text: string, isError = false): Record<string, unknown> => ({ content: [{ type: "text", text }], isError });
 
+// Every tool schema has to survive llama.cpp's grammar converter, which is how a local model is held to a tool's shape:
+// it reads `items` before `prefixItems` and refuses a boolean schema, so zod's closed-tuple form (`items: false`) fails
+// the conversion of the WHOLE tool set, not just its own tool. Length is what closes a tuple, and `maxItems` still says
+// it, so no other reader sees a different shape. Applied again by the daemon's bridge, whose peers are separately
+// installed software that can be any age.
+export const converterReadable = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map(converterReadable);
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const node = value as Record<string, unknown>;
+    const prefix = node["prefixItems"];
+    const tupleLength = node["items"] === false && Array.isArray(prefix) ? prefix.length : undefined;
+    const walked = Object.fromEntries(
+        Object.entries(node).flatMap(([key, child]) => (tupleLength !== undefined && key === "items" ? [] : [[key, converterReadable(child)] as const])),
+    );
+    return tupleLength === undefined ? walked : { ...walked, maxItems: tupleLength };
+};
+
 // Builds one tool from a single zod schema; the generic carries its type to the handler, and `McpTool` erases it again
 // since the dispatch table holds every tool. `$schema` is dropped from the JSON Schema output as redundant.
 export const tool = <Schema extends z.ZodType, Ctx>(spec: {
@@ -34,7 +55,7 @@ export const tool = <Schema extends z.ZodType, Ctx>(spec: {
     return {
         name: spec.name,
         description: spec.description,
-        inputSchema,
+        inputSchema: converterReadable(inputSchema) as Record<string, unknown>,
         call: async (args, ctx) => {
             const parsed = spec.input.safeParse(args);
             // Readable enough for a model to fix its own call: which field, and what was expected.

package/src/protocol/routes.test.ts

@@ -1,5 +1,5 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { describe, expect, it } from "vitest";
+import { describe, it, expect } from "bun:test";
 import { z } from "zod";
 import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "../index.js";
 import { contractRoutes, routeNameForRequest, routeShapes, streamOf } from "./routes.js";
@@ -183,7 +183,9 @@ describe(`the real sandbox contract`, () => {
                 `system.manageDeviceSandbox`,
                 `system.runDeviceAgentFlow`,
                 `vpn.connect`,
-            ].filter((name) => name in SANDBOX_ROUTE_SHAPES).toSorted(),
+            ]
+                .filter((name) => name in SANDBOX_ROUTE_SHAPES)
+                .toSorted(),
         ).toEqual([
             `agent.attach`,
             `capabilities.add`,

package/src/schemas/agent.ts

@@ -3,6 +3,7 @@ import { CONVERSATION_ID } from "../ids/conversation-ids.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
 import { NATIVE_PROVIDERS } from "../models/provider-specs.js";
 import { AgentPlacementSchema } from "../protocol/runner-protocol.js";
+import { MENTION_LIMIT } from "../text/mentions.js";
 import { entryId } from "./internal.js";
 // Agent runtimes the daemon can serve: native providers have dedicated adapters, `endpoint/<id>` names an installed
 // endpoint capability, anything else is an ACP agent capability id. A bare string, not an enum, so an unknown id is a
@@ -77,6 +78,9 @@ export type CommandLocus = z.infer<typeof CommandLocusSchema>;
 export const CommandClassSchema = z.enum([
     // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
     "git.destructive",
+    // Moves a checkout to another branch. Only ever matches in a tree the conversation SHARES with its owner: inside
+    // its own copy a conversation may stand where it likes, and the drift that causes is reported, not refused.
+    "git.branch-switch",
     // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
     "files.destructive",
     // State nothing recovers at this locus; which roots count (/, /history in the sandbox) depends on the locus.
@@ -136,6 +140,15 @@ export const AgentTurnSchema = z
             .max(20)
             .optional()
             .describe("Files to hand the agent along with the prompt, as workspace paths. Upload them first."),
+        // Read out of the prompt's own `@path` tokens rather than chosen: a tokenizer over pasted text guesses, so a
+        // miss here is dropped and only a chosen attachment can refuse the turn.
+        mentions: z
+            .array(z.string().min(1))
+            .max(MENTION_LIMIT)
+            .optional()
+            .describe(
+                "Workspace paths the prompt mentions with `@`. Unlike attachments, one that escapes the workspace or names no file is ignored rather than refused.",
+            ),
         // Which provider serves the turn, absent = claude; a sessionId resumes only on the provider that minted it.
         agent: AgentProviderSchema.optional().describe("Which model provider serves this turn. Leave it out for Claude."),
         // Which agentic loop runs the turn, absent = provider's own; "claude-code" forces the SDK loop for any

package/src/schemas/agents.ts

@@ -291,6 +291,14 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Who asked for the first turn, as the sandbox verified it: a member's email, token:<label> for a program's control token, or agent:<conversation id> for a child another conversation spawned. Absent when nothing was verified (a wake, a loopback caller).",
         ),
+    // The fence it was born with. Rides the summary because it is what decides who may see the row at all
+    // (auth/fleet-scope.ts visibleTo); without it here a fenced reader's board would be empty of even their own work.
+    areas: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Which named areas of the workspace this conversation was started within, latched from whoever asked for the first turn. Absent means its starter held the whole workspace, which is why a fenced member is not shown it.",
+        ),
     // Responsibility, beside provenance: the starter says who asked, this says who answers for it now. Absent means
     // nobody has claimed it, which is what a program's or an automation's conversation is until somebody does.
     owner: SessionOwnerSchema.optional().describe(
@@ -436,6 +444,22 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Outside conditions this conversation is parked on, each of which will wake it. Absent means none, which is nearly every conversation: an armed watch is why a finished-looking agent starts working by itself, and why a hosted machine will not go idle.",
         ),
+    // In memory only: a daemon restart leaves transcript rows naming jobs this list no longer carries.
+    jobs: z
+        .array(
+            z.object({
+                id: z.string().describe("The daemon's handle for this job, the one its transcript row names."),
+                label: z.string().describe("What the job is, in the agent's own words when it gave any, else its command on one line."),
+                session: z.string().describe("The terminal session its pane runs in, which is what opening it focuses."),
+                startedAt: z.number().describe("When it started, in milliseconds."),
+                endedAt: z.number().optional().describe("When the command exited, in milliseconds. Absent while it runs."),
+                exitCode: z.number().int().optional().describe("The code it exited with. Absent while it runs, or when its exit left none."),
+            }),
+        )
+        .optional()
+        .describe(
+            "Commands this conversation left running in the background, and how the most recent ones ended. Absent means none since the daemon started. A job is running exactly while it has no end.",
+        ),
     // Epoch ms it was archived; nothing is lost (branch, transcript, counters stay), and unarchiving re-attaches a
     // fresh worktree from the branch.
     archivedAt: z
@@ -448,6 +472,8 @@ export const AgentSummarySchema = z.object({
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
 // One armed watch as a card carries it; derived from AgentSummarySchema.watches so the two shapes can't drift apart.
 export type AgentWatch = NonNullable<AgentSummary["watches"]>[number];
+// One background job as a card carries it.
+export type AgentJob = NonNullable<AgentSummary["jobs"]>[number];
 // AgentsListSchema is declared later, after AutomationApprovalSchema, since the fleet list carries held wakes and zod
 // needs that type declared first.
 export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
@@ -665,6 +691,13 @@ export type LandConflict = z.infer<typeof LandConflictSchema>;
 // hand.
 export const LandResultSchema = z.object({
     landed: z.boolean().describe("Whether the entire composed change was applied."),
+    // Merged and nothing moved is the one outcome with nothing to show for itself; without this the caller cannot tell
+    // it from a merge that carried work, and a press that did nothing looked exactly like a press that worked.
+    changed: z
+        .boolean()
+        .describe(
+            "Whether anything actually moved. False alongside merged means there was nothing on the branch to apply: the work is already in your tree, or the branch never carried any.",
+        ),
     conflicts: z.array(LandConflictSchema).optional().describe("What stopped the whole composed change, grouped per repository."),
     resolving: z
         .array(

package/src/schemas/areas.test.ts

@@ -1,5 +1,5 @@
 import { PUBLIC_DIR, STATE_DIR } from "@intentic/constants";
-import { describe, expect, test } from "vitest";
+import { describe, test, expect } from "bun:test";
 import { AreaFolderSchema } from "./areas.js";
 
 // What an area may name. These refusals are load-bearing rather than cosmetic: an area's folders become the fence
@@ -22,13 +22,7 @@ describe("AreaFolderSchema", () => {
     });
 
     test("the sandbox's own configuration and its outbox can never be named", () => {
-        for (const folder of [
-            STATE_DIR,
-            `${STATE_DIR}/config`,
-            `${STATE_DIR}/config/hooks`,
-            PUBLIC_DIR,
-            `${PUBLIC_DIR}/site`,
-        ]) {
+        for (const folder of [STATE_DIR, `${STATE_DIR}/config`, `${STATE_DIR}/config/hooks`, PUBLIC_DIR, `${PUBLIC_DIR}/site`]) {
             expect(AreaFolderSchema.safeParse(folder).success, folder).toBe(false);
         }
     });

package/src/schemas/automations.ts

@@ -124,7 +124,7 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
     }),
 ]);
 export type Trigger = z.infer<typeof TriggerSchema>;
-// The Front Desk widget's settings, present only on `webchat` listener automations. Split into what the widget itself
+// The Visitor chat widget's settings, present only on `webchat` listener automations. Split into what the widget itself
 // may read (public by construction) and what only the daemon may (turnstileSecret); GET /webchat/<id>/config serves the
 // first group by naming it, never by omitting the second.
 export const WebchatConfigSchema = z.object({
@@ -177,7 +177,7 @@ export const WebchatConfigSchema = z.object({
     sessionTtlMinutes: z.number().int().positive().optional(),
 });
 export type WebchatConfig = z.infer<typeof WebchatConfigSchema>;
-// Default daily agent-turn ceiling for an unconfigured Front Desk; high enough for real traffic, low enough to blunt a
+// Default daily agent-turn ceiling for an unconfigured Visitor chat; high enough for real traffic, low enough to blunt a
 // script.
 export const WEBCHAT_DAILY_MAX_DEFAULT = 200;
 // The widget wire: the shapes GET /webchat/<id>/config, GET .../challenge and POST .../message speak, living beside the
@@ -201,7 +201,7 @@ export const WebchatPublicConfigSchema = z.object({
 });
 export type WebchatPublicConfig = z.infer<typeof WebchatPublicConfigSchema>;
 // A proof-of-work challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` starts with `difficulty` zero bits. One
-// shape for every public door (Front Desk, bug intake), and one matching solver, embed.ts.
+// shape for every public door (Visitor chat, bug intake), and one matching solver, embed.ts.
 export const PowChallengeSchema = z.object({ salt: z.string(), difficulty: z.number().int().positive() });
 export type PowChallenge = z.infer<typeof PowChallengeSchema>;
 // One visitor message; `conversationId` is the widget's own localStorage id, a thread key rather than a secret — the
@@ -224,7 +224,7 @@ export const WebchatMessageSchema = z.object({
 });
 export type WebchatMessage = z.infer<typeof WebchatMessageSchema>;
 // What GET /webchat/<id>/messages answers: replies queued after the visitor's stream closed, which is every reply an
-// approval-gated desk produces and every one a human writes as the agent. Public by construction, like the config:
+// approval-gated guest produces and every one a human writes as the agent. Public by construction, like the config:
 // reaching it needs nothing but an allowed origin and the conversation id already in that browser.
 export const WebchatPendingSchema = z.object({
     // Oldest first, so appending them to the log preserves the order they were written in.
@@ -272,7 +272,7 @@ export const AutomationSchema = z.object({
             "A command run before the wake that decides whether there is anything to do. Skipped by the guard is often the most useful thing an automation can report.",
         ),
     prompt: z.string().min(1).describe("What the woken agent is told."),
-    // The Front Desk widget's settings, `webchat` listener automations only, ignored on every other trigger.
+    // The Visitor chat widget's settings, `webchat` listener automations only, ignored on every other trigger.
     webchat: WebchatConfigSchema.optional().describe("Settings for the public chat widget, for an automation that answers visitors."),
     // Bug intake settings, `issues` triggers only; its own field rather than a shared bag, since a chat's and an
     // intake's fields mostly don't overlap.

package/src/schemas/capabilities.ts

@@ -24,12 +24,13 @@ export const CapabilityKindSchema = z.enum([
     "docker",
     "browser",
     "identity",
-    "host",
+    "device",
     "webext",
     "agent",
     "endpoint",
     "localmodel",
     "wallet",
+    "fleet",
 ]);
 export type CapabilityKind = z.infer<typeof CapabilityKindSchema>;
 export const CapabilityStateSchema = z.enum(["active", "pending", "error", "inactive"]);
@@ -164,7 +165,7 @@ export type IdentityConfig = z.infer<typeof IdentityConfigSchema>;
 // machine, never here, so a compromised sandbox can't exceed what the owner ticked.
 // on/off, not boolean: capability configs arrive from the form as strings, and a select renders an enum.
 const hostScope = z.enum(["on", "off"]);
-export const HostScopesSchema = z.object({
+export const DeviceScopesSchema = z.object({
     // Run commands in a real shell (PowerShell on Windows, the login shell on Linux). Off ⇒ files/screen only.
     shell: hostScope.default("on"),
     // Create, modify and trash files under `roots`. Reads are always allowed within them; this is the write half.
@@ -181,8 +182,8 @@ export const HostScopesSchema = z.object({
     // One directory per line. Empty ⇒ the machine's home directory, which is what the agent reports at connect.
     roots: z.string().optional(),
 });
-export type HostScopes = z.infer<typeof HostScopesSchema>;
-export const HostConfigSchema = HostScopesSchema.extend({ platform: z.string().min(1) });
+export type DeviceScopes = z.infer<typeof DeviceScopesSchema>;
+export const DeviceConfigSchema = DeviceScopesSchema.extend({ platform: z.string().min(1) });
 // An ACP agent served as a chat provider: the daemon spawns `command` as a long-lived JSON-RPC subprocess, and the
 // capability id becomes the provider id. `env` is a pasted KEY=VALUE block, the whole secret field; `loginCommand` runs
 // an interactive device-code login in a visible terminal.
@@ -287,6 +288,14 @@ export const WalletConfigSchema = z.object({
     deny: z.string().optional(),
 });
 export type WalletConfig = z.infer<typeof WalletConfigSchema>;
+// The owner's Intentic account, reachable from inside this sandbox: what lets it create sandboxes on that account
+// instead of asking a person to fetch a setup code from the browser. The token is minted at Settings ▸ Tokens and is
+// account-scoped, so it is held by the daemon and never injected into the agent's env — the approval card on every
+// create is only an approval while the agent cannot mint a claim behind it.
+export const FleetConfigSchema = z.object({
+    token: z.string().min(1).describe("A provisioning token from Settings ▸ Tokens. Stored, never echoed back."),
+});
+export type FleetConfig = z.infer<typeof FleetConfigSchema>;
 export type McpConfig = z.infer<typeof McpConfigSchema>;
 export type CliConfig = z.infer<typeof CliConfigSchema>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
@@ -294,7 +303,7 @@ export type ExtensionConfig = z.infer<typeof ExtensionConfigSchema>;
 export type SshConfig = z.infer<typeof SshConfigSchema>;
 export type DockerConfig = z.infer<typeof DockerConfigSchema>;
 export type BrowserConfig = z.infer<typeof BrowserConfigSchema>;
-export type HostConfig = z.infer<typeof HostConfigSchema>;
+export type DeviceConfig = z.infer<typeof DeviceConfigSchema>;
 export type AcpAgentConfig = z.infer<typeof AcpAgentConfigSchema>;
 export type EndpointConfig = z.infer<typeof EndpointConfigSchema>;
 export const CapabilitySchema = z.discriminatedUnion("kind", [
@@ -321,7 +330,7 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     z.object({ id: entryId, kind: z.literal("browser"), config: BrowserConfigSchema }),
     // One email identity browser accounts are born from; they join it via their own `identity` field.
     z.object({ id: entryId, kind: z.literal("identity"), config: IdentityConfigSchema }),
-    z.object({ id: entryId, kind: z.literal("host"), config: HostConfigSchema }),
+    z.object({ id: entryId, kind: z.literal("device"), config: DeviceConfigSchema }),
     // The user's own browser, through their installed extension; `host`'s sibling, one capability per browser. Distinct
     // from `browser`, the sandbox's own Chromium profile: this one is the person's, already signed into everything,
     // only ever borrowed.
@@ -335,6 +344,8 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     z.object({ id: entryId, kind: z.literal("localmodel"), config: LocalModelConfigSchema }),
     // The sandbox's USDC wallet (WalletConfigSchema), one per sandbox; the key never enters the container.
     z.object({ id: entryId, kind: z.literal("wallet"), config: WalletConfigSchema }),
+    // The owner's account, one per sandbox: the box holding this may provision sandboxes on it.
+    z.object({ id: entryId, kind: z.literal("fleet"), config: FleetConfigSchema }),
 ]);
 export type Capability = z.infer<typeof CapabilitySchema>;
 // A credential the owner must type elsewhere (a WhatsApp pairing code); rendered large and copyable, not buried in
@@ -365,7 +376,7 @@ export const CapabilitySummarySchema = z.object({
 // by catalog card, not kind, since several cards share one kind. Re-derived on every read, so it drops out once its
 // evidence moves; `prefill` is never a secret, even one sitting in a checked-in file.
 export const CapabilityRecommendationSchema = z.object({
-    card: z.string().describe("Which connection is being suggested."),
+    entry: z.string().describe("Which catalog entry is being suggested."),
     evidence: z
         .string()
         .describe("What was seen that prompted it: a file, a remote, printed verbatim so the claim can be checked rather than believed."),
@@ -398,9 +409,9 @@ export const CapabilityConnectionSchema = z.object({
         .describe("Its settings exactly as stored, credentials included. The field names are its own kind's, which the caller already knows."),
 });
 export type CapabilityConnection = z.infer<typeof CapabilityConnectionSchema>;
-// DELETE /capabilities/recommendations/{card}: the declined evidence is recorded daemon-side, so the suggestion returns
+// DELETE /capabilities/recommendations/{entry}: the declined evidence is recorded daemon-side, so the suggestion returns
 // once the workspace changes under it.
-export const CapabilityCardParamSchema = z.object({ card: z.string().describe("Which suggestion to stop making.") });
+export const CapabilityEntryParamSchema = z.object({ entry: z.string().describe("Which suggestion to stop making.") });
 // POST /capabilities/{id}/secret: replaces just the per-kind secret field and re-runs the capability's idempotent
 // apply.
 export const CapabilitySecretInputSchema = z.object({

package/src/schemas/chat-route.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { AgentProviderSchema } from "./agent.js";
+import { entryId } from "./internal.js";
+
+// One reading, asked once per chat on the message it opens with, answering whichever of two questions the chat still
+// has: which persona handles it, and what it runs on. Both are the same classification over lists the sandbox supplies,
+// both are only answerable before anything has run, and neither is worth a model call of its own — so there is one
+// call, and `model`/`persona` on the ask say which halves it is being paid to answer.
+
+export const ChatRouteAskSchema = z.object({
+    prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
+    paths: z
+        .array(z.string().min(1).max(500))
+        .max(50)
+        .default([])
+        .describe("Workspace paths the message names: uploads, @-mentions, the editor's own file. How much real code the work touches, and which persona's ground it stands on."),
+    folder: z.string().max(200).optional().describe("The workspace folder the chat was opened in, when it was opened in one."),
+    editorContext: z.boolean().optional().describe("Whether the message carries a file and selection the user pointed at, so it is about real code."),
+    planMode: z.boolean().optional().describe("Whether the chat opens in plan mode, which is a request to think before acting."),
+    // The two halves, each a fact about THIS chat rather than a setting: a chat already pointed at a model or a persona
+    // by hand has nothing left to ask about it, whatever the sandbox's settings say.
+    model: z.boolean().describe("Whether to choose the model, effort and account: true when the chat is on Auto and nothing has been picked by hand."),
+    persona: z.boolean().describe("Whether to choose the persona: true when persona matching is on and the chat has not been pointed at one by hand."),
+});
+export type ChatRouteAsk = z.infer<typeof ChatRouteAskSchema>;
+
+export const ModelPickSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves the conversation."),
+    model: z.string().min(1).describe("Which of its models."),
+    effort: z.string().optional().describe("How hard it should think, where the model offers a choice. Absent takes the model's own default."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which connected account pays, by its daemon-minted id. Absent leaves it to whichever account has the most headroom."),
+});
+export type ModelPick = z.infer<typeof ModelPickSchema>;
+
+// Absent `id` is a real, safe answer: the chat stays open to every account, and the reason says why nothing was named.
+export const PersonaVerdictSchema = z.object({
+    id: entryId.optional().describe("The persona this message belongs to, or absent when none does."),
+    reason: z.string().describe("Why, in the one clause a chat can show. Present whether or not a persona was named."),
+});
+
+// Absent `pick` is a real, safe answer: the chat runs on whatever the picker remembered, and the reason says why.
+export const ModelVerdictSchema = z.object({
+    pick: ModelPickSchema.optional().describe("What the conversation should run on, or absent when nothing could be chosen and the usual pick stands."),
+    reason: z.string().describe("Why, in the one clause a chat can show. Present whether or not a model was named."),
+});
+
+// One verdict per half asked for; a half that wasn't asked is absent, never a verdict with an empty answer.
+export const ChatRouteSchema = z.object({
+    persona: PersonaVerdictSchema.optional().describe("The persona half's answer, present only when it was asked for."),
+    model: ModelVerdictSchema.optional().describe("The model half's answer, present only when it was asked for."),
+    // Absent means nothing was spent: a folder match, the only runnable model, an unset role, a spent chain, or the
+    // deadline passing before any rung answered.
+    judge: z
+        .string()
+        .optional()
+        .describe("Which model answered, as `provider:model`, so the chat can name what the reading cost. Absent when no model was reached at all."),
+});
+export type ChatRoute = z.infer<typeof ChatRouteSchema>;

package/src/schemas/context-trim.test.ts

@@ -0,0 +1,38 @@
+import { test, expect } from "bun:test";
+import { contextTrimLine } from "./context-trim.js";
+
+// The one thing a reader ever sees of this mechanism. It has to answer three questions in one line: why the turn ran
+// thin, what it lost, and whether the reader's own instructions were among the losses.
+
+test("the window comes first, then what went, then what stayed", () => {
+    const line = contextTrimLine({ window: 16_384, omitted: ["Map of this project", "How this sandbox asks agents to work"], base: true });
+
+    expect(line).toContain("16k window");
+    expect(line).toContain("Map of this project, How this sandbox asks agents to work");
+    // Without this clause the line reads as "your AGENTS.md may not have arrived", which is the one thing it is not.
+    expect(line).toContain("Your workspace rules");
+});
+
+// A swapped base is a bigger change than any note and is stated as its own fact, not folded into the list.
+test("a swapped base says so, and a kept one does not", () => {
+    const swapped = contextTrimLine({ window: 16_384, omitted: [], base: true });
+    const kept = contextTrimLine({ window: 32_768, omitted: ["Map of this project"], base: false });
+
+    expect(swapped).toContain("base instructions were swapped");
+    expect(kept).not.toContain("base instructions");
+});
+
+// Nothing to list happens for real: a turn whose optional notes were all off already, on a window small enough to swap
+// the base. The sentence must not trail off into an empty list.
+test("an empty list leaves no dangling clause", () => {
+    const line = contextTrimLine({ window: 16_384, omitted: [], base: true });
+
+    expect(line).toContain("16k window.");
+    expect(line).not.toContain("left out");
+});
+
+// A user's own server can be started with any number at all, and rounding it to "24k" would misquote the thing the
+// reader has to go and change.
+test("a window that is not a round number is spelled out", () => {
+    expect(contextTrimLine({ window: 24_000, omitted: ["Map of this project"], base: false })).toContain("24,000 window");
+});