@intentic/sandbox-contract 1.240.0 → 1.243.0

package/src/plan-pools.test.ts

@@ -0,0 +1,71 @@
+import { expect, test } from "vitest";
+import { bindingWindow, gatesModel, gatingWindows, scopedWindow } from "./plan-pools.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. */
+
+const window = (over: Partial<UsageWindow> & Pick<UsageWindow, "kind">): UsageWindow => ({ utilization: 10, gates: "all", ...over });
+const usage = (...windows: UsageWindow[]): AccountUsage => ({ windows, measuredAt: 0 });
+
+const GOOGLE = usage(
+    window({ kind: "google:gemini-weekly", label: "Gemini models", utilization: 100, gates: { models: ["gemini"] } }),
+    window({ kind: "google:3p-weekly", label: "Claude and GPT models", utilization: 27, gates: { models: ["claude", "gpt"] } }),
+);
+
+const CLAUDE = usage(
+    window({ kind: "five_hour", utilization: 12 }),
+    window({ kind: "seven_day", utilization: 30 }),
+    window({ kind: "model:Opus", label: "Opus", utilization: 100, gates: { models: ["Opus"] } }),
+    window({ kind: "surface:Cowork", label: "Cowork", utilization: 99, gates: "none" }),
+);
+
+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);
+    expect(gatesModel("all", { id: "anything" })).toBe(true);
+    expect(gatesModel("none", { id: "anything" })).toBe(false);
+});
+
+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%.
+    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.
+    expect(bindingWindow(GOOGLE, { id: "kimi-k2" })).toBeUndefined();
+});
+
+test("a Claude account's spent Opus slice does not bind a Haiku call, and its own 5-hour and weekly pools do", () => {
+    expect(gatingWindows(CLAUDE, { id: "claude-haiku-4-5" }).map((entry) => entry.kind)).toEqual(["five_hour", "seven_day"]);
+    expect(bindingWindow(CLAUDE, { id: "claude-haiku-4-5" })?.kind).toBe("seven_day");
+    expect(bindingWindow(CLAUDE, { id: "claude-opus-4-6" })?.kind).toBe("model:Opus");
+});
+
+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();
+    expect(bindingWindow(usage())).toBeUndefined();
+});
+
+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.
+    expect(scopedWindow(CLAUDE, { id: "claude-haiku-4-5" })).toBeUndefined();
+    const layered = usage(
+        window({ kind: "model:Opus", gates: { models: ["Opus"] } }),
+        window({ kind: "model:Claude Opus", gates: { models: ["Claude Opus"] } }),
+    );
+    expect(scopedWindow(layered, { id: "claude-opus-4-6" })?.kind).toBe("model:Claude Opus");
+    const tied = usage(window({ kind: "model:Opus", gates: { models: ["Opus"] } }), window({ kind: "model:Claude", gates: { models: ["Claude"] } }));
+    expect(scopedWindow(tied, { id: "claude-opus-4-6" })).toBeUndefined();
+});

package/src/plan-pools.ts

@@ -0,0 +1,92 @@
+import type { AccountUsage, UsageWindow, WindowGates } from "./schemas/plan-limits.js";
+
+/* WHICH OF AN ACCOUNT'S POOLS STAND BETWEEN A TURN AND A MODEL, read once, for both sides of the wire.
+ *
+ * Every question about headroom is really a question about ONE model: which account should serve this Haiku
+ * call, is this Google fleet spent for Claude Opus, when does the pool that refused this turn reopen, what
+ * does the ring beside the composer measure. The pools a reading carries answer that only through their
+ * `gates` (UsageWindowSchema says why the reader decides them), and this file is the one place the gate is
+ * read, so the daemon's account picker, its quick-model walk, its refusal dressing and the browser's rings,
+ * rail and picker rows all agree about which pool is binding for a given model.
+ *
+ * WITHOUT A MODEL the answer is the account's own tightest pool, which is what a roster or a rail that has not
+ * chosen a model yet is asking. Pools gated to `none` are left out of that too: a code-review limit is the
+ * account's to see, never the thing that decides whether a chat turn can run. */
+
+/* WHEN A POOL HAS NOTHING LEFT IN IT, on the wire's own scale, read the same way by both sides.
+ *
+ * 100, and deliberately not the browser's 90 (usageStatus' SPENT_PERCENT): the two thresholds answer different
+ * questions. 90 is a WARNING — the point at which a surface stops recommending an account for a long turn, and
+ * what the rings and the bands take their red from. This is EXHAUSTION: the point past which a call is certain
+ * to be refused, which is what the daemon needs before it steers a turn elsewhere and the only line a list of
+ * offers may hide an account behind. A subscription with a tenth of its week left can still run the next task,
+ * and dropping it off a rail titled "Ready to run" answers the reader's question with the wrong one. */
+export const SPENT_UTILIZATION = 100;
+
+export interface ModelRef {
+    // The wire id ("claude-opus-4-6", "gemini-3-pro").
+    readonly id: string;
+    // What the picker calls it ("Claude Opus 4.6"), when the caller has it. Both are matched, because which of
+    // the two carries the tier word differs by vendor.
+    readonly label?: string | undefined;
+}
+
+/* TOKENS, NOT SUBSTRINGS. A pool is named by the plan ("Opus", "gemini") and the model by its vendor
+ * ("claude-opus-4-6", "Claude Opus 4.6"), and the two only ever agree on a word. A substring test would match
+ * "opus" inside an id that merely mentions it, and a normalized-string equality would match nothing at all. */
+export const wordsOf = (text: string): readonly string[] =>
+    text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+
+// Whether `needle` appears as a run of whole words in `words`: "claude opus" is in "claude-opus-4-6", "opus" is
+// in "Claude Opus 4.6", and "sonnet" is in neither.
+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));
+
+// The pools that gate a model, or, with no model named, every pool that gates anything at all.
+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 WILL GATE THE NEXT TURN: the fullest of the ones this model spends. A single headroom number
+ * can only ever be this one, the account is as constrained as its tightest allowance, whichever that happens
+ * to be today. Undefined when nothing gates the model (or nothing was measured), which every reader keeps
+ * distinct from a measured 0%. */
+export const bindingWindow = (usage: AccountUsage | undefined, model?: ModelRef): UsageWindow | undefined => fullest(gatingWindows(usage, model));
+
+/* THE POOL A PLAN METERS THIS MODEL BY ON ITS OWN, when it does: the model-scoped window whose name is the most
+ * specific match. Distinct from bindingWindow, which answers "what stops the next turn" and may well be the
+ * all-models weekly; this answers "does the plan keep a separate allowance for this tier", which is what a
+ * sentence naming the allowance wants ("Opus 82% used").
+ *
+ * AMBIGUITY ANSWERS NOTHING. Two pools matching one model at the same specificity (a plan metering "Opus" and
+ * "Claude Opus" separately, or the same name twice) means we cannot say which allowance a turn spends, so the
+ * more specific one wins and a tie returns undefined: no sentence beats a sentence naming the wrong pool. */
+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;
+};

package/src/provider-specs.test.ts

@@ -0,0 +1,130 @@
+import { PROVIDER_BRAND_PATHS } from "@intentic/constants";
+import { describe, expect, test } from "vitest";
+import { accessFor, capabilitiesOf, harnessChoosable, PROVIDER_ACCESS, PROVIDER_VENDOR, PROVIDERS, providerLabel } from "./agent-catalog.js";
+import { ACCESS_COST, cliProxyIdOf, KEY_PROVIDERS, keyEndpointOf, NATIVE_PROVIDERS, PROVIDER_SPECS, providerSpec } from "./provider-specs.js";
+import { NativeProviderParamSchema } from "./schemas/agent.js";
+import { TranslatorAccountsSchema } from "./schemas/plan-limits.js";
+import { KeyedProviderSchema } from "./schemas/provider-subscriptions.js";
+
+/* THE SPEC TABLE'S OWN GUARD, and it walks the TABLE rather than a list of names, which is the property that
+ * makes it worth having: a provider added tomorrow is covered the day it is added, and one removed takes its
+ * assertions with it.
+ *
+ * What it is for. Ten surfaces used to keep their own enumeration of the same providers; six were
+ * `Record<NativeProvider, …>` and could not be short a row, and the other four were arrays and if-chains that
+ * silently could. Those four are derived now, and this is what says so: for every provider in the table, every
+ * derived list contains it, and every derived answer is one a surface can actually render. */
+
+describe("every provider in the table", () => {
+    test.each(PROVIDER_SPECS.map((spec) => ({ id: spec.id, spec })))("$id is described completely", ({ id, spec }) => {
+        // The strings a surface prints. Empty is the failure worth naming: each of these lands somewhere a
+        // person reads, and a blank one renders as a row with no name rather than as an error anybody notices.
+        for (const [field, value] of Object.entries({
+            label: spec.label,
+            vendor: spec.vendor,
+            accountLabel: spec.accountLabel,
+            destination: spec.destination,
+            requirement: spec.access.requirement,
+            runs: spec.access.runs,
+        })) {
+            expect(value.trim(), `${id}.${field}`).not.toBe("");
+        }
+        // A brand mark, not the fallback glyph. `brand` is typed against these keys so this cannot fail without
+        // someone reaching for a cast, which is exactly when a test earns its place.
+        expect(PROVIDER_BRAND_PATHS[spec.brand], `${id} has no brand mark`).toEqual(expect.any(String));
+        expect(ACCESS_COST[spec.access.kind], `${id} has an unpriced access kind`).toBeTypeOf("number");
+    });
+
+    test.each(PROVIDER_SPECS.map((spec) => ({ id: spec.id, spec })))("$id declares a reachable credential", ({ id, spec }) => {
+        if (spec.auth.kind === "translator") {
+            // The proxy's own name for it, which is what the daemon addresses its management API by. Reading
+            // back undefined here is the `…/model-definitions/undefined` request that used to be possible.
+            expect(cliProxyIdOf(id), `${id} is routed but names no CLIProxyAPI provider`).toBe(spec.auth.cliProxy);
+            expect(KeyedProviderSchema.options, `${id} is routed but missing from KeyedProvider`).toContain(id);
+            expect(Object.keys(TranslatorAccountsSchema.shape), `${id} has no slot in TranslatorAccounts`).toContain(id);
+            return;
+        }
+        if (spec.auth.kind === "key") {
+            const endpoint = keyEndpointOf(id);
+            expect(endpoint, `${id} is keyed but names no endpoint`).toMatchObject({ kind: "key" });
+            expect(KEY_PROVIDERS, `${id} is keyed but missing from KEY_PROVIDERS`).toContain(id);
+            /* THE TURN URL AND THE CATALOG URL ARE DIFFERENT SURFACES OF ONE VENDOR, and both halves of that
+             * sentence are asserted: same host (a pair that drifted apart would send the catalog to one vendor
+             * and the turn to another), and the turn's base carries NO version segment, because the harness
+             * appends `/v1/messages` itself and a doubled one is a 404 mid-conversation. */
+            expect(new URL(endpoint!.anthropicBase).host, `${id}'s catalog and turn hosts differ`).toBe(new URL(endpoint!.catalogBase).host);
+            expect(endpoint!.anthropicBase, `${id}'s turn base carries a version segment the harness would double`).not.toMatch(/\/v\d+$/);
+            expect(new URL(endpoint!.console).protocol, `${id}'s key console is not a link`).toBe("https:");
+            return;
+        }
+        // An oauth provider is served by a handshake this daemon runs; it is in neither routed list.
+        expect(KeyedProviderSchema.options, `${id} is not routed but appears in KeyedProvider`).not.toContain(id);
+        expect(KEY_PROVIDERS, `${id} is not keyed but appears in KEY_PROVIDERS`).not.toContain(id);
+    });
+
+    test.each(PROVIDER_SPECS.map((spec) => ({ id: spec.id })))("$id is in every derived list", ({ id }) => {
+        expect(NATIVE_PROVIDERS).toContain(id);
+        expect(
+            PROVIDERS.map((option) => option.value),
+            "the picker's list",
+        ).toContain(id);
+        expect(Object.keys(PROVIDER_ACCESS), "the access table").toContain(id);
+        expect(Object.keys(PROVIDER_VENDOR), "the vendor table").toContain(id);
+        // The catalog route's param schema is closed over the same vocabulary, so a provider the daemon holds a
+        // catalog for but the schema does not name is a 400 on its own models route.
+        expect(NativeProviderParamSchema.safeParse({ provider: id }).success, "the catalog route's param").toBe(true);
+        // The two lookups every surface goes through, rather than the tables behind them.
+        expect(providerSpec(id)?.id).toBe(id);
+        expect(accessFor(id)?.requirement).toEqual(expect.any(String));
+        expect(providerLabel(id)).not.toBe(id);
+    });
+});
+
+/* IDS ARE THE KEY EVERYTHING ELSE IS FILED UNDER, so a duplicate is not a cosmetic problem: the derived Records
+ * would silently keep the last row, and `providerSpec` the first. */
+test("provider ids are unique", () => {
+    const ids = PROVIDER_SPECS.map((spec) => spec.id);
+    expect(new Set(ids).size).toBe(ids.length);
+});
+
+/* An id may contain neither a slash nor a colon, and both exclusions are load-bearing rather than tidy.
+ * `endpoint/<id>` uses the slash to namespace a capability-minted provider, and the picker's pinned selections
+ * are `${provider}:${model}` split on the FIRST colon (quick-model.ts), so an id carrying either would parse as
+ * something else entirely, silently. */
+test("no provider id can be mistaken for an endpoint or a pinned selection", () => {
+    for (const spec of PROVIDER_SPECS) {
+        expect(spec.id, `${spec.id} would collide with the picker's key shapes`).toMatch(/^[a-z0-9-]+$/);
+    }
+});
+
+/* THE HARNESS AXIS IS A FACT ABOUT THE TABLE, not a list any surface keeps. A provider whose two runtimes are
+ * the same one has nothing to choose, and the chip must not be offered; one with two must offer it. Both
+ * directions matter: the version of this that lived in the web named two providers and would have offered
+ * Kimi, Meta and Z.ai a switch between two identical loops. */
+test("the harness chip is offered exactly where the two harnesses run different loops", () => {
+    for (const spec of PROVIDER_SPECS) {
+        const native = capabilitiesOf(spec.id, "native");
+        const claudeCode = capabilitiesOf(spec.id, "claude-code");
+        expect(harnessChoosable(spec.id), `${spec.id}`).toBe(native.runtime !== claudeCode.runtime);
+    }
+});
+
+/* A KEYED PROVIDER HAS NO NATIVE RUNTIME, by construction rather than by coincidence: it is reached by pointing
+ * the Claude Code loop at the vendor's own Anthropic endpoint, and there is no second loop to point anywhere
+ * else. A spec row that claimed one would produce a picker chip offering a runtime nothing serves. */
+test("a keyed provider runs the Claude Code loop on both harnesses", () => {
+    for (const provider of KEY_PROVIDERS) {
+        expect(capabilitiesOf(provider, "native").runtime, provider).toBe("claude-code");
+        expect(capabilitiesOf(provider, "claude-code").runtime, provider).toBe("claude-code");
+    }
+});
+
+// An id that names no provider must fall through every lookup rather than resolving to a neighbour's row, which
+// is what makes ACP agents and endpoint capabilities safe to name with arbitrary strings.
+test("an id that is not a provider resolves to nothing", () => {
+    for (const id of ["", "some-installed-agent", "endpoint/ollama", "META", "z.ai"]) {
+        expect(providerSpec(id), id).toBeUndefined();
+        expect(cliProxyIdOf(id), id).toBeUndefined();
+        expect(keyEndpointOf(id), id).toBeUndefined();
+    }
+});