@intentic/sandbox-contract 1.300.0 → 1.300.1

package/src/contracts/system.contract.ts

@@ -1,4 +1,5 @@
-import { eventIterator, oc } from "@orpc/contract";
+import { oc } from "@orpc/contract";
+import { streamOf } from "../protocol/routes.js";
 import { z } from "zod";
 import { SessionTranscriptSchema } from "../events/transcript.js";
 import { SystemEventSchema } from "../events/system-events.js";
@@ -78,7 +79,7 @@ export const systemContract = {
                 "A stream held open for as long as you want it, carrying heartbeats so a caller notices the sandbox dying at once, batches of file changes so a tree or an editor can refresh itself, and the roster of who else is looking. Give it an id for this connection to appear in that roster; leave it out and you watch without being seen.",
         })
         .input(z.object({ clientId: z.string().optional() }))
-        .output(eventIterator(SystemEventSchema)),
+        .output(streamOf(SystemEventSchema)),
     // A tab's activity self-report (view/session/file/idle), fanned back out to every member on /events.
     presence: oc
         .route({
@@ -191,7 +192,7 @@ export const systemContract = {
                 "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(DeviceSandboxFlowInputSchema)
-        .output(eventIterator(DeviceFlowLineSchema)),
+        .output(streamOf(DeviceFlowLineSchema)),
     // Closed set of actions; the daemon builds the command line, not the caller. One sentence is the whole answer.
     runDeviceCommand: oc
         .route({
@@ -213,5 +214,5 @@ export const systemContract = {
                 "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)),
+        .output(streamOf(DeviceFlowLineSchema)),
 };

package/src/contracts/vpn.contract.ts

@@ -1,4 +1,5 @@
-import { eventIterator, oc } from "@orpc/contract";
+import { oc } from "@orpc/contract";
+import { streamOf } from "../protocol/routes.js";
 import { IntenticLineSchema } from "../events/system-events.js";
 import { OkSchema } from "../schemas/shared.js";
 import { ForticlientImportInputSchema, ForticlientImportSchema, VpnConnectInputSchema, VpnIdParamSchema, VpnListSchema } from "../schemas/vpn.js";
@@ -28,7 +29,7 @@ export const vpnContract = {
                 "Brings a stored tunnel up, streaming the client's progress as it authenticates and then sets up routing. Streamed because a dial takes seconds and can fail with something you have to read: a wrong password, a gateway certificate nobody trusts, a code it wants. Connecting one that is already up simply says so.",
         })
         .input(VpnConnectInputSchema)
-        .output(eventIterator(IntenticLineSchema)),
+        .output(streamOf(IntenticLineSchema)),
     // Drops a tunnel; tolerates one already down, since the contract is "not up," not "it was up."
     disconnect: oc
         .route({

package/src/protocol/routes.test.ts

@@ -2,7 +2,7 @@ import { eventIterator, oc } from "@orpc/contract";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "../index.js";
-import { contractRoutes, routeNameForRequest, routeShapes } from "./routes.js";
+import { contractRoutes, routeNameForRequest, routeShapes, streamOf } from "./routes.js";
 
 const fixture = {
     vpn: {
@@ -111,18 +111,38 @@ describe(`routeShapes`, () => {
         expect(routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`]).not.toBe(shapes[`vpn.list`]);
     });
 
-    it(`omits a route whose shape cannot be expressed rather than failing the walk`, () => {
-        // An oRPC event iterator wraps its output in an opaque type with no schema, so `watch` here keeps its name but
-        // no shape.
+    it(`fingerprints a stream through the frames it declares`, () => {
         const withStream = {
+            vpn: {
+                list: fixture.vpn.list,
+                watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(streamOf(z.object({ a: z.string() }))),
+            },
+        };
+        expect(Object.keys(routeShapes(withStream)).toSorted()).toEqual([`vpn.list`, `vpn.watch`]);
+        // A changed frame is a changed route, which is the whole point of reaching past the iterator.
+        const reframed = { vpn: { watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(streamOf(z.object({ a: z.number() }))) } };
+        expect(routeShapes(reframed)[`vpn.watch`]).not.toBe(routeShapes(withStream)[`vpn.watch`]);
+    });
+
+    it(`tells a stream of X apart from a route that answers X`, () => {
+        const frame = z.object({ a: z.string() });
+        const streamed = { vpn: { watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(streamOf(frame)) } };
+        const answered = { vpn: { watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(frame) } };
+        expect(routeShapes(streamed)[`vpn.watch`]).not.toBe(routeShapes(answered)[`vpn.watch`]);
+    });
+
+    it(`omits a route whose shape cannot be expressed rather than failing the walk`, () => {
+        // oRPC's own eventIterator hides its frames, which is why contracts declare streams with streamOf; one that
+        // slipped through keeps its name and loses only its shape, instead of breaking the walk for every other route.
+        const withRawIterator = {
             vpn: {
                 list: fixture.vpn.list,
                 watch: oc.route({ method: "GET", path: "/vpn/watch" }).output(eventIterator(z.object({ a: z.string() }))),
             },
         };
-        expect(Object.keys(routeShapes(withStream)).toSorted()).toEqual([`vpn.list`]);
+        expect(Object.keys(routeShapes(withRawIterator)).toSorted()).toEqual([`vpn.list`]);
         expect(
-            contractRoutes(withStream)
+            contractRoutes(withRawIterator)
                 .map((route) => route.name)
                 .toSorted(),
         ).toEqual([`vpn.list`, `vpn.watch`]);
@@ -130,34 +150,47 @@ describe(`routeShapes`, () => {
 });
 
 describe(`the real sandbox contract`, () => {
-    it(`fingerprints all but the streaming routes`, () => {
-        const unshaped = SANDBOX_ROUTE_NAMES.filter((name) => !(name in SANDBOX_ROUTE_SHAPES));
-        // oRPC gives an event iterator's output no schema, so these can't be fingerprinted; named rather than counted
-        // so a new one added here fails the test.
-        expect(unshaped.toSorted()).toEqual([
+    it(`fingerprints every route, streams included`, () => {
+        // Nothing may opt out: a route with no fingerprint is a route the browser can never tell has drifted, and the
+        // streaming ones (system.events, agent.attach, the exit dials) carry the frames a stale daemon breaks first.
+        expect(SANDBOX_ROUTE_NAMES.filter((name) => !(name in SANDBOX_ROUTE_SHAPES))).toEqual([]);
+    });
+
+    it(`fingerprints the streaming routes eventIterator used to hide`, () => {
+        expect(
+            [
+                `agent.attach`,
+                `capabilities.add`,
+                `exit.rotate`,
+                `exit.start`,
+                `exit.use`,
+                `intentic.applyEvents`,
+                `intentic.run`,
+                `netdisk.mount`,
+                `system.events`,
+                `system.manageDeviceSandbox`,
+                `system.runDeviceAgentFlow`,
+                `vpn.connect`,
+            ].filter((name) => name in SANDBOX_ROUTE_SHAPES).toSorted(),
+        ).toEqual([
             `agent.attach`,
             `capabilities.add`,
-            // The three exit moves stream since bringing an exit up dials and verifies over tens of seconds, failing at
-            // any step.
             `exit.rotate`,
             `exit.start`,
             `exit.use`,
             `intentic.applyEvents`,
             `intentic.run`,
-            // A mount dials a file server and can fail at any step with something to read, like a vpn dial.
             `netdisk.mount`,
             `system.events`,
             `system.manageDeviceSandbox`,
-            // The device agent updates or restarts itself; the stream dies with the process, so lines arrive as they
-            // happen.
             `system.runDeviceAgentFlow`,
             `vpn.connect`,
         ]);
     });
 
-    it(`fingerprints every other route exactly once`, () => {
+    it(`fingerprints every route exactly once`, () => {
         expect(Object.keys(SANDBOX_ROUTE_SHAPES).every((name) => SANDBOX_ROUTE_NAMES.includes(name))).toBe(true);
-        expect(Object.keys(SANDBOX_ROUTE_SHAPES).length).toBe(SANDBOX_ROUTE_NAMES.length - 12);
+        expect(Object.keys(SANDBOX_ROUTE_SHAPES).length).toBe(SANDBOX_ROUTE_NAMES.length);
     });
 
     it(`derives a route table with no duplicate names`, () => {

package/src/protocol/routes.ts

@@ -1,9 +1,23 @@
+import { eventIterator } from "@orpc/contract";
 import { z } from "zod";
 
 // Named route surface of the daemon's contract (`<group>.<route>`), derived automatically so nothing here is
 // hand-maintained. The daemon advertises which routes it implements (the /events hello frame); the browser diffs that
 // against its own contract so an old daemon's gap is a named feature check, not a silent 404.
 
+// Every streamed route declares its frames through this, never oRPC's `eventIterator` directly: that returns an opaque
+// standard-schema validator holding no reachable inner schema, so a stream's payload would be unfingerprintable and its
+// drift invisible. The frame schema rides along under a symbol, which oRPC never reads and JSON never serializes.
+// Typed as a plain `symbol`, not the inferred unique one: a unique symbol would ride into every contract's inferred
+// type and break declaration emit on a local name nothing outside can refer to.
+const FRAME: symbol = Symbol.for("intentic.contract.frame");
+
+export const streamOf = <T extends z.ZodType>(frame: T) => Object.assign(eventIterator(frame), { [FRAME]: frame });
+
+// The frame schema behind a streamed route's validator, or undefined for an ordinary request/response schema.
+const frameOf = (schema: unknown): z.ZodType | undefined =>
+    typeof schema === "object" && schema !== null && FRAME in schema ? ((schema as Record<symbol, unknown>)[FRAME] as z.ZodType) : undefined;
+
 // Structural shape of `~orpc.route`, the metadata oRPC attaches to every `oc.route(...)` procedure; read this way since
 // oRPC's internal types aren't public.
 interface ContractProcedureLike {
@@ -85,18 +99,24 @@ const fingerprint = (value: unknown): string => {
     return hash.toString(36);
 };
 
-// One route's wire shape, or undefined if it can't be expressed (a streaming route with no underlying schema). `io`
-// matters: a `.default()` field is optional in and required out, so both directions must be read separately.
+// One side of a route as JSON Schema. A streamed side is read through its frame and tagged, so "answers X" and "streams
+// frames of X" can never fingerprint alike. `io` matters: a `.default()` field is optional in and required out.
+const wireShape = (schema: unknown, io: "input" | "output"): unknown => {
+    if (schema === undefined) {
+        return undefined;
+    }
+    const frame = frameOf(schema);
+    return frame === undefined ? z.toJSONSchema(schema as z.ZodType, { io }) : { stream: z.toJSONSchema(frame, { io }) };
+};
+
+// One route's wire shape, or undefined if it can't be expressed at all.
 const procedureShape = (value: unknown): string | undefined => {
     if (typeof value !== "object" || value === null || !("~orpc" in value)) {
         return undefined;
     }
     const { inputSchema, outputSchema } = (value as ContractSchemasLike)["~orpc"];
     try {
-        return fingerprint({
-            in: inputSchema === undefined ? undefined : z.toJSONSchema(inputSchema as z.ZodType, { io: "input" }),
-            out: outputSchema === undefined ? undefined : z.toJSONSchema(outputSchema as z.ZodType, { io: "output" }),
-        });
+        return fingerprint({ in: wireShape(inputSchema, "input"), out: wireShape(outputSchema, "output") });
     } catch {
         return undefined;
     }

package/src/schemas/devices.ts

@@ -1,6 +1,6 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
-import { type HostFacts, HostFactsSchema, WslEnvironmentSchema } from "./hosts.js";
+import { hostCardOf, hostEnvironmentOf, type HostFacts, HostFactsSchema, WslEnvironmentSchema } from "./hosts.js";
 import { DEV_VERSION } from "../state/versions.js";
 // Desktop-sync report shape shared by the agent, daemon and browser, produced only by `intentic-machine status --json`.
 // The agent never reports `sandboxes`; the docker half is filled in by whoever reads the report, scoped to the reader's
@@ -451,54 +451,100 @@ export type DevicesList = z.infer<typeof DevicesListSchema>;
 // The physical computer a device is an environment of. Windows and every WSL distro on it are one machine with one
 // Docker engine, one screen and one set of disks, each environment holding its own agent and its own door.
 export interface Machine {
-    /** A lone device's own key, so its address does not change; a folded machine's is the hostname its doors share. */
+    /** The card its doors hang off, else the hostname they share, else a lone uncarded device's own key. */
     readonly key: string;
     readonly label: string;
-    /** Windows first, then distros by label: the side that owns the screen leads. */
+    /** Windows first, then distros by the name WSL registered: the side that owns the screen leads. */
     readonly environments: readonly Device[];
 }
 
 export const deviceHostname = (device: Device): string | undefined => device.facts?.hostname ?? device.report?.hostname;
-export const deviceEnvironment = (device: Device): string | undefined => environmentOf(device.facts, device.report);
-export const isWslDevice = (device: Device): boolean => deviceEnvironment(device)?.startsWith("wsl:") === true;
 
-// Two native installs that merely share a name stay two machines; only a distro joins the machine whose hostname it
-// carries, which is the one fact that makes the name safe to join on.
-const byEnvironment = (a: Device, b: Device): number => Number(isWslDevice(a)) - Number(isWslDevice(b)) || a.label.localeCompare(b.label);
+// Which side of a machine a device is. Its door id names the environment it connected under (`<card>::wsl:<distro>`),
+// and that is all an environment nobody has reached since this daemon booted can say about itself: liveness resets on
+// restart, so facts and reports are absent on a side that is merely asleep.
+export const deviceEnvironment = (device: Device): string | undefined =>
+    environmentOf(device.facts, device.report) ?? (device.hostId === undefined ? undefined : hostEnvironmentOf(device.hostId));
+
+const WSL_PREFIX = "wsl:";
+export const isWslDevice = (device: Device): boolean => deviceEnvironment(device)?.startsWith(WSL_PREFIX) === true;
+// The distro a device runs, by whatever evidence it holds; absent on a native install and on one that has said nothing.
+export const deviceDistro = (device: Device): string | undefined => {
+    const environment = deviceEnvironment(device);
+    return environment?.startsWith(WSL_PREFIX) === true ? environment.slice(WSL_PREFIX.length) : undefined;
+};
+
+// Native first, then distros by the name WSL registered them under rather than by their door id, which is that same
+// name behind a card's and so would order a PC's distros by which card each was connected through.
+const byEnvironment = (a: Device, b: Device): number =>
+    Number(isWslDevice(a)) - Number(isWslDevice(b)) || (deviceDistro(a) ?? a.label).localeCompare(deviceDistro(b) ?? b.label);
 
 const hostnameKey = (device: Device): string | undefined => deviceHostname(device)?.toLowerCase();
 
-const siblingsOf = (device: Device, devices: readonly Device[]): Device[] => {
-    const key = hostnameKey(device);
-    const shared = key === undefined ? [device] : devices.filter((candidate) => hostnameKey(candidate) === key);
-    return shared.length > 1 && shared.some(isWslDevice) ? shared.toSorted(byEnvironment) : [device];
+// The card a device's door hangs off: one card is one computer, so two doors naming the same card are one machine
+// whatever either has said about itself — which is the whole of what an environment that has never connected says.
+const cardKey = (device: Device): string | undefined => (device.hostId === undefined ? undefined : hostCardOf(device.hostId));
+
+// What makes two devices one computer: a shared card, or a shared hostname where a distro answers to it, since WSL
+// hands a distro the Windows machine's name. Two native installs that merely share a name stay two machines.
+const tokensOf = (device: Device, distroNames: ReadonlySet<string>): string[] => {
+    const card = cardKey(device);
+    const hostname = hostnameKey(device);
+    return [
+        ...(card === undefined ? [] : [`card:${card.toLowerCase()}`]),
+        ...(hostname !== undefined && distroNames.has(hostname) ? [`host:${hostname}`] : []),
+    ];
 };
 
-const machineOf = (device: Device, environments: readonly Device[]): Machine => {
-    if (environments.length === 1) {
-        return { key: device.key, label: device.label, environments };
-    }
-    // Folding needs a hostname, so it is present here; the fallback only keeps the type honest.
-    const hostname = deviceHostname(device) ?? device.key;
-    return { key: hostname, label: hostname, environments };
-};
+// Components over both joins at once: a device holding a card token and a hostname token is the evidence that merges
+// the machines those tokens named, so a distro connected under a card of its own still lands on the PC it runs on.
+interface Component {
+    readonly tokens: Set<string>;
+    readonly devices: Device[];
+}
 
-export const machinesOf = (devices: readonly Device[]): Machine[] => {
-    const folded = new Set<Device>();
-    const machines: Machine[] = [];
+const componentsOf = (devices: readonly Device[]): Component[] => {
+    const distroNames = new Set(devices.filter(isWslDevice).map(hostnameKey).filter((name) => name !== undefined));
+    const components: Component[] = [];
     for (const device of devices) {
-        if (folded.has(device)) {
+        const tokens = tokensOf(device, distroNames);
+        const [head, ...merged] = components.filter((component) => tokens.some((token) => component.tokens.has(token)));
+        if (head === undefined) {
+            components.push({ tokens: new Set(tokens), devices: [device] });
             continue;
         }
-        const environments = siblingsOf(device, devices);
-        for (const environment of environments) {
-            folded.add(environment);
+        for (const other of merged) {
+            other.tokens.forEach((token) => head.tokens.add(token));
+            head.devices.push(...other.devices);
+            components.splice(components.indexOf(other), 1);
         }
-        machines.push(machineOf(device, environments));
+        for (const token of tokens) {
+            head.tokens.add(token);
+        }
+        head.devices.push(device);
     }
-    return machines;
+    return components;
 };
 
+// Addressed by the card of the side that owns the screen, an address that does not change when a second environment
+// connects — unlike a row key, which is a hostname another environment can take first. An uncarded fold has only the
+// hostname its doors share, and an uncarded lone device its own key. Called what the owner calls it: the name the
+// leading environment carries, unless that is nothing but its door id, which reads as a PC named after one of its
+// own sides.
+const machineOf = (environments: readonly Device[]): Machine => {
+    const [first, ...rest] = environments;
+    // A component holds the device that made it; the empty case only keeps the type honest.
+    if (first === undefined) {
+        return { key: "", label: "", environments };
+    }
+    const named = environments.map(cardKey).find((key) => key !== undefined) ?? (rest.length === 0 ? undefined : deviceHostname(first));
+    const label = first.label === first.hostId ? (cardKey(first) ?? first.label) : first.label;
+    return { key: named ?? first.key, label, environments };
+};
+
+export const machinesOf = (devices: readonly Device[]): Machine[] =>
+    componentsOf(devices).map((component) => machineOf(component.devices.toSorted(byEnvironment)));
+
 // Every door whose docker reports a given sandbox slug, in list order. More than one is the ordinary case, not a
 // conflict: Windows and the WSL distros on it share one engine, so each door answers for the same containers.
 const doorsRunningSandbox = (devices: readonly Device[], slug: string | undefined): Device[] =>

package/src/state/history-state.ts

@@ -32,6 +32,9 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "provider-refusals.json", portability: "carry" },
     // Models refused to this sandbox's credentials; expires daily, same subscriptions apply elsewhere.
     { path: "model-refusals.json", portability: "carry" },
+    // What each account has run out of, for a plan publishing no allowance to poll — the refusal is the reading.
+    // Carried like the refusals above: an allowance belongs to the account, not to the machine that spent it.
+    { path: "observed-limits.json", portability: "carry" },
     // First-time dependency setup requests; carried so an interrupted queue survives export, entries self-remove.
     { path: "dependency-requests.json", portability: "carry" },
     // Which device cards were already offered; carry, not identity, since it holds ids, never a token.