@intentic/sandbox-contract 1.246.1 → 1.247.0

package/src/model-pins.ts

@@ -0,0 +1,183 @@
+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 ModelRole, modelRole } from "./model-roles.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 the settings row's "Auto: …" line, 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.
+ *
+ * WHAT AN EMPTY LIST MEANS IS THE ROLE'S OWN ANSWER (model-roles.ts): a `helper` role derives the Auto ladder
+ * from whatever is connected, a `run` role resolves to nothing and lets the caller's floor answer. That fork
+ * used to be two near-identical files; it is one line here because it was always one difference. */
+
+/* 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 fall silently back to Auto and spend 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. 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 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;
+
+// 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: ModelSource): 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
+// Auto 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. The floor under
+ * every `helper` role, and under nothing else.
+ *
+ * Ranked on TIER FIRST, then cost. That order is the point: a helper's Auto 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.
+ *
+ * NOTE WHAT AUTO IS AND IS NOT AN ARGUMENT FOR. It is the answer for an owner who has said nothing, not a claim
+ * that cheap is right: an owner who pins Opus to commit messages is not being talked out of it, which is the
+ * whole reason these lists are per role. Auto is what a row says while it is empty.
+ *
+ * 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. */
+export const autoLadder = (sources: readonly ModelSource[]): readonly ModelPin[] =>
+    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 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, empty for the role's own
+ * floor.
+ *
+ * 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. 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 whenever any of it survives that filter. The floor is NOT appended
+ * underneath, and that is deliberate: a user who writes down three models has said which accounts this job 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 the floor takes over rather than leaving a dead button.
+ *
+ * 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 role has nothing it can reach. For a `helper` that is a sandbox with nothing connected at
+ * all, and the caller renders a control that says so rather than a live button that fails on click; for a `run`
+ * it is the ordinary state of an unpinned role, and the caller's own floor answers. */
+export const resolveRoleModels = (sources: readonly ModelSource[], pinned: readonly ModelPin[], role: ModelRole): 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 Auto's ladder can rank a provider the user has also pinned.
+     *
+     * 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);
+        }
+    }
+    if (chain.length > 0) {
+        return chain;
+    }
+    // The floor, which the role declares. An id outside the table has no floor to fall to, and answering with
+    // the cheapest connected model for it would be this file inventing a job.
+    return modelRole(role)?.kind === `helper` ? autoLadder(sources) : [];
+};

package/src/model-roles.ts

@@ -0,0 +1,224 @@
+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.
+ *
+ * TWO KINDS, and the only thing that separates them is what an EMPTY list means. That is a real fork rather
+ * than a leftover of the old grouping, and 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. An empty list resolves to the
+ *            AUTO LADDER: every connected provider's cheapest row, best-first (model-pins.ts). Deriving is the
+ *            right default here because the job is small and repeatable, so the cost of a wrong guess is one
+ *            cheap call, and because a derived answer improves by itself when an account is connected tomorrow.
+ *
+ *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
+ *            composer. An empty list resolves to NOTHING, and the caller's own floor answers: the model the
+ *            owner picked for their chat. Nothing here can judge whether a job is worth the frontier tier, and
+ *            a wrong guess is billed in whole sessions rather than in tokens, so the honest fallback is a
+ *            choice they made rather than one this table invented.
+ *
+ * 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>;
+
+/* 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;
+    // 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.
+ *
+ * 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",
+    },
+    {
+        id: "pipeline-fix",
+        label: "Pipeline fixes",
+        blurb: "The agent started by Fix on a red pipeline.",
+        kind: "run",
+        icon: "wave-pulse",
+    },
+    {
+        id: "deployment-fix",
+        label: "Deployment fixes",
+        blurb: "The agent started by Fix on a deployment that is down.",
+        kind: "run",
+        icon: "server",
+    },
+    {
+        id: "maintenance-chore",
+        label: "Maintenance chores",
+        blurb: "A chore run started from the Maintenance board.",
+        kind: "run",
+        icon: "wrench",
+    },
+    {
+        id: "documentation-run",
+        label: "Documentation runs",
+        blurb: "A pass over a repo's own documentation.",
+        kind: "run",
+        icon: "book",
+    },
+    {
+        id: "acceptance-run",
+        label: "Acceptance runs",
+        blurb: "One session per story in an acceptance fan-out.",
+        kind: "run",
+        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",
+        icon: "cloud-upload",
+    },
+    {
+        id: "automation-wake",
+        label: "Automation wakes",
+        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
+        kind: "run",
+        icon: "clock",
+    },
+    {
+        id: "approval-queue",
+        label: "Approvals queue",
+        blurb: "The turn that publishes or acts on what you approved.",
+        kind: "run",
+        icon: "check-circle",
+    },
+    {
+        id: "extension-review",
+        label: "Extension update reviews",
+        blurb: "The agent that reads an extension update before it is applied.",
+        kind: "run",
+        icon: "box",
+    },
+    {
+        id: "loop-iteration",
+        label: "Loop iterations",
+        blurb: "Each round of a loop working towards its goal.",
+        kind: "run",
+        icon: "repeat",
+    },
+    {
+        id: "watch-wake",
+        label: "Watch wakes",
+        blurb: "The turn a watch starts when the thing it was watching happens.",
+        kind: "run",
+        icon: "eye",
+    },
+    {
+        id: "verify-nudge",
+        label: "Verify nudges",
+        blurb: "The follow-up turn sent when work was left unverified.",
+        kind: "run",
+        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",
+        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[]]);
+
+const BY_ID = new Map<string, ModelRoleSpec>(MODEL_ROLES.map((role) => [role.id, role]));
+
+/** What this role is, or undefined for an id no build of this table declares. */
+export const modelRole = (id: string): ModelRoleSpec | undefined => BY_ID.get(id);
+
+/** The roles of one kind, in table order: the two blocks the settings page draws. */
+export const modelRolesOfKind = (kind: ModelRoleKind): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => role.kind === kind);

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) {

package/src/schemas/agent.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ModelRoleSchema } from "../model-roles.js";
 import { NATIVE_PROVIDERS } from "../provider-specs.js";
 import { AgentPlacementSchema } from "../runner-protocol.js";
 import { entryId } from "./internal.js";
@@ -267,6 +268,23 @@ export const AgentTurnSchema = z
             .describe(
                 "Whether this turn's work merges into the workspace when it finishes. Overrides the conversation's own setting for this turn only.",
             ),
+        /* WHAT STARTED THIS TURN, when it was not a person at a composer, and therefore which of the owner's
+         * model lists answers for it (settings.modelRoles, model-roles.ts declares the roles).
+         *
+         * IT NAMES THE JOB, NOT THE TIER. Before this field there was one list for every unattended turn, so a
+         * production incident and a documentation sweep were configured together, and a surface added tomorrow
+         * inherited that tier by saying nothing. Now a starter says what it IS, and the owner gets to answer
+         * per job: cheap for the sweep, frontier for the incident.
+         *
+         * ONLY FILLS A SILENCE. The daemon applies the role's list to a turn that named no model AND no
+         * provider (turn-resume.ts): a caret pick, an acceptance run's own choice, a workflow step pinned to a
+         * provider — all of those already answered the question, and this must not overrule them.
+         *
+         * A `run` role, always. The `helper` roles never reach here: a one-shot is not a turn, it has no
+         * conversation and no worktree, and it asks its own role directly at the seam that spends it. */
+        runRole: ModelRoleSchema.optional().describe(
+            "What started this turn, when it was not a person typing: which of the sandbox's per-job model lists answers for it. Only used when the turn names no model of its own.",
+        ),
         // Set ONLY by the daemon's own automation dispatchers: this turn opens a conversation on behalf of an
         // outside message rather than a user. Recorded on the registry entry so the fleet can say where the
         // agent came from. Requires conversationId, there is nothing to record it on otherwise.
@@ -311,7 +329,7 @@ export const AgentTurnSchema = z
          * opposite defaults, the chat wants the provider's own catalog default, an unattended run wants the
          * tier its owner chose for work that spends money while they are not watching.
          *
-         * The daemon fills `agent`/`model` and the pinned entry's own knobs from agentRunModels for any turn that says
+         * The daemon fills `agent`/`model` and the pinned entry's own knobs from the turn's own role list for any turn that says
          * this and names none of them (startConversationTurn), walking that list until one can actually be
          * started. Naming one still wins: every surface-started run now carries a caret that overrides the list
          * for that run alone, and Acceptance picks per run because it fans a session out per story. Either way
@@ -416,14 +434,14 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
  * Shared rather than re-declared per route because every surface that starts an agent for the user now carries
  * that caret, and they must all mean the same thing by it: the pair rides onto the turn as `agent`/`model`, and
  * the daemon's own fill step then leaves it alone (turn-resume.ts fills only what is absent). ABSENT is the
- * ordinary case and the one to keep cheap, nobody touched the caret, so `agentRunModels` answers.
+ * ordinary case and the one to keep cheap, nobody touched the caret, so the turn's `runRole` list answers.
  *
  * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
  * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
  * has never heard of is a supported pick, since the picker offers a custom-id escape hatch.
  *
  * AND THE TIER IT RUNS AT, because naming a model is only half of what the standing setting says. A pinned
- * entry carries its own effort (AgentRunPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
+ * entry carries its own effort (ModelPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
  * named no model (turn-resume.ts): so a caret that could re-point the model but not the tier moved every
  * override onto the provider's own default effort, and the one moment somebody reaches for the caret is the
  * failure that just beat the standing order. Optional, and absent means absent, the turn goes out without an
@@ -442,29 +460,36 @@ export const AgentRunPickSchema = z
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
-/* A MODEL PINNED FOR EVERY SURFACE-STARTED RUN, one entry of settings.agentRunModels: the standing version of
- * the pick above, and not merely which model but HOW it is to be run.
+/* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not
+ * merely which model but HOW it is to be run.
  *
- * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object where the setting
- * used to hold a `${provider}:${model}` string. The reasoning effort was a single field beside the list, so one
- * tier answered for every model in it — and the entries of that list are deliberately NOT interchangeable: it
- * is a frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is
- * a property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
+ * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object rather than a
+ * `${provider}:${model}` string. The reasoning effort was once a single field beside a list, so one tier
+ * answered for every model in it — and the entries of such a list are deliberately NOT interchangeable: it is a
+ * frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is a
+ * property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
  * is switched off), so a shared effort was either off-scale for half the list or the lowest common rung for all
- * of it. Each entry now carries what the composer's picker configures for the turn in front of you.
+ * of it. Each entry carries what the composer's picker configures for the turn in front of you.
+ *
+ * THE SAME SHAPE FOR EVERY ROLE, one-shot helpers included, and that is a deliberate widening. A commit
+ * message or a session title used to be pinnable by model alone, on the argument that the daemon runs those
+ * with reasoning off and no effort, so a control for either would be a switch with nothing behind it. True of
+ * the machinery, and it made the machinery the argument: an owner who pins a reasoning model to their commit
+ * subjects was paying that model's price to have its distinguishing feature suppressed. The knobs now travel
+ * through the one-shot path too, so an entry means the same thing wherever it is written.
  *
- * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the turn goes out without the field and the
+ * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the work goes out without the field and the
  * provider's own default answers, exactly as an unconfigured pin always did. Nothing here invents a "low".
  *
  * NO TIER HOLD, and its absence is the rule rather than an omission: automatic tier selection gates on
- * `unattended` (prompt-complexity.ts), so a surface-started run is never downgraded in the first place and a
- * veto over it would be a control whose state can make no difference to anything.
+ * `unattended` (prompt-complexity.ts), so a role-started run is never downgraded in the first place and a veto
+ * over it would be a control whose state can make no difference to anything.
  *
  * The pair is BOTH HALVES for the reason the pick above is: a model id is only meaningful to the provider that
  * vends it, so half a pin would send a Codex id to Claude. Taken verbatim, never validated against a catalog:
  * the picker offers a custom-id escape hatch, so a model this build has never heard of is a supported pin. */
-export const AgentRunPinSchema = z.object({
-    provider: AgentProviderSchema.describe("Which provider serves the run."),
+export const ModelPinSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves this work."),
     model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),
     effort: z
         .string()
@@ -474,7 +499,7 @@ export const AgentRunPinSchema = z.object({
     fast: z.boolean().optional().describe("Ask for this model's work at a higher rate for a higher price. A request rather than a promise."),
     harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
 });
-export type AgentRunPin = z.infer<typeof AgentRunPinSchema>;
+export type ModelPin = z.infer<typeof ModelPinSchema>;
 // POST /agent's ack: the daemon-minted id of the detached turn run it started. The turn executes daemon-side
 // regardless of any client connection; every window, the initiator included, renders it via /agent/attach.
 export const StartedTurnSchema = z.object({

package/src/schemas/agents.ts

@@ -182,8 +182,8 @@ export const LandedMessageSchema = z.object({
         .describe("What this change takes away, for anything already relying on it. Nearly always absent: it is for removals, not for additions."),
 });
 export type LandedMessage = z.infer<typeof LandedMessageSchema>;
-/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The quick-model chain tries the
- * connected models in order (agent/quick-model.ts), and each rung ends one of four ways:
+/* ONE MODEL'S TURN IN THE DRAFTING WALK, asked, and what became of the ask. The one-shot helper chain tries the
+ * connected models in order (agent/role-model.ts), and each rung ends one of four ways:
  *   asking  , in flight right now; `ms` absent because it is still being spent.
  *   answered, it wrote the sentence, in `ms`.
  *   refused , it failed or declined, in `ms`, with its own words in `reason`.

package/src/schemas/plan-limits.ts

@@ -58,6 +58,56 @@ export const AccountUsageSchema = z.object({
     measuredAt: z.number(),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+/* THE ONE WAY PAST A SPENT SESSION WINDOW THAT IS NOT WAITING, which Anthropic grants once a week per account.
+ *
+ * Every other affordance around a refused turn is about WHEN: arm the appointment, count down to the reset,
+ * press when it opens. This one moves the clock. The provider reopens the five-hour window immediately and
+ * charges the account one of its weekly resets; the WEEKLY allowance is untouched and still binds, so this
+ * buys back the session pool and nothing else. Upstream's own CLI spells it `/limit-reset`.
+ *
+ * THE ANSWER IS THE PROVIDER'S, NEVER OURS. There is no rule here to re-derive: eligibility turns on the plan
+ * tier, how long the account has existed, whether it is actually at the wall, whether another experiment holds
+ * it, and whether the week's reset is already spent — all of it decided server-side and none of it visible from
+ * a usage reading. So this shape is a transcription of what the endpoint said, and the button exists only while
+ * it says `available`. A client must never infer availability from a 100% window.
+ *
+ * `reason` is the provider's own word for the refusal ("tier", "tenure", "not_at_wall", "weekly_limit",
+ * "already_used", …) and is carried rather than translated, because the set is the provider's to extend and a
+ * word we don't recognise is still worth showing to somebody asking why the button is not there. */
+export const LimitResetStatusSchema = z.object({
+    available: z
+        .boolean()
+        .describe("Whether the provider will reopen this account's session window right now. The only thing a button may be drawn from."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why not, in the provider's own word, when it gave one. Absent when it is available, or when the provider said nothing."),
+    // Both epoch SECONDS, matching every other reset instant on the wire (UsageWindow.resetsAt, limitResetsAt).
+    nextAvailableAt: z
+        .number()
+        .optional()
+        .describe("When the next reset may be claimed, in epoch seconds, where the provider publishes it. Absent means unknown, never 'now'."),
+    weeklyResetsAt: z.number().optional().describe("When the weekly allowance itself reopens, in epoch seconds, where the provider publishes it."),
+});
+export type LimitResetStatus = z.infer<typeof LimitResetStatusSchema>;
+/* WHAT CLAIMING IT DID, in the provider's own vocabulary plus the two failures that are ours.
+ *
+ * `reset` is the only outcome that changed anything, and the caller's cue to send the held turn again. The rest
+ * are all "nothing happened", and they are kept APART rather than folded into one failure because they are read
+ * by somebody who just pressed a button and is owed the difference: `already_used` means come back next week,
+ * `not_limited` means the window reopened while they were reading, `ineligible` means this account never had
+ * it, and `unavailable`/`error` mean try again. Collapsing them would make every one of those read as a fault.
+ *
+ * Never throws over the wire: a claim that fails leaves the account exactly as it was, and the honest answer to
+ * a press is a word, not a stack trace. */
+export const LimitResetClaimSchema = z.object({
+    result: z
+        .enum(["reset", "already_used", "not_limited", "ineligible", "unavailable", "error"])
+        .describe("What the provider did. Only `reset` reopened the window; every other value means nothing changed."),
+    nextAvailableAt: z.number().optional().describe("When another reset may be claimed, in epoch seconds, where the provider published it."),
+    detail: z.string().optional().describe("What went wrong, in words, for the two outcomes that are this sandbox's fault rather than the plan's."),
+});
+export type LimitResetClaim = z.infer<typeof LimitResetClaimSchema>;
 /* THE LAST TIME A PROVIDER ACTUALLY REFUSED A TURN, the other half of "can I run on this", and the half no
  * meter can supply.
  *