@intentic/sandbox-contract 1.246.1 → 1.248.0

package/src/model-pins.ts

@@ -0,0 +1,132 @@
+import { modelsFor } from "./agent-catalog.js";
+import type { AgentProvider, ModelPin } from "./schemas/agent.js";
+
+/* WHICH MODELS A ROLE MAY RUN, IN THE ORDER TO TRY THEM. One resolver over every list in
+ * settings.modelRoles, and the browser and the daemon both read it.
+ *
+ * IT IS AN ORDER, NOT A MODEL, and that is the shape of every list this file answers for. A single pick is a
+ * single point of failure: the account it names spends its allowance on the chat all morning, and the role
+ * fails on a limit for the rest of the day while three other connected providers sit idle. So a setting is a
+ * LIST read top to bottom, this hands back the whole ladder, and the caller walks it until one answers. Nothing
+ * here decides WHICH failures are worth stepping over — only the runner has made the call and seen it fail —
+ * this side 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 that job's settings row, before anything has run. Two
+ * implementations would drift precisely where it matters most, since a row promising Haiku while the daemon
+ * bills Opus is worse than no row at all.
+ *
+ * AN EMPTY LIST RESOLVES TO NOTHING, FOR EVERY ROLE, and this file no longer derives a floor for any of them.
+ * It used to: a `helper` role with no list got an "Auto ladder" worked out from whatever was connected —
+ * every provider's cheapest row, best-first — so an owner who had never opened the settings page still got
+ * commit messages, session titles and safety verdicts from a model this file picked. That was the wrong
+ * default, and the settings row saying "Auto: Gemini 3 Flash Lite, then Claude Haiku 4.5, then …" was the
+ * tell: a recommendation nobody asked for, over accounts they had connected for something else, changing
+ * under them whenever an account was added. NOT SET NOW MEANS NOT SET. Nothing is auto-selected and nothing
+ * is recommended: the owner names the models for a job or the job does not run, which is a state they can
+ * read off the row and a bill they cannot be surprised by.
+ *
+ * The two kinds of role (model-roles.ts) still differ in what the CALLER does with an empty answer — a
+ * `helper` is simply off, a `run` falls to the model the owner picked for their own chat — but that is the
+ * caller's business, and nothing here has to know which kind it is holding. */
+
+/* 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 rung to point it at. `endpoint/<id>` providers ARE, and have to be: their models
+ * appear in the same picker the settings rows build their options from, so a pin naming one has to hold rather
+ * than drop out and leave the job running on an account the user was deliberately steering away from. */
+export interface ModelSource {
+    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union, and
+    // what a turn on somebody's own model server costs is not a fact this repo can know — which is fine here,
+    // because nothing on this side ranks anything. A pin either names a provider that can run it or it does not.
+    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;
+    // What the provider publishes. NOTHING IN THIS FILE READS IT any more: it was the input to the derived Auto
+    // ladder, and a pin is taken verbatim. Kept because it is what a source IS, and the daemon's helper walk
+    // still gathers it (role-model.ts); a caller with no catalog to hand passes an empty list and loses nothing.
+    readonly models: readonly string[];
+}
+
+export interface ModelChoice {
+    readonly provider: AgentProvider;
+    readonly model: string;
+}
+
+// A (provider, model) pair on the wire: `${provider}:${modelId}`, the same key shape the model picker mints for
+// its entries (PickerEntry.key). Every role list stores PINS rather than these keys — an entry says how it runs
+// as well as which model it is — but the key is still how two entries are compared, how a role list dedupes,
+// and how `autoFastModels` (which pins no knobs, see its own note in settings.ts) is stored.
+export const modelPinKey = (choice: ModelChoice): string => `${choice.provider}:${choice.model}`;
+
+/* Split on the FIRST colon only: a provider id never contains one and a model id might. Exported because
+ * `autoFastModels` stores these keys, and because a session composed from a pin travels as one
+ * (composeSession). */
+export const parsePinned = (pinned: string): ModelChoice | undefined => {
+    const separator = pinned.indexOf(`:`);
+    if (separator <= 0 || separator === pinned.length - 1) {
+        return undefined;
+    }
+    return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
+};
+
+/* A pin as a person reads it: the catalog's own label 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: ModelChoice): string =>
+    modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
+
+/* WHICH MODELS THIS ROLE MAY RUN, IN THE ORDER TO TRY THEM, given what this sandbox has connected.
+ * `pinned` is the stored setting: settings.modelRoles[role], an ordered list of pins.
+ *
+ * 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 while the sandbox can plainly still answer from the rung
+ * below. 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 PINNED LIST IS THE WHOLE ANSWER, and there is nothing underneath it. A user who writes down three models
+ * has said which accounts this job may spend, and 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. A user who writes down none
+ * has said the job picks no model at all.
+ *
+ * THE WHOLE PIN SURVIVES, not the pair inside it: an entry's effort, thinking, speed and harness are what the
+ * work is composed from, so a resolver handing 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 THE LIST HAS NOTHING IT MAY REACH, from two different causes the caller can tell apart by
+ * looking at `pinned`: an empty list is an owner who set no model, and a full list that survives none of the
+ * readiness filter is an owner whose accounts have gone. The first is the job being switched off, the second
+ * is worth a sentence about the accounts.
+ *
+ * ONE FUNCTION FOR BOTH KINDS OF LADDER, and it is `resolveRoleModels` that stopped existing rather than this
+ * one arriving to replace it. A role's list used to add the role's own floor beneath the ready chain, which is
+ * the only thing it did that a persona card's list (schemas/personas.ts `personaModels`) did not — so the walk
+ * was split out to be shared. With the floor gone there is no difference left to share around: a role's list
+ * and a card's list are the same question over the same sources, and two names for it would be two places to
+ * read before believing they agree. */
+export const readyChain = (sources: readonly ModelSource[], pinned: readonly ModelPin[]): readonly ModelPin[] => {
+    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
+    // Taken verbatim, unvalidated against the catalog on purpose: the picker 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 requested = pinned.filter((pin) => ready.has(pin.provider));
+    /* The same model twice would spend two attempts proving one account is out — a real state, since the list is
+     * hand-edited and the bulk editor writes one pin across many jobs.
+     *
+     * THE FIRST OF A PAIR WINS, WHOLE. Two entries can 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: ModelPin[] = [];
+    for (const pin of requested) {
+        if (!chain.some((held) => modelPinKey(held) === modelPinKey(pin))) {
+            chain.push(pin);
+        }
+    }
+    return chain;
+};

package/src/model-roles.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "vitest";
+import { MODEL_ROLE_BLOCKS, MODEL_ROLES, type ModelRoleSpec } from "./model-roles.js";
+
+/* THE CATALOG DRAWS THE SETTINGS PAGE, so the properties the page relies on have to be true of the TABLE rather
+ * than remembered by whoever last added a row. Eighteen jobs in one unbroken list is what the blocks exist to
+ * break up, and the failure they replace is a silent one: a role that belongs to no block is simply missing
+ * from Sandbox ▸ Agent ▸ Models, with no error anywhere and a page that looks completely normal. */
+
+// The table at its declared width rather than as the literal tuple: `trigger` is absent from a helper's literal
+// type, and what is under test is exactly whether it is absent where it should be.
+const roles: readonly ModelRoleSpec[] = MODEL_ROLES;
+
+/* WHAT STARTS A RUN IS THE BLOCK IT IS READ IN, and asserting the two against each other is what stops them
+ * drifting: a run whose trigger says one thing while the page draws it under the other heading is a row telling
+ * an owner that a session nobody is watching is one they start. A helper answers with its own kind, because it
+ * has no trigger and its block is the kind itself. */
+test("every whole session says what starts it, and it is the block it is drawn in", () => {
+    const blockOf = new Map(MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => [role.id, block.id] as const)));
+
+    for (const role of roles) {
+        expect(role.kind === `run` ? role.trigger : role.kind, role.id).toBe(blockOf.get(role.id));
+    }
+});
+
+test("a one-shot declares no trigger at all: nothing presses a commit subject into being", () => {
+    for (const helper of roles.filter((role) => role.kind === `helper`)) {
+        expect(Object.keys(helper), helper.id).not.toContain(`trigger`);
+    }
+});
+
+/* THE BLOCKS PARTITION THE TABLE: every role in exactly one, nothing invented. Asserted as a partition rather
+ * than block by block, because the two ways to get this wrong are opposites and only one of them is visible —
+ * a role in no block vanishes from the page, a role in two is drawn twice and would be caught by eye. */
+test("the blocks hold every role once, in the table's own order", () => {
+    const blocked = MODEL_ROLE_BLOCKS.flatMap((block) => block.roles.map((role) => role.id));
+
+    expect(blocked.toSorted()).toEqual(MODEL_ROLES.map((role) => role.id).toSorted());
+    /* AND THE ORDER SURVIVES THE SPLIT. Reading the blocks in order is reading the table in order: the table
+     * argues its sequence is REACH (jobs nobody picked a model for, then sessions a click starts, then sessions
+     * that start without one), and a block re-sorted here would leave that argument describing a page it no
+     * longer matches. */
+    expect(blocked).toEqual(MODEL_ROLES.map((role) => role.id));
+});
+
+test("each block says what it is, so the page keeps no headings of its own", () => {
+    for (const block of MODEL_ROLE_BLOCKS) {
+        expect(block.label, block.id).toMatch(/\S/);
+        expect(block.caption, block.id).toMatch(/\S/);
+        // A block with nothing in it would draw a heading over an empty surface.
+        expect(block.roles.length, block.id).toBeGreaterThan(0);
+    }
+});

package/src/model-roles.ts

@@ -0,0 +1,320 @@
+import { z } from "zod";
+
+/* EVERY JOB IN THIS SANDBOX THAT PICKS A MODEL, LISTED BY THE JOB IT IS, one row per answer the owner is
+ * entitled to give differently.
+ *
+ * WHAT THIS REPLACED, and why it had to go. Model settings used to be grouped by how HARD the work was assumed
+ * to be: a "quick model" for the small automatic jobs, an "agent runs" tier for the big ones. Both names
+ * described an intensity rather than a job, and an intensity is a guess somebody else made about work the owner
+ * knows better. A commit message written by a frontier model is not a mistake, it is a preference, and the
+ * grouping made it unsayable: pinning Opus to get better commit subjects also pinned it to session titles, to
+ * every loop verdict, and to the safety judge. One bundled row could not say the thing anyone actually wanted
+ * to say.
+ *
+ * SO THE UNIT IS THE ROLE. Each entry here is one place a model gets chosen, and each gets its own ordered list
+ * in settings.modelRoles. Seventeen rows is more than four, and that is the point rather than a cost being
+ * absorbed: the configuration and the UI both already existed per use-case, and collapsing them was the only
+ * thing standing between the owner and a choice the machinery could already honour. A simpler face over this
+ * (presets: "cheap everywhere", "frontier everywhere") is a thing that can be built ON TOP of a true model, and
+ * cannot be unpicked from a lossy one.
+ *
+ * EVERY LIST IS AN ORDERED LADDER, whatever the role, and for one reason: the interesting failure of a pinned
+ * model is not that it is wrong, it is that it is CONNECTED AND WILL NOT ANSWER TODAY. The account's allowance
+ * went on the chat this morning, and one spent provider takes the role down for hours while three others sit
+ * idle. Written in order, the next entry catches it.
+ *
+ * AN EMPTY LIST IS THE JOB SWITCHED OFF, and NOTHING IS DERIVED FOR IT. A helper role used to fall to an
+ * "Auto ladder" worked out from whatever was connected — every provider's cheapest row, best-first — so a
+ * sandbox that had never been configured still spent somebody's account on commit messages and safety
+ * verdicts, on a recommendation this table invented, which re-ranked itself the day another account was
+ * connected. Not set now means not set: no auto-selection, no recommendation, and the owner names the models
+ * for a job or the job does not happen.
+ *
+ * TWO KINDS, and what separates them is what the CALLER does with that empty answer. It is declared per role
+ * because it is a property of the job:
+ *
+ *   helper — a one-shot. One prompt, no tools, one string back, and it is over. With no list the job does not
+ *            run at all: no commit subject is drafted, no session is renamed, no command is judged. Every one
+ *            of them already had a road for "the model could not answer" (the derived title stands, the
+ *            commit box stays empty, the gate falls to its standing rule), so an owner who wants none of them
+ *            leaves the row empty and pays nothing.
+ *
+ *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
+ *            composer. With no list the caller's own floor answers: the model the owner picked for their chat.
+ *            That is not this table recommending anything — it is a choice they already made, in front of
+ *            them, on the composer they work in.
+ *
+ * EVERY ENTRY IS A FULL PIN (ModelPinSchema): which model, and how it runs — effort, thinking, speed, harness.
+ * The helper roles carry them too, which they did not use to: a one-shot ran with reasoning forcibly off, so
+ * pinning a reasoning model to commit messages bought the price of one and the behaviour of neither. The knobs
+ * now ride through the one-shot path (the daemon's role-model.ts), so an entry means what it says wherever it
+ * is written.
+ *
+ * ADDING A ROLE IS ONE ROW HERE. The settings key, the resolver's floor, the daemon's lookup and the settings
+ * page's row all read this table, so a job that starts picking a model tomorrow becomes configurable by saying
+ * what it is. That is the property the old grouping cost: a new surface inherited "agent runs" by being
+ * unattended, which is how a documentation sweep and a production incident came to share one tier. */
+
+export const ModelRoleKindSchema = z.enum(["helper", "run"]);
+export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
+
+/* WHAT STARTS A RUN, declared for the run roles alone.
+ *
+ * It is not a wire value and never has been: it decides which BLOCK a job is read in, and the argument for
+ * reading them apart is the same one that separates a helper from a run — an owner holds a session nobody is
+ * watching to a different budget from one they are sitting in front of. The settings page used to make that
+ * argument in a comment over a thirteen-row list ("the ones somebody presses ahead of the ones that fire on
+ * their own"), which is a claim no reader can check and no row has to honour. Declared, it draws the page.
+ *
+ * A HELPER DECLARES NONE, and that is the honest answer rather than a gap: nobody presses "write me a commit
+ * subject". It happens because something else did. */
+export type ModelRoleTrigger = "pressed" | "unprompted";
+
+/* The shape of a row. `id` is a bare string HERE and narrowed on the exported type below, because the id union
+ * is derived from this very table: a self-referential `satisfies` would be a type that has to know its own
+ * answer before it can check it. */
+interface ModelRoleRow {
+    readonly id: string;
+    // What the settings row is called. A JOB, in the owner's words, never a tier.
+    readonly label: string;
+    // The row's one line: what this model is asked to do. Read beside the label, so it says what the label
+    // cannot rather than restating it.
+    readonly blurb: string;
+    readonly kind: ModelRoleKind;
+    /** Runs only, and required for every one of them: see `ModelRoleTrigger`. */
+    readonly trigger?: ModelRoleTrigger;
+    // The row's glyph, from the shared icon set. Here rather than in a web-side map because the whole value of
+    // this table is that a role is declared ONCE; a second table keyed by the same ids is the drift this
+    // replaced, moved one layer up.
+    readonly icon: string;
+}
+
+/* THE TABLE. Ordered as the settings page draws it, and the order is an argument about reach: the one-shots
+ * first, because nobody chose a model for them and they run constantly; then the runs somebody's click starts;
+ * then the runs that start themselves, which are the ones an owner is least likely to be watching and most
+ * likely to want held to a budget. Those three are BLOCKS now (see MODEL_ROLE_BLOCKS) rather than an ordering
+ * this comment asserts and nothing holds to.
+ *
+ * The ids are the wire vocabulary: a turn carries one (AgentTurn.runRole), so they are kebab-case and stable,
+ * and renaming one is a breaking change to the setting rather than a cosmetic edit. */
+export const MODEL_ROLES = [
+    {
+        id: "commit-message",
+        label: "Commit messages",
+        blurb: "The subject written when an agent's work lands, and the release note under it.",
+        kind: "helper",
+        icon: "file-edit",
+    },
+    {
+        id: "session-title",
+        label: "Session titles",
+        blurb: "The name a conversation wears on the board, written a second into its first turn.",
+        kind: "helper",
+        icon: "pencil",
+    },
+    {
+        /* THE ONE HELPER WHOSE INPUT IS ADVERSARIAL, and the reason the old bundling was worst here. Its prompt
+         * contains a command the agent is about to run, which may have arrived from a stranger's web page, and a
+         * small model can be talked round by it. Being wrong is expensive in both directions: a needless card
+         * teaches the owner to click through the next one. */
+        id: "safety-judge",
+        label: "Safety judge",
+        blurb: "Which model reads your safety policy before a flagged command runs.",
+        kind: "helper",
+        icon: "shield",
+    },
+    {
+        id: "loop-verdict",
+        label: "Loop verdicts",
+        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
+        kind: "helper",
+        icon: "check-square",
+    },
+    {
+        /* THE ONE HELPER THAT ANSWERS A CLASSIFICATION rather than writing prose: one card id, or none, from the
+         * owner's own short list (schemas/personas.ts `brief`). Cheap by construction, once per chat, and the
+         * job a small model does well, which is the whole argument for routing chats onto static cards rather
+         * than asking a model to compose a context per session. */
+        id: "persona-router",
+        label: "Persona routing",
+        blurb: "Which model reads a new chat's first message and picks the persona for it.",
+        kind: "helper",
+        icon: "users",
+    },
+    {
+        id: "pipeline-fix",
+        label: "Pipeline fixes",
+        blurb: "The agent started by Fix on a red pipeline.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wave-pulse",
+    },
+    {
+        id: "deployment-fix",
+        label: "Deployment fixes",
+        blurb: "The agent started by Fix on a deployment that is down.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "server",
+    },
+    {
+        id: "maintenance-chore",
+        label: "Maintenance chores",
+        blurb: "A chore run started from the Maintenance board.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "wrench",
+    },
+    {
+        id: "documentation-run",
+        label: "Documentation runs",
+        blurb: "A pass over a repo's own documentation.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "book",
+    },
+    {
+        id: "acceptance-run",
+        label: "Acceptance runs",
+        blurb: "One session per story in an acceptance fan-out.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "list-check",
+    },
+    {
+        id: "pre-push-fix",
+        label: "Pre-push fixes",
+        blurb: "The fix proposed when a check fails on the way to a push.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "cloud-upload",
+    },
+    {
+        /* PRESSED, ON THE STRENGTH OF THE APPROVAL. Nothing here runs until somebody reads the item and says
+         * yes, and that press is the start of this turn as much as Fix is the start of a pipeline run — the
+         * queue between the two is machinery, not a second decision. */
+        id: "approval-queue",
+        label: "Approvals queue",
+        blurb: "The turn that publishes or acts on what you approved.",
+        kind: "run",
+        trigger: "pressed",
+        icon: "check-circle",
+    },
+    {
+        id: "automation-wake",
+        label: "Automation wakes",
+        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "clock",
+    },
+    {
+        id: "extension-review",
+        label: "Extension update reviews",
+        blurb: "The agent that reads an extension update before it is applied.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "box",
+    },
+    {
+        id: "loop-iteration",
+        label: "Loop iterations",
+        blurb: "Each round of a loop working towards its goal.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "repeat",
+    },
+    {
+        id: "watch-wake",
+        label: "Watch wakes",
+        blurb: "The turn a watch starts when the thing it was watching happens.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "eye",
+    },
+    {
+        id: "verify-nudge",
+        label: "Verify nudges",
+        blurb: "The follow-up turn sent when work was left unverified.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "search",
+    },
+    {
+        /* THE ONE ROLE THAT ANSWERS A CHOICE RATHER THAN FILLING A SILENCE. A spawning agent may name its
+         * child's provider, and when it does that wins, exactly as a caret pick wins on every other run role.
+         * This is what answers when it names none, which used to be a hardcoded "claude". */
+        id: "child-agent",
+        label: "Child agents",
+        blurb: "What an agent's own subagents run on when it names no model for them.",
+        kind: "run",
+        trigger: "unprompted",
+        icon: "users",
+    },
+] as const satisfies readonly ModelRoleRow[];
+
+export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
+export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
+
+export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
+
+/* The wire form. An enum rather than a string, unlike most ids in this contract, because there is no case for
+ * an unknown one: a role is a place in THIS codebase where a model gets chosen, so a value outside the table
+ * names nothing, and a settings file or a turn carrying one is a typo worth a clean error rather than a list
+ * silently ignored. */
+export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
+
+/* ═══ THE BLOCKS THE SETTINGS PAGE READS IN ═══
+ *
+ * EIGHTEEN JOBS IN ONE LIST IS A TABLE, NOT A PAGE. The unit being the role is right and is not in question —
+ * it is what lets an owner pin Opus to commit subjects without pinning it to every session title — but the cost
+ * lands on whoever opens the page: one unbroken run of eighteen rows, each with a name, a sentence, a control
+ * and a list under it, with no landmark to say where you are in it or which rows are like the one you came for.
+ *
+ * SO THE BLOCKS ARE DECLARED, AND THEY ARE THE DISTINCTIONS THE TABLE ALREADY MAKES. Nothing here is a fresh
+ * taxonomy invented for the layout: `kind` was always the difference between a one-shot and a whole session,
+ * and `trigger` is the sentence the old table wrote in a comment about its own ordering. A block is what those
+ * two answers already separate, given a name and a heading.
+ *
+ * THE LABELS LIVE HERE, beside the role labels, for the same reason those do: a heading kept in a web-side map
+ * keyed by the same ids is the drift a single table exists to stop. What is NOT here is anything about how the
+ * page draws them — that is the page's, and it changes on its own schedule.
+ *
+ * ORDER IS REACH, and it is the order of the table itself: jobs nobody picked a model for, then sessions a
+ * click of yours starts, then sessions that start without one. Every role belongs to exactly one block and
+ * every block keeps the table's order, which is what makes a role added upstairs appear on the page by
+ * existing. */
+export type ModelRoleBlockId = "helper" | "pressed" | "unprompted";
+
+export interface ModelRoleBlock {
+    readonly id: ModelRoleBlockId;
+    /** The group's heading on the settings page. */
+    readonly label: string;
+    /** One line beside it: what the jobs in this block have in common that the others do not. */
+    readonly caption: string;
+    /** Its roles, in table order. */
+    readonly roles: readonly ModelRoleSpec[];
+}
+
+const rolesWhere = (match: (role: ModelRoleSpec) => boolean): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => match(role));
+
+export const MODEL_ROLE_BLOCKS: readonly ModelRoleBlock[] = [
+    {
+        id: "helper",
+        label: "Automatic helpers",
+        caption: "One prompt, no tools, one answer back.",
+        roles: rolesWhere((role) => role.kind === "helper"),
+    },
+    {
+        id: "pressed",
+        label: "Runs you start",
+        caption: "Whole sessions, begun by a click of yours.",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "pressed"),
+    },
+    {
+        id: "unprompted",
+        label: "Runs that start themselves",
+        caption: "Whole sessions nobody pressed for.",
+        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "unprompted"),
+    },
+];

package/src/plan-pools.ts

@@ -6,7 +6,7 @@ import type { AccountUsage, UsageWindow, WindowGates } from "./schemas/plan-limi
  * 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,
+ * read, so the daemon's account picker, its one-shot helper 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

package/src/prompt-complexity.test.ts

@@ -88,7 +88,7 @@ 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 agentRunModels already makes in the other direction: a run billed whole, with a worktree in
+    // 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`);
 });

package/src/prompt-complexity.ts

@@ -3,7 +3,7 @@
  * The job is narrow on purpose: decide whether this turn could have run on the cheap rung of the provider the
  * user is already on. Nothing here picks a model, nothing here reads a catalog, and nothing here calls
  * anything. It is a pure function over the turn's own words and shape, so the daemon and the composer can both
- * ask it and get the same answer, which is the same reason quick-model.ts lives in the contract rather than in
+ * ask it and get the same answer, which is the same reason model-pins.ts lives in the contract rather than in
  * either of them.
  *
  * IT CAN ONLY EVER ROUTE DOWN. The standard tier is not a setting: it is whatever the user already picked. So
@@ -213,7 +213,7 @@ const forcing = (input: ComplexityInput, text: string): ComplexityRule[] => {
         rules.push("plan-mode");
     }
     /* An unattended run is billed whole and nobody is watching it fail. The settings this repo already ships
-     * make the same call in the other direction: agentRunModels resolves to NOTHING when empty precisely
+     * make the same call in the other direction: a `run` role resolves to NOTHING when empty precisely
      * because "nothing here can judge whether a job is worth the frontier tier". This file does judge, but not
      * for the runs where a wrong guess costs a whole session with a worktree in it. */
     if (input.unattended) {

package/src/provider-specs.test.ts

@@ -115,7 +115,7 @@ test("provider ids are unique", () => {
 
 /* 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
+ * 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) {