@intentic/sandbox-contract 1.248.0 → 1.250.0

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

package/src/{prompt-complexity.test.ts → models/prompt-complexity.test.ts}

@@ -1,14 +1,8 @@
 import { expect, test } from "vitest";
 import { type ComplexityInput, FAST_CEILING, judgeComplexity } from "./prompt-complexity.js";
 
-/* WHETHER A TURN COULD HAVE RUN ON THE CHEAP RUNG, judged before anything is spent.
- *
- * What these tests pin is the ASYMMETRY, not the accuracy: the judge can only ever route down, so every one of
- * its mistakes in the "standard" direction costs a fraction of a cent and every mistake in the "fast" direction
- * costs a user their turn. So the properties worth nailing down are that silence resolves to standard, that a
- * gate or an escalating rule ends the question whatever else the sentence says, and that no rule ORDER can
- * change an answer. The weights themselves are a hypothesis with a ledger under it (settings.autoTier
- * "shadow"), and a test that froze them would be a test that made them impossible to fit. */
+// Pins the asymmetry: the judge only ever routes down, so silence resolves to standard, any escalating rule or gate
+// wins regardless of order, and the weights (settings.autoTier "shadow") stay unpinned.
 
 const turn = (prompt: string, over: Partial<ComplexityInput> = {}): ComplexityInput => ({
     prompt,
@@ -23,24 +17,16 @@ const turn = (prompt: string, over: Partial<ComplexityInput> = {}): ComplexityIn
 
 const tierOf = (prompt: string, over: Partial<ComplexityInput> = {}) => judgeComplexity(turn(prompt, over)).tier;
 
-// --- silence, and what it is read as -----------------------------------------------------------------
-
 test("a prompt matching nothing at all stays on the model the user picked", () => {
-    // The single most important default in the file. An unrecognised request is MEDIUM, never simple: the
-    // conservative reading of silence is the only safe one when a wrong downgrade costs a retry and a
-    // user who stops trusting the feature.
     const verdict = judgeComplexity(turn(`Have another go at the thing we were discussing yesterday afternoon`));
 
     expect(verdict.tier).toBe(`standard`);
     expect(verdict.score).toBeGreaterThan(FAST_CEILING);
-    // Nothing in the sentence made a positive claim in either direction, so only the two absence features
-    // fired, and the pair of them cannot reach the ceiling by design.
+    // Only the two absence features fire on this input; together they cannot reach the ceiling.
     expect(verdict.rules).toEqual([`short-prompt`, `no-workspace-reference`]);
 });
 
 test("a short vague request is not read as an easy one", () => {
-    // Absence of complexity is not evidence of simplicity. Weighted the obvious way, "short and naming no
-    // file" reached the ceiling by itself and downgraded every terse request in the product.
     expect(tierOf(`fix the bug`)).toBe(`standard`);
     expect(tierOf(`have a look at the thing we discussed`)).toBe(`standard`);
 });
@@ -49,37 +35,26 @@ test("an empty-ish prompt is not mistaken for an easy one", () => {
     expect(tierOf(`   `)).toBe(`standard`);
 });
 
-// --- the fast end ------------------------------------------------------------------------------------
-
 test("a short question about nothing in the workspace is the case this feature exists for", () => {
     expect(tierOf(`what is a closure?`)).toBe(`fast`);
 });
 
 test("naming a file keeps an otherwise easy question on the user's own model", () => {
-    // "explain" is the easiest word in the lexicon, but the turn is now about real code in this repo rather
-    // than about a concept, and the cheap rung's failures on real code are the silent kind.
+    // Same easy word; naming a real file, not a concept, tips the verdict to standard.
     expect(tierOf(`explain what is a closure`)).toBe(`fast`);
     expect(tierOf(`explain what src/agent/turn-plan.ts does`)).toBe(`standard`);
 });
 
 test("a trivial aside inside a hard conversation still gets through", () => {
-    // The reason afterHardTurn is a weight and not a lock: a conversation that has been doing hard work is
-    // still allowed to be asked an easy question, and locking it out is a mechanism that saves nothing.
     expect(tierOf(`what is a closure?`, { afterHardTurn: true })).toBe(`fast`);
 });
 
 test("a workspace-adjacent errand stops being cheap once the conversation has done hard work", () => {
-    // The contrast with the test above is the whole rule. A pure knowledge question survives the penalty
-    // because it earns every easing feature there is; an errand about this repo does not, and after hard work
-    // it is far likelier to be the deceptive follow-up than a genuine aside.
     expect(tierOf(`list the exports`, { afterHardTurn: false })).toBe(`fast`);
     expect(tierOf(`list the exports`, { afterHardTurn: true })).toBe(`standard`);
 });
 
-// --- gates: the turn's situation, whatever its words say ---------------------------------------------
-
 test("a screenshot is never sent to the cheap rung, however simple the question about it", () => {
-    // The tier most likely to misread an image, on the turn least likely to notice that it did.
     expect(tierOf(`what is this?`, { hasImages: true, attachments: 1 })).toBe(`standard`);
 });
 
@@ -88,8 +63,6 @@ test("plan mode is a request to think, so it is never answered by the model that
 });
 
 test("a surface-started run is never downgraded, because nobody is watching it fail", () => {
-    // Same call a `run` role already makes in the other direction: a run billed whole, with a worktree in
-    // it, is not the place to spend a guess.
     expect(tierOf(`what is a closure?`, { unattended: true })).toBe(`standard`);
 });
 
@@ -100,8 +73,6 @@ test("a gate reports itself and scores 1, so the ledger can tell a gate from a h
     expect(verdict.rules).toContain(`unattended`);
 });
 
-// --- escalating rules: any one ends the question ------------------------------------------------------
-
 test.each([
     [`pasted code`, "explain this\n```ts\nconst x = 1;\n```"],
     [`a stack trace`, "it broke\n  at Object.run (/work/x.ts:12:3)"],
@@ -116,9 +87,7 @@ test.each([
 });
 
 test("an escalating rule beats every easing feature at once, so rule order cannot change an answer", () => {
-    // Short, easy-worded, no workspace reference, a bare question: every negative weight in the file, plus one
-    // escalating rule. Monotone escalation means the rule wins, which is what makes adding a rule tomorrow a
-    // safe change: it can only ever move turns UP a tier.
+    // This prompt trips every easing weight in the file, plus one escalating rule; escalation still wins.
     const verdict = judgeComplexity(turn(`what is a race condition?`));
 
     expect(verdict.tier).toBe(`standard`);
@@ -135,11 +104,7 @@ test("three files in, the job is about a shape rather than about a file", () =>
     expect(tierOf(`have a look`, { attachments: 1 })).toBe(`standard`);
 });
 
-// --- the verdict as a record --------------------------------------------------------------------------
-
 test("names every rule that fired, because a score alone cannot say which feature did the work", () => {
-    // The ledger stores these. Re-fitting the weights against real traffic needs to know WHICH feature moved a
-    // turn, not merely that a threshold was crossed.
     const verdict = judgeComplexity(turn(`what is this?`));
 
     expect(verdict.rules).toEqual([`short-prompt`, `easy-words`, `bare-question`, `no-workspace-reference`]);
@@ -159,16 +124,10 @@ test("the score never leaves 0..1, so a stored row is always comparable against
     expect(ceiling.score).toBeLessThanOrEqual(1);
 });
 
-// --- the one dial, and the property it may not move ------------------------------------------------------
-
-/* The owner can move the cutoff (settings.autoTierEagerness) because "err toward my model or toward the cheap
- * one" is a preference nobody else can hold for them. What these pin is that the dial moves the cutoff and
- * NOTHING else, in particular not the rule that a downgrade needs something positively easy to have been said,
- * which was the property the old ceiling held only by arithmetic coincidence. */
+// eagerness moves only the cutoff; a downgrade still needs a positive easy signal at any setting.
 
 test("the dial widens what counts as simple, in the direction it says", () => {
-    // A question about a real file: eased by its words, held back by naming a path. The middle stop keeps it on
-    // the user's pick, and the eager stop is precisely the choice to let it through.
+    // Eased by its words, held back by naming a real file; balanced keeps it standard, eager lets it through.
     const aboutAFile = `explain what src/app.ts does`;
 
     expect(tierOf(aboutAFile, { eagerness: `balanced` })).toBe(`standard`);
@@ -176,8 +135,7 @@ test("the dial widens what counts as simple, in the direction it says", () => {
 });
 
 test("the cautious stop wants every easing signal at once, not merely an easy word", () => {
-    // Its whole content: leave no room for doubt. A statement in easy words still qualifies at the default,
-    // and does not here; only a short bare question naming no file survives every stop.
+    // "explain closures" fails the cautious stop (not a bare question); only a bare question clears every stop.
     expect(tierOf(`explain closures`, { eagerness: `balanced` })).toBe(`fast`);
     expect(tierOf(`explain closures`, { eagerness: `cautious` })).toBe(`standard`);
     expect(tierOf(`what is a closure?`, { eagerness: `cautious` })).toBe(`fast`);
@@ -191,8 +149,6 @@ test("an absent dial is the balanced stop, so every row recorded before it exist
 });
 
 test("no setting of the dial can downgrade a short vague request", () => {
-    // The whole safety argument for offering an eager stop at all. Absence of complexity is not evidence of
-    // simplicity at ANY cutoff, so this is a rule in the judge rather than a sum that happens to clear it.
     for (const eagerness of [`cautious`, `balanced`, `eager`] as const) {
         expect(tierOf(`fix the bug`, { eagerness })).toBe(`standard`);
         expect(tierOf(`have a look at the thing we discussed`, { eagerness })).toBe(`standard`);
@@ -200,30 +156,22 @@ test("no setting of the dial can downgrade a short vague request", () => {
 });
 
 test("the deceptive follow-up is standard at every stop, because it never says anything easy", () => {
-    /* "now do the same for the other file" is the case the whole afterHardTurn signal was built for, and the
-     * easing rule turns out to answer it more strongly than any cutoff can: those words make no positive claim
-     * of ease, so no setting of the dial reaches them. The weight still does its own job one test down. */
     for (const eagerness of [`cautious`, `balanced`, `eager`] as const) {
         expect(tierOf(`now do the same for the other file`, { eagerness, afterHardTurn: true })).toBe(`standard`);
     }
 });
 
 test("a turn following hard work has to clear a higher bar, and at the default an eased one no longer does", () => {
-    // It raises the bar rather than locking the door (see ComplexityInput.afterHardTurn), so this is a shift of
-    // one stop's worth, not a gate: the same words that route in a fresh conversation stay put in a hard one.
     expect(tierOf(`explain closures`)).toBe(`fast`);
     expect(tierOf(`explain closures`, { afterHardTurn: true })).toBe(`standard`);
 });
 
 test("the verdict carries the cutoff it was judged against, because a score alone stopped being an answer", () => {
-    // With the cutoff an owner setting, the same 0.35 is standard on one stop and fast on another. A ledger of
-    // bare scores could not tell those two rows apart; the ceiling beside each is what keeps a refit honest.
     const cautious = judgeComplexity(turn(`explain closures`, { eagerness: `cautious` }));
     const eager = judgeComplexity(turn(`explain closures`, { eagerness: `eager` }));
 
     expect(cautious.ceiling).toBeLessThan(FAST_CEILING);
     expect(eager.ceiling).toBeGreaterThan(FAST_CEILING);
-    // Same words, same score, opposite verdicts: the pair that a column of bare scores could not have told apart.
     expect(cautious.score).toBe(eager.score);
     expect([cautious.tier, eager.tier]).toEqual([`standard`, `fast`]);
 });

package/src/models/prompt-complexity.ts

@@ -0,0 +1,215 @@
+// Judges whether a turn could run on the cheap rung of the provider the user is already on: a pure function over the
+// turn's shape, no model or catalog access. Never fails up: every ambiguous case resolves to standard, since
+// substituting a pricier model would just be honoring the original request.
+
+// A verdict lists these, the shadow ledger stores them, a screen renders them: renaming one is a breaking change.
+export type ComplexityRule =
+    // Gates: any one ends the question, standard with no score computed.
+    | "images"
+    | "plan-mode"
+    | "unattended"
+    // Escalating rules: any one forces standard; order between them cannot matter.
+    | "code-block"
+    | "stack-trace"
+    | "hard-words"
+    | "multi-step"
+    | "cross-cutting"
+    | "long-prompt"
+    | "many-attachments"
+    // Graded features: these only move the score.
+    | "medium-prompt"
+    | "attachment"
+    | "editor-context"
+    | "paths"
+    | "many-verbs"
+    | "after-hard-turn"
+    | "short-prompt"
+    | "easy-words"
+    | "bare-question"
+    | "no-workspace-reference";
+
+export type ComplexityTier = "fast" | "standard";
+
+// Everything the judge may know: primitive counts, flags and the prompt itself, no shared objects, so the daemon's turn
+// and the composer's draft can each build one independently.
+export interface ComplexityInput {
+    readonly prompt: string;
+    // Uploaded files plus @-mentioned workspace paths, resolved by the daemon into one count.
+    readonly attachments: number;
+    // Any attachment the model will read as an image; a cheap rung misreading one is the worst cell in the matrix.
+    readonly hasImages: boolean;
+    // The opt-in editor chip: the user pointed at a file and a selection, so the turn is about real code.
+    readonly editorContext: boolean;
+    // A surface started this, not a person at a composer (AgentTurn.unattended).
+    readonly unattended: boolean;
+    // The turn opens in plan mode: it is being asked to think before it acts.
+    readonly planMode: boolean;
+    // Whether the prior turn's judgement (not what it ran) was standard; a weight that raises the bar, not a lock.
+    readonly afterHardTurn: boolean;
+    // settings.autoTierEagerness; absent means balanced, what every pre-knob verdict was judged against.
+    readonly eagerness?: TierEagerness;
+}
+
+export interface ComplexityVerdict {
+    readonly tier: ComplexityTier;
+    // 0..1, rounded to three places so ledger rows compare exactly; 1 whenever a gate or escalating rule fired.
+    readonly score: number;
+    // Every rule that fired, in declaration order; empty means the base score, above the fast ceiling.
+    readonly rules: readonly ComplexityRule[];
+    // The ceiling this score was judged against, carried out since the ceiling is itself a setting that can change.
+    readonly ceiling: number;
+}
+
+// Above the fast ceiling on purpose: a prompt matching no rule at all is medium, not simple.
+const BASE_SCORE = 0.5;
+
+// How eager the judge is (settings.autoTierEagerness), the one knob this feature exposes:
+// - cautious: floor of 0, downgrades only the clearest easy asks
+// - balanced: the shipped default; every verdict before this knob existed was judged against it
+// - eager: also lets an easy-worded question about real code through
+export const FAST_CEILINGS = { cautious: 0, balanced: 0.25, eager: 0.4 } as const;
+export type TierEagerness = keyof typeof FAST_CEILINGS;
+
+// The stop used when nobody chose one: balanced, what every pre-knob verdict was judged against.
+export const FAST_CEILING = FAST_CEILINGS.balanced;
+
+// Characters, not tokens: thresholds mark a sentence turning into a brief, or carrying unfenced paste.
+const MEDIUM_PROMPT_CHARS = 600;
+const LONG_PROMPT_CHARS = 2400;
+const SHORT_PROMPT_CHARS = 140;
+// Three files in is a job about a shape rather than about a file, whatever the words say.
+const MANY_ATTACHMENTS = 3;
+// Three or more distinct imperatives is a list of jobs wearing the grammar of one.
+const MANY_VERBS = 3;
+
+// Short, boring word lists, case-insensitive on word boundaries; easy only lowers score, hard forces standard.
+const EASY_WORDS =
+    /\b(?:what(?:'s| is| are)|explain|describe|summari[sz]e|list|show me|where(?:'s| is| are)|rename|typo|reword|reformat|format this|tidy|define|translate|spell|abbreviat)/i;
+
+const HARD_WORDS =
+    /\b(?:refactor|redesign|architect|architecture|migrat|root cause|debug|investigat|diagnos|optimi[sz]|race condition|deadlock|memory leak|regression|security|threat model|benchmark|profil|audit|design a|plan (?:a|the|out)|why (?:does|is|are|did|would|can't|cannot))/i;
+
+// "Do this, and also that": the strongest cheap signal of a job that is several jobs.
+const MULTI_STEP = /\b(?:and then|after that|once (?:that|you)|followed by|as well as|then also)\b/i;
+
+// A job whose subject is the shape of the codebase, not a place in it; the cheap rung is worst at exactly this.
+const CROSS_CUTTING =
+    /\b(?:across (?:the|all|every)|every(?: single)? (?:file|module|package|component|usage|call ?site)|all (?:the|of the) (?:files|usages|call ?sites|places)|everywhere|throughout the|codebase-wide|repo-wide)\b/i;
+
+// Fenced code, a diff, or an inline patch: proof the turn is real code, where the cheap rung fails silently.
+const CODE_BLOCK = /```|^diff --git |^@@ .* @@|^[+-]{3} [ab]\//m;
+
+// A thrown error the user pasted in: the canonical case where the expensive tier earns its price.
+const STACK_TRACE =
+    /(?:^|\n)\s*(?:at [\w$.<>]+ \(|Traceback \(most recent call last\)|Caused by:|panic:|thread '.*' panicked|Unhandled|[A-Z]\w*(?:Error|Exception): )/;
+
+// A workspace path or @-mention, distinguishing "explain closures" from "explain what this file does".
+const PATH_LIKE =
+    /(?:^|\s)(?:@[\w./-]+|[\w-]+\/[\w./-]+\.[a-z]{1,5}\b|\b[\w-]+\.(?:ts|tsx|js|jsx|vue|py|go|rs|java|rb|css|scss|json|ya?ml|md|sql|sh)\b)/i;
+
+// One sentence, ending in a question mark, with no second clause: knowledge, not work.
+const BARE_QUESTION = /^[^.!?]{0,200}\?\s*$/;
+
+// Imperatives that start a request, counted rather than matched: one is a task, three is a list.
+const VERBS =
+    /\b(?:add|remove|delete|fix|write|create|make|update|change|move|rename|split|merge|extract|inline|wire|hook|test|check|run|build|deploy|document|implement|replace|convert|handle|support|expose|log|render|validate|parse|sort|filter|cache)\b/gi;
+
+// Bullets and numbered steps, a checklist however casually it is written.
+const LIST_LINES = /^\s*(?:[-*+]\s|\d+[.)]\s)/gm;
+
+// Every rule that ends the question on its own; split from the graded features below because these are answers, not
+// evidence.
+const forcing = (input: ComplexityInput, text: string): ComplexityRule[] => {
+    const rules: ComplexityRule[] = [];
+    // Gates first, cheapest and least arguable: about the turn's situation rather than its words.
+    if (input.hasImages) {
+        rules.push("images");
+    }
+    if (input.planMode) {
+        rules.push("plan-mode");
+    }
+    // Unattended turns are billed whole with nobody watching a bad guess.
+    if (input.unattended) {
+        rules.push("unattended");
+    }
+    // Then the words: each of these claims the turn is about real code doing something real.
+    if (CODE_BLOCK.test(text)) {
+        rules.push("code-block");
+    }
+    if (STACK_TRACE.test(text)) {
+        rules.push("stack-trace");
+    }
+    if (HARD_WORDS.test(text)) {
+        rules.push("hard-words");
+    }
+    if (MULTI_STEP.test(text) || (text.match(LIST_LINES)?.length ?? 0) >= 2) {
+        rules.push("multi-step");
+    }
+    if (CROSS_CUTTING.test(text)) {
+        rules.push("cross-cutting");
+    }
+    if (text.length > LONG_PROMPT_CHARS) {
+        rules.push("long-prompt");
+    }
+    if (input.attachments >= MANY_ATTACHMENTS) {
+        rules.push("many-attachments");
+    }
+    return rules;
+};
+
+// Weights are a fitted hypothesis with a ledger under them, not a claim (ships in shadow first). A fast verdict always
+// requires a positive `easing` feature to have fired: absence of complexity is not evidence of simplicity.
+interface GradedFeature {
+    readonly rule: ComplexityRule;
+    readonly weight: number;
+    readonly of: (input: ComplexityInput, text: string) => boolean;
+    // A positive reason to think this is easy, not merely an absence of reasons to think it is hard.
+    readonly easing?: true;
+}
+
+const GRADED: readonly GradedFeature[] = [
+    { rule: "medium-prompt", weight: +0.2, of: (_input, text) => text.length > MEDIUM_PROMPT_CHARS },
+    { rule: "attachment", weight: +0.15, of: (input) => input.attachments > 0 },
+    { rule: "editor-context", weight: +0.1, of: (input) => input.editorContext },
+    // Naming a file holds an easy-worded question at standard on balanced; eager is the choice to let it through.
+    { rule: "paths", weight: +0.15, of: (_input, text) => PATH_LIKE.test(text) },
+    {
+        rule: "many-verbs",
+        weight: +0.15,
+        of: (_input, text) => new Set((text.match(VERBS) ?? []).map((verb) => verb.toLowerCase())).size >= MANY_VERBS,
+    },
+    // The heaviest weight: the only feature seeing past the words, heavy enough eager cannot downgrade past it.
+    { rule: "after-hard-turn", weight: +0.25, of: (input) => input.afterHardTurn },
+    // Declared in ledger order. `easing` marks the two positive signals; the rest are light absence features.
+    { rule: "short-prompt", weight: -0.1, of: (_input, text) => text.length <= SHORT_PROMPT_CHARS },
+    { rule: "easy-words", weight: -0.25, easing: true, of: (_input, text) => EASY_WORDS.test(text) },
+    { rule: "bare-question", weight: -0.15, easing: true, of: (_input, text) => BARE_QUESTION.test(text) },
+    {
+        rule: "no-workspace-reference",
+        weight: -0.1,
+        of: (input, text) => input.attachments === 0 && !input.editorContext && !PATH_LIKE.test(text),
+    },
+];
+
+// Three places, so a stored score is a value not a float artefact, and same-rule rows compare equal.
+const round3 = (value: number): number => Math.round(value * 1000) / 1000;
+
+// Gates and escalators force standard at score 1 (monotone: a new rule only moves turns up a tier). Fast otherwise
+// needs both a sub-ceiling score and a positive `easing` signal; silence alone never downgrades.
+export const judgeComplexity = (input: ComplexityInput): ComplexityVerdict => {
+    const ceiling = FAST_CEILINGS[input.eagerness ?? "balanced"];
+    const text = input.prompt.trim();
+    const forced = forcing(input, text);
+    if (forced.length > 0) {
+        return { tier: "standard", score: 1, rules: forced, ceiling };
+    }
+    const hits = GRADED.filter((feature) => feature.of(input, text));
+    const score = Math.min(1, Math.max(0, BASE_SCORE + hits.reduce((total, feature) => total + feature.weight, 0)));
+    const eased = hits.some((feature) => feature.easing === true);
+    return {
+        tier: eased && score <= ceiling ? "fast" : "standard",
+        score: round3(score),
+        rules: hits.map((feature) => feature.rule),
+        ceiling,
+    };
+};

package/src/{provider-specs.test.ts → models/provider-specs.test.ts}

@@ -11,23 +11,16 @@ import {
     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";
+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. */
+// Walks the spec table itself rather than a list of provider names, so a provider added or removed carries its
+// assertions with it; every surface's derived list is checked against the table.
 
 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.
+        // Strings a surface prints; empty renders as a nameless row rather than a visible error.
         for (const [field, value] of Object.entries({
             label: spec.label,
             vendor: spec.vendor,
@@ -38,16 +31,14 @@ describe("every provider in the table", () => {
         })) {
             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.
+        // brand is typed against these keys, so this only fails if someone reaches for a cast.
         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.
+            // The CLIProxyAPI's own name for this provider, addressed by the daemon's management API.
             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);
@@ -55,14 +46,10 @@ describe("every provider in the table", () => {
         }
         if (spec.auth.kind === "minted") {
             expect(MINTED_PROVIDERS, `${id} is minted but missing from MINTED_PROVIDERS`).toContain(id);
-            // At least one estate to sign in to, because the head of this list is what a `login/start` that names
-            // no variant gets: an empty one is a provider whose connect row has no button that can do anything.
+            // The head of this list is what a login/start naming no variant gets; empty means a dead connect button.
             expect(spec.auth.variants.length, `${id} is minted but offers no estate to sign in to`).toBeGreaterThan(0);
             for (const variant of spec.auth.variants) {
-                /* THE TURN URL AND THE CATALOG URL ARE DIFFERENT SURFACES OF ONE ESTATE, 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. */
+                // Catalog and turn share one host (else different vendors); the turn base carries no version segment.
                 expect(new URL(variant.anthropicBase).host, `${id}/${variant.id}'s catalog and turn hosts differ`).toBe(
                     new URL(variant.catalogBase).host,
                 );
@@ -70,19 +57,19 @@ describe("every provider in the table", () => {
                     /\/v\d+$/,
                 );
                 expect(variant.label.trim(), `${id}/${variant.id} has no estate label`).not.toBe("");
-                // The lookup every surface goes through, rather than the row behind it: an id that names a
-                // variant must resolve to that variant and nothing else.
+                // The lookup every surface goes through, not the row behind it: a named variant must resolve to itself
+                // only.
                 expect(mintedVariant(id, variant.id), `${id}/${variant.id} does not resolve`).toEqual(variant);
             }
-            // An absent variant takes the head of the list, which is what a single-estate provider's connect row
-            // always sends and what a `login/start` with no choice on it means.
+            // An absent variant defaults to the list's head: what a single-estate row or a choice-less login/start
+            // means.
             expect(mintedVariant(id), `${id}'s default estate is not the head of its list`).toEqual(spec.auth.variants[0]);
-            // An estate id nobody declared is NOT the default: falling back would mint a key on one estate and
-            // dial it at another, and report the refusal as an authentication problem.
+            // An unknown estate must not default: it would mint on one estate and dial another, misread as an auth
+            // failure.
             expect(mintedVariant(id, "no-such-estate"), `${id} defaults an unknown estate instead of refusing`).toBeUndefined();
             return;
         }
-        // An oauth provider is served by a handshake this daemon runs; it is in neither routed list.
+        // An oauth provider is served by a handshake this daemon runs directly; it belongs in neither routed list.
         expect(KeyedProviderSchema.options, `${id} is not routed but appears in KeyedProvider`).not.toContain(id);
         expect(MINTED_PROVIDERS, `${id} is not minted but appears in MINTED_PROVIDERS`).not.toContain(id);
         expect(mintedVariants(id), `${id} is not minted but names estates`).toBeUndefined();
@@ -96,8 +83,7 @@ describe("every provider in the table", () => {
         ).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.
+        // The catalog route's param schema shares this vocabulary, or an untracked provider 400s on its 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);
@@ -106,27 +92,17 @@ describe("every provider in the table", () => {
     });
 });
 
-/* 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 (model-pins.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");
@@ -135,9 +111,6 @@ test("the harness chip is offered exactly where the two harnesses run different
     }
 });
 
-/* A MINTED 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 minted provider runs the Claude Code loop on both harnesses", () => {
     for (const provider of MINTED_PROVIDERS) {
         expect(capabilitiesOf(provider, "native").runtime, provider).toBe("claude-code");
@@ -145,8 +118,6 @@ test("a minted provider runs the Claude Code loop on both harnesses", () => {
     }
 });
 
-// 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();