@intentic/sandbox-contract 1.311.0 → 1.313.0

package/src/protocol/ingress-contract.test.ts

@@ -1,5 +1,14 @@
 import { generateKeyPairSync } from "node:crypto";
-import { hostOwnerId, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+import { readFileSync } from "node:fs";
+import { hostOwnerId, type ReachabilityGrant, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+
+// The edge's rules as both implementations must answer them; the Rust edge reads the same file. Its grants were minted
+// by a throwaway pair whose private half was never kept, so a new grant case takes a new pair and every token again.
+const FIXTURE = JSON.parse(readFileSync(new URL("./ingress-contract.fixture.json", import.meta.url), "utf8")) as {
+    readonly publicKey: string;
+    readonly grants: readonly { readonly token: string; readonly claim: ReachabilityGrant | null }[];
+    readonly owners: readonly { readonly host: string; readonly owner: string | null }[];
+};
 
 const pemPair = (): { privateKey: string; publicKey: string } => {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
@@ -31,10 +40,11 @@ describe("reachability grant", () => {
         expect(verifyReachabilityGrant(keys.publicKey, `${prefix}.${forged}.${signature}`)).toBeUndefined();
     });
 
-    it("answers undefined for garbage rather than throwing", () => {
-        const keys = pemPair();
-        for (const junk of ["", "ig1", "ig1..", "nonsense.a.b", "ig2.a.b", "ig1.%%%.%%%"]) {
-            expect(verifyReachabilityGrant(keys.publicKey, junk)).toBeUndefined();
+    it("answers every grant in the shared fixture as it states, and garbage with undefined rather than a throw", () => {
+        // Both verdicts, so the loop below can never pass by holding only one kind of case.
+        expect(new Set(FIXTURE.grants.map(({ claim }) => (claim === null ? "refused" : "accepted")))).toEqual(new Set(["accepted", "refused"]));
+        for (const { token, claim } of FIXTURE.grants) {
+            expect({ token, claim: verifyReachabilityGrant(FIXTURE.publicKey, token) ?? null }).toEqual({ token, claim });
         }
     });
 
@@ -44,27 +54,9 @@ describe("reachability grant", () => {
 });
 
 describe("hostOwnerId", () => {
-    it("owns the daemon's own name and every labelled name", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`preview-operator-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`port-0f0f0f0f0f0f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`public-1a2b3c4d5e6f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-    });
-
-    it("ignores a port suffix", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev:443`)).toBe(SANDBOX_ID);
-    });
-
-    it("owns nothing that does not end in a 12-hex tail", () => {
-        // The ingress's own door, the zone apex, the loopback name's bare-id label, and a near-miss tail.
-        for (const host of [
-            "ingress.sbx.example.dev",
-            "sbx.example.dev",
-            `${SANDBOX_ID}.local.sbx.example.dev`,
-            "sandbox-abc123def45.sbx.example.dev",
-            "",
-        ]) {
-            expect(hostOwnerId(host)).toBeUndefined();
+    it("owns every host in the shared fixture as it states, port or not", () => {
+        for (const { host, owner } of FIXTURE.owners) {
+            expect({ host, owner: hostOwnerId(host) ?? null }).toEqual({ host, owner });
         }
     });
 });

package/src/protocol/ingress-contract.ts

@@ -63,8 +63,9 @@ export const hostOwnerId = (host: string): string | undefined => {
 
 // Wire constants
 
-// Tunnel door on the ingress; versioned so a v2 session shape adds a new path instead of replacing this one.
-export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
+// Tunnel door on the ingress (the tunnel crate's TUNNEL_PATH); versioned, so a new session shape adds a path. `/tunnel/v1`
+// is the edge's alone to answer now, for fronts that predate this one.
+export const INGRESS_TUNNEL_PATH = "/tunnel/v2";
 
 // Grant travels as a header on the tunnel upgrade; this connection is never a browser's.
 export const INGRESS_GRANT_HEADER = "x-intentic-grant";
@@ -73,32 +74,16 @@ export const INGRESS_GRANT_HEADER = "x-intentic-grant";
 export const ENV_INGRESS_URL = "INGRESS_URL";
 export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
 
-// The daemon-side surface
-
-// Daemon-side tunnel behavior this contract requires: dial, register, forward to the loopback listener, and reconnect
-// forever with backoff, never giving up. `close()` is for shutdown and tests.
-export interface IngressTunnelOptions {
-    // e.g. https://ingress.<zone>; the daemon derives the wss:// door itself via INGRESS_TUNNEL_PATH.
-    readonly url: string;
-    readonly grant: string;
-    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
-    readonly targetPort: number;
-    readonly log: (message: string, error?: unknown) => void;
-}
-
-export interface IngressTunnelHandle {
-    readonly close: () => Promise<void>;
-    // For /health and the boot log: whether the tunnel currently holds a registered session.
-    readonly connected: () => boolean;
-}
-
-export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
-
-// What the ingress side must also honor, enforced by ingress-protocol tests:
+// What the edge (_platform/ingress, Rust) must also honor, held by its suites and by ingress-contract.fixture.json:
 // - Register: verify the grant offline; if PLATFORM_URL is set, check the sandbox exists (GET /api/reachability/<id>)
 //   and cache the answer, failing open if the platform doesn't respond. A 404 refuses the tunnel.
 // - Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
-// - Liveness: WebSocket ping every 15s; a peer silent for 45s is unregistered.
+// - Streams: every exchange is a stream of its own carrying HTTP/1.1 (yamux over a WebSocket, or QUIC). Over TCP a
+//   transfer rides the bulk socket: a preview's request, or a route the front announced (tunnel-bulk.ts); over QUIC a
+//   stream that sends a megabyte without pausing yields to the others.
+// - Liveness: the front pings every 15s; a peer silent for 45s is unregistered.
 // - Routing: host maps via hostOwnerId to a registered tunnel; no tunnel answers 502 naming the sandbox label, with
 //   the verdict header and CORS of edge-verdict.ts, and admits the preflight of the request it is about to refuse.
 // - The tunnel door and any host without a sandbox id are served directly by the ingress, never routed.
+// - `/health` lists the tunnel doors the build serves (`"doors":["/tunnel/v1","/tunnel/v2"]`); a sandbox image moves
+//   onto a tag sandboxes pull only once the live edge lists INGRESS_TUNNEL_PATH (_tools/scripts/image/require-edge-door.sh).

package/src/protocol/raw-routes.ts

@@ -8,26 +8,26 @@ import { runnerTranslatorPath } from "./runner-protocol.js";
 export const RAW_ROUTES = {
     // The "is a daemon there" probe every flow uses; it names the sandbox and says whether it is still converging.
     "GET /health": { auth: "door", beforeBoot: true },
-    "GET /diff/raw": {},
+    "GET /diff/raw": { lane: "bulk" },
     // Arming the dictation model is a read any tier makes; dictating is writing a message, the collaborator's grant.
     "GET /speech/status": { guest: true },
     "POST /speech/transcribe": { floor: "collaborator", guest: true },
     // The bytes behind the workspace reads; each applies the caller's fence itself.
-    "GET /workspace/raw": { guest: true },
+    "GET /workspace/raw": { guest: true, lane: "bulk" },
     // No door, unlike media: the page fetches a thumbnail itself, so the request carries the header.
     "GET /workspace/thumb": { guest: true },
     // Fetched by a <video>/<audio> tag, which sends no header: its scoped ticket is checked in the handler.
-    "GET /workspace/media": { auth: "door", guest: true },
+    "GET /workspace/media": { auth: "door", guest: true, lane: "bulk" },
     // An attachment is part of the message it rides with; any other target edits the shared tree.
-    "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator" },
+    "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator", lane: "bulk" },
     "POST /workspace/upload-diff": {},
-    "POST /workspace/upload-archive": {},
+    "POST /workspace/upload-archive": { lane: "bulk" },
     // Minting is cheap: each WebSocket upgrade floors its own redemption.
     "POST /system/ws-ticket": { beforeBoot: true, floor: "collaborator", control: "never" },
     // A WebSocket upgrade carries no Authorization header; the terminal and both browser wires check a query ticket.
-    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never" },
+    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", front: true },
     // Desktop sync's byte pipe, guarded again by sshd's own key check against the same enrollment.
-    "GET /system/sync/ssh": { sync: "pipe", control: "never" },
+    "GET /system/sync/ssh": { sync: "pipe", control: "never", lane: "bulk" },
     "GET /system/browser-profile": { auth: "door", beforeBoot: true, control: "never" },
     "GET /system/browser-view": { auth: "door", beforeBoot: true, control: "never" },
     // Deploy-target enrollment, gated by the connect token.
@@ -68,7 +68,7 @@ export const RAW_ROUTES = {
     "DELETE /bundles": { control: "never" },
     "POST /bundles/ticket": { control: "never" },
     // Navigated to by the browser, so no header: its ticket is checked in the handler.
-    "GET /bundles/download": { auth: "door", control: "never" },
+    "GET /bundles/download": { auth: "door", control: "never", lane: "bulk" },
     "GET /definition": {},
     "POST /definition/diff": {},
     "GET /definition/workspace": {},
@@ -78,7 +78,7 @@ export const RAW_ROUTES = {
     "POST /arrivals/scan": {},
     "POST /arrivals/apply": {},
     "DELETE /arrivals": {},
-    "GET /extensions/{id}/bundle": {},
+    "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
     "ALL /x/*": {},
     // The `capabilities` CLI: discovery by name, and the ask that parks on an owner-decided card.
@@ -102,11 +102,12 @@ export const RAW_ROUTES = {
     "GET /fleet": { agent: true },
     "POST /fleet/message": { agent: true },
     "GET /fleet/{handle}": { agent: true },
-    // An extension gateway's realtime-listener control, reached with the panel token.
-    "GET /listeners/{provider}/state": {},
-    "POST /listeners/{provider}/dispatch": {},
-    "POST /listeners/{provider}/failure": {},
-    "POST /listeners/{provider}/status": {},
+    // An extension gateway's realtime-listener control: /state hands back its connectors' stored credentials, so only the
+    // extension token of the extension declaring that `listener.provider` reaches them, checked in the handler too.
+    "GET /listeners/{provider}/state": { floor: "maintainer", panel: false, control: "never" },
+    "POST /listeners/{provider}/dispatch": { panel: false, control: "never" },
+    "POST /listeners/{provider}/failure": { panel: false, control: "never" },
+    "POST /listeners/{provider}/status": { panel: false, control: "never" },
     // The CI webhook receiver, gated by the per-sandbox webhook secret.
     "POST /ci/webhook/{host}": { auth: "door" },
     // Below maintainer a pairing is capped to port-mirror, so a collaborator may mint a preview tunnel.
@@ -118,33 +119,28 @@ export const RAW_ROUTES = {
     "DELETE /system/hosts/{id}": { control: "never" },
     // A peer's socket reconnects on its own backoff, so it answers before boot.
     "GET /system/hosts/connect": { auth: "door", beforeBoot: true, control: "never" },
-    // The MCP bridge onto a peer, carrying the per-boot bridge token its handler checks.
-    "POST /mcp/hosts/{id}": { auth: "door" },
-    "GET /mcp/hosts/{id}": { auth: "door" },
-    "DELETE /mcp/hosts/{id}": { auth: "door" },
     "POST /system/webext/pair": { control: "never" },
     "POST /system/webext/enroll": { auth: "door", control: "never" },
     "GET /system/webext": { control: "never" },
     "DELETE /system/webext/{id}": { control: "never" },
     "GET /system/webext/connect": { auth: "door", beforeBoot: true, control: "never" },
-    "POST /mcp/webext/{id}": { auth: "door" },
-    "GET /mcp/webext/{id}": { auth: "door" },
-    "DELETE /mcp/webext/{id}": { auth: "door" },
     "POST /system/runners/pair": { control: "never" },
     "POST /system/runners/enroll": { auth: "door", control: "never" },
     "GET /system/runners": { control: "never" },
     "DELETE /system/runners/{id}": { control: "never" },
     "GET /system/runners/connect": { auth: "door", beforeBoot: true, control: "never" },
-    // A turn's own browser router, carrying the per-boot browser bridge token.
-    "POST /system/browser/prepare": { auth: "door", control: "never" },
+    // Every MCP server the daemon hosts for a turn (its browser routers, the machines and browsers it was granted, its
+    // extension cards' endpoints), by server name: the handler checks the conversation's mount bearer the turn's tool
+    // config carries, and that the running turn mounted that name.
+    "ALL /mcp/{mount}": { auth: "door", control: "never" },
     // A connected browser's credential doors, on its durable token: a sign-in moves in (`session`) or out (`lend`).
     "POST /system/webext/session": { auth: "door", control: "never" },
     "POST /system/webext/lend": { auth: "door", control: "never" },
     "POST /system/runners/{id}/definition/sync": { control: "never" },
     // A runner's git door and credential doors, each on the runner's own bearer.
-    "GET /system/runners/git/{repo}/info/refs": { auth: "door", control: "never" },
-    "POST /system/runners/git/{repo}/git-upload-pack": { auth: "door", control: "never" },
-    "POST /system/runners/git/{repo}/git-receive-pack": { auth: "door", control: "never" },
+    "GET /system/runners/git/{repo}/info/refs": { auth: "door", control: "never", lane: "bulk" },
+    "POST /system/runners/git/{repo}/git-upload-pack": { auth: "door", control: "never", lane: "bulk" },
+    "POST /system/runners/git/{repo}/git-receive-pack": { auth: "door", control: "never", lane: "bulk" },
     "POST /system/runners/credentials": { auth: "door", control: "never" },
     "POST /system/runners/credentials/refresh": { auth: "door", control: "never" },
     [`ALL ${runnerTranslatorPath}/*` as const]: { auth: "door", control: "never" },

package/src/protocol/route-meta.ts

@@ -33,7 +33,46 @@ export interface RouteMeta {
     // Withheld from the panel token, which reaches every other route: it puts a stored credential in motion.
     readonly panel?: false;
     readonly control?: ControlReach;
+    // A transfer: announced to the edge through the front (tunnel-bulk.ts), which sends it down the tunnel's bulk socket,
+    // off the connection every keystroke and call waits on.
+    readonly lane?: "bulk";
+    // Served by intentic-front itself (_sandbox/front, term/): the daemon only answers the front's question about it.
+    readonly front?: true;
 }
 
+// The floor a route gets when it declares none: a read (GET, HEAD) floors at viewer, anything else (`ALL` included) at
+// maintainer, so a route nobody classified can under-serve, never over-grant.
+export const defaultFloor = (method: string): MemberRole => (method === "GET" || method === "HEAD" ? "viewer" : "maintainer");
+
+// The fields that say how a request travels, not who may send it; every other RouteMeta field decides reach.
+type TransportField = "lane" | "front";
+
+// Every field that decides who reaches a route, with its default resolved, so an absent field and a declared one read
+// alike and loosening either is a changed value: what contract.lock.json records per route (`access:METHOD /path`),
+// where the lock check and the push gate see it. Keyed by the interface: a RouteMeta field added above fails this
+// package's typecheck until it is read here or named a TransportField.
+const ACCESS = {
+    auth: (meta) => meta.auth ?? "session",
+    embedded: (meta) => meta.embedded === true,
+    beforeBoot: (meta) => meta.beforeBoot === true,
+    stream: (meta) => meta.stream === true,
+    floor: (meta, method) => meta.floor ?? defaultFloor(method),
+    guest: (meta) => meta.guest === true,
+    attachmentFloor: (meta) => meta.attachmentFloor ?? "none",
+    enrolment: (meta) => meta.enrolment === true,
+    agent: (meta) => meta.agent === true,
+    sync: (meta) => meta.sync ?? "none",
+    panel: (meta) => meta.panel !== false,
+    // `floor`: no reach of its own, the control rungs read the route's floor alone.
+    control: (meta) => meta.control ?? "floor",
+} as const satisfies { readonly [K in Exclude<keyof RouteMeta, TransportField>]-?: (meta: RouteMeta, method: string) => string | boolean };
+
+export type RouteAccess = { readonly [K in keyof typeof ACCESS]: ReturnType<(typeof ACCESS)[K]> };
+
+// One route's reach as its declaration states it, every default filled in.
+export const routeAccess = (method: string, meta: RouteMeta): RouteAccess =>
+    // SAFETY: every entry is one of ACCESS's own keys paired with what its reader returned, which RouteAccess spells.
+    Object.fromEntries(Object.entries(ACCESS).map(([field, read]) => [field, read(meta, method)])) as RouteAccess;
+
 // The builder every sandbox procedure starts from, so each carries a RouteMeta and whatever it leaves out defaults.
 export const procedure = oc.$meta<RouteMeta>({});

package/src/protocol/runner-protocol.ts

@@ -188,6 +188,59 @@ export const RunnerTurnSchema = z.object({
 });
 export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
 
+// OFFLOADED COMMANDS: one shell line the parent hands a runner instead of running it itself (settings `offload`). The
+// code travels as a snapshot commit of the parent's working tree, uncommitted and untracked work included, parked under
+// this ref in the repo's git dir for the runner to fetch through the git door, and deleted once the run ends.
+export const OFFLOAD_REF_PREFIX = "refs/intentic-offload/";
+export const offloadRef = (runId: string): string => `${OFFLOAD_REF_PREFIX}${runId}`;
+const OffloadRunIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{7,63}$/u);
+const EnvNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+
+export const RunnerCommandSchema = z.object({
+    runId: OffloadRunIdSchema,
+    // The repo id the git door serves (a /history/gits entry: `root` for the workspace itself).
+    repo: z.string().min(1),
+    // The snapshot commit's ref in that repo, always under OFFLOAD_REF_PREFIX.
+    ref: z.string().startsWith(OFFLOAD_REF_PREFIX),
+    // Where in the repo the line runs, repo-relative; "" is the repo root.
+    cwd: z.string().refine((path) => !path.startsWith("/") && !path.split("/").includes(".."), "must stay inside the repo"),
+    command: z.string().min(1).max(64_000),
+    // Values set for the line, beside the runner's own environment. Never a secret: a line that needs one runs here.
+    env: z.record(EnvNameSchema, z.string()).default({}),
+    // Variables the line writes a file to (a report path): the runner points each at a scratch file and hands the file
+    // back with the exit.
+    exports: z.array(EnvNameSchema).max(8).default([]),
+    // The heavy-command rule it matched here, named in the runner's own output and queue.
+    label: z.string().min(1).max(80),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(6 * 60 * 60_000)
+        .optional(),
+});
+export type RunnerCommand = z.infer<typeof RunnerCommandSchema>;
+
+// What a running command streams back: narration of the runner's own steps (fetch, install, queue), the line's output
+// as it comes, and last its end: the exit, every file it changed as a binary git patch against the snapshot, and the
+// exported files, base64.
+export const RunnerCommandFrameSchema = z.union([
+    z.object({ kind: z.literal("status"), text: z.string() }),
+    z.object({ kind: z.literal("output"), stream: z.enum(["stdout", "stderr"]), text: z.string() }),
+    z.object({
+        kind: z.literal("exit"),
+        code: z.number().int(),
+        signal: z.string().optional(),
+        // Why the run did not end on its own: stopped, timed out, or never started (a fetch or install that failed).
+        failure: z.string().optional(),
+        // False when the line never started there, which sends it back to run on the parent.
+        ran: z.boolean().default(true),
+        patchBase64: z.string().optional(),
+        files: z.record(EnvNameSchema, z.string()).default({}),
+    }),
+]);
+export type RunnerCommandFrame = z.infer<typeof RunnerCommandFrameSchema>;
+
 // Where a conversation runs, fixed on its first turn like `isolated` placement: later turns follow the registry, not
 // the sender. `runner` implies isolation since a remote conversation is branch-anchored; absent means local.
 export const AgentPlacementSchema = z.union([z.object({ kind: z.literal("local") }), z.object({ kind: z.literal("runner"), id: z.string().min(1) })]);

package/src/protocol/tunnel-bulk.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { servedRoute } from "./routes.js";
+import { RAW_ROUTE_LIST } from "./raw-routes.js";
+import { hostOwnerId } from "./ingress-contract.js";
+import { tunnelBulkRoutes } from "./tunnel-bulk.js";
+
+// The shared fixture the edge reads too (the tunnel crate's bulk.rs): `bulk` is what the daemon announces, and every
+// case is the lane the daemon's own router gives the request, which the edge's reading of `bulk` must match.
+// SAFETY: the fixture is this repository's own file, and both tests below fail on a key it lacks.
+const FIXTURE = JSON.parse(readFileSync(new URL("./ingress-contract.fixture.json", import.meta.url), "utf8")) as {
+    readonly bulk: readonly string[];
+    readonly lanes: readonly { readonly host: string; readonly method: string; readonly path: string; readonly lane: "interactive" | "bulk" }[];
+};
+
+// A preview's dev server rides bulk; a daemon request rides its route's lane, the route found as the router finds it.
+const laneOf = (host: string, method: string, path: string): "interactive" | "bulk" => {
+    const id = hostOwnerId(host);
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    if (id === undefined || label !== `sandbox-${id}`) {
+        return "bulk";
+    }
+    return servedRoute(RAW_ROUTE_LIST, [], method, path)?.meta.lane ?? "interactive";
+};
+
+test("the fixture's announcement is what the daemon announces today", () => {
+    expect(tunnelBulkRoutes()).toEqual([...FIXTURE.bulk]);
+    for (const route of tunnelBulkRoutes()) {
+        expect(route).toMatch(/^[A-Z]+ \/\S*$/);
+    }
+});
+
+test("every request the shared fixture names rides the lane the daemon's router gives it", () => {
+    expect(FIXTURE.lanes.length).toBeGreaterThan(20);
+    for (const { host, method, path, lane } of FIXTURE.lanes) {
+        expect({ host, method, path, lane: laneOf(host, method, path) }).toEqual({ host, method, path, lane });
+    }
+});

package/src/protocol/tunnel-bulk.ts

@@ -0,0 +1,7 @@
+import { RAW_ROUTE_LIST } from "./raw-routes.js";
+
+// What the daemon announces to the edge as its transfers (RouteMeta `lane`), handed to the front with the tunnel's door
+// and carried on each of its sockets' upgrades (the tunnel crate's `x-intentic-bulk`), so the edge sends a transfer
+// down the bulk socket and a keystroke never queues behind it on one TCP connection. The edge compiles in nothing of it.
+export const tunnelBulkRoutes = (): string[] =>
+    RAW_ROUTE_LIST.filter(({ meta }) => meta.lane === "bulk").map(({ method, path }) => `${method} ${path}`);

package/src/protocol/x402.test.ts

@@ -0,0 +1,29 @@
+import { atomicToUsd, USDC_NETWORKS, usdcNetworkOf, usdToAtomic } from "./x402.js";
+
+it("converts USD and atomic units without floats, in both directions", () => {
+    expect(usdToAtomic("1.00")).toBe(1_000_000n);
+    expect(usdToAtomic("0.1")).toBe(100_000n);
+    expect(usdToAtomic("0.000001")).toBe(1n);
+    // The classic float trap: 0.1 + 0.2 in binary floating point is not 0.3, and money must not care.
+    expect(usdToAtomic("0.1") + usdToAtomic("0.2")).toBe(usdToAtomic("0.3"));
+    expect(atomicToUsd(1_000_000n)).toBe("1.00");
+    expect(atomicToUsd(100_000n)).toBe("0.10");
+    expect(atomicToUsd(1n)).toBe("0.000001");
+});
+
+it("reads a bare whole or fraction, cuts past the sixth decimal, and writes zero as cents", () => {
+    expect(usdToAtomic("5")).toBe(5_000_000n);
+    expect(usdToAtomic(".5")).toBe(500_000n);
+    expect(usdToAtomic("0.0000019")).toBe(1n);
+    expect(atomicToUsd(0n)).toBe("0.00");
+    expect(atomicToUsd(12_345_670n)).toBe("12.34567");
+});
+
+it("knows USDC on Base and Base Sepolia by CAIP-2 id, and nothing else", () => {
+    expect(USDC_NETWORKS.map(({ network, chainId, asset }) => [network, chainId, asset])).toEqual([
+        ["eip155:8453", 8453, "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
+        ["eip155:84532", 84532, "0x036CbD53842c5426634e7929541eC2318f3dCF7e"],
+    ]);
+    expect(usdcNetworkOf("eip155:84532")?.v1Network).toBe("base-sepolia");
+    expect(usdcNetworkOf("base")).toBeUndefined();
+});

package/src/protocol/x402.ts

@@ -0,0 +1,61 @@
+// The money side of x402 every tier states alike: which USDC contracts a payment may move, and dollars as atomic units.
+
+// One chain's USDC: token contract, EIP-712 domain defaults, explorer; an asset not on the list below is refused.
+export interface UsdcNetwork {
+    // CAIP-2 ("eip155:8453"), the v2 vocabulary and the wallet config's.
+    readonly network: string;
+    // How v1 challenges spell the same chain ("base"), matched on parse, echoed on the v1 retry header.
+    readonly v1Network: string;
+    readonly chainId: number;
+    readonly asset: string;
+    // EIP-712 domain fallbacks; `extra.{name,version}` on the challenge wins when present.
+    readonly domainName: string;
+    readonly domainVersion: string;
+    readonly label: string;
+    readonly explorer: string;
+    readonly rpc: string;
+}
+
+export const USDC_NETWORKS: readonly UsdcNetwork[] = [
+    {
+        network: "eip155:8453",
+        v1Network: "base",
+        chainId: 8453,
+        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        domainName: "USD Coin",
+        domainVersion: "2",
+        label: "Base",
+        explorer: "https://basescan.org/tx/",
+        rpc: "https://mainnet.base.org",
+    },
+    {
+        network: "eip155:84532",
+        v1Network: "base-sepolia",
+        chainId: 84532,
+        asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        domainName: "USDC",
+        domainVersion: "2",
+        label: "Base Sepolia (test)",
+        explorer: "https://sepolia.basescan.org/tx/",
+        rpc: "https://sepolia.base.org",
+    },
+];
+
+export const usdcNetworkOf = (network: string): UsdcNetwork | undefined => USDC_NETWORKS.find((entry) => entry.network === network);
+
+// Every amount is a bigint of atomic units, never a float; USD strings ("1.50") are the display and policy vocabulary.
+export const USDC_DECIMALS = 6n;
+const ATOMIC_PER_USD = 10n ** USDC_DECIMALS;
+
+// Digits past the sixth decimal are cut, not rounded: a price is never read as more than was written.
+export const usdToAtomic = (usd: string): bigint => {
+    const [whole, fraction = ""] = usd.split(".");
+    return BigInt(whole || "0") * ATOMIC_PER_USD + BigInt(fraction.padEnd(6, "0").slice(0, 6) || "0");
+};
+
+// At least cents ("1.50"), and every non-zero atomic digit after them ("0.000001").
+export const atomicToUsd = (atomic: bigint): string => {
+    const whole = atomic / ATOMIC_PER_USD;
+    const fraction = (atomic % ATOMIC_PER_USD).toString().padStart(6, "0").replace(/0+$/, "");
+    return fraction === "" ? `${whole}.00` : `${whole}.${fraction.padEnd(2, "0")}`;
+};

package/src/schemas/activity.ts

@@ -20,7 +20,9 @@ export const ActivityEventSchema = z.object({
     // in: message.received, voice_utterance.received, voice_transcript.received
     // out: message.send, reaction.add, messages.read, api.call (unclassified endpoint)
     // system: gateway.login_failed, dispatch.failed, voice.session_started, voice.session_ended, automation.run,
-    // turn.started, turn.plan, turn.error, turn.completed, rule.blocked_push, rule.held_work, rule.continued_turn
+    // turn.started, turn.plan, turn.error, turn.completed, rule.held_work, deps.verify_green, deps.verify_red,
+    // deps.breakage_routed, deps.breakage_fixup, deps.breakage_waiting, deps.breakage_held, deps.breakage_resolved,
+    // deps.breakage_spent; rule.blocked_push and rule.continued_turn are retired and only appear in older logs
     type: z
         .string()
         .describe(

package/src/schemas/agent.ts

@@ -1,3 +1,4 @@
+import { TurnErrandSchema } from "./speaker.js";
 import { z } from "zod";
 import { CONVERSATION_ID } from "../ids/conversation-ids.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
@@ -129,6 +130,9 @@ export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 // The turn's fields before the cross-field refinements below, so a subset (TurnProfileSchema) can be picked from them.
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
+    errand: TurnErrandSchema.optional().describe(
+        "What the words are for, when the app or the sandbox composed them rather than a person typing them: a land conflict to resolve, a red main line to fix. Shown as the sandbox's words, not yours. Leave it out for your own words.",
+    ),
     // Minted by the sender so a send whose answer was lost can be sent again without being delivered twice.
     messageId: z
         .string()
@@ -164,8 +168,14 @@ const AgentTurnFieldsSchema = z.object({
     // Which agentic loop runs the turn, absent = provider's own; "claude-code" forces the SDK loop for any
     // provider.
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs the turn. Leave it out to use each provider's own."),
-    // Which connected account of that provider serves the turn; absent = the provider's first account.
-    account: z.string().optional().describe("Which of that provider's connected accounts pays for the turn. Leave it out for the first one."),
+    // Intent, not a guess: absent continues on the conversation's own account, or picks by serviceability where there is
+    // none on this provider yet (agent/providers/accounts/routing.ts).
+    account: z
+        .string()
+        .optional()
+        .describe(
+            "Which of that provider's connected accounts pays for the turn. Leave it out to continue on the account the conversation runs on, or, for its first turn on this provider, to take whichever account can serve with the most room. To move a running conversation, use `switchAccount`.",
+        ),
     // Distinct from `account` (who pays): whose name the turn posts as; absent means something different for each
     // mode.
     actsAs: entryId.optional().describe("Which persona the turn speaks as out in the world. Not the same as which account pays for it."),
@@ -317,6 +327,19 @@ export const AgentTurnSchema = AgentTurnFieldsSchema
         message: 'forkOf.files "then" requires isolated',
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
+// What a turn naming no provider or loop runs on, stated once. Applied where a request comes in (the daemon's turn port),
+// so nothing downstream defaults them again: the engine takes a turn with both named (withRuntimeDefaults).
+/** A turn with its provider and loop named, as the engine takes it past the door. */
+export type RoutedAgentTurn = AgentTurn & { readonly agent: AgentProvider; readonly harness: AgentHarness };
+export const DEFAULT_PROVIDER: AgentProvider = "claude";
+export const DEFAULT_HARNESS: AgentHarness = "native";
+export const withRuntimeDefaults = <T extends { readonly agent?: AgentProvider | undefined; readonly harness?: AgentHarness | undefined }>(
+    turn: T,
+): T & { readonly agent: AgentProvider; readonly harness: AgentHarness } => ({
+    ...turn,
+    agent: turn.agent ?? DEFAULT_PROVIDER,
+    harness: turn.harness ?? DEFAULT_HARNESS,
+});
 // Which turn this is, as opposed to what it says: who serves it and how (agent, harness, account, model and its knobs),
 // as whom (actsAs), where (isolated), whether anyone watches (unattended) and for which job (runRole). A turn that
 // continues another (a resume, a wake, a nudge, a child's follow-up) carries this whole, never a hand-picked part.
@@ -357,7 +380,9 @@ export const AgentRunPickSchema = z
         account: z
             .string()
             .optional()
-            .describe("Which connected account of that provider pays, by its daemon-minted id. Leave it out for whichever has headroom."),
+            .describe(
+                "Which connected account of that provider pays, by its daemon-minted id. Leave it out to take whichever account can serve with the most room.",
+            ),
         harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
         effort: z
             .string()