@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/models/model-order.ts

@@ -0,0 +1,163 @@
+// Orders a model catalog the same way for every provider, since only Anthropic's /v1/models returns one worth keeping.
+// Every other provider hands back a set in registry order, so this file derives an order instead, from the two facts an
+// id reliably carries: tier (the adjective) and release (the numbers).
+
+// A version-ish segment: digits/dots, optionally prefixed by v or k (`5.1`, `k3`); anything else is a name.
+const VERSION_SEGMENT = /^(?:v|k)?[\d.]+$/i;
+
+// A date stamp, not a version component: 6+ digits; conflating the two misorders a dated build's compare.
+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.
+// Derived, never listed.
+export const familyOf = (id: string): string => {
+    const stem = segmentsOf(id)
+        .filter((segment) => !VERSION_SEGMENT.test(segment))
+        .join("-");
+    // An all-numeric id, or an ACP row's empty one, has no stem: it stands as its own family.
+    return stem === "" ? id : stem;
+};
+
+export interface ModelRelease {
+    // Version components in id order; empty for an unversioned id, which then reads as the oldest of its tier.
+    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(/^[vk]/i, ""));
+    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; the date stamp breaks the rest.
+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;
+};
+
+// Unranked families lead, not sink: an id with no tier word is likelier a new flagship than a budget model.
+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 that costs less than the one above it.
+    haiku: 2,
+    // An open-weights model re-served beside a vendor's line (gpt-oss on Google's) is this rung by construction.
+    oss: 2,
+    lite: 2,
+    nano: 2,
+    fast: 2,
+    small: 2,
+};
+
+const UNRANKED = -1;
+
+// A release-local ladder (Codex 5.6 sol>terra>luna), kept separate so cross-release recency still outranks it.
+const RELEASE_TIER_RANK: Readonly<Record<string, number>> = {
+    sol: 0,
+    terra: 1,
+    luna: 2,
+};
+
+const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): number => {
+    let rank = UNRANKED;
+    for (const segment of family.split("-")) {
+        const found = ranks[segment];
+        if (found !== undefined) {
+            rank = found;
+        }
+    }
+    return rank;
+};
+
+const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
+
+// How hard an id says it will think; ties on tier, so only compareCheapestFirst's tiebreak may read it.
+const THINKING_RANK: Readonly<Record<string, number>> = {
+    minimal: 0,
+    none: 0,
+    low: 1,
+    medium: 3,
+    high: 4,
+    max: 4,
+    // A switch, not a level: vending `kimi-k2` beside `kimi-k2-thinking` names the same model, reasoning turned on.
+    thinking: 4,
+};
+
+// An id naming no level sits between both ends, the provider's default, not the cheapest or dearest reading.
+const UNSTATED_THINKING = 2;
+
+const thinkingRankOf = (family: string): number => {
+    const rank = lastRankOf(family, THINKING_RANK);
+    return rank === UNRANKED ? UNSTATED_THINKING : rank;
+};
+
+// The last recognized word wins: gemini-flash-lite is Flash's cheap end, gpt-codex-max is Codex's frontier end.
+export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
+
+// The canonical order of two ids: tier first, then release, then a release-local tier. Stable under Array#toSorted, so
+// ids this rule cannot separate keep their arrival order.
+export const compareModelIds = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(leftFamily) - tierRankOf(rightFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(leftFamily) - releaseTierRankOf(rightFamily)
+    );
+};
+
+// The order for a catalog its endpoint published as an unordered set (everything but Anthropic). Ties break on id, not
+// arrival order, since a registry can reorder a tied set between refreshes.
+export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);
+
+// The same tier scale read from the weakest end, for the caller that wants the cheapest model, not the strongest. An
+// unranked family still sinks last on both orders; a tier-less catalog (Kimi) falls back to its newest release.
+export const compareCheapestFirst = (left: string, right: string): number => {
+    const leftFamily = familyOf(left);
+    const rightFamily = familyOf(right);
+    return (
+        tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
+        // Before release: two rows differing only by thinking are the same model; recency must not pick between them.
+        thinkingRankOf(leftFamily) - thinkingRankOf(rightFamily) ||
+        compareRelease(releaseOf(left), releaseOf(right)) ||
+        releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
+    );
+};
+
+// Tier only, not release or thinking level, so a downgrade stays legible as one. An unranked family is false on either
+// side: an unranked candidate might be the next flagship, and an unranked pick's tier is unknown to have been beaten.
+export const isCheaperRung = (candidate: string, pick: string): boolean => {
+    const candidateRank = tierRankOf(familyOf(candidate));
+    const pickRank = tierRankOf(familyOf(pick));
+    return candidateRank !== UNRANKED && pickRank !== UNRANKED && candidateRank > pickRank;
+};
+
+// True only for an id that spells out a level above the quiet end, so an unannotated id is never accused of it.
+// Exported so a settings row can label a pinned thinking variant.
+export const namesThinking = (id: string): boolean => thinkingRankOf(familyOf(id)) > UNSTATED_THINKING;

package/src/models/model-pins.test.ts

@@ -0,0 +1,87 @@
+import { expect, test } from "vitest";
+import { type ModelSource, modelPinKey, parsePinned, readyChain } from "./model-pins.js";
+import type { ModelPin } from "../schemas/agent.js";
+
+// Which models a job spends, and in what order: the owner's own list decides, nothing is derived for an empty one, and
+// there is a fallback rung whenever one is written.
+
+// A pin as settings rows store one; tests focus on order, so most entries carry just provider:model.
+const pin = (key: string): ModelPin => {
+    const at = key.indexOf(`:`);
+    return { provider: key.slice(0, at), model: key.slice(at + 1) };
+};
+
+// Catalogs as providers publish them; the resolver never reads them, so a wrong fixture would hide it.
+const CLAUDE: ModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5-20251001`] };
+const GOOGLE: ModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-flash`, `gemini-3-flash-lite`, `gemini-3-pro`] };
+const CODEX: ModelSource = { provider: `codex`, ready: true, models: [`gpt-5.4-mini`, `gpt-5.6`] };
+const KIMI: ModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2.6`, `kimi-k2.7-code`, `kimi-k3`] };
+
+const offline = (source: ModelSource): ModelSource => ({ ...source, ready: false });
+
+// The model that answers when nothing goes wrong: the head of the chain, what every surface reads.
+const head = (sources: readonly ModelSource[], pinned: readonly string[]): ModelPin | undefined => readyChain(sources, pinned.map(pin))[0];
+
+test("honours a pinned model verbatim, including an id no catalog lists yet", () => {
+    expect(head([CLAUDE, GOOGLE], [`claude:claude-opus-5`])).toEqual({ provider: `claude`, model: `claude-opus-5` });
+    // The picker's custom-id escape hatch reaches here too: a lagging catalog still must run the exact id named.
+    expect(head([CLAUDE], [`claude:claude-haiku-9`])).toEqual({ provider: `claude`, model: `claude-haiku-9` });
+});
+
+test("refuses a malformed key rather than reading half a pin out of it", () => {
+    for (const key of [`claude`, `claude:`, `:claude-haiku-4-5`, ` `]) {
+        expect(parsePinned(key)).toBeUndefined();
+    }
+    expect(parsePinned(`claude:claude-haiku-4-5`)).toEqual({ provider: `claude`, model: `claude-haiku-4-5` });
+});
+
+test("resolves an unset job to nothing, however many accounts are connected", () => {
+    expect(readyChain([CLAUDE, GOOGLE, KIMI], [])).toEqual([]);
+    expect(head([CLAUDE, GOOGLE], [])).toBeUndefined();
+});
+
+test("carries an entry's run settings through untouched", () => {
+    const configured: ModelPin = { provider: `claude`, model: `claude-opus-5`, effort: `max`, thinking: true, harness: `claude-code` };
+
+    expect(readyChain([CLAUDE], [configured])).toEqual([configured]);
+});
+
+test("reports nothing when the accounts a job named have all gone", () => {
+    expect(head([offline(CLAUDE), GOOGLE], [`claude:claude-haiku-4-5-20251001`])).toBeUndefined();
+    expect(head([], [`claude:claude-haiku-4-5`])).toBeUndefined();
+});
+
+test("keeps the pinned models in the order they were written", () => {
+    expect(readyChain([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`].map(pin))).toEqual([
+        { provider: `codex`, model: `gpt-5.6` },
+        { provider: `gemini`, model: `gemini-3-flash` },
+        { provider: `claude`, model: `claude-haiku-4-5-20251001` },
+    ]);
+});
+
+test("drops a pin whose provider went away and keeps the rest of the order intact", () => {
+    expect(readyChain([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`].map(pin))).toEqual([
+        { provider: `codex`, model: `gpt-5.6` },
+        { provider: `claude`, model: `claude-haiku-4-5` },
+    ]);
+});
+
+test("stops at the end of a pinned list rather than reaching for an account the user left out", () => {
+    expect(readyChain([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`].map(pin))).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
+});
+
+test("names each model once, however many times the list repeats it", () => {
+    // A duplicate pin is a real state (hand-edited lists, one entry reused across jobs), not a bug to collapse.
+    expect(readyChain([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`].map(pin))).toEqual([
+        { provider: `claude`, model: `claude-haiku-4-5` },
+    ]);
+});
+
+// A configured endpoint is a provider like any other here: its picker options come from the same catalog.
+const OLLAMA: ModelSource = { provider: `endpoint/ollama`, ready: true, models: [`qwen3-coder`, `gemma3-27b`] };
+
+test("honours a pin on a configured endpoint: the whole id, not the half before its slash", () => {
+    expect(head([CLAUDE, OLLAMA], [`endpoint/ollama:qwen3-coder`])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
+    // parsePinned splits on the first colon; an id with its own colon needs the slash form or parsing breaks.
+    expect(modelPinKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
+});

package/src/models/model-pins.ts

@@ -0,0 +1,57 @@
+import { modelsFor } from "./agent-catalog.js";
+import type { AgentProvider, ModelPin } from "../schemas/agent.js";
+
+// The order to try models in for a role or job (settings.modelRoles), shared by daemon and browser so both agree what a
+// job will spend before it runs. An empty list resolves to nothing for every role: nothing is derived or auto-selected.
+// The caller decides what an empty answer means (a helper is off; a run falls back to the chat's own pick).
+
+// One provider's standing in the decision: can a turn go, and what its catalog holds. ACP agents have no rung here (an
+// empty model id), but endpoint/<id> providers must be included, matching the picker's own options.
+export interface ModelSource {
+    // AgentProvider, not NativeProvider: an endpoint's id is user-created, no fixed union; nothing here ranks cost.
+    readonly provider: AgentProvider;
+    // Same connection predicate every surface gates on; a nonempty catalog does not imply ready to send.
+    readonly ready: boolean;
+    // Nothing here reads this (a pin is verbatim); kept because it's what a source is, and callers still gather it.
+    readonly models: readonly string[];
+}
+
+export interface ModelChoice {
+    readonly provider: AgentProvider;
+    readonly model: string;
+}
+
+// A (provider, model) pair on the wire: `${provider}:${modelId}`, the same key shape the picker mints. Used to compare
+// entries, dedupe a role list, and store autoFastModels.
+export const modelPinKey = (choice: ModelChoice): string => `${choice.provider}:${choice.model}`;
+
+// Splits on the first colon only: a provider id never contains one, a model id might. Exported since autoFastModels
+// stores these keys.
+export const parsePinned = (pinned: string): ModelChoice | undefined => {
+    const separator = pinned.indexOf(`:`);
+    if (separator <= 0 || separator === pinned.length - 1) {
+        return undefined;
+    }
+    return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
+};
+
+// A pin as a person reads it: the catalog's own label, or the raw id when the static catalog has not caught up with it
+// (a real case, via the picker's custom-id escape hatch).
+export const pinnedModelLabel = (choice: ModelChoice): string =>
+    modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
+
+// Filters pinned entries to ready providers only; there is no floor beneath a written list, so an account left unnamed
+// is never reached. Returns whole pins, not bare pairs, since effort, thinking and harness must survive with the pick.
+export const readyChain = (sources: readonly ModelSource[], pinned: readonly ModelPin[]): readonly ModelPin[] => {
+    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
+    // Taken verbatim, unvalidated: the picker's custom-id escape hatch must run exactly the id it names.
+    const requested = pinned.filter((pin) => ready.has(pin.provider));
+    // First occurrence wins, whole: two entries can name one model with different knobs, and the earlier is meant.
+    const chain: ModelPin[] = [];
+    for (const pin of requested) {
+        if (!chain.some((held) => modelPinKey(held) === modelPinKey(pin))) {
+            chain.push(pin);
+        }
+    }
+    return chain;
+};

package/src/models/model-roles.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "vitest";
+import { MODEL_ROLE_BLOCKS, MODEL_ROLES, type ModelRoleSpec } from "./model-roles.js";
+
+// The catalog draws the settings page directly, so its properties (every role in one block) must hold of the table
+// itself, not be remembered by whoever adds a row.
+
+// Typed at its declared width, not the literal tuple: trigger is absent from a helper's type, under test here.
+const roles: readonly ModelRoleSpec[] = MODEL_ROLES;
+
+test("every whole session says what starts it, and it is the block it is drawn in", () => {
+    const blockOf = new Map(MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => [role.id, block.id] as const)));
+
+    for (const role of roles) {
+        expect(role.kind === `run` ? role.trigger : role.kind, role.id).toBe(blockOf.get(role.id));
+    }
+});
+
+test("a one-shot declares no trigger at all: nothing presses a commit subject into being", () => {
+    for (const helper of roles.filter((role) => role.kind === `helper`)) {
+        expect(Object.keys(helper), helper.id).not.toContain(`trigger`);
+    }
+});
+
+test("the blocks hold every role once, in the table's own order", () => {
+    const blocked = MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => role.id));
+
+    expect(blocked.toSorted()).toEqual(MODEL_ROLES.map((role) => role.id).toSorted());
+    // The block order mirrors reach ordering (unpicked jobs, then click-started sessions, then auto-started ones).
+    expect(blocked).toEqual(MODEL_ROLES.map((role) => role.id));
+});
+
+test("each block says what it is, so the page keeps no headings of its own", () => {
+    for (const block of MODEL_ROLE_BLOCKS) {
+        expect(block.label, block.id).toMatch(/\S/);
+        // A block with nothing in it would draw a heading over an empty surface.
+        expect(block.roles.length, block.id).toBeGreaterThan(1);
+    }
+});

package/src/models/model-roles.ts

@@ -0,0 +1,180 @@
+import { z } from "zod";
+
+// Every job that picks a model, one row per job; the unit is the role, not a difficulty tier. Each list is an ordered
+// fallback ladder; empty means the job is off (helper) or falls back to the caller's own chat model (run). Adding a
+// role is one row here, settings, resolver and daemon all read this table.
+
+export const ModelRoleKindSchema = z.enum(["helper", "run"]);
+export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
+
+// Which block a run role sorts into on the settings page: pressed by the owner, or started unprompted; helpers declare
+// none.
+export type ModelRoleTrigger = "pressed" | "unprompted";
+
+// `id` is a bare string here; narrowed to the role union on `ModelRoleSpec` below, since that union derives from this
+// table via `satisfies`.
+interface ModelRoleRow {
+    readonly id: string;
+    // The owner's own words for the job; never a difficulty tier.
+    readonly label: string;
+    // Must add information beyond the label, not restate it.
+    readonly blurb: string;
+    readonly kind: ModelRoleKind;
+    /** Required when `kind` is "run"; unset for helpers. */
+    readonly trigger?: ModelRoleTrigger;
+    // Icon name from the shared icon set; kept here, not in a separate web-side map keyed by id.
+    readonly icon: string;
+}
+
+// Ids are wire-stable (`AgentTurn.runRole`); order matches the settings page's block grouping below.
+export const MODEL_ROLES = [
+    {
+        id: "commit-message",
+        label: "Commit messages",
+        blurb: "The subject written when an agent's work lands, and the release note under it.",
+        kind: "helper",
+        icon: "file-edit",
+    },
+    {
+        id: "session-title",
+        label: "Session titles",
+        blurb: "The name a conversation wears on the board, written a second into its first turn.",
+        kind: "helper",
+        icon: "pencil",
+    },
+    {
+        // Prompt includes the command about to run, which may be attacker-controlled; a small model can be swayed.
+        id: "safety-judge",
+        label: "Safety judge",
+        blurb: "Which model reads your safety policy before a flagged command runs.",
+        kind: "helper",
+        icon: "shield",
+    },
+    {
+        id: "loop-verdict",
+        label: "Loop verdicts",
+        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
+        kind: "helper",
+        icon: "check-square",
+    },
+    {
+        // Picks one persona id or none from a fixed list; a classification, not free text.
+        id: "persona-router",
+        label: "Persona routing",
+        blurb: "Which model reads a new chat's first message and picks the persona for it.",
+        kind: "helper",
+        icon: "users",
+    },
+    {
+        id: "pipeline-fix",
+        label: "Pipeline fixes",
+        blurb: "The agent started by Fix on a red pipeline.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wave-pulse",
+    },
+    {
+        id: "deployment-fix",
+        label: "Deployment fixes",
+        blurb: "The agent started by Fix on a deployment that is down.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "server",
+    },
+    {
+        id: "maintenance-chore",
+        label: "Maintenance chores",
+        blurb: "A chore run started from the Maintenance board.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wrench",
+    },
+    {
+        id: "documentation-run",
+        label: "Documentation runs",
+        blurb: "A pass over a repo's own documentation.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "book",
+    },
+    {
+        id: "acceptance-run",
+        label: "Acceptance runs",
+        blurb: "One session per story in an acceptance fan-out.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "list-check",
+    },
+    {
+        id: "pre-push-fix",
+        label: "Pre-push fixes",
+        blurb: "The fix proposed when a check fails on the way to a push.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "cloud-upload",
+    },
+    {
+        // Pressed trigger: the owner's approval click starts this turn; the queue between is just machinery.
+        id: "approval-queue",
+        label: "Approvals queue",
+        blurb: "The turn that publishes or acts on what you approved.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "check-circle",
+    },
+    {
+        id: "extension-review",
+        label: "Extension update reviews",
+        blurb: "The agent that reads an extension update before it is applied.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "box",
+    },
+    {
+        id: "loop-iteration",
+        label: "Loop iterations",
+        blurb: "Each round of a loop working towards its goal.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "repeat",
+    },
+] as const satisfies readonly ModelRoleRow[];
+
+export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
+export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
+
+export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
+
+// Enum, not a string: an id outside this table names nothing, so it should fail loudly rather than be ignored.
+export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
+
+// Groups MODEL_ROLES for the settings page by kind and trigger; each role belongs to exactly one block, in table order.
+export type ModelRoleBlockId = "helper" | "pressed" | "unprompted";
+
+export interface ModelRoleBlock {
+    readonly id: ModelRoleBlockId;
+    /** Heading shown on the settings page. */
+    readonly label: string;
+    /** Its roles, in MODEL_ROLES order. */
+    readonly roles: readonly ModelRoleSpec[];
+}
+
+const rolesWhere = (match: (role: ModelRoleSpec) => boolean): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => match(role));
+
+export const MODEL_ROLE_BLOCKS: readonly ModelRoleBlock[] = [
+    {
+        id: "helper",
+        label: "Automatic helpers",
+        roles: rolesWhere((role) => role.kind === "helper"),
+    },
+    {
+        id: "pressed",
+        label: "Runs you start",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "pressed"),
+    },
+    {
+        id: "unprompted",
+        label: "Runs that start themselves",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "unprompted"),
+    },
+];

package/src/{plan-pools.test.ts → models/plan-pools.test.ts}

@@ -1,10 +1,9 @@
 import { expect, test } from "vitest";
 import { bindingWindow, gatesModel, gatingWindows, scopedWindow } from "./plan-pools.js";
-import type { AccountUsage, UsageWindow } from "./schemas/plan-limits.js";
+import type { AccountUsage, UsageWindow } from "../schemas/plan-limits.js";
 
-/* ONE RULE FOR "WHICH POOL STANDS IN THE WAY OF THIS MODEL", shared by the daemon's picker and the browser's
- * rings. What these pin is the case the six rules it replaced disagreed on: a plan that meters models
- * separately, where the account's fullest pool and the pool a given model spends are different allowances. */
+// One rule for which pool blocks a given model, shared by the daemon and the browser: a plan can meter models
+// separately, so the account's fullest pool need not be the model's own.
 
 const window = (over: Partial<UsageWindow> & Pick<UsageWindow, "kind">): UsageWindow => ({ utilization: 10, gates: "all", ...over });
 const usage = (...windows: UsageWindow[]): AccountUsage => ({ windows, measuredAt: 0 });
@@ -24,7 +23,6 @@ const CLAUDE = usage(
 test("matches a pool's names as runs of whole words against the id and the label alike", () => {
     expect(gatesModel({ models: ["opus"] }, { id: "claude-opus-4-6" })).toBe(true);
     expect(gatesModel({ models: ["Opus"] }, { id: "some-id", label: "Claude Opus 4.6" })).toBe(true);
-    // "Sonnet" is not in "claude-opus-4-6", and a substring test is what would have said "son" was.
     expect(gatesModel({ models: ["son"] }, { id: "claude-sonnet-4-6" })).toBe(false);
     expect(gatesModel({ models: ["claude opus"] }, { id: "claude-opus-4-6" })).toBe(true);
     expect(gatesModel({ models: ["opus claude"] }, { id: "claude-opus-4-6" })).toBe(false);
@@ -33,12 +31,11 @@ test("matches a pool's names as runs of whole words against the id and the label
 });
 
 test("a Google account spent for Gemini still has room for Claude Opus, and the other way round", () => {
-    // The Antigravity case: one sign-in, two allowances on two clocks. Reading the account's fullest pool put a
-    // red ring over Claude Opus while its own pool sat at 27%.
+    // One account, two independently metered pools (Gemini vs Claude/GPT), each on its own clock.
     expect(bindingWindow(GOOGLE, { id: "claude-opus-4-6-thinking" })?.kind).toBe("google:3p-weekly");
     expect(bindingWindow(GOOGLE, { id: "gpt-oss-120b" })?.kind).toBe("google:3p-weekly");
     expect(bindingWindow(GOOGLE, { id: "gemini-3-pro" })?.kind).toBe("google:gemini-weekly");
-    // A family the channel has not published a pool for is gated by nothing: unmeasured, never blocked.
+    // A model family with no published pool is unmeasured, not blocked.
     expect(bindingWindow(GOOGLE, { id: "kimi-k2" })).toBeUndefined();
 });
 
@@ -49,8 +46,6 @@ test("a Claude account's spent Opus slice does not bind a Haiku call, and its ow
 });
 
 test("with no model named, the account's tightest pool is the answer, and a pool gating nothing is never it", () => {
-    // The Cowork surface pool is at 99% and gates none of this sandbox's turns: shown on the roster, never the
-    // account's headroom.
     expect(bindingWindow(CLAUDE)?.kind).toBe("model:Opus");
     expect(gatingWindows(CLAUDE).map((entry) => entry.kind)).toEqual(["five_hour", "seven_day", "model:Opus"]);
     expect(bindingWindow(undefined)).toBeUndefined();
@@ -59,7 +54,7 @@ test("with no model named, the account's tightest pool is the answer, and a pool
 
 test("names the pool a plan meters this model by on its own, preferring the more specific and refusing a tie", () => {
     expect(scopedWindow(CLAUDE, { id: "claude-opus-4-6" })?.kind).toBe("model:Opus");
-    // The all-models weekly is not this model's own allowance, so a plan with no slice for it says nothing.
+    // five_hour and seven_day meter all models, not just this one; scopedWindow needs a model-specific pool.
     expect(scopedWindow(CLAUDE, { id: "claude-haiku-4-5" })).toBeUndefined();
     const layered = usage(
         window({ kind: "model:Opus", gates: { models: ["Opus"] } }),

package/src/models/plan-pools.ts

@@ -0,0 +1,65 @@
+import type { AccountUsage, UsageWindow, WindowGates } from "../schemas/plan-limits.js";
+
+// Single reading of which account pool gates a given model (or, with none named, the account's tightest pool), shared
+// by the daemon's picker/refusal logic and the browser's rings and rail. A pool gated `none` is excluded from the
+// no-model case: visible to the account, never a gate on a turn.
+
+// 100 = exhaustion (the call will be refused), not the browser's 90% warning threshold (usageStatus SPENT_PERCENT).
+export const SPENT_UTILIZATION = 100;
+
+export interface ModelRef {
+    // Wire model id.
+    readonly id: string;
+    // Display name, when available; matched too, since the tier word may be in either id or label.
+    readonly label?: string | undefined;
+}
+
+// Splits into lowercase alnum words for whole-word matching: a substring test would match "opus" inside a word that
+// merely contains it.
+export const wordsOf = (text: string): readonly string[] =>
+    text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+
+// Whether `needle` appears as a contiguous run of whole words within `words`.
+export const runOfWords = (words: readonly string[], needle: readonly string[]): boolean =>
+    needle.length > 0 && words.some((_, at) => needle.every((word, index) => words[at + index] === word));
+
+const nameMatches = (name: string, model: ModelRef): boolean => {
+    const needle = wordsOf(name);
+    return runOfWords(wordsOf(model.id), needle) || (model.label !== undefined && runOfWords(wordsOf(model.label), needle));
+};
+
+export const gatesModel = (gates: WindowGates, model: ModelRef): boolean =>
+    gates === "all" ? true : gates === "none" ? false : gates.models.some((name) => nameMatches(name, model));
+
+// Pools that gate this model, or, with no model given, every pool that gates anything.
+export const gatingWindows = (usage: AccountUsage | undefined, model?: ModelRef): readonly UsageWindow[] =>
+    (usage?.windows ?? []).filter((window) => (model === undefined ? window.gates !== "none" : gatesModel(window.gates, model)));
+
+const fullest = (windows: readonly UsageWindow[]): UsageWindow | undefined =>
+    windows.reduce<UsageWindow | undefined>((worst, window) => (worst === undefined || window.utilization > worst.utilization ? window : worst), undefined);
+
+// The pool that gates the next turn: the fullest of the windows this model spends. Undefined means nothing gates it (or
+// nothing was measured) — distinct from a measured 0%.
+export const bindingWindow = (usage: AccountUsage | undefined, model?: ModelRef): UsageWindow | undefined => fullest(gatingWindows(usage, model));
+
+// The model's own metered pool, by most specific name match; distinct from bindingWindow, which may answer with an
+// all-models pool. Two matches tied in specificity return undefined rather than guess.
+export const scopedWindow = (usage: AccountUsage | undefined, model: ModelRef): UsageWindow | undefined => {
+    const matched = (usage?.windows ?? [])
+        .flatMap((window) => {
+            if (window.gates === "all" || window.gates === "none") {
+                return [];
+            }
+            const specificity = Math.max(0, ...window.gates.models.filter((name) => nameMatches(name, model)).map((name) => wordsOf(name).length));
+            return specificity === 0 ? [] : [{ window, specificity }];
+        })
+        .toSorted((left, right) => right.specificity - left.specificity);
+    const best = matched[0];
+    if (best === undefined || matched[1]?.specificity === best.specificity) {
+        return undefined;
+    }
+    return best.window;
+};