@intentic/sandbox-contract 1.158.0 → 1.160.0

package/src/model-order.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { compareModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
+import { compareCheapestFirst, 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
@@ -26,6 +26,29 @@ test("lands the same models at the head and the tail whichever order the endpoin
     }
 });
 
+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",
@@ -57,6 +80,16 @@ test("leads with a family carrying no tier word at all, so a brand-new flagship
     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"]);
@@ -102,3 +135,42 @@ test("sorts an unversioned rolling alias under the releases that name their vers
     expect(releaseOf("kimi-latest").version).toEqual([]);
     expect(["kimi-latest", "kimi-k2-0711-preview"].toSorted(compareModelIds)).toEqual(["kimi-k2-0711-preview", "kimi-latest"]);
 });
+
+// --- the cheap end (compareCheapestFirst) ---------------------------------------------------------------
+// What the quick model behind a one-click helper resolves against: the same tier scale, read for the weakest
+// row instead of the strongest.
+
+test("opens on the efficient rung and buries the frontier one — the exact inverse of the picker's order", () => {
+    const claude = ["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"];
+
+    expect(claude.toSorted(compareCheapestFirst)).toEqual(["claude-haiku-4-5-20251001", "claude-sonnet-5", "claude-opus-5"]);
+    expect(claude.toSorted(compareModelIds)).toEqual(["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001"]);
+});
+
+test("keeps an UNRANKED family off the cheap end, where a plain reversal would have seated it first", () => {
+    // The whole reason this is not `-compareModelIds`. An id with no tier word is the provider's base line, and
+    // an unheard-of family is likelier the next flagship than the next budget tier — so both orders agree it is
+    // not the efficient rung, and a helper never spends frontier money on a commit message.
+    expect(["gpt-5.6", "gpt-5.4-mini"].toSorted(compareCheapestFirst)).toEqual(["gpt-5.4-mini", "gpt-5.6"]);
+    expect(["claude-mythos-1", "claude-haiku-4-5", "claude-sonnet-5"].toSorted(compareCheapestFirst).at(-1)).toBe("claude-mythos-1");
+});
+
+test("takes the NEWEST build of the cheap rung, not merely any of them", () => {
+    // Within one tier the release rule runs unchanged: cheap is a tier, not an excuse to serve a stale model.
+    expect(["claude-haiku-4-5-20251001", "claude-haiku-4-5-20260210"].toSorted(compareCheapestFirst)[0]).toBe("claude-haiku-4-5-20260210");
+    expect(["gemini-3-flash-lite", "gemini-2-flash-lite"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash-lite");
+});
+
+test("finds each vendor's own cheap rung, including a re-served open-weights row", () => {
+    expect(["gemini-3-pro", "gemini-3-flash", "gemini-3-flash-lite"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash-lite");
+    // Google's channel vends gpt-oss beside Gemini's own line; it is there to be the cheap option, and `oss`
+    // is what says so — without that word the id carries no tier at all and would sink to the bottom.
+    expect(["claude-opus-4-6-thinking", "gpt-oss-120b-medium"].toSorted(compareCheapestFirst)[0]).toBe("gpt-oss-120b-medium");
+    expect(["grok-4", "grok-4-fast"].toSorted(compareCheapestFirst)[0]).toBe("grok-4-fast");
+});
+
+test("falls back on the newest release for a catalog that publishes no cheap tier at all", () => {
+    // Kimi names no tier word anywhere, so every row is UNRANKED and the tier term cancels. Serving the newest
+    // of what it does publish is the honest answer — there is no cheaper rung to find.
+    expect(["kimi-k2-0711-preview", "kimi-k2-0905-preview"].toSorted(compareCheapestFirst)[0]).toBe("kimi-k2-0905-preview");
+});

package/src/model-order.ts

@@ -97,6 +97,10 @@ const TIER_RANK: Readonly<Record<string, number>> = {
     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,
@@ -122,3 +126,30 @@ export const tierRankOf = (family: string): number => {
 // 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);
+
+/* THE SAME TIER SCALE READ FROM THE OTHER END, for the one caller that wants the WEAKEST model rather than the
+ * strongest: the quick model behind a one-click helper (the commit box's autofill). A picker orders a catalog by
+ * what a user reaches for; this orders it by what a helper should spend, and the two are exact opposites — so
+ * they share TIER_RANK rather than each naming its own list of cheap ids.
+ *
+ * The direction of UNRANKED is the reason this can't just be compareModelIds reversed. There, an unrecognized
+ * family LEADS, because an id carrying no tier word is the provider's base line and a family nobody here has
+ * heard of is likelier the next flagship than the next budget tier. Reversing would therefore seat exactly that
+ * unknown-probably-flagship id as the cheap pick. So unknown sinks to LAST here too — both orders agree it is
+ * not the efficient rung — and the cheap end is only ever a family whose tier word is actually recognized.
+ * Falling off the end of a catalog with no efficient tier at all (Kimi publishes none) is then honest: the
+ * newest of what it does publish, chosen by the release tiebreak below. */
+export const compareCheapestFirst = (left: string, right: string): number =>
+    tierRankOf(familyOf(right)) - tierRankOf(familyOf(left)) || compareRelease(releaseOf(left), releaseOf(right));

package/src/path-refs.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { isTestPath, 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"]);
+    });
+});
+
+test("isTestPath: test files, fixture dirs and runner configs — never product code that merely says 'test'", () => {
+    for (const path of [
+        `src/agents/land.test.ts`,
+        `src/pages/Foo.spec.tsx`,
+        `_apps/cli/src/cli.e2e.test.ts`,
+        `src/e2e-harness.ts`,
+        `pkg/__tests__/helper.ts`,
+        `_libs/iq-recall/src/__fixtures__/transcripts/a.jsonl`,
+        `vitest.config.ts`,
+        `_apps/web/vitest.workspace.config.mts`,
+        `playwright.config.ts`,
+    ]) {
+        expect(isTestPath(path), path).toBe(true);
+    }
+    for (const path of [
+        `src/pages/testimonials.vue`,
+        `src/latest.ts`,
+        `src/test-utils.ts`,
+        `contest/results.ts`,
+        `src/attestation.spec.md.bak`,
+        `docs/testing.md`,
+    ]) {
+        expect(isTestPath(path), path).toBe(false);
+    }
+});

package/src/path-refs.ts

@@ -0,0 +1,59 @@
+/* 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);
+
+/* IS THIS FILE TEST CODE — the one classification rule for every surface that splits a diff into "the
+ * change" and "the proof". The agent review header answers "how much of this is tests?" with it; anything
+ * else that wants the split (fleet cards, commit summaries) must use this same predicate, because two
+ * classifiers that disagree turn the readout into a lie the user can't detect.
+ *
+ * Convention-based, matching what this monorepo (and the ecosystems it scaffolds) actually writes: a
+ * `.test.` / `.spec.` filename in any extension, a `__tests__` / `__fixtures__` directory anywhere on the
+ * path, an `e2e-harness`, or a test-runner config. Deliberately NOT "anything containing 'test'": a
+ * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one —
+ * it tells a reviewer not to look. */
+const TEST_DIRS = new Set([`__tests__`, `__fixtures__`, `__mocks__`, `__snapshots__`]);
+const TEST_FILE = /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[^/.]+|[^/]*\.e2e\.[^/]+|e2e-harness\.[^/]+|(?:vitest|jest|playwright)(?:\.[\w-]+)*\.config\.[^/]+)$/;
+
+export const isTestPath = (path: string): boolean =>
+    TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));

package/src/quick-model.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "vitest";
+import { type QuickModelSource, quickModelKey, resolveQuickModel } from "./quick-model.js";
+
+/* Which model a one-click helper spends. The rule answers two surfaces at once — the daemon runs it, the
+ * browser names it in the sparkle's tooltip — so what these tests pin is that a sandbox's connections alone
+ * decide it, with no stored id to go stale. */
+
+// Catalogs as their providers actually publish them: Claude's ranked list, the rest in registry order.
+const CLAUDE: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
+const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
+const CODEX: QuickModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
+const KIMI: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-0711-preview`, `kimi-k2-0905-preview`] };
+
+const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
+
+test("reaches for the efficient rung of the one connected provider, never its flagship", () => {
+    expect(resolveQuickModel([CLAUDE], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+});
+
+test("spends the FREE channel over the subscription when both offer the same rung", () => {
+    // Both publish a cheap-tier row, so nothing separates them on capability — and one of them costs the user
+    // nothing while the other eats headroom they watch. Clicking sparkle should not quietly bill the Claude plan.
+    expect(resolveQuickModel([CLAUDE, GOOGLE], ``)).toEqual({ provider: `gemini`, model: `gemini-3-flash-lite` });
+});
+
+test("puts tier ahead of cost — a free frontier model is still the wrong tool for a commit message", () => {
+    // Google connected but publishing only its Pro line. Ordering on price first would seat a flagship here,
+    // which is the exact outcome the feature exists to avoid.
+    const proOnly: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
+
+    expect(resolveQuickModel([CLAUDE, proOnly], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+});
+
+test("prefers a subscription to a metered key at equal tier, since only one of them charges per click", () => {
+    const kimiCheap: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
+    const claudeCheap: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
+
+    expect(resolveQuickModel([kimiCheap, claudeCheap], ``)?.provider).toBe(`claude`);
+});
+
+test("answers the same thing however the connected providers happen to be listed", () => {
+    // The daemon assembles these from live stores and the browser from its own refs; neither order is a fact.
+    const answers = [
+        resolveQuickModel([CLAUDE, GOOGLE, CODEX], ``),
+        resolveQuickModel([CODEX, CLAUDE, GOOGLE], ``),
+        resolveQuickModel([GOOGLE, CODEX, CLAUDE], ``),
+    ];
+
+    expect(new Set(answers.map((answer) => quickModelKey(answer!))).size).toBe(1);
+});
+
+test("honours a pinned model verbatim, including an id no catalog lists yet", () => {
+    expect(resolveQuickModel([CLAUDE, GOOGLE], `claude:claude-opus-5`)).toEqual({ provider: `claude`, model: `claude-opus-5` });
+    // The picker's custom-id escape hatch reaches here too: a catalog can lag a release, and running something
+    // other than what the settings row names would be the worse failure.
+    expect(resolveQuickModel([CLAUDE], `claude:claude-haiku-9`)).toEqual({ provider: `claude`, model: `claude-haiku-9` });
+});
+
+test("falls back to Auto when the pinned provider is no longer connected", () => {
+    // Rather than failing every click with a credential error while the sandbox can plainly still answer.
+    expect(resolveQuickModel([offline(CLAUDE), GOOGLE], `claude:claude-haiku-4-5-20251001`)).toEqual({
+        provider: `gemini`,
+        model: `gemini-3-flash-lite`,
+    });
+});
+
+test("ignores a malformed pin instead of running an empty model id", () => {
+    for (const pinned of [`claude`, `claude:`, `:claude-haiku-4-5`, ` `]) {
+        expect(resolveQuickModel([CLAUDE], pinned)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    }
+});
+
+test("serves the newest of a catalog that publishes no cheap tier at all", () => {
+    // Kimi names no tier word anywhere. There is no cheaper rung to find, so the newest row is the honest answer.
+    expect(resolveQuickModel([KIMI], ``)).toEqual({ provider: `kimi`, model: `kimi-k2-0905-preview` });
+});
+
+test("reports nothing when no account is connected, so the button can say so instead of failing on click", () => {
+    expect(resolveQuickModel([offline(CLAUDE), offline(GOOGLE)], ``)).toBeUndefined();
+    expect(resolveQuickModel([], `claude:claude-haiku-4-5`)).toBeUndefined();
+});
+
+test("skips a connected provider whose catalog has not loaded yet", () => {
+    const unloaded: QuickModelSource = { provider: `grok`, ready: true, models: [] };
+
+    expect(resolveQuickModel([unloaded, CLAUDE], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+    expect(resolveQuickModel([unloaded], ``)).toBeUndefined();
+});

package/src/quick-model.ts

@@ -0,0 +1,103 @@
+import { ACCESS_COST, accessFor, PROVIDERS } from "./agent-catalog.js";
+import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
+import type { NativeProvider } from "./schemas.js";
+
+/* THE QUICK MODEL — the cheap, fast model a one-click helper spends instead of the frontier model the chat runs
+ * on. Today that is the commit box's autofill; anything else of that shape (a branch name, a PR description)
+ * reads the same answer, which is the reason this is a `quickModel` setting rather than a commit-message one.
+ *
+ * The rule lives in the contract because BOTH sides need the same answer for different jobs: the daemon runs
+ * the model, and the browser has to NAME it — in the sparkle's tooltip and in the settings row's "Auto (…)"
+ * label — before anything has been run. Two implementations would drift precisely where it matters most, since
+ * a tooltip promising Haiku while the daemon bills Opus is worse than no tooltip.
+ *
+ * The default is DERIVED, NEVER STORED. `quickModel` ships as "" and that empty string means "work it out from
+ * whatever is connected right now", so connecting a Google account tomorrow improves the default by itself and
+ * disconnecting the pinned provider degrades to Auto instead of to a dead button. Same instinct as the rest of
+ * this repo's model handling: model-order.ts derives tier and recency from the id and curates nothing, and the
+ * web's defaultModelFor reads the live catalog rather than naming an id that a release will falsify. */
+
+// One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
+// ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
+// own model, so there is no cheap rung to point it at.
+export interface QuickModelSource {
+    readonly provider: NativeProvider;
+    // The same connection predicate every other surface gates on (access.ts web-side, the daemon's own account
+    // stores daemon-side). A catalog is never empty by construction, so "has rows" says nothing about "can send".
+    readonly ready: boolean;
+    readonly models: readonly string[];
+}
+
+export interface QuickModelChoice {
+    readonly provider: NativeProvider;
+    readonly model: string;
+}
+
+// A pinned selection on the wire: `${provider}:${modelId}`, the same key shape the model picker already mints
+// for its entries (PickerEntry.key). Empty ⇒ Auto.
+export const quickModelKey = (choice: QuickModelChoice): string => `${choice.provider}:${choice.model}`;
+
+// Split on the FIRST colon only: a provider id never contains one and a model id might.
+const parsePinned = (pinned: string): QuickModelChoice | undefined => {
+    const separator = pinned.indexOf(`:`);
+    if (separator <= 0 || separator === pinned.length - 1) {
+        return undefined;
+    }
+    return { provider: pinned.slice(0, separator) as NativeProvider, model: pinned.slice(separator + 1) };
+};
+
+// The cheapest row a provider publishes — its whole catalog read from the cheap end. Undefined for a catalog
+// that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
+// asked it.
+const cheapestOf = (source: QuickModelSource): string | undefined => source.models.toSorted(compareCheapestFirst)[0];
+
+// Where a provider's cheapest row sits on the shared tier scale, and therefore how well it answers the question
+// this whole module asks. UNRANKED (-1) is a genuine last place: it means the id carries no tier word we know,
+// so the row is the provider's base line rather than its budget one.
+const tierOf = (model: string): number => tierRankOf(familyOf(model));
+
+// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read — the property
+// compareUnrankedModelIds exists to guarantee, and the one a default actually needs.
+const providerOrder = (provider: NativeProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
+
+// How much a call on this provider costs at the margin. Every native provider declares an access kind, so the
+// fallback is unreachable — it exists because AgentProvider is a bare string on the wire.
+const costOf = (provider: NativeProvider): number => {
+    const access = accessFor(provider);
+    return access === undefined ? ACCESS_COST.key : ACCESS_COST[access.kind];
+};
+
+/* Which model a quick helper runs, given what this sandbox has connected. `pinned` is the stored setting.
+ *
+ * A pin only holds while its provider is READY: an account the user disconnected would otherwise leave the
+ * button failing on every click with a credential error, when the sandbox can plainly still answer. Auto taking
+ * over is the same move the composer already makes when a live catalog stops offering the selected model.
+ *
+ * Auto ranks candidates on TIER FIRST, then cost. That order is the point of the feature: the helper exists to
+ * not be the frontier model, so a free flagship is still the wrong tool, while a free Haiku-class row and a
+ * subscription Haiku-class row differ only in whose quota they spend. Cost then breaks that tie towards the
+ * channel the user is not paying per token for — and against the one they are.
+ *
+ * Undefined when nothing is connected: the caller renders a disabled control that says so, rather than a live
+ * button that fails on click. */
+export const resolveQuickModel = (sources: readonly QuickModelSource[], pinned: string): QuickModelChoice | undefined => {
+    const requested = parsePinned(pinned);
+    if (requested !== undefined && sources.some((source) => source.provider === requested.provider && source.ready)) {
+        // Taken verbatim, unvalidated against the catalog on purpose: the picker already offers a custom-id
+        // escape hatch for a model a catalog hasn't caught up with, and second-guessing the user's own id here
+        // would silently run a different model than the settings row names.
+        return requested;
+    }
+    const candidates = sources
+        .filter((source) => source.ready)
+        .flatMap((source) => {
+            const model = cheapestOf(source);
+            return model === undefined ? [] : [{ provider: source.provider, model }];
+        });
+    return candidates.toSorted(
+        (left, right) =>
+            tierOf(right.model) - tierOf(left.model) ||
+            costOf(left.provider) - costOf(right.provider) ||
+            providerOrder(left.provider) - providerOrder(right.provider),
+    )[0];
+};

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;
+};