@intentic/sandbox-contract 1.295.0 → 1.296.0

package/src/models/model-offer.ts

@@ -0,0 +1,151 @@
+import { modelPinKey } from "./model-pins.js";
+import type { AgentProvider } from "../schemas/agent.js";
+import type { ModelPick } from "../schemas/model-route.js";
+
+// What the Auto judge is allowed to choose from, and how its reply is read back. Pure: the daemon gathers the facts
+// (catalogs, connected accounts, headroom readings) and this turns them into the lines the model sees and the
+// validator that reads its answer. Nothing outside the offer can be chosen, so a hallucinated model id is caught here
+// rather than at the provider.
+
+export interface OfferedWindow {
+    // Narrow token for the pool's length, e.g. "5h", "wk"; absent when nothing names how long the window runs.
+    readonly short?: string;
+    readonly label?: string;
+    // 0-100 REMAINING, the complement of the reading's utilization: the judge is asked about what is left, not spent.
+    readonly left: number;
+    // Epoch seconds, as every reset instant on this wire.
+    readonly resetsAt?: number;
+}
+
+export interface OfferedAccount {
+    readonly id: string;
+    // The owner's own name for it where there is one; the id is what must be replied with either way.
+    readonly label?: string;
+    // Empty means never measured, which is not the same as measured full and must not read as it.
+    readonly windows: readonly OfferedWindow[];
+}
+
+export interface OfferedModel {
+    readonly provider: AgentProvider;
+    readonly model: string;
+    readonly label: string;
+    // Weakest first, as the catalog row published them; empty means this model takes no effort setting.
+    readonly efforts: readonly string[];
+    // One short clause about what the model is for, where the catalog carries one.
+    readonly note?: string;
+}
+
+export interface ModelOffer {
+    // Already filtered: a model whose every account is at cap never reaches here.
+    readonly models: readonly OfferedModel[];
+    // Accounts that can pay, per provider id. A provider with none still offers its models: an unnamed account is a
+    // real state (a plain key, an endpoint), and the turn resolves one itself.
+    readonly accounts: Readonly<Record<string, readonly OfferedAccount[]>>;
+}
+
+// Relative phrasing of a reset, since an absolute instant would need the reader's timezone; deliberately coarse at
+// every scale. `reopensAt` is epoch seconds, `now` epoch ms.
+export const renewsInWords = (reopensAt: number, now: number): string => {
+    const seconds = reopensAt - Math.floor(now / 1000);
+    if (seconds <= 60) {
+        return `any moment`;
+    }
+    if (seconds < 60 * 60) {
+        return `in about ${Math.round(seconds / 60)} min`;
+    }
+    if (seconds < 36 * 60 * 60) {
+        return `in about ${Math.round(seconds / 3600)}h`;
+    }
+    return `in about ${Math.round(seconds / 86_400)} days`;
+};
+
+const windowWords = (window: OfferedWindow, now: number): string => {
+    const name = window.short ?? window.label ?? `allowance`;
+    const renews = window.resetsAt === undefined ? `` : ` (renews ${renewsInWords(window.resetsAt, now)})`;
+    return `${name}: ${Math.round(window.left)}% left${renews}`;
+};
+
+// An account with no reading says so rather than being left off: "not measured" is a fact the judge should weigh,
+// and an account silently missing from the list would read as one that cannot pay.
+const accountLine = (account: OfferedAccount, now: number): string => {
+    const name = account.label === undefined || account.label === account.id ? account.id : `${account.id} (${account.label})`;
+    const state = account.windows.length === 0 ? `allowance never measured` : account.windows.map((window) => windowWords(window, now)).join(`, `);
+    return `- ${name} — ${state}`;
+};
+
+const modelLine = (model: OfferedModel): string => {
+    const efforts = model.efforts.length === 0 ? `` : ` Effort: ${model.efforts.join(`, `)}.`;
+    const note = model.note === undefined ? `` : ` ${model.note.trim().replace(/\.$/u, ``)}.`;
+    return `- ${modelPinKey(model)} — ${model.label}.${note}${efforts}`;
+};
+
+// The two blocks the prompt shows: what may be run, and who can pay for it. Providers keep the offer's own order, so a
+// reply can be compared against the list a person would read.
+export const offerLines = (offer: ModelOffer, now: number): readonly string[] => {
+    const providers = [...new Set(offer.models.map((model) => model.provider))];
+    return [
+        `Models you may choose:`,
+        ...offer.models.map(modelLine),
+        ``,
+        `Accounts that can pay, and how much allowance each has left:`,
+        ...providers.flatMap((provider) => {
+            const accounts = offer.accounts[provider] ?? [];
+            return accounts.length === 0
+                ? [`- ${provider}: no named account; this provider resolves its own.`]
+                : [`- ${provider}:`, ...accounts.map((account) => `  ${accountLine(account, now)}`)];
+        }),
+    ];
+};
+
+// Wrapper words a model reaches for anyway: a fence, a bullet, quotes, a trailing period.
+const FENCE_LINE = /^```/u;
+const BULLET_LINE = /^[-*•]\s+/u;
+const FIELD = /^(model|effort|account)\s*:\s*(.+)$/iu;
+
+const bare = (value: string): string => value.trim().replace(/^[`'"]+/u, ``).replace(/[.`'"]+$/u, ``).trim();
+
+// The reply's `key: value` lines, lowercased keys, bullets and fences stripped. First wins: a model that answers twice
+// meant its first answer, and a later line is commentary on it.
+const fieldsOf = (reply: string): ReadonlyMap<string, string> => {
+    const fields = new Map<string, string>();
+    for (const line of reply.split(`\n`)) {
+        const trimmed = line.trim().replace(BULLET_LINE, ``);
+        const found = FENCE_LINE.test(trimmed) ? null : FIELD.exec(trimmed);
+        const key = found?.[1]?.toLowerCase();
+        if (key !== undefined && found?.[2] !== undefined && !fields.has(key)) {
+            fields.set(key, bare(found[2]));
+        }
+    }
+    return fields;
+};
+
+export interface ParsedPick {
+    readonly pick: ModelPick | undefined;
+    // The reply's literal model line, for the sentence explaining why a rung was stepped over.
+    readonly token: string;
+}
+
+// Reads the keyed reply (`model:` / `effort:` / `account:`) against the offer. The MODEL is the load-bearing choice:
+// one that names nothing offered yields no pick, and the caller steps to the next rung rather than running an id no
+// provider has. An unrecognised effort or account is dropped instead, keeping the model it came with — those are
+// refinements, and the turn's own defaults answer for them correctly.
+export const parseModelPick = (reply: string, offer: ModelOffer): ParsedPick => {
+    const fields = fieldsOf(reply);
+    const token = fields.get(`model`) ?? ``;
+    const chosen = offer.models.find((model) => modelPinKey(model).toLowerCase() === token.toLowerCase());
+    if (chosen === undefined) {
+        return { pick: undefined, token };
+    }
+    const effort = fields.get(`effort`);
+    const account = fields.get(`account`);
+    const named = (offer.accounts[chosen.provider] ?? []).find((entry) => entry.id.toLowerCase() === account?.toLowerCase());
+    return {
+        pick: {
+            provider: chosen.provider,
+            model: chosen.model,
+            ...(effort !== undefined && chosen.efforts.includes(effort.toLowerCase()) ? { effort: effort.toLowerCase() } : {}),
+            ...(named === undefined ? {} : { account: named.id }),
+        },
+        token,
+    };
+};

package/src/models/model-roles.ts

@@ -65,6 +65,15 @@ export const MODEL_ROLES = [
         kind: "helper",
         icon: "users",
     },
+    {
+        // Picks one offered `provider:model` line, an effort and an account from a fixed list; a classification, not
+        // free text. Prompt carries live account headroom, so it must not be a model whose own allowance it is reading.
+        id: "model-router",
+        label: "Auto model choice",
+        blurb: "Which model reads a new chat's first message and picks the model, effort and account it runs on.",
+        kind: "helper",
+        icon: "sparkles",
+    },
     {
         id: "pipeline-fix",
         label: "Pipeline fixes",

package/src/schemas/agent.ts

@@ -262,6 +262,13 @@ export const AgentTurnSchema = z
             ),
         // Vetoes automatic tier selection for this turn; the judge still runs and records its verdict, but nothing is
         // substituted.
+        // Set by the composer on the one turn whose model the Auto judge chose; the daemon only records it.
+        autoPicked: z
+            .boolean()
+            .optional()
+            .describe(
+                "Whether this turn's model was chosen for you by reading the conversation's opening message, rather than picked by hand. Recorded so the choice can be judged later against what you did next.",
+            ),
         tierHold: z
             .boolean()
             .optional()

package/src/schemas/model-route.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { AgentProviderSchema } from "./agent.js";
+
+// Asked once per chat, on the message it opens with; answers with the model, effort and account that whole
+// conversation runs on. Distinct from prompt-complexity.ts, which judges a turn at a time and may only ever name a
+// cheaper rung of the provider already picked: this one chooses freely, and only before anything has run.
+
+export const ModelRouteAskSchema = z.object({
+    prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
+    paths: z
+        .array(z.string().min(1).max(500))
+        .max(50)
+        .default([])
+        .describe("Workspace paths the message names: uploads, @-mentions, the editor's own file. How much real code the work touches."),
+    editorContext: z.boolean().optional().describe("Whether the message carries a file and selection the user pointed at, so it is about real code."),
+    planMode: z.boolean().optional().describe("Whether the chat opens in plan mode, which is a request to think before acting."),
+});
+export type ModelRouteAsk = z.infer<typeof ModelRouteAskSchema>;
+
+export const ModelPickSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves the conversation."),
+    model: z.string().min(1).describe("Which of its models."),
+    effort: z.string().optional().describe("How hard it should think, where the model offers a choice. Absent takes the model's own default."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which connected account pays, by its daemon-minted id. Absent leaves it to whichever account has the most headroom."),
+});
+export type ModelPick = z.infer<typeof ModelPickSchema>;
+
+export const ModelRouteSchema = z.object({
+    // Absent is a real, safe answer: the chat runs on whatever the picker remembered, and says why nothing moved.
+    pick: ModelPickSchema.optional().describe("What the conversation should run on, or absent when nothing could be chosen and the usual pick stands."),
+    reason: z.string().describe("Why, in the one line a chat can show. Present whether or not a model was named."),
+    // Absent means nothing was spent: the role was unset, every rung refused, or the deadline passed first.
+    judge: z
+        .string()
+        .optional()
+        .describe(
+            "Which model answered, as `provider:model`, so the chat can name what the reading cost. Absent when no model was reached at all.",
+        ),
+});
+export type ModelRoute = z.infer<typeof ModelRouteSchema>;

package/src/schemas/providers/usage.ts

@@ -102,6 +102,10 @@ export const UsageTurnSchema = z.object({
     tierCeiling: z.number().optional(),
     // The turn carried AgentTurn.tierHold: the user vetoed a fast verdict. Absent means no veto.
     tierDenied: z.boolean().optional(),
+    // This turn's model was chosen by the Auto judge reading the conversation's opening message, not picked by hand.
+    // Marked on that one turn only; a later row of the same conversation naming a different model is the user
+    // overruling it, which is the escalation rate this feature has to be able to answer for.
+    autoPicked: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 // Ledger grouped by day, provider, account, model, harness and conversation, one panel's worth of rows per active day.

package/src/schemas/settings.ts

@@ -317,11 +317,15 @@ export const SandboxSettingsSchema = z.object({
     // off: the judge never runs.
     // shadow (default): the judge scores every turn to the ledger; nothing is routed.
     // on: a turn judged fast runs on the cheap rung, where the provider publishes one.
+    // judge: the deterministic scorer keeps writing shadow rows but routes nothing; the Auto picker row is offered
+    // instead, and a model reads a new chat's opening message once to choose what the whole conversation runs on.
+    // Exclusive with `on` because the two answer the same question at different moments, and a per-turn downgrade
+    // underneath a picked-by-model conversation would be overruling a choice already made about this chat.
     autoTier: z
-        .enum(["off", "shadow", "on"])
+        .enum(["off", "shadow", "on", "judge"])
         .default("shadow")
         .describe(
-            "Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for.",
+            "Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for. The fourth, Auto, answers a different question: rather than downgrading turns one by one, it offers an Auto row in the model picker and has a model read a new chat's first message to choose what that whole conversation runs on.",
         ),
     // `balanced` is what every verdict recorded before this setting existed was judged against, so shadow history stays
     // comparable.