@intentic/sandbox-contract 1.157.0 → 1.159.0

package/src/model-order.test.ts

@@ -0,0 +1,137 @@
+import { expect, test } from "vitest";
+import { compareModelIds, compareUnrankedModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
+
+/* The order every provider's catalog is served and browsed in. The rule exists because only Anthropic publishes
+ * a ranking: the OpenAI-compatible endpoints behind Codex, Gemini, Kimi and Grok hand back a SET, and taking
+ * their registry order for a preference is what opened the Codex group on GPT 5.4 Mini and started fresh Codex
+ * conversations on whichever id sorted first. */
+
+// A Codex catalog exactly as an OpenAI-compatible /v1/models hands it over: alphabetical, i.e. meaningless.
+const CODEX = ["gpt-5.1-codex", "gpt-5.4-mini", "gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra"];
+
+test("ranks the frontier line above the cheap one and the newest release above its predecessors", () => {
+    // The base line (no tier word) leads, newest first; the mini rung sinks under all of it regardless of how
+    // recently it shipped — which is the whole decision a user makes in this list.
+    expect(CODEX.toSorted(compareModelIds)).toEqual(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.5", "gpt-5.1-codex", "gpt-5.4-mini"]);
+});
+
+test("lands the same models at the head and the tail whichever order the endpoint listed them in", () => {
+    // Arrival order survives only as the tiebreak between two ids the rule ranks equally (the 5.6 siblings), so
+    // an alphabetical registry and a reversed one can no longer disagree about which model the group opens on.
+    for (const arrival of [CODEX.toSorted(), CODEX.toReversed()]) {
+        const ordered = arrival.toSorted(compareModelIds);
+
+        expect(ordered.slice(0, 2).toSorted()).toEqual(["gpt-5.6-sol", "gpt-5.6-terra"]);
+        expect(ordered.at(-1)).toBe("gpt-5.4-mini");
+    }
+});
+
+test("an unranked catalog settles its own ties, so the SAME sibling opens the group on every refresh", () => {
+    // The measured failure: the translator's /v1/models hands sol/terra/luna back in a different order per
+    // request, and the rule above ranks all three equally — same tier, same 5.6 release. Under plain stability
+    // the catalog's head (i.e. the model a fresh conversation starts on) followed that reshuffling.
+    const arrivals = [
+        ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"],
+        ["gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.6-sol"],
+        ["gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"],
+    ];
+    const heads = arrivals.map((arrival) => arrival.toSorted(compareUnrankedModelIds)[0]);
+
+    expect(new Set(heads).size).toBe(1);
+    // Same rule, so ranking still outranks the tiebreak: the mini rung stays at the tail, under every sibling.
+    expect(["gpt-5.4-mini", ...arrivals[0]!].toSorted(compareUnrankedModelIds).at(-1)).toBe("gpt-5.4-mini");
+});
+
+test("leaves a RANKED catalog's ties alone — the id tiebreak is for sets, and Anthropic publishes an opinion", () => {
+    // compareUnrankedModelIds would seat claude-fable-5 ahead of claude-opus-5 on the id alone. Anthropic's
+    // catalog arrives newest-first, so that order is a fact about the provider, not a leftover to be broken.
+    expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
+    expect(["claude-opus-5", "claude-fable-5"].toSorted(compareUnrankedModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
+});
+
+test("reads each vendor's tier vocabulary, not just Claude's", () => {
+    expect(["gemini-3-flash", "gemini-3-flash-lite", "gemini-3-pro"].toSorted(compareModelIds)).toEqual([
+        "gemini-3-pro",
+        "gemini-3-flash",
+        "gemini-3-flash-lite",
+    ]);
+    expect(["grok-4-fast", "grok-code-fast-1", "grok-4", "grok-3"].toSorted(compareModelIds)).toEqual([
+        "grok-4",
+        "grok-3",
+        "grok-4-fast",
+        "grok-code-fast-1",
+    ]);
+    expect(["kimi-k2-turbo-preview", "kimi-k2-0711-preview", "kimi-k2-mini"].toSorted(compareModelIds)).toEqual([
+        "kimi-k2-0711-preview",
+        "kimi-k2-turbo-preview",
+        "kimi-k2-mini",
+    ]);
+});
+
+test("the rightmost tier word wins, because tier words compose", () => {
+    // flash-lite is the cheap end of Flash, codex-max the frontier end of Codex — reading the leftmost word
+    // instead would file both under the tier they modify.
+    expect(tierRankOf(familyOf("gemini-3-flash-lite"))).toBe(tierRankOf("lite"));
+    expect(tierRankOf(familyOf("gpt-5.1-codex-max"))).toBe(tierRankOf("max"));
+});
+
+test("leads with a family carrying no tier word at all, so a brand-new flagship is never buried by its novelty", () => {
+    // The precise inverse of the ranking this replaced, which sank unrecognized ids BELOW the everyday tier.
+    expect(["claude-sonnet-5", "claude-mythos-1", "claude-opus-5"].toSorted(compareModelIds)[0]).toBe("claude-mythos-1");
+});
+
+test("files a re-served open-weights model on the cheap rung, not at the head of the catalog it visits", () => {
+    // Google's channel vends gpt-oss beside Gemini and Claude. It carries no tier word of its own, so the
+    // lead-the-unknown rule would open that whole section on it — above Opus.
+    expect(["gpt-oss-120b-medium", "claude-opus-4-6-thinking", "gemini-pro-agent"].toSorted(compareModelIds)).toEqual([
+        "claude-opus-4-6-thinking",
+        "gemini-pro-agent",
+        "gpt-oss-120b-medium",
+    ]);
+});
+
+test("keeps the arrival order between ids the rule cannot separate — Anthropic's catalog IS ranked", () => {
+    // Same tier, same version: nothing here outranks the order the provider itself reported.
+    expect(["claude-opus-5", "claude-fable-5"].toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-fable-5"]);
+    expect(["claude-fable-5", "claude-opus-5"].toSorted(compareModelIds)).toEqual(["claude-fable-5", "claude-opus-5"]);
+});
+
+test("groups every version of a family under one key, whatever shape its id takes", () => {
+    expect(familyOf("claude-opus-4-8")).toBe(familyOf("claude-opus-5"));
+    expect(familyOf("claude-haiku-4-5-20251001")).toBe(familyOf("claude-haiku-4-5"));
+    expect(familyOf("gpt-5.1")).toBe(familyOf("gpt-5"));
+    // Distinct lines stay distinct: a variant word is part of the family, not a version of the base one.
+    expect(familyOf("gpt-5.1-codex")).not.toBe(familyOf("gpt-5.1"));
+});
+
+test("stands an id with nothing but numbers (and an ACP row's empty one) as its own family", () => {
+    expect(familyOf("4-5")).toBe("4-5");
+    expect(familyOf("")).toBe("");
+});
+
+test("holds date stamps apart from version components, or a dated build outranks the point release after it", () => {
+    // The failure this prevents: claude-opus-4-1-20250805 (Opus 4.1) read as (4,1,20250805) loses to
+    // claude-opus-4-20250514 (Opus 4.0) read as (4,20250514) — the older model, by six digits.
+    expect(releaseOf("claude-opus-4-1-20250805")).toEqual({ version: [4, 1], date: 20250805 });
+    expect(["claude-opus-4-20250514", "claude-opus-4-1-20250805"].toSorted(compareModelIds)).toEqual([
+        "claude-opus-4-1-20250805",
+        "claude-opus-4-20250514",
+    ]);
+});
+
+test("breaks a version tie by date stamp, so two builds of one release still order", () => {
+    expect(["claude-haiku-4-5-20251001", "claude-haiku-4-5-20260210"].toSorted(compareModelIds)).toEqual([
+        "claude-haiku-4-5-20260210",
+        "claude-haiku-4-5-20251001",
+    ]);
+});
+
+test("reads a longer version as the newer one, so 5.1 outranks 5", () => {
+    expect(["gpt-5", "gpt-5.1"].toSorted(compareModelIds)).toEqual(["gpt-5.1", "gpt-5"]);
+});
+
+test("sorts an unversioned rolling alias under the releases that name their version", () => {
+    // `kimi-latest` claims no release; guessing one for it would seat it above models that do say what they are.
+    expect(releaseOf("kimi-latest").version).toEqual([]);
+    expect(["kimi-latest", "kimi-k2-0711-preview"].toSorted(compareModelIds)).toEqual(["kimi-k2-0711-preview", "kimi-latest"]);
+});

package/src/model-order.ts

@@ -0,0 +1,140 @@
+/* HOW A MODEL CATALOG IS ORDERED — one rule for every provider, because only one provider publishes an order
+ * worth keeping.
+ *
+ * Anthropic's REST /v1/models answers newest-first: that IS a provider opinion, and Claude's catalog rides it
+ * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models — Codex and
+ * Gemini via the bundled translator, Kimi via Moonshot — or out of xAI's "Did you mean" rejection, and those
+ * endpoints publish a SET, not a ranking: they hand the ids back in whatever order their registry iterates,
+ * which in practice is alphabetical. Reading that as a preference is what put "GPT 5.4 Mini" at the head of the
+ * Codex group with GPT 5.6 below it, and what made a fresh Codex conversation start on whichever id happened to
+ * sort first — models[0] is the provider default.
+ *
+ * So for those providers the order is DERIVED from the id, out of the only two facts an id reliably carries:
+ * which TIER the model is (the adjective) and which RELEASE it is (the numbers). Both are provider-agnostic —
+ * every vendor names its models the same way — which is what lets the daemon's four catalog services and the
+ * web's picker share one rule instead of each inventing a local one. */
+
+// A version-ish segment: digits and dots, optionally v-prefixed (`4`, `5.1`, `v2`, `20251001`). Everything else
+// is a NAME segment and belongs to the family — which is what makes the split below exhaustive.
+const VERSION_SEGMENT = /^v?[\d.]+$/;
+
+// A date stamp rather than a version component: six digits or more (20251001, 250514). The distinction is not
+// cosmetic — claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
+// with the stamps held apart, and as (4,1,20250805) vs (4,20250514) — the OLDER model winning — without.
+const DATE_SEGMENT = /^\d{6,}$/;
+
+const segmentsOf = (id: string): string[] => id.split(/[-_]/);
+
+// A model's FAMILY — its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land
+// together (as do gpt-5.1/gpt-5, and claude-haiku-4-5-20251001 with its date suffix). Derived, never listed: a
+// family that ships tomorrow groups itself. The id is the stable key here — labels get renamed, ids don't.
+export const familyOf = (id: string): string => {
+    const stem = segmentsOf(id)
+        .filter((segment) => !VERSION_SEGMENT.test(segment))
+        .join("-");
+    // An all-numeric id (and an ACP row's empty one) has no stem to speak of; it stands as its own family.
+    return stem === "" ? id : stem;
+};
+
+export interface ModelRelease {
+    // The version components in id order: gpt-5.1 → [5, 1], claude-opus-4-8 → [4, 8]. EMPTY for an unversioned
+    // id (kimi-latest, gemini-pro-agent), which therefore reads as the oldest of its tier: a rolling alias names
+    // no release, and inventing one for it would outrank the models that do name theirs.
+    readonly version: readonly number[];
+    // The id's date stamp, 0 for none — the tiebreak between two builds of the SAME version.
+    readonly date: number;
+}
+
+export const releaseOf = (id: string): ModelRelease => {
+    const numeric = segmentsOf(id)
+        .filter((segment) => VERSION_SEGMENT.test(segment))
+        .map((segment) => segment.replace(/^v/, ""));
+    const stamps = numeric.filter((segment) => DATE_SEGMENT.test(segment)).map(Number);
+    return {
+        version: numeric
+            .filter((segment) => !DATE_SEGMENT.test(segment))
+            .flatMap((segment) => segment.split(".").map(Number))
+            .filter((component) => Number.isFinite(component)),
+        date: Math.max(0, ...stamps),
+    };
+};
+
+// Newest first. A missing component reads as -1, so gpt-5 sorts under gpt-5.1 and an unversioned id sorts under
+// every versioned one; the date stamp breaks what is left.
+const compareRelease = (left: ModelRelease, right: ModelRelease): number => {
+    for (let index = 0; index < Math.max(left.version.length, right.version.length); index += 1) {
+        const diff = (right.version[index] ?? -1) - (left.version[index] ?? -1);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return right.date - left.date;
+};
+
+/* THE ONE CURATED FACT in this file, and the only one the providers publish nowhere the app can read: which tier
+ * is the frontier and which is the cheap one. It ranks FAMILIES, never models, and it is a vocabulary of tier
+ * ADJECTIVES rather than a table of ids — that scoping is the whole point, because a per-model ranking table
+ * failed here once already. The words are the ones every vendor reaches for, so a release that ships tomorrow
+ * ranks itself as long as it is named like its predecessors, and a release named some other way ranks as unknown.
+ *
+ * An UNKNOWN family LEADS rather than sinks, and that direction is the point: the ranking this replaced sank
+ * unrecognized ids to a floor below the everyday tier, so a brand-new flagship sorted beneath the model it
+ * replaced. An id carrying no tier word at all is the provider's BASE line (gpt-5.6, grok-4, kimi-k2) — which is
+ * exactly the line a user reaches for — and a family nobody here has heard of is far likelier to be the next
+ * flagship than the next budget tier. Being wrong costs one row's position; being wrong the other way hides a
+ * launch. */
+const TIER_RANK: Readonly<Record<string, number>> = {
+    // Frontier: the tier a vendor ships last and charges most for.
+    opus: 0,
+    fable: 0,
+    pro: 0,
+    max: 0,
+    ultra: 0,
+    heavy: 0,
+    // Everyday: the workhorse a step below the frontier.
+    sonnet: 1,
+    flash: 1,
+    mini: 1,
+    // Efficient: the cheap/fast end, the rung whose whole purpose is to cost less than the one above it.
+    haiku: 2,
+    // An open-weights model a vendor re-serves beside its own (gpt-oss-120b on Google's channel) is that rung by
+    // construction: it is there to be the free/cheap option next to the frontier line, never the flagship. Without
+    // it the id carries no tier word at all and would LEAD the section it sits in.
+    oss: 2,
+    lite: 2,
+    nano: 2,
+    fast: 2,
+    small: 2,
+};
+
+const UNRANKED = -1;
+
+// The LAST recognized word wins, because tier words compose and the rightmost is the most specific one:
+// gemini-flash-lite is the cheap end of Flash, gpt-codex-max the frontier end of Codex.
+export const tierRankOf = (family: string): number => {
+    let rank = UNRANKED;
+    for (const segment of family.split("-")) {
+        const found = TIER_RANK[segment];
+        if (found !== undefined) {
+            rank = found;
+        }
+    }
+    return rank;
+};
+
+// The canonical order of two model ids: tier first, then release. Hand it straight to Array#toSorted — that sort
+// is stable, so two ids this rule cannot separate keep the order they arrived in (for Claude, the provider's own).
+export const compareModelIds = (left: string, right: string): number =>
+    tierRankOf(familyOf(left)) - tierRankOf(familyOf(right)) || compareRelease(releaseOf(left), releaseOf(right));
+
+/* The order for a catalog its endpoint published as a SET — Codex, Gemini, Kimi and Grok, i.e. everything but
+ * Anthropic's ranked list. Falling back on arrival order is what the rule above does with a tie, and for a RANKED
+ * catalog that is exactly right: the tie is the provider's own opinion, so claude-opus-5 stays ahead of
+ * claude-fable-5. For a set there is no opinion to keep, and the header of this file assumed the leftover order
+ * was at least alphabetical — it is not. A subscription vending sol/terra/luna (same tier, same 5.6 release, three
+ * ids this rule cannot separate) hands its rows back in whatever order its registry iterated THIS request, so the
+ * tie decided which model a fresh conversation opened on AND flipped between catalog refreshes.
+ *
+ * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary — but it is the same
+ * arbitrary answer every refresh, which is the property `default` actually needs. */
+export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);

package/src/path-refs.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import { rankRefCandidates, referenceTails } from "./path-refs.js";
+
+describe("referenceTails", () => {
+    test("offers the reference itself first, then shorter tails of it", () => {
+        expect(referenceTails("_apps/web/src/foo.ts", "/work")).toEqual(["_apps/web/src/foo.ts", "web/src/foo.ts", "src/foo.ts"]);
+    });
+
+    test("anchors an absolute path under the workspace root", () => {
+        expect(referenceTails("/work/_apps/foo.ts", "/work")[0]).toBe("_apps/foo.ts");
+    });
+
+    test("strips an isolated turn's worktree lead by dropping segments", () => {
+        // The worktree mirrors the workspace layout below /history/worktrees/<id>, so the real path is a tail.
+        expect(referenceTails("/history/worktrees/agent-7/_apps/foo.ts", "/work")).toContain("_apps/foo.ts");
+    });
+
+    test("never cuts down to a bare filename — one `index.ts` is as good as another", () => {
+        expect(referenceTails("a/b/index.ts", "/work").at(-1)).toBe("b/index.ts");
+        expect(referenceTails("index.ts", "/work")).toEqual([]);
+    });
+
+    test("normalizes a ./ lead and windows separators", () => {
+        expect(referenceTails("./src/foo.ts", "/work")).toEqual(["src/foo.ts"]);
+        expect(referenceTails("src\\foo.ts", "/work")).toEqual(["src/foo.ts"]);
+    });
+});
+
+describe("rankRefCandidates", () => {
+    test("keeps only matches that end in the tail on a segment boundary", () => {
+        // `mypages/` merely ends with the same characters — the daemon's glob can't tell, so this must.
+        expect(rankRefCandidates("pages/Foo.vue", ["app/mypages/Foo.vue", "app/pages/Foo.vue"])).toEqual(["app/pages/Foo.vue"]);
+    });
+
+    test("ranks the shallowest match first — the app's file, not a copy in a fixture tree", () => {
+        expect(rankRefCandidates("pages/Foo.vue", ["a/b/c/pages/Foo.vue", "a/pages/Foo.vue"])).toEqual(["a/pages/Foo.vue", "a/b/c/pages/Foo.vue"]);
+    });
+
+    test("matches the tail as a whole path too", () => {
+        expect(rankRefCandidates("src/foo.ts", ["src/foo.ts", "vendor/src/foo.ts"])).toEqual(["src/foo.ts", "vendor/src/foo.ts"]);
+    });
+});

package/src/path-refs.ts

@@ -0,0 +1,43 @@
+/* Which file a NAMED reference means. A path written in prose is only loosely anchored to the workspace: an
+ * agent that has been working in `_apps/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
+ * isolated worktree prints `/history/worktrees/<id>/_apps/web/src/foo.ts` — neither is the workspace-relative
+ * path the file routes speak, but both END in it.
+ *
+ * So a reference is resolved by matching progressively shorter TAILS of it against the real tree. The rules
+ * live here, in the contract package, because both sides run them: the browser first against the workspace
+ * tree it already has cached, then the daemon (/workspace/resolve) against the iq engine's full sweep, which
+ * sees the files the capped tree walk left out. Two matchers that disagreed would make a link's destination
+ * depend on which one answered. */
+
+// How many leading segments a reference may carry that the workspace doesn't (the `/history/worktrees/<id>/`
+// lead of a worktree path is 3; a foreign absolute root is rarely deeper).
+const MAX_DROPS = 6;
+// A tail is never cut down to a bare filename: `index.ts` names a hundred files in a monorepo and picking one
+// at random is worse than not linking. The link grammar never emits a slash-less reference either.
+const MIN_SEGMENTS = 2;
+// Enough candidates for a picker; a reference matching more than this is ambiguous by any measure.
+export const MAX_REF_CANDIDATES = 10;
+
+// The tails worth matching, longest (most specific) first. `root` is the container workspace root: a path
+// under it is already the answer minus that lead, and a path under any OTHER absolute root (a worktree) still
+// mirrors the layout below its own lead, which the successive drops strip.
+export const referenceTails = (raw: string, root: string): readonly string[] => {
+    const normalized = raw.replaceAll(`\\`, `/`).replace(/^\.\//, ``);
+    const anchored = normalized.startsWith(`${root}/`) ? normalized.slice(root.length + 1) : normalized.replace(/^\/+/, ``);
+    const segments = anchored.split(`/`).filter((segment) => segment !== `` && segment !== `.`);
+    const tails: string[] = [];
+    for (let drop = 0; drop <= MAX_DROPS && segments.length - drop >= MIN_SEGMENTS; drop++) {
+        tails.push(segments.slice(drop).join(`/`));
+    }
+    return tails;
+};
+
+// The paths that genuinely END in `tail` on a segment boundary, best first — the shared ranking both matchers
+// return their candidates in. Shallowest wins: `pages/Foo.vue` means the app's page, not the copy six
+// directories down in a fixture tree. (The daemon's glob is anchored only at the string level — `**/pages/x.vue`
+// also matches `mypages/x.vue` — so the boundary is enforced here rather than by the pattern.)
+export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
+    paths
+        .filter((path) => path === tail || path.endsWith(`/${tail}`))
+        .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
+        .slice(0, MAX_REF_CANDIDATES);

package/src/routes.test.ts

@@ -0,0 +1,83 @@
+import { oc } from "@orpc/contract";
+import { describe, expect, it } from "vitest";
+import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTES, sandboxRouteName } from "./index.js";
+import { contractRoutes, routeNameForRequest } from "./routes.js";
+
+const fixture = {
+    vpn: {
+        list: oc.route({ method: "GET", path: "/vpn" }),
+        connect: oc.route({ method: "POST", path: "/vpn/{id}/connect" }),
+    },
+    system: {
+        killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }),
+    },
+};
+
+describe(`contractRoutes`, () => {
+    it(`names every procedure <group>.<route>, sorted`, () => {
+        expect(contractRoutes(fixture).map((route) => route.name)).toEqual([`system.killTerminal`, `vpn.connect`, `vpn.list`]);
+    });
+
+    it(`carries the wire method and path template`, () => {
+        expect(contractRoutes(fixture).find((route) => route.name === `vpn.connect`)).toEqual({
+            name: `vpn.connect`,
+            method: `POST`,
+            path: `/vpn/{id}/connect`,
+        });
+    });
+
+    it(`ignores non-procedure members rather than inventing routes for them`, () => {
+        expect(contractRoutes({ vpn: { list: fixture.vpn.list, NOT_A_ROUTE: { hello: true } } }).map((r) => r.name)).toEqual([`vpn.list`]);
+    });
+});
+
+describe(`routeNameForRequest`, () => {
+    const routes = contractRoutes(fixture);
+
+    it(`matches a literal path`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/vpn`)).toBe(`vpn.list`);
+    });
+
+    it(`matches a templated segment`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn/corp-gw/connect`)).toBe(`vpn.connect`);
+        expect(routeNameForRequest(routes, `DELETE`, `/system/terminals/web-1`)).toBe(`system.killTerminal`);
+    });
+
+    it(`strips the query string before matching`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/vpn?refresh=1`)).toBe(`vpn.list`);
+    });
+
+    it(`is method-sensitive`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn`)).toBeUndefined();
+    });
+
+    it(`never matches a longer or shorter path than the template`, () => {
+        expect(routeNameForRequest(routes, `POST`, `/vpn/corp-gw/connect/extra`)).toBeUndefined();
+        expect(routeNameForRequest(routes, `POST`, `/vpn/connect`)).toBeUndefined();
+    });
+
+    it(`does not let an empty segment stand in for a param`, () => {
+        expect(routeNameForRequest(routes, `DELETE`, `/system/terminals/`)).toBeUndefined();
+    });
+
+    it(`returns undefined for the daemon's hand-written non-contract routes`, () => {
+        expect(routeNameForRequest(routes, `GET`, `/health`)).toBeUndefined();
+    });
+});
+
+describe(`the real sandbox contract`, () => {
+    it(`derives a route table with no duplicate names`, () => {
+        expect(SANDBOX_ROUTE_NAMES.length).toBe(SANDBOX_ROUTES.length);
+        expect(new Set(SANDBOX_ROUTE_NAMES).size).toBe(SANDBOX_ROUTE_NAMES.length);
+    });
+
+    it(`covers every oc.route in the contract`, () => {
+        // Guards the walk against a future contract nesting deeper than group → procedure, which would
+        // silently advertise fewer routes than the daemon serves.
+        expect(SANDBOX_ROUTES.length).toBeGreaterThan(100);
+    });
+
+    it(`resolves a known concrete request back to its contract name`, () => {
+        expect(sandboxRouteName(`GET`, `/vpn`)).toBe(`vpn.list`);
+    });
+});

package/src/routes.ts

@@ -0,0 +1,84 @@
+/* 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
+ * normal and neither should force an update.
+ *
+ * What must not happen is the failure being SILENT. A route the daemon predates answers 404, which the browser
+ * has no way to tell apart from "you asked for a file that isn't there" — so a missing feature reads as a
+ * broken one, and diagnosing it costs an hour of "did the image rebuild?".
+ *
+ * So the daemon ADVERTISES the routes it implements (the /events hello frame) and the browser compares that
+ * against the contract it was itself built with. Everything present on both sides works exactly as before;
+ * anything the daemon lacks is a KNOWN, NAMED gap the UI can gate a feature on or explain in an error, instead
+ * of a mystery 404. Old daemon + new browser stays fully supported — it just stops being confusing.
+ *
+ * Route names are `<group>.<route>` (`vpn.list`, `kimi.models`), derived from the contract object both sides
+ * import. Nothing is generated and nothing is hand-maintained: adding a route to the contract adds it here.
+ *
+ * Everything here is a pure function of a contract passed in — index.ts binds them to `sandboxContract` once it
+ * is assembled, which is what keeps this module out of an import cycle with it. */
+
+// The shape we read off an oRPC contract procedure. `~orpc.route` is the contract metadata oRPC attaches to
+// every `oc.route(...)` procedure; we only need the wire method + path, so this is deliberately structural
+// rather than an import of oRPC's internal types (which are not part of its public surface).
+interface ContractProcedureLike {
+    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string } };
+}
+
+const procedureRoute = (value: unknown): { method: string; path: string } | undefined => {
+    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
+        return undefined;
+    }
+    const { route } = (value as ContractProcedureLike)["~orpc"];
+    if (route?.method === undefined || route.path === undefined) {
+        return undefined;
+    }
+    return { method: route.method, path: route.path };
+};
+
+// One advertised route: its contract name plus the wire shape, so a concrete request path can be matched back
+// to the name it came from (see routeNameForRequest).
+export interface ContractRoute {
+    readonly name: string;
+    readonly method: string;
+    // The oRPC path template, with `{param}` placeholders — e.g. `/system/terminals/{name}`.
+    readonly path: string;
+}
+
+// Walk a contract object (two levels: group → procedure) into its flat route list, sorted by name so the
+// advertised array is stable and diffable.
+export const contractRoutes = (contract: Record<string, unknown>): ContractRoute[] => {
+    const routes: ContractRoute[] = [];
+    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>)) {
+            const route = procedureRoute(procedure);
+            if (route !== undefined) {
+                routes.push({ name: `${group}.${name}`, method: route.method, path: route.path });
+            }
+        }
+    }
+    return routes.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+// 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 => {
+    const wanted = template.split("/");
+    const actual = path.split("/");
+    if (wanted.length !== actual.length) {
+        return false;
+    }
+    return wanted.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}") ? actual[index] !== "" : segment === actual[index]));
+};
+
+// The contract route a concrete request belongs to, or undefined when the path is not a contract route at all
+// (the daemon also serves hand-written Hono routes like /health and /workspace/raw — those are never gated).
+// The query string is stripped first; callers pass whatever they handed to fetch.
+export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
+    const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
+    const upper = method.toUpperCase();
+    return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
+};