@intentic/sandbox-contract 1.246.1 → 1.248.0

package/src/agent-run-model.test.ts

@@ -1,76 +0,0 @@
-import { expect, test } from "vitest";
-import { resolveAgentRunModels } from "./agent-run-model.js";
-import type { QuickModelSource } from "./quick-model.js";
-import type { AgentRunPin } from "./schemas/agent.js";
-
-/* Which model a run somebody's BUTTON started opens on. The rule answers the same two surfaces its quick-model
- * sibling does: the daemon walks it, the settings row names it, so what these pin is the pair of properties
- * that separate the two: an account this sandbox cannot reach never sits at the head of the chain, and an empty
- * answer stays empty rather than being filled in with a tier nobody chose.
- *
- * And one property neither of those covers, new with the pins being objects: an entry's own knobs are the
- * entry's, so what survives the walk is the WHOLE pin. A resolver that handed back the pair inside it would run
- * the fallback at the head's effort, which is a tier that appears nowhere on the user's screen. */
-
-const CLAUDE: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-opus-5`, `claude-sonnet-5`] };
-const CODEX: QuickModelSource = { provider: `codex`, ready: true, models: [`gpt-5.6`] };
-const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`gemini-3-pro`] };
-
-const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
-
-const pin = (provider: string, model: string, knobs: Partial<AgentRunPin> = {}): AgentRunPin => ({ provider, model, ...knobs });
-
-test("keeps the user's own order, this list is read, never ranked", () => {
-    // The opposite of the quick chain, which sorts by tier and cost. Here the order IS the setting: someone who
-    // put Opus above GPT wants Opus first, and a resolver that knew better would spend the wrong account.
-    expect(resolveAgentRunModels([CLAUDE, CODEX], [pin(`codex`, `gpt-5.6`), pin(`claude`, `claude-opus-5`)])).toEqual([
-        { provider: `codex`, model: `gpt-5.6` },
-        { provider: `claude`, model: `claude-opus-5` },
-    ]);
-});
-
-test("steps over a provider this sandbox has no credential for", () => {
-    // The whole reason the setting is a list. With Claude disconnected the head would otherwise be an account
-    // that fails every Fix with agent, while a perfectly good Codex sits underneath it.
-    expect(resolveAgentRunModels([offline(CLAUDE), CODEX], [pin(`claude`, `claude-opus-5`), pin(`codex`, `gpt-5.6`)])).toEqual([
-        { provider: `codex`, model: `gpt-5.6` },
-    ]);
-});
-
-test("each surviving entry keeps its own knobs, not the head's", () => {
-    // The effort used to be one setting beside the list, so a fallback ran at whatever the head was set to. It
-    // is now a property of the entry that actually answers, which is the only place it was ever true.
-    expect(
-        resolveAgentRunModels(
-            [offline(CODEX), CLAUDE],
-            [pin(`codex`, `gpt-5.6`, { effort: `low` }), pin(`claude`, `claude-opus-5`, { effort: `max`, thinking: true })],
-        ),
-    ).toEqual([{ provider: `claude`, model: `claude-opus-5`, effort: `max`, thinking: true }]);
-});
-
-test("resolves to nothing when no pin is reachable: it does NOT fall back to whatever is connected", () => {
-    // The deliberate difference from resolveQuickModels, which lands on its Auto ladder here. An agent run is
-    // billed in whole sessions, so an unreachable list hands the choice back to the caller's floor (the user's
-    // own composer pick) rather than spending an account they never pointed at.
-    expect(resolveAgentRunModels([offline(CLAUDE), GOOGLE], [pin(`claude`, `claude-opus-5`)])).toEqual([]);
-});
-
-test("an empty list resolves to nothing even with accounts connected", () => {
-    expect(resolveAgentRunModels([CLAUDE, CODEX, GOOGLE], [])).toEqual([]);
-});
-
-test("drops a duplicate rather than spending two attempts proving one account is out, and the first one's knobs are the ones kept", () => {
-    // Two entries can now name one model and disagree about how hard it thinks, which is what reordering a list
-    // by hand produces. The one the user reads first is the one they meant.
-    expect(
-        resolveAgentRunModels([CLAUDE], [pin(`claude`, `claude-opus-5`, { effort: `max` }), pin(`claude`, `claude-opus-5`, { effort: `low` })]),
-    ).toEqual([{ provider: `claude`, model: `claude-opus-5`, effort: `max` }]);
-});
-
-test("carries a model id the static catalog has never heard of", () => {
-    // The picker offers a custom-id escape hatch, so a pin can name a model released after this build. Second-
-    // guessing it here would quietly run something other than what the settings row says.
-    expect(resolveAgentRunModels([CLAUDE], [pin(`claude`, `claude-opus-9-preview`)])).toEqual([
-        { provider: `claude`, model: `claude-opus-9-preview` },
-    ]);
-});

package/src/agent-run-model.ts

@@ -1,65 +0,0 @@
-import { quickModelKey, type QuickModelSource } from "./quick-model.js";
-import type { AgentRunPin } from "./schemas/agent.js";
-
-/* WHAT A SURFACE-STARTED AGENT RUN OPENS ON, the resolver for `agentRunModels`, sibling to resolveQuickModels
- * and deliberately not the same function.
- *
- * BOTH ARE ORDERED LISTS, FOR THE SAME REASON. One connected account whose allowance went on the chat this
- * morning is enough to take every one of these down: the user presses Fix with agent on a red pipeline, an
- * isolated session opens, and it dies on a credential error they cannot see from the row. Written in order, the
- * next entry catches it.
- *
- * THEY DIFFER ON WHAT AN EMPTY LIST MEANS, and that difference is the whole reason this is its own file rather
- * than a flag on the other one. A quick helper exists to stay OFF the frontier tier, so "work it out from what
- * is connected" is a good answer and quickModel's empty list resolves to a derived Auto ladder. An agent run is
- * a full session with a worktree, billed whole: nothing here can judge whether a job is worth the frontier tier,
- * so an empty list resolves to NOTHING and the caller falls back to the model the user picked for their own
- * chat, a choice they made, rather than one this file guessed for them. For the same reason there is no Auto
- * ladder underneath a list that has been emptied by disconnection: it would spend an account the user never
- * pointed at, on the most expensive kind of run this app starts.
- *
- * WHAT "STEPPED OVER" MEANS HERE IS NARROWER than the quick chain's, and worth being exact about. The quick
- * chain re-asks the next rung when a call comes back refused, because a one-shot that failed has cost nothing
- * and can simply be run again. An agent session cannot be replayed that way, by the time a provider refuses
- * mid-turn the agent may have already edited files, so this list is read ONCE, at the moment the turn is
- * composed, and steps over exactly one thing: an account that is not connected. A model that accepts the turn
- * and fails later is a failed run the user reads on the card, like any other. */
-
-/* The pins that could actually be started right now, in the user's own order.
- *
- * `sources` is the same readiness view resolveQuickModels takes, so both settings rows agree about which
- * accounts this sandbox can send to, a pin greyed as "Not connected" in one row and silently spent by the
- * other would be the worst of both.
- *
- * A pin whose provider is gone is DROPPED rather than held: it would otherwise sit at the head of the chain
- * failing every run, which is exactly what the list exists to prevent. It stays on SCREEN, greyed, the settings
- * row renders the stored list, not this one, because a setting that vanished from view would look like the app
- * had eaten it.
- *
- * THE WHOLE PIN SURVIVES, not the pair inside it: the entry's own effort, harness and cost knobs are what the
- * turn is composed from (turn-resume.ts), so a resolver that handed back a bare (provider, model) would silently
- * run the head of the list at the provider's defaults. Nothing here reads or judges those fields, which is the
- * point of carrying them whole.
- *
- * Empty out means nobody has pinned anything this sandbox can reach, and the caller's floor takes over. */
-export const resolveAgentRunModels = (sources: readonly QuickModelSource[], pinned: readonly AgentRunPin[]): readonly AgentRunPin[] => {
-    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
-    // Taken verbatim, unvalidated against the catalog, the same reading resolveQuickModels gives its keys and
-    // for the same reason: the picker offers a custom-id escape hatch for a model the static catalog has not
-    // caught up with, and second-guessing the id here would run a different model than the settings row names.
-    const requested = pinned.filter((pin) => ready.has(pin.provider));
-    /* The same model twice would spend two attempts proving the same account is out. Hand-edited list, so this
-     * is a real state rather than a defensive branch.
-     *
-     * THE FIRST OF A PAIR WINS, WHOLE. Two entries can now name one model and differ in their knobs (the same
-     * Sonnet at Max and again at Low, written while reordering the list), and the one the user reads first is
-     * the one they meant; keeping the earlier position with the later entry's effort would run a tier that
-     * appears nowhere the pin does. */
-    const chain: AgentRunPin[] = [];
-    for (const pin of requested) {
-        if (!chain.some((held) => quickModelKey(held) === quickModelKey(pin))) {
-            chain.push(pin);
-        }
-    }
-    return chain;
-};

package/src/quick-model.test.ts

@@ -1,158 +0,0 @@
-import { expect, test } from "vitest";
-import { type QuickModelChoice, type QuickModelSource, quickModelKey, resolveQuickModels } from "./quick-model.js";
-
-/* Which models a small automatic helper spends, and in which order. The rule answers two surfaces at once:
- * the daemon walks it, the browser names its head in the settings row, so what these tests pin is that a
- * sandbox's connections alone decide it, with no stored id to go stale, and that there is always a rung
- * underneath the first one whenever the sandbox has another account to reach for. */
-
-// 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.6`, `kimi-k2.7-code`, `kimi-k3`] };
-
-const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
-
-// The model that answers when nothing goes wrong: the head of the chain, which is what most of what follows is
-// about and what every surface naming the spend up front reads.
-const head = (sources: readonly QuickModelSource[], pinned: readonly string[]): QuickModelChoice | undefined =>
-    resolveQuickModels(sources, pinned)[0];
-
-test("reaches for the efficient rung of the one connected provider, never its flagship", () => {
-    expect(head([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. A background helper should not quietly bill the Claude plan.
-    expect(head([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(head([CLAUDE, proOnly], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-});
-
-test("uses stable provider order when two subscriptions offer the same tier", () => {
-    const kimiCheap: QuickModelSource = { provider: `kimi`, ready: true, models: [`kimi-k2-mini`] };
-    const claudeCheap: QuickModelSource = { provider: `claude`, ready: true, models: [`claude-haiku-4-5`] };
-
-    expect(head([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 = [head([CLAUDE, GOOGLE, CODEX], []), head([CODEX, CLAUDE, GOOGLE], []), head([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(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 catalog can lag a release, and running something
-    // other than what the settings row names would be the worse failure.
-    expect(head([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(head([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(head([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(head([KIMI], [])).toEqual({ provider: `kimi`, model: `kimi-k3` });
-});
-
-test("reports nothing when no account is connected, so the button can say so instead of failing on click", () => {
-    expect(head([offline(CLAUDE), offline(GOOGLE)], [])).toBeUndefined();
-    expect(resolveQuickModels([offline(CLAUDE), offline(GOOGLE)], [])).toEqual([]);
-    expect(head([], [`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(head([unloaded, CLAUDE], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-    expect(head([unloaded], [])).toBeUndefined();
-});
-
-/* THE CHAIN: what the daemon walks when the model at the top of it refuses. A spent allowance is the ordinary
- * case, not the exotic one: the account a helper shares with the chat runs out mid-afternoon, and the whole
- * point of the list is that the click still lands on the next rung down. */
-
-test("keeps the pinned models in the order they were written", () => {
-    expect(resolveQuickModels([CLAUDE, GOOGLE, CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5-20251001`])).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(resolveQuickModels([CLAUDE, offline(GOOGLE), CODEX], [`codex:gpt-5.6`, `gemini:gemini-3-flash`, `claude:claude-haiku-4-5`])).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", () => {
-    // Google and Kimi are connected and cheaper. The user wrote down one model, so one model is what this may
-    // spend: a pin exists precisely to keep a helper off the accounts it does not name.
-    expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [`claude:claude-haiku-4-5`])).toEqual([{ provider: `claude`, model: `claude-haiku-4-5` }]);
-});
-
-test("names each model once, however many times the list repeats it", () => {
-    // The list is edited by hand; a duplicate would spend a second attempt proving the same account is out.
-    expect(resolveQuickModels([CLAUDE], [`claude:claude-haiku-4-5`, `claude:claude-haiku-4-5`])).toEqual([
-        { provider: `claude`, model: `claude-haiku-4-5` },
-    ]);
-});
-
-test("Auto is a ladder too, every connected provider's cheap rung, best first", () => {
-    expect(resolveQuickModels([CLAUDE, GOOGLE, KIMI], [])).toEqual([
-        { provider: `gemini`, model: `gemini-3-flash-lite` },
-        { provider: `claude`, model: `claude-haiku-4-5-20251001` },
-        { provider: `kimi`, model: `kimi-k3` },
-    ]);
-});
-
-/* A MODEL ENDPOINT the user configured is a provider like any other here, and the reason it has to be is the
- * settings row: its options are built from the same picker catalog, so a pin naming one that this resolver
- * dropped would print one model's name in the settings row and spend a different account entirely. */
-const OLLAMA: QuickModelSource = { 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` });
-    // And it round-trips through the key shape the picker mints, which is where the slash-not-colon rule earns
-    // itself: parsePinned splits on the FIRST colon, so an `endpoint:ollama` id would have parsed the provider
-    // as "endpoint" and the model as "ollama:qwen3-coder": a pin that silently resolves to nothing.
-    expect(quickModelKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
-});
-
-test("leaves Auto to the providers whose price is known, rather than reaching for someone's own server", () => {
-    // Claude publishes a Haiku-class row; the endpoint's ids carry no tier word at all, so they are UNRANKED and
-    // lose on tier. What a turn on a user's own model API costs is not a fact this repo holds, and Auto should
-    // not be asserting one.
-    expect(head([CLAUDE, OLLAMA], [])).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
-});
-
-test("still answers from an endpoint when it is the only thing configured", () => {
-    // No tier word in either id, so the shared id-derived ordering decides between them exactly as it does for
-    // Kimi above: the point here is that a sandbox whose only model API is its owner's still gets an answer
-    // rather than the disabled "nothing connected" button.
-    expect(head([offline(CLAUDE), OLLAMA], [])).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
-});

package/src/quick-model.ts

@@ -1,162 +0,0 @@
-import { accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js";
-import { ACCESS_COST } from "./provider-specs.js";
-import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import type { AgentProvider } from "./schemas/agent.js";
-
-/* THE QUICK MODEL, the cheap, fast model a small automatic job spends instead of the frontier model the chat
- * runs on. Today that is the commit message written when an agent's work lands; 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.
- *
- * IT IS AN ORDER, NOT A MODEL, and that is the whole shape of this file. A single pick is a single point of
- * failure: the account it names spends its allowance on the chat all morning, and every job for the rest of the
- * day fails on a limit while three other connected providers sit idle. So the setting is a LIST
- * read top to bottom, the resolver hands back the whole ladder, and the daemon walks it until one answers.
- * Nothing here decides WHICH failures are worth stepping over, that is the daemon's, since only it has run
- * the call, this side only says what the running order is.
- *
- * 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 settings row's "Auto (…)" label, before anything has been
- * run. Two implementations would drift precisely where it matters most, since a label promising Haiku while the
- * daemon bills Opus is worse than no label.
- *
- * The default is DERIVED, NEVER STORED. `quickModel` ships EMPTY and that means "work it out from whatever is
- * connected right now", so connecting a Google account tomorrow improves the default by itself and
- * disconnecting a 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. `endpoint/<id>` providers ARE, and have to be: their
- * models appear in the same picker the settings row builds its options from, so a pin naming one has to hold
- * rather than fall silently back to Auto and spend an account the user was deliberately steering away from. */
-export interface QuickModelSource {
-    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
-    // ranking degrades gracefully for one, costOf falls to the metered rung and an id with no tier word is
-    // UNRANKED, which is genuine last place, so an endpoint effectively only wins Auto when nothing else is
-    // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
-    // costs is not a fact this repo can know, so it is not one Auto should be asserting.
-    readonly provider: AgentProvider;
-    // 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: AgentProvider;
-    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). An empty LIST of these ⇒ 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. Exported because the
- * key is what several surfaces carry a pinned pair AS: `autoFastModels` stores the same keys, the settings rows
- * read one back to draw the model they name, and a session composed from a pin travels as one (composeSession).
- *
- * `agentRunModels` is the one list that does NOT: an agent-run entry is an object, because it carries how the
- * model is to be run beside which model it is (AgentRunPinSchema), and a key with knobs spelled into it would
- * be a second encoding of the same thing for nobody's benefit. */
-export 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), model: pinned.slice(separator + 1) };
-};
-
-/* A pin as a person reads it: the catalog's own label for the id, or the id itself for one the static catalog
- * has not caught up with (the picker offers a custom-id escape hatch, so this is a real case rather than a
- * defensive branch). Beside parsePinned because the two are always wanted together, by any surface that has to
- * name what a click is about to spend BEFORE it spends it, and the two loudest of those are extensions that
- * share no other code with each other. */
-export const pinnedModelLabel = (choice: QuickModelChoice): string =>
-    modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
-
-// 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. An endpoint is in no fixed
-// list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
-const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
-
-/* WHAT AN ENDPOINT COSTS, one rung past every provider's, and the reason it is a number here rather than a
- * member of AccessKind. That axis describes the providers this repo ships, and every one of them is unlocked by
- * signing in to something the user already holds, so none of them is metered per call. An endpoint is the
- * opposite: whatever gateway somebody pointed us at, whose bill this repo cannot see. Reading it as dearer than
- * anything on the table is the conservative answer, and it is what keeps Auto from reaching for a paid gateway
- * on its own initiative. */
-const METERED_COST = Math.max(...Object.values(ACCESS_COST)) + 1;
-
-// How much a call on this provider costs at the margin. Every native provider declares an access kind; an
-// endpoint declares none, and takes the metered rung above.
-const costOf = (provider: AgentProvider): number => {
-    const access = accessFor(provider);
-    return access === undefined ? METERED_COST : ACCESS_COST[access.kind];
-};
-
-/* AUTO, every connected provider's cheapest row, best-first, as a ladder rather than a winner.
- *
- * Ranked 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.
- *
- * The whole ladder, not just its head, because the same ranking that picks the best answer also states the best
- * SECOND answer, and a sandbox with three accounts connected should not lose its commit messages for six hours
- * because one of them is spent. */
-const autoLadder = (sources: readonly QuickModelSource[]): readonly QuickModelChoice[] =>
-    sources
-        .filter((source) => source.ready)
-        .flatMap((source) => {
-            const model = cheapestOf(source);
-            return model === undefined ? [] : [{ provider: source.provider, model }];
-        })
-        .toSorted(
-            (left, right) =>
-                tierOf(right.model) - tierOf(left.model) ||
-                costOf(left.provider) - costOf(right.provider) ||
-                providerOrder(left.provider) - providerOrder(right.provider),
-        );
-
-/* WHICH MODELS A QUICK HELPER MAY RUN, IN THE ORDER IT SHOULD TRY THEM, given what this sandbox has connected.
- * `pinned` is the stored setting: an ordered list of `${provider}:${model}` keys, empty for Auto.
- *
- * A pin only holds while its provider is READY: an account the user disconnected would otherwise sit at the
- * head of the chain failing on a credential error, when the sandbox can plainly still answer. Dropping it is
- * the same move the composer already makes when a live catalog stops offering the selected model.
- *
- * THE PINNED LIST IS THE WHOLE ANSWER whenever any of it survives that filter. Auto does NOT get appended
- * underneath, and that is deliberate: a user who writes down three models has said which accounts this feature
- * may spend, and quietly reaching for a fourth when all three are out is exactly the "spend an account they
- * were steering away from" failure a pin exists to prevent. When NONE of the pins is connected any more the
- * list has stopped saying anything about this sandbox, so Auto takes over rather than leaving a dead button.
- *
- * Empty when nothing is connected: the caller renders a control that says so, rather than a live button that
- * fails on click. */
-export const resolveQuickModels = (sources: readonly QuickModelSource[], pinned: readonly string[]): readonly QuickModelChoice[] => {
-    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
-    const requested = pinned.flatMap((key) => {
-        // 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.
-        const choice = parsePinned(key);
-        return choice === undefined || !ready.has(choice.provider) ? [] : [choice];
-    });
-    // The same model twice would spend two attempts proving the same account is out, a real state, since the
-    // list is edited by hand and Auto's ladder can rank a provider the user has also pinned.
-    const chain = [...new Map(requested.map((choice) => [quickModelKey(choice), choice])).values()];
-    return chain.length > 0 ? chain : autoLadder(sources);
-};

package/src/schemas/context.ts

@@ -1,87 +0,0 @@
-// context: which part of the workspace a conversation carries
-import { z } from "zod";
-import { entryId } from "./internal.js";
-
-/* A CONVERSATION SEES A CHOSEN PART OF THE WORKSPACE, and these three schemas are how the choice is spelled.
- *
- * A workspace grows into more than any one session should open on: dozens of repositories, hundreds of skills,
- * a shelf of reference clones. Every conversation used to get all of it, one worktree per repository, frozen at
- * its first turn (sandbox agents/worktrees.ts). The cost is paid twice, in checkouts nobody reads and in a
- * project map and a skill listing that describe everything to a session that needs a corner of it
- * (docs/context-composition-plan.md at the workspace root measures both).
- *
- * THREE WORDS. A SHELF is what the owner writes: the items a session MAY take, in the order they are loaded and,
- * when a cap bites, shed from the tail. A COMPOSITION is the pick for one conversation, a list of item ids in
- * shelf order, stored on its registry entry. An ITEM ID names one thing in the workspace, `<kind>:<name>`.
- *
- * ONE KIND TODAY, `repo:`, which is the whole of what a composition can make real: a repository is in the
- * conversation (a worktree of it exists) or it is not (the directory does not exist). The grammar takes a kind
- * prefix so the next ones (a directory inside a repository through a sparse cone, a skill folder, a reference
- * shelf entry, a capability) widen this list and change nothing else. The root repository is never an item: it
- * is the workspace itself and every conversation stands in it. */
-export const CONTEXT_ITEM_KINDS = ["repo"] as const;
-export type ContextItemKind = (typeof CONTEXT_ITEM_KINDS)[number];
-
-/* `<kind>:<name>`. The name is a workspace-relative path or an id: safe segments, no `..`, no empty segment, so
- * joining it under a root can never escape, the same shape repo-discovery.ts accepts for a repo id. */
-const ITEM = /^(repo):[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
-export const ContextItemIdSchema = z
-    .string()
-    .min(1)
-    .max(200)
-    .regex(ITEM)
-    .describe("One thing in the workspace a conversation can carry, as `<kind>:<name>`. Today the kind is `repo` and the name is a repository's workspace-relative path.");
-export type ContextItemId = z.infer<typeof ContextItemIdSchema>;
-
-// The two halves of an id, for the code that has to act on the name. The schema above already proved the shape.
-export const contextItem = (id: ContextItemId): { readonly kind: ContextItemKind; readonly name: string } => {
-    const at = id.indexOf(":");
-    return { kind: id.slice(0, at) as ContextItemKind, name: id.slice(at + 1) };
-};
-
-/* HOW MANY OF EACH KIND A COMPOSITION MAY HOLD. Counted per kind because the kinds cost differently: a repository
- * is a checkout, a skill is a line in every prompt. Absent means no limit. A pinned item is never shed to meet
- * a cap: `pinned` is the owner saying "always", and a cap that could override it would make two fields disagree
- * about the same item. */
-export const ContextCapsSchema = z.object({
-    repos: z.number().int().min(0).optional().describe("How many repositories a composition may hold. Absent means as many as the shelf allows."),
-});
-export type ContextCaps = z.infer<typeof ContextCapsSchema>;
-
-/* WHAT A SESSION MAY TAKE, in the owner's order. One file per shelf under `.intentic/config/context/<id>.json`,
- * tracked and carried like a persona card (workspace-state.ts), for the same reason: a shelf is a list of
- * names, holds no credential, and belongs in a pull request.
- *
- * `allowed` IS ORDERED, and the order is the only priority there is: it is what a curator is shown, the order
- * items are loaded, and the order they are shed from the tail when a cap is hit. The owner fixes the order and
- * the ceiling; whoever picks (a model, a person on the card, the shelf itself when nobody picks) decides
- * membership and nothing else.
- *
- * `pinned` is always in, whether or not it is also listed in `allowed`. `denied` wins over everything, including
- * a pinned item, so a shelf that inherits a list it did not write can still take one thing off it. */
-export const ContextShelfSchema = z.object({
-    id: entryId.describe("The shelf's id, which is also its file name."),
-    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id."),
-    pinned: z.array(ContextItemIdSchema).max(200).default([]).describe("Items every composition from this shelf carries."),
-    allowed: z
-        .array(ContextItemIdSchema)
-        .max(500)
-        .default([])
-        .describe("Items a composition may carry, in the order they are loaded and shed. The order is the priority; nothing else is."),
-    denied: z.array(ContextItemIdSchema).max(200).default([]).describe("Items no composition from this shelf carries, whatever else says so."),
-    caps: ContextCapsSchema.optional().describe("How many of each kind a composition may hold."),
-});
-export type ContextShelf = z.infer<typeof ContextShelfSchema>;
-
-/* THE PICK FOR ONE CONVERSATION, on its registry entry beside the worktree composition it decides.
- *
- * `items` is exactly what the conversation carries, in shelf order, and the root repository besides. A
- * conversation whose entry has NO composition carries everything the workspace has, which is what every
- * conversation did before shelves existed and what a conversation opened with no shelf still does. Those two
- * are one state on purpose: the absence is the answer, and a stored "everything" would be a second spelling of
- * it that could disagree with the first. */
-export const ContextCompositionSchema = z.object({
-    shelf: entryId.optional().describe("Which shelf this pick was made from. Absent when the items were set without one."),
-    items: z.array(ContextItemIdSchema).max(500).describe("What the conversation carries, in shelf order. The root repository is always carried and never listed."),
-});
-export type ContextComposition = z.infer<typeof ContextCompositionSchema>;