@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/routes.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 /* The daemon's route surface, named. A sandbox daemon is baked into an image, so the browser talking to it is
  * routinely NEWER than the daemon: a released app plane serves every user's sandbox, whatever image they last
  * pulled, and in local development the web app is always ahead of the last `pnpm build:sandbox`. Both are
@@ -63,6 +65,114 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
     return routes.toSorted((a, b) => a.name.localeCompare(b.name));
 };
 
+/* ---- the SHAPE of a route, not just its name ----
+ *
+ * The route list above answers "does this daemon have it". It cannot answer the other half: a route that
+ * exists on BOTH sides but whose payload changed between the two builds. Names match, so the call goes out,
+ * and a field the browser expects is simply missing from the answer — no 404, no message, nothing to attribute
+ * it to. That is the one skew failure the named-gap mechanism still leaves silent.
+ *
+ * So each route also advertises a fingerprint of its wire shape: input and output schema together, reduced to
+ * one short string. Same string ⇒ the two builds agree, which is the overwhelmingly common case and costs a
+ * comparison. Different ⇒ a NAMED route whose payload moved, which the UI can explain in exactly the words it
+ * already uses for a missing one.
+ *
+ * NOTHING IS HAND-MAINTAINED, which is the whole reason this is a fingerprint and not a version number. The
+ * codebase already rejected the hand-bumped alternative once (see the web app's buildEpoch.ts: a SCHEMA_VERSION
+ * "hangs on someone remembering"). Changing a field in a contract schema changes that route's fingerprint by
+ * itself, on both sides, with nobody to remember anything. */
+
+// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above —
+// they are internal metadata, not part of its public surface.
+interface ContractSchemasLike {
+    readonly "~orpc": { readonly inputSchema?: unknown; readonly outputSchema?: unknown };
+}
+
+/* The JSON Schema keywords whose array value is a SET — order carries no meaning, so two schemas that differ
+ * only in it are the same wire shape. `required` is the one that matters in practice: JSON Schema spells an
+ * object's fields twice, once as `properties` (an object, so key-sorting settles it) and once as `required`
+ * (an array, in declaration order) — so without this, moving a field up a `z.object` for readability reads as
+ * drift on every route that carries it. The union keywords are here for the same reason a step lower down. */
+const UNORDERED = new Set(["required", "enum", "anyOf", "oneOf", "allOf"]);
+
+/* Canonical JSON: object keys sorted, set-valued arrays sorted, everything else left in the order it was
+ * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it — which
+ * is what keeps a purely cosmetic edit from being reported to a user as a payload that moved.
+ *
+ * Ordered arrays stay ordered: a tuple's `prefixItems` is positional, and sorting it would call two genuinely
+ * different shapes identical — the failure that actually costs something here. */
+const canonical = (value: unknown, key?: string): unknown => {
+    if (Array.isArray(value)) {
+        const items = value.map((item) => canonical(item));
+        return key !== undefined && UNORDERED.has(key) ? items.toSorted((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) : items;
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const entries = Object.entries(value as Record<string, unknown>).toSorted(([a], [b]) => a.localeCompare(b));
+    return entries.map(([name, nested]) => [name, canonical(nested, name)]);
+};
+
+/* FNV-1a over the canonical JSON, base36. Deliberately not a cryptographic hash: this is a drift SIGNAL, and
+ * the cost of a collision is one warning that never appears — never a wrong action, never a blocked call. A
+ * crypto digest would mean a subtle-crypto round trip in the browser (async, and unavailable on insecure
+ * origins) to buy nothing this use has any need of. */
+const fingerprint = (value: unknown): string => {
+    const text = JSON.stringify(canonical(value));
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+};
+
+/* One route's wire shape, or undefined when it cannot be expressed.
+ *
+ * `io` matters and is not cosmetic: a field with `.default()` is OPTIONAL on the way in and REQUIRED on the
+ * way out, so reading both sides in the same direction would call two genuinely different shapes identical.
+ *
+ * A schema that will not convert yields undefined rather than throwing the walk away. Every such route in the
+ * contract today is a streaming one — oRPC wraps an event iterator's output in an opaque type with no schema
+ * underneath it — and their absence lands them in exactly the right place: a route with no advertised shape is
+ * assumed compatible, which is the same "positive evidence only" rule the missing-route check already runs on. */
+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" }),
+        });
+    } catch {
+        return undefined;
+    }
+};
+
+// Every route whose shape THIS build can express, as name → fingerprint. Same walk as contractRoutes, and
+// deliberately a separate map rather than a field on ContractRoute: the two are advertised independently
+// (existence covers every route, shape covers the ones that can be expressed) and read by different checks.
+export const routeShapes = (contract: Record<string, unknown>): Record<string, string> => {
+    const shapes: Record<string, string> = {};
+    for (const [group, procedures] of Object.entries(contract)) {
+        if (typeof procedures !== "object" || procedures === null) {
+            continue;
+        }
+        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
+            if (procedureRoute(procedure) === undefined) {
+                continue;
+            }
+            const shape = procedureShape(procedure);
+            if (shape !== undefined) {
+                shapes[`${group}.${name}`] = shape;
+            }
+        }
+    }
+    return shapes;
+};
+
 // Does a concrete request path match this route's template? Segment-wise, with `{param}` matching exactly one
 // segment — the same shape oRPC mounts, so a template can never match a longer or shorter path.
 const pathMatches = (template: string, path: string): boolean => {
@@ -82,3 +192,28 @@ export const routeNameForRequest = (routes: readonly ContractRoute[], method: st
     const upper = method.toUpperCase();
     return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
 };
+
+// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract —
+// `['git','stashApply']` — which is the contract's own name for it, so this is a lookup rather than a match.
+export const routeForProcedure = (routes: readonly ContractRoute[], procedure: readonly string[]): ContractRoute | undefined =>
+    routes.find((route) => route.name === procedure.join("."));
+
+// THE CONCRETE PATH A TYPED CALL WILL CARRY — the route template with every `{param}` replaced by the input
+// field of the same name, which is how the OpenAPI link fills them.
+//
+// This exists so a permission gate can check the string the daemon will actually route on rather than the
+// template it came from. Checking the template would quietly widen every grant: a wildcard glob matches the
+// literal `{repo}` braces just as happily as it matches a repo name, so a manifest that narrowed the grant to
+// one repo would still admit calls for every other — the gate would be comparing two patterns instead of
+// testing a value against one.
+//
+// A param with no matching input field keeps its placeholder. That cannot be reached through the typed client
+// (the contract's input schema requires the field), and leaving the braces in is the safe failure: a glob
+// segment still matches it, a literal segment does not.
+export const requestPathFor = (route: ContractRoute, input: unknown): string => {
+    const fields = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+    return route.path.replace(/\{([^}]+)\}/g, (placeholder, name: string) => {
+        const value = fields[name];
+        return value === undefined ? placeholder : encodeURIComponent(String(value));
+    });
+};

package/src/runtime-state.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { RUNTIME_DOMAIN_BINDINGS, runtimeBoundQueryKeys, staleRuntimeQueryKeys } from "./runtime-state.js";
+
+describe(`staleRuntimeQueryKeys`, () => {
+    it(`maps a pushed domain to the queries it makes stale`, () => {
+        expect(staleRuntimeQueryKeys([`terminals`])).toEqual([[`terminals`]]);
+    });
+
+    it(`dedupes across a batch, because one sweep can move several domains at once`, () => {
+        // The port sampler publishes both: a dev server binding its port is a new port AND the panel above it
+        // turning healthy (panels.ts reads health off the listening sockets). Order is the TABLE's, not the
+        // frame's, so a repeated domain and a reordered frame produce the same list.
+        expect(staleRuntimeQueryKeys([`ports`, `panels`, `ports`])).toEqual([[`panels`], [`apps`], [`ports`]]);
+    });
+
+    it(`ignores a domain this build has never heard of`, () => {
+        // A daemon newer than the browser names domains this table doesn't carry. Refreshing what we understand
+        // and dropping the rest beats throwing away the whole frame.
+        expect(staleRuntimeQueryKeys([`terminals`, `something-later`])).toEqual([[`terminals`]]);
+    });
+
+    it(`names a NESTED key whole, so a domain can refresh one family without its siblings`, () => {
+        // The review is filed under ["git","changes"] and the commit log under ["git","log"]. A landing's drafted
+        // message belongs to the first and has nothing to say about the second, which is the case the single
+        // segment this table used to carry could not express.
+        expect(staleRuntimeQueryKeys([`landings`])).toEqual([[`git`, `changes`]]);
+    });
+
+    it(`asks for nothing when nothing matched`, () => {
+        expect(staleRuntimeQueryKeys([])).toEqual([]);
+    });
+});
+
+describe(`runtimeBoundQueryKeys`, () => {
+    it(`covers every declared domain, since a reconnect is the only recovery for a frame nobody received`, () => {
+        // Compared as joined paths: the assertion is about which keys are covered, and two equal paths are two
+        // different arrays.
+        const joined = (keys: readonly (readonly string[])[]): string[] => [...new Set(keys.map((key) => key.join(`/`)))].toSorted();
+        expect(joined(runtimeBoundQueryKeys())).toEqual(joined(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates)));
+    });
+
+    it(`leaves no domain declaring no keys — a domain nothing renders has no reason to be pushed`, () => {
+        expect(RUNTIME_DOMAIN_BINDINGS.filter((binding) => binding.invalidates.length === 0)).toEqual([]);
+    });
+});

package/src/runtime-state.ts

@@ -0,0 +1,124 @@
+/* WHICH RUNNING THING BACKS WHICH VIEW — the twin of workspace-state.ts, for state that never touches a file.
+ *
+ * That table answers "the agent wrote a file, so which view is stale". This one answers the same question for
+ * the half of the sandbox that has no file to watch: the tmux sessions, the dev-server panels, the listening
+ * sockets, the agent's Chromiums, the children its turns spawn. None of them are on disk, so no
+ * `workspaceChanged` batch can ever mention them — and for want of a push, every one of those views polled.
+ *
+ * The polls were the tell. Six always-on timers (a 10s terminals relist behind THREE mounted surfaces, a 15s
+ * port scan behind the shell rail, a 4s panel relist for as long as any dev server ran) that each asked a
+ * question whose answer is almost always "nothing changed", forever, in every open tab. The daemon knew the real
+ * answer the whole time: it is the process that starts the panel, mints the browser, and opens the session.
+ *
+ * So the daemon says so, on the stream that already carries every other change, and the browser asks only when
+ * told to. The declaration lives HERE for the reason its twin does: the daemon publishes a DOMAIN and the
+ * browser turns it into query keys, and those two facts drift the moment they are written down in two packages.
+ *
+ * A key belongs to whoever queries it — the extension views that render ports and panels ask under the SAME key
+ * as core (api.sandbox.key("ports") is sandboxKey("ports")), so one entry here refreshes both surfaces and an
+ * extension needs no declaration of its own. */
+
+/* One query key as the browser files it, a segment per level — so a binding can name a NESTED key and not only
+ * a top-level one. Most domains here are a single segment and read as they always did; the review is not. Its
+ * key is `["git", "changes"]` (the browser appends the sandbox id, and every open file diff hangs beneath it),
+ * and a domain that could only say `"git"` would drop the commit log along with it — a second read of the graph
+ * to deliver a sentence that has nothing to do with it. */
+export type QueryKeyPath = readonly string[];
+
+export interface RuntimeDomainBinding {
+    // What moved, in the daemon's words. Wire data: it rides the runtimeChanged frame.
+    readonly domain: string;
+    /* The browser query keys this domain's state feeds. Invalidation reaches only queries something is
+     * OBSERVING, so a domain nobody has on screen costs a frame and no request — which is what lets a domain be
+     * pushed eagerly without billing every tab for a view it isn't showing. */
+    readonly invalidates: readonly QueryKeyPath[];
+}
+
+/* Declared `as const` so the domain names survive as literal types (see RuntimeDomain below), then published
+ * under the interface — the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
+const RUNTIME_DOMAINS = [
+    /* Every attachable tmux session: the terminal panel's tab strip, the rail's activity badge, and the work
+     * popover's background-process rows all read this one list. Sampled rather than announced — a pane dies
+     * when its command exits and tmux tells nobody — but sampled ONCE in the daemon, on a connection the
+     * browsers already hold, instead of once per browser per 10s over the tunnel. */
+    { domain: "terminals", invalidates: [["terminals"]] },
+
+    /* A repo's dev server: running, healthy, and the preview URL it answers on. Two independent things move it,
+     * and it needs both — the process manager starting or reaping a session (announced), and the server
+     * actually binding its port some seconds later, which is what flips "starting" to "healthy" (seen by the
+     * port sampler, since panel health is read off the listening sockets — see panels.ts listenersByRepo).
+     *
+     * `apps` rides it because a monorepo's per-app previews ARE managed processes under the same manager
+     * (workspace.routes appsList reads processes.portOf), just listed per repo instead of per repo-root. One
+     * domain, because there is one fact: a dev server the daemon runs started, settled, or died. */
+    { domain: "panels", invalidates: [["panels"], ["apps"]] },
+
+    /* Every listening TCP socket in the sandbox, and which of them are forwarded to a public preview hostname.
+     * The daemon runs no port poller for the ANSWER — attributing a socket to its process walks every /proc fd
+     * table, far too much to do on a timer — so what is sampled is only the LISTEN set out of /proc/net/tcp:
+     * two file reads, enough to know that the answer changed and worth nobody's while to compute until a view
+     * asks. Change detection and payload are deliberately different sizes here. */
+    { domain: "ports", invalidates: [["ports"]] },
+
+    // The agent's Chromiums and the pages each holds open — daemon-held records, minted from the hooks that see
+    // the agent's own browser tool calls, so every change to this roster passes through this process.
+    { domain: "browsers", invalidates: [["browsers"]] },
+
+    // The agents this sandbox's agents started. Daemon-held like the browsers, and the one roster here that
+    // changes while nothing starts or stops: a working child reports tool uses and tokens continuously, which
+    // is why the daemon rate-limits this domain rather than pushing every mutation (see runtime-watch.ts).
+    { domain: "subagents", invalidates: [["subagents"]] },
+
+    /* The post queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation and
+     * refetches itself, but everything after that happens while nobody is touching the page: a held post coming
+     * due, a Discord send landing, a publish turn writing back what went out. Those are the moments the row on
+     * screen stops being true — and this queue is watched precisely because its rows go out in public, so it is
+     * the last place to leave someone reading a stale one. */
+    { domain: "drafts", invalidates: [["drafts"]] },
+
+    /* WHAT A LANDED AGENT'S WORK IS CALLED — the commit message drafted from the diff the moment that work
+     * reaches the main tree (agents/landed-subject.ts), which the review's "From" chip files into the commit box.
+     *
+     * It needs a push of its own because it arrives LATE, and alone. The review refreshes when a turn ends; the
+     * sentence is a model call that STARTS there and answers seconds later, so the refresh the landing itself
+     * causes is always too early to carry it. Nothing followed. The message then sat in the daemon, correct and
+     * unread, until some unrelated write happened to refresh the panel again — and a chip clicked in that window
+     * filed nothing at all, which is indistinguishable from the feature having been removed.
+     *
+     * Neither a file nor a ref, so this is the only feed that could carry it: the entry holding it lives on
+     * /history, outside the watched tree, and no ref moves when a sentence is written.
+     *
+     * Being in this table also puts the review on the reconnect re-ask (runtimeBoundQueryKeys), and that is the
+     * half of the fix nothing else covers: a publish with no browser connected is dropped, so a landing drafted
+     * while the app was closed or the tunnel was down would otherwise stay invisible for as long as the panel's
+     * snapshot survived — which, at staleTime Infinity, is until something unrelated moved. It costs one review
+     * read per (re)connect, against a chip that files nothing for the rest of the session. */
+    { domain: "landings", invalidates: [["git", "changes"]] },
+] as const satisfies readonly RuntimeDomainBinding[];
+
+export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;
+
+/* Every domain this table declares, as a type — so a publish site names one of THESE and nothing else, and a
+ * renamed domain is a compile error in the daemon rather than a frame the browser silently routes nowhere. */
+export type RuntimeDomain = (typeof RUNTIME_DOMAINS)[number]["domain"];
+
+/* Distinct key paths, in table order — two domains in one frame routinely feed the same view, and a Set cannot
+ * see that because each path is its own array. Compared by their segments joined, which is exact: a segment is
+ * one identifier from this file, never a caller's string, so there is no separator to collide on. */
+const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...new Map(keys.map((key) => [key.join(`/`), key])).values()];
+
+/* The query keys a pushed set of domains makes stale, deduped and stable — the browser's `/events` handler
+ * calls this, exactly as it calls staleQueryKeys for a path batch. Kept here rather than in the web so the rule
+ * is unit-testable without a query client, and so the daemon can assert against the same table.
+ *
+ * An unknown domain contributes nothing rather than throwing: a daemon newer than the browser may name a domain
+ * this build has never heard of, and the honest response to that is to refresh what we do understand. */
+export const staleRuntimeQueryKeys = (domains: readonly string[]): readonly QueryKeyPath[] =>
+    dedupe(RUNTIME_DOMAIN_BINDINGS.filter((binding) => domains.includes(binding.domain)).flatMap((binding) => binding.invalidates));
+
+/* Every query key any runtime domain feeds — what a NEW /events connection re-asks wholesale, for precisely the
+ * reason fileBoundQueryKeys exists: this push is these views' ONLY live feed, and a frame produced while the
+ * stream was down is a frame nobody will resend. A panel that finished starting, a session that exited, a port
+ * that closed while the browser was away would otherwise sit wrong until the next unrelated change. Re-asking
+ * on connect bounds that at one cheap read per key, which is what lets these views go entirely unpolled. */
+export const runtimeBoundQueryKeys = (): readonly QueryKeyPath[] => dedupe(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates));

package/src/schemas.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { CapabilitiesListSchema, DeployOverviewResponseSchema, SandboxSettingsSchema } from "./schemas.js";
+import { CapabilitiesListSchema, IpsecVpnConfigSchema, SandboxSettingsSchema } from "./schemas.js";
 
 /* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
  * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
@@ -34,7 +34,7 @@ test("a payload from a build that predates a toggle parses, with the new toggle
  * failed on every field the product added. */
 test("no field is required — a workspace that has never written settings parses", () => {
     const defaults = SandboxSettingsSchema.parse({});
-    expect(Object.keys(defaults).sort()).toEqual(Object.keys(SandboxSettingsSchema.shape).sort());
+    expect(Object.keys(defaults).toSorted()).toEqual(Object.keys(SandboxSettingsSchema.shape).toSorted());
 });
 
 test("a key of the wrong type is still a parse failure — tolerance is for absence, not for garbage", () => {
@@ -53,34 +53,21 @@ test("a capability list from a daemon that predates recommendations parses, with
     expect(CapabilitiesListSchema.parse(older).recommendations).toEqual([]);
 });
 
-/* The deployments board crosses the same seam and learned it the hard way. `repos` (workspace repo → Komodo
- * stack links) shipped REQUIRED, and the first sandbox whose daemon predated it rendered
- * `Invalid input: expected array, received undefined at repos` instead of the board — a dead page, on the one
- * surface whose job is to say whether production is up, to hide a band of suggestions.
- *
- * `viewer` is the deliberate contrast: also added later, also absent from an older daemon, but OPTIONAL rather
- * than defaulted, because its absence is information. The empty state tells "the key can see nothing" apart
- * from "we could not tell", and defaulting it would have collapsed the two. */
+/* An ipsec tunnel's routed networks decide whether it is split or full, and both ends of that are load-bearing:
+ * a value the daemon splices into rightsubnet unchecked reaches charon as a config it refuses WHOLESALE (every
+ * tunnel on the sandbox stops loading, and the error names the file rather than the field), while a default that
+ * stopped being 0.0.0.0/0 would silently narrow tunnels that reach those networks today. */
+const ipsec = { provider: "ipsec", server: "gw.example.com", presharedKey: "group-secret" };
 
-test("an overview from a daemon that predates repo links parses, with no links rather than no board", () => {
-    const older = { komodoUrl: "https://komodo.example.com", reachable: true, resources: [], servers: [], alerts: [] };
-    const parsed = DeployOverviewResponseSchema.parse(older);
-    expect(parsed.repos).toEqual([]);
-    // Absent, NOT defaulted: the empty state reads this to avoid claiming an empty Komodo it cannot vouch for.
-    expect(parsed.viewer).toBeUndefined();
+test("an ipsec tunnel is a full tunnel unless it says otherwise", () => {
+    expect(IpsecVpnConfigSchema.parse(ipsec).routedNetworks).toBe("0.0.0.0/0");
 });
 
-test("a board that did carry links keeps them, and garbage in them is still a failure", () => {
-    const current = {
-        komodoUrl: "https://komodo.example.com",
-        reachable: true,
-        viewer: { username: "intentic", admin: false },
-        repos: [{ repo: "app", projectName: "app", composePath: "app/compose.yaml", suggestions: ["app-prod"] }],
-        resources: [],
-        servers: [],
-        alerts: [],
-    };
-    expect(DeployOverviewResponseSchema.parse(current).repos[0]?.suggestions).toEqual(["app-prod"]);
-    // Tolerance is for absence, not for the wrong shape — a `repos` that is present and wrong is real drift.
-    expect(DeployOverviewResponseSchema.safeParse({ ...current, repos: "none" }).success).toBe(false);
+test("routed networks take a CIDR list and reject what charon could not load", () => {
+    expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "10.0.0.0/8, 192.168.0.0/16" }).routedNetworks).toBe("10.0.0.0/8, 192.168.0.0/16");
+    expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "fd00::/8" }).routedNetworks).toBe("fd00::/8");
+    // A bare host address is the easy mistake — strongSwan wants the prefix, and the message says so.
+    expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "192.168.0.168" }).success).toBe(false);
+    expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "10.0.0.0/8,nonsense" }).success).toBe(false);
+    expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "" }).success).toBe(false);
 });