@intentic/sandbox-contract 1.176.3 → 1.209.1

package/src/history-state.ts

@@ -16,7 +16,7 @@ import type { StateFile } from "./state-portability.js";
  * these entries would be a column of empty arrays. What they share is the portability class, and that is
  * imported rather than duplicated.
  *
- * `history-state.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
+ * `history-state-coverage.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
  * directions — the same shape-recognizing guard that covers the workspace table.
  */
 
@@ -38,10 +38,26 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
+    // What each message can be put back to — a workspace checkpoint, or an isolated conversation's own commits.
+    // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a
+    // restored conversation reads back whole and offers no way back into it, even though both the messages and
+    // the states they name travelled.
+    { path: "turn-anchors.json", portability: "carry" },
+    /* WHICH CONVERSATIONS ARE PUBLISHED AS PAGES ANYONE WITH THE LINK CAN READ.
+     *
+     * Carried, and it is the entry with the most to say for itself: the PAGES live in the workspace's outbox
+     * (`public/`), so they travel with `/work` whatever this says. Leaving the index behind would restore a
+     * sandbox that is still serving somebody's conversation on the internet with nothing in the app that knows
+     * it — no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
+     * a published page withdrawable, so it goes wherever the pages go. */
+    { path: "shares.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
     { path: "usage.jsonl", portability: "carry" },
     { path: "account-usage.json", portability: "carry" },
     { path: "provider-refusals.json", portability: "carry" },
+    // Explicit first-time dependency setup requests. Carrying the worklist preserves the owner's decision when
+    // an export interrupts the queue before its terminal starts; fulfilled entries remove themselves.
+    { path: "dependency-requests.json", portability: "carry" },
     // The deploy engine's own ledgers — a run's events and the check results the Pipelines view reads back.
     { path: "apply-events.ndjson", portability: "carry" },
     { path: "check-events/", portability: "carry" },
@@ -66,6 +82,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "logs/", portability: "derived" },
     { path: "trash/", portability: "derived" },
     { path: ".isolation-probe", portability: "derived" },
+    /* The finished bundles themselves. `derived` is doing real work here rather than describing leftovers: an
+     * export that carried the export directory would pack every previous bundle into the new one, and the next
+     * export would pack THAT — each one a multiple of the last. Living on this volume is the other half of the
+     * same guard; under `/work` the file would also be watched, indexed by iq, and snapshotted into history. */
+    { path: "exports/", portability: "derived" },
 
     /* ---- credentials ---- */
 
@@ -88,6 +109,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
      * target — an export becomes a credential — and the target minting its own costs exactly one sign-in. */
     { path: "session-secret", portability: "identity", note: "Sign in again — the target signs its own sessions." },
+    {
+        path: "browser-access-disabled",
+        portability: "identity",
+        note: "Account-deletion retirement belongs to the source sandbox; the imported copy starts with fresh browser access.",
+    },
     {
         path: "push.json",
         portability: "identity",
@@ -96,5 +122,8 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },
     { path: "host-enrollments.json", portability: "identity" },
+    // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
+    // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
+    { path: "host-pair-consumed.json", portability: "identity" },
     { path: "local-cert/", portability: "identity" },
 ];

package/src/hostnames.ts

@@ -48,22 +48,34 @@ export const CATCH_ALL = { service: "http_status:404" } as const;
 // ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
 // port's hostname is not derivable from the (public) sandbox id alone — see tunnel-ids for why that matters.
 //
-// A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>`) — the unit
-// the platform's /sandbox/preview-route mints, so one endpoint serves both schemes.
+// Outbox scheme: `public-<slot>-<sandboxId>.<zone>` — the same shape again, serving the workspace's `public/`
+// directory as static files. <slot> is publicSlotFromToken (./tunnel-ids), salted for the same reason the port
+// slots are, and one record per sandbox rather than a pool: there is one outbox, and its link has to stay good
+// for as long as the file does.
+//
+// A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>` /
+// `public-<slot>`) — the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
+export const publicLabel = (slot: string): string => `public-${slot}`;
 
 // The hostname a label resolves to — what the platform's /sandbox/preview-route mints from the label alone.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);
 export const portHostname = (slot: string, id: string, zone: string): string => labelHostname(portLabel(slot), id, zone);
+export const publicHostname = (slot: string, id: string, zone: string): string => labelHostname(publicLabel(slot), id, zone);
 
-// A panel's / forwarded port's preview URL — undefined unless the sandbox has both a zone and an id
-// (headless/loopback sandboxes have neither and advertise no preview).
+// A label's public URL — undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
+// have neither and advertise nothing). One builder, three vocabularies: a panel's preview, a forwarded port's,
+// and the outbox's.
+const labelUrl = (label: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${labelHostname(label, sandboxId, zone)}` : undefined;
 export const previewUrl = (panel: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${previewHostname(panel, sandboxId, zone)}` : undefined;
+    labelUrl(previewLabel(panel), zone, sandboxId);
 export const portUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
-    zone !== undefined && zone !== "" && sandboxId !== undefined ? `https://${portHostname(slot, sandboxId, zone)}` : undefined;
+    labelUrl(portLabel(slot), zone, sandboxId);
+export const publicUrl = (slot: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
+    labelUrl(publicLabel(slot), zone, sandboxId);
 
 // The key after `<prefix>` from a request's Host header. The first DNS label must carry the prefix (the
 // own-Cloudflare wildcard also catches stray subdomains → undefined → the caller's 404) and, when the sandbox
@@ -87,6 +99,8 @@ export const panelFromHost = (hostHeader: string | undefined, sandboxId: string
     keyFromHost("preview-", hostHeader, sandboxId);
 export const portSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
     keyFromHost("port-", hostHeader, sandboxId);
+export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: string | undefined): string | undefined =>
+    keyFromHost("public-", hostHeader, sandboxId);
 
 // The sandbox's identity AS THE USER SEES IT: the leading DNS label of its public URL, minus the `sandbox-`
 // prefix — `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ContractRoute } from "./routes.js";
-import { contractRoutes, routeNameForRequest } from "./routes.js";
+import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes } from "./routes.js";
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
@@ -8,31 +8,33 @@ import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
 import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
-import { codexContract } from "./contracts/codex.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
-import { geminiContract } from "./contracts/gemini.contract.js";
+import { personasContract } from "./contracts/personas.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
 import { grokContract } from "./contracts/grok.contract.js";
 import { historyContract } from "./contracts/history.contract.js";
 import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
-import { kimiContract } from "./contracts/kimi.contract.js";
-import { komodoContract } from "./contracts/komodo.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
-import { memoryContract } from "./contracts/memory.contract.js";
+import { loopsContract } from "./contracts/loops.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
+import { publicContract } from "./contracts/public.contract.js";
 import { prepushContract } from "./contracts/prepush.contract.js";
+import { providersContract } from "./contracts/providers.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
+import { shareContract } from "./contracts/share.contract.js";
+import { skillsContract } from "./contracts/skills.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
 import { usageContract } from "./contracts/usage.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
+import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
 
 export { activityContract } from "./contracts/activity.contract.js";
@@ -43,11 +45,10 @@ export { capabilitiesContract } from "./contracts/capabilities.contract.js";
 export { choresContract } from "./contracts/chores.contract.js";
 export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
-export { codexContract } from "./contracts/codex.contract.js";
 export { draftsContract } from "./contracts/drafts.contract.js";
-export { endpointsContract } from "./contracts/endpoints.contract.js";
+export { endpointsContract, TrialStatusSchema, type TrialStatusResponse } from "./contracts/endpoints.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
-export { geminiContract } from "./contracts/gemini.contract.js";
+export { personasContract } from "./contracts/personas.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
 export { grokContract } from "./contracts/grok.contract.js";
 export { historyContract } from "./contracts/history.contract.js";
@@ -56,37 +57,61 @@ export { historyContract } from "./contracts/history.contract.js";
 export { hostContract } from "./contracts/host.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
-export { kimiContract } from "./contracts/kimi.contract.js";
-export { komodoContract } from "./contracts/komodo.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
-export { memoryContract } from "./contracts/memory.contract.js";
+export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";
+export { publicContract } from "./contracts/public.contract.js";
 export { prepushContract } from "./contracts/prepush.contract.js";
+export { providersContract } from "./contracts/providers.contract.js";
 export { pushContract } from "./contracts/push.contract.js";
 export { secretsContract } from "./contracts/secrets.contract.js";
 export { sessionsContract } from "./contracts/sessions.contract.js";
 export { settingsContract } from "./contracts/settings.contract.js";
+export { shareContract } from "./contracts/share.contract.js";
+export { skillsContract } from "./contracts/skills.contract.js";
 export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
 export { usageContract } from "./contracts/usage.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
+export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
 export * from "./events.js";
 export * from "./sse.js";
 export * from "./routes.js";
+/* THE CONTAINER'S FIXED DIRECTORY LAYOUT, re-exported so extensions can reach it.
+ *
+ * The names are defined once in @intentic/constants, which sits at the bottom of the dependency graph. An
+ * EXTENSION may not import that package — the boundary rule (.oxlintrc.json, _extensions/README.md) allows
+ * only the SDK halves and this contract, so that an extension cannot couple itself to app or engine internals.
+ * That rule is right, and it left extensions with no way to name the workspace root except by spelling it.
+ *
+ * Re-exporting here is what closes that gap without widening the boundary: the layout is exactly the kind of
+ * thing this package already carries — shared vocabulary both sides of the wire must agree on, alongside the
+ * state-file table below — and there is still one definition, in one place, that everything resolves to. */
+export { HISTORY_ROOT, HOST_STATE_ROOT, STATE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
 export * from "./workspace-state.js";
+export * from "./runtime-state.js";
 export * from "./state-portability.js";
 export * from "./history-state.js";
 export * from "./agent-catalog.js";
+export * from "./agent-run-model.js";
+export * from "./capability-env.js";
+export * from "./conversation-ids.js";
 export * from "./host-protocol.js";
+export * from "./listener-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
 export * from "./path-refs.js";
 export * from "./quick-model.js";
+export * from "./output-fields.js";
+export * from "./publish-drafts.js";
 export * from "./schemas.js";
+export * from "./search-globs.js";
 export * from "./terminal-protocol.js";
 export * from "./title.js";
+export * from "./versions.js";
+export * from "./workflow-faults.js";
 
 // The aggregated contract — implemented on the server by the per-domain route factories and consumed by the
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
@@ -100,32 +125,34 @@ export const sandboxContract = {
     chores: choresContract,
     ci: ciContract,
     claude: claudeContract,
-    codex: codexContract,
     drafts: draftsContract,
     endpoints: endpointsContract,
     extensions: extensionsContract,
+    personas: personasContract,
     sessions: sessionsContract,
     settings: settingsContract,
+    share: shareContract,
+    skills: skillsContract,
     intentic: intenticContract,
-    gemini: geminiContract,
     git: gitContract,
     grok: grokContract,
-    kimi: kimiContract,
-    komodo: komodoContract,
     history: historyContract,
     workspace: workspaceContract,
     inventory: inventoryContract,
     logs: logsContract,
-    memory: memoryContract,
+    loops: loopsContract,
     panels: panelsContract,
     ports: portsContract,
+    public: publicContract,
     prepush: prepushContract,
+    providers: providersContract,
     push: pushContract,
     secrets: secretsContract,
     system: systemContract,
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    workflows: workflowsContract,
 };
 
 // Every route in THIS build of the contract, and the names the daemon advertises on its hello frame. Bound here
@@ -135,6 +162,20 @@ export const sandboxContract = {
 export const SANDBOX_ROUTES: readonly ContractRoute[] = contractRoutes(sandboxContract);
 export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route) => route.name);
 
+/* And the SHAPE of each of those routes, advertised beside the names for the failure the names cannot describe:
+ * a route both builds have, answering a payload only one of them expects. Computed once at module load — it
+ * walks every contract schema through `z.toJSONSchema`, which is far too much work to repeat per connection and
+ * exactly the kind of thing that never changes for the life of a process. See routes.ts. */
+export const SANDBOX_ROUTE_SHAPES: Readonly<Record<string, string>> = routeShapes(sandboxContract);
+
 // The contract route a concrete browser request belongs to, bound to this build's route table.
 export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined =>
     routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);
+
+// The method and concrete path a TYPED call is about to put on the wire, bound to this build's route table.
+// Undefined when the procedure is not one this contract declares, which a typed caller cannot reach — the host
+// gate treats it as a refusal rather than assuming it is harmless.
+export const sandboxRequestFor = (procedure: readonly string[], input: unknown): { method: string; path: string } | undefined => {
+    const route = routeForProcedure(SANDBOX_ROUTES, procedure);
+    return route === undefined ? undefined : { method: route.method, path: requestPathFor(route, input) };
+};

package/src/listener-protocol.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { ActivityStatusSchema } from "./schemas.js";
+
+/* The wire between the daemon and an extension's realtime-listener GATEWAY process (ext-discord, ext-slack,
+ * ext-telegram, ext-whatsapp, ext-imap): the four provider-scoped routes app.ts mounts under
+ * /listeners/:provider — state, dispatch, failure, status. These shapes used to live daemon-side only, with
+ * every gateway hand-writing its own copy of the payloads as untyped literals; a field rename broke five
+ * producers silently. They live in the contract now so BOTH ends compile against one declaration — the daemon
+ * parses with the schemas, the gateways (via @intentic/connector-runtime) type against the inferred types. */
+
+// One normalized inbound event — serialized as a JSON line in the automation's payload, and the JSON body a
+// realtime source POSTs to /listeners/<provider>/dispatch. A zod schema (not a bare interface) because it's
+// parsed from an extension gateway's request; `provider` and `type` are open strings — the source is
+// extension-declared (contributes.listener), not a core enum.
+export const ListenerMessageSchema = z.object({
+    provider: z.string().min(1),
+    type: z.string().min(1),
+    id: z.string(),
+    channelId: z.string(),
+    author: z.object({ id: z.string(), name: z.string() }),
+    content: z.string(),
+    // Discord message: it @mentions one of our bots or replies to a bot's message. Voice events never set it.
+    mentioned: z.boolean().optional(),
+    // CI pipeline event: the ref it ran on. Top-level rather than inside `extra` for the same reason
+    // `mentioned` is — the dispatcher MATCHES on it, and a narrowing axis the trigger can name has to be
+    // a field of the message rather than a key in a provider's opaque bag.
+    branch: z.string().optional(),
+    // Prior channel messages (chronological) fetched when a bot is tagged, so the agent can reason about why.
+    // Kept a top-level field (not in `extra`) so it reaches the model's payload but stays out of the activity
+    // feed, which logs only content/extra.
+    history: z
+        .array(
+            z.object({
+                author: z.object({ id: z.string(), name: z.string() }),
+                content: z.string(),
+                timestamp: z.string(),
+                self: z.boolean().optional(),
+            }),
+        )
+        .optional(),
+    timestamp: z.string(),
+    // Provider-specific fields (discord message: guildId, attachments; voice_utterance: path;
+    // voice_transcript: path, participants, durationSeconds).
+    extra: z.record(z.string(), z.unknown()).optional(),
+});
+export type ListenerMessage = z.infer<typeof ListenerMessageSchema>;
+
+// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response — a text delta for one automation's
+// reply, the provider's own failure sentence, or that automation's terminal marker. A type, not a schema: the
+// DAEMON produces these (listener.routes.ts), so nothing parses them from untrusted input.
+export interface ListenerDispatchFrame {
+    readonly automationId: string;
+    readonly delta?: string;
+    // The turn refused or broke, in the provider's own words — forwarded verbatim because a gateway delivers
+    // into the owner's own channel, where the actual sentence is the useful thing.
+    readonly failed?: string;
+    readonly end?: boolean;
+}
+
+/* WHERE ONE CAPABILITY'S LINK-A-DEVICE CEREMONY STANDS (whatsapp), reported every status tick.
+ *
+ * A CODE IS NOT THE ONLY THING WORTH SAYING, and publishing only codes is what made a phone that had never
+ * linked read as connected: the seconds before the first code, a gateway that just restarted, and a number
+ * WhatsApp refused all looked identical from the daemon's side — an absent code — so the card fell through to
+ * "ready" and the owner was sent away from the one screen that could have shown them the step. Each of those is
+ * its own state here, and every one of them means NOT PAIRED YET.
+ *
+ * `since` stamps the CURRENT code. WhatsApp closes an unpaired socket after a minute or so and each reopen mints
+ * a fresh code, so a code is a thing with an age — the card says how old the one on screen is rather than
+ * leaving the owner to type a dead one twice. */
+export const ListenerPairingSchema = z.object({
+    // waiting: a socket is up and the code hasn't arrived (or the last one died with its socket).
+    // code: `code` is live — type it on the phone. failed: `detail` says what WhatsApp refused.
+    state: z.enum(["waiting", "code", "failed"]),
+    code: z.string().optional(),
+    detail: z.string().optional(),
+    since: z.number().optional(),
+});
+export type ListenerPairing = z.infer<typeof ListenerPairingSchema>;
+
+// Push-based listener status: a gateway process POSTs its live connection/voice snapshot to
+// /listeners/<provider>/status, and the activity route reads it from there — the daemon holds no provider
+// connection of its own to probe. The body IS the ActivityStatus the /activity/status probe used to build from
+// in-process discord singletons, plus the per-gateway extras that ride the same channel: whether whisper is
+// present (discord's voice-pending signal) and each unpaired capability's ceremony by id (whatsapp's
+// link-a-device flow — the capability card renders it as the step the owner is standing in front of).
+export const ListenerStatusSchema = ActivityStatusSchema.extend({
+    whisperReady: z.boolean().optional(),
+    pairing: z.record(z.string(), ListenerPairingSchema).optional(),
+});
+export type ListenerStatus = z.infer<typeof ListenerStatusSchema>;
+
+// A connection's place in the reconcile lifecycle, as the status snapshot reports it: `idle` = up but holding
+// nothing on purpose (no enabled listener automation to connect for), `pairing` = the socket is up but the
+// credential is a ceremony nobody has completed yet (whatsapp), the rest are the connect loop.
+export type ListenerGatewayPhase = "idle" | "ready" | "pairing" | "connecting" | "disconnected";

package/src/model-order.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { compareCheapestFirst, compareModelIds, compareUnrankedModelIds, familyOf, releaseOf, tierRankOf } from "./model-order.js";
+import { compareCheapestFirst, compareModelIds, compareUnrankedModelIds, familyOf, namesThinking, releaseOf, tierRankOf } from "./model-order.js";
 
 /* The order every provider's catalog is served and browsed in. The rule exists because only Anthropic publishes
  * a ranking: the OpenAI-compatible endpoints behind Codex, Gemini, Kimi and Grok hand back a SET, and taking
@@ -186,6 +186,37 @@ test("reads a release-local tier ladder from the cheap end too", () => {
     expect(["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"].toSorted(compareCheapestFirst)[0]).toBe("gpt-5.6-luna");
 });
 
+test("refuses the thinking variant of a model, however new it is", () => {
+    /* The bug this rule exists for, in the shape the live catalog actually publishes it: a routed channel vends
+     * one row per thinking LEVEL, and the newest row of the cheapest model was the high one — so the ladder
+     * whose whole job is to be the cheap rung reached for the most expensive reading of it, and a commit
+     * message that takes 2s took closer to 30. */
+    expect(["gemini-3.6-flash-high", "gemini-3.5-flash-extra-low"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-extra-low");
+    // …and it is the LEVEL that decides, not the release: same model, quieter row wins.
+    expect(["gemini-3.5-flash-high", "gemini-3.5-flash-minimal"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-minimal");
+    // Tier still outranks it: a thinking cheap model beats a silent expensive one, which is the order that
+    // keeps this from quietly promoting a frontier row for being unannotated.
+    expect(["gemini-3-pro", "gemini-3.6-flash-high"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.6-flash-high");
+    // An id nobody annotated is not accused of thinking, and is not credited with silence either: it sits
+    // between the stated ends.
+    expect(["gemini-3-flash", "gemini-3.5-flash-low"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3.5-flash-low");
+    expect(["gemini-3-flash", "gemini-3.6-flash-high"].toSorted(compareCheapestFirst)[0]).toBe("gemini-3-flash");
+});
+
+test("names the thinking rows, and only those", () => {
+    // What a settings row shows beside a pin, so that choosing one is a choice rather than an accident.
+    expect(namesThinking("gemini-3.6-flash-high")).toBe(true);
+    expect(namesThinking("gemini-3.1-pro-low")).toBe(false);
+    expect(namesThinking("gemini-3.5-flash-extra-low")).toBe(false);
+    expect(namesThinking("claude-haiku-4-5-20251001")).toBe(false);
+    expect(namesThinking("gpt-5.6-luna")).toBe(false);
+    // An effort word that is not `high` still names one; so does the on/off form a channel vends beside its
+    // quiet row.
+    expect(namesThinking("gpt-oss-120b-medium")).toBe(true);
+    expect(namesThinking("kimi-k2-thinking")).toBe(true);
+    expect(namesThinking("kimi-k2")).toBe(false);
+});
+
 test("falls back on the newest release for a catalog that publishes no cheap tier at all", () => {
     // Kimi names no tier word anywhere, so every row is UNRANKED and the tier term cancels. Serving the newest
     // of what it does publish is the honest answer — there is no cheaper rung to find.

package/src/model-order.ts

@@ -135,6 +135,46 @@ const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): nu
 
 const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
 
+/* HOW HARD AN ID SAYS IT WILL THINK. A routed catalog does not publish one row per model — it publishes one row
+ * per model PER THINKING LEVEL, spelling the level into the id: `gemini-3.6-flash-high` and
+ * `gemini-3.5-flash-extra-low` are the same Flash at opposite ends of its reasoning budget.
+ *
+ * Which the ranking above cannot see at all, and that blind spot has a direction: `high` and `low` are both
+ * unrecognized words, so two variants of one model tie on tier and the RELEASE tiebreak settles them — and the
+ * newest variant a channel publishes is routinely the high one. The quick model, whose entire job is to be the
+ * cheap rung, would therefore reach for the most expensive reading of the cheapest model it can find.
+ *
+ * That is not a small mis-sort. Thinking is the difference between a commit message that is in the box before
+ * the user has finished reading the file list and one that arrives half a minute later — measured at ~2s versus
+ * ~27s on the same model and the same diff (agent/one-shot.ts, which disables thinking for the rungs where a
+ * request parameter can). For a routed rung there is no such parameter: the id IS the setting, so this ranking
+ * is the only place the choice can be made.
+ *
+ * Read ONLY by the cheap-end order. A picker orders a catalog by what a person reaches for, and a person
+ * pinning `-high` on purpose means it — see compareCheapestFirst for the seam this belongs to. */
+const THINKING_RANK: Readonly<Record<string, number>> = {
+    minimal: 0,
+    none: 0,
+    low: 1,
+    medium: 3,
+    high: 4,
+    max: 4,
+    // Not a level but a switch, and the loudest statement an id can make about this: a channel that vends
+    // `kimi-k2` beside `kimi-k2-thinking` is naming the same model with its reasoning turned on.
+    thinking: 4,
+};
+
+/* An id naming NO level sits between the two ends rather than at either — the provider's own default, which for
+ * a model that can think is usually some thinking. Ranking it cheapest would seat a silent default ahead of an
+ * id that explicitly says `minimal`, and ranking it dearest would bury every model whose channel publishes no
+ * variants at all (Anthropic's, Kimi's) beneath one that does. Neither is what the id claims. */
+const UNSTATED_THINKING = 2;
+
+const thinkingRankOf = (family: string): number => {
+    const rank = lastRankOf(family, THINKING_RANK);
+    return rank === UNRANKED ? UNSTATED_THINKING : rank;
+};
+
 // The LAST recognized word wins, because tier words compose and the rightmost is the most specific one:
 // gemini-flash-lite is the cheap end of Flash, gpt-codex-max the frontier end of Codex.
 export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
@@ -165,9 +205,9 @@ export const compareModelIds = (left: string, right: string): number => {
 export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);
 
 /* THE SAME TIER SCALE READ FROM THE OTHER END, for the one caller that wants the WEAKEST model rather than the
- * strongest: the quick model behind a one-click helper (the commit box's autofill). A picker orders a catalog by
- * what a user reaches for; this orders it by what a helper should spend, and the two are exact opposites — so
- * they share TIER_RANK rather than each naming its own list of cheap ids.
+ * strongest: the quick model behind an automatic helper (the commit message written at land time). A picker
+ * orders a catalog by what a user reaches for; this orders it by what a helper should spend, and the two are
+ * exact opposites — so they share TIER_RANK rather than each naming its own list of cheap ids.
  *
  * The direction of UNRANKED is the reason this can't just be compareModelIds reversed. There, an unrecognized
  * family LEADS, because an id carrying no tier word is the provider's base line and a family nobody here has
@@ -181,7 +221,20 @@ export const compareCheapestFirst = (left: string, right: string): number => {
     const rightFamily = familyOf(right);
     return (
         tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
+        // BEFORE release, and that placement is the point: two rows of one model differing only in thinking
+        // level are the same model, so recency has nothing to say between them, and letting it speak is what
+        // seated the high variant. Tier still wins over both — a thinking Haiku is cheaper than a silent Opus.
+        thinkingRankOf(leftFamily) - thinkingRankOf(rightFamily) ||
         compareRelease(releaseOf(left), releaseOf(right)) ||
         releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
     );
 };
+
+/* WOULD RUNNING THIS ID MAKE THE MODEL THINK — as far as its name admits, which for a routed catalog is as far
+ * as anyone can tell without running it. True only for an id that spells out a level ABOVE the quiet end, so an
+ * ordinary id nobody has annotated (claude-haiku-4-5, kimi-k2) is never accused of it.
+ *
+ * Exported for one job: a settings row that lets someone pin the quick model has to be able to say that the row
+ * they picked is the thinking one. The ordering above keeps Auto off these by construction; a PIN is a
+ * deliberate choice and is honoured as written, which only works if the choice is legible when it is made. */
+export const namesThinking = (id: string): boolean => thinkingRankOf(familyOf(id)) > UNSTATED_THINKING;

package/src/output-fields.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+
+/* A DECLARED OUTPUT SHAPE — the answer to "what does this session produce?", written once and used three ways.
+ *
+ * An agentic session's natural output is prose, and prose is unusable as an input to the next session: a step
+ * that must hand "the three files worth changing" to the step after it cannot hand over a paragraph that
+ * mentions them. So a session that feeds another one declares its shape here, and that one declaration
+ * becomes: the sentence in the prompt that tells the model what to write, the validator that decides whether
+ * it complied, and the table the run view renders. Written once because the three drift apart the moment they
+ * are written twice — a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
+ * says nothing useful about why.
+ *
+ * WHY A FIELD LIST AND NOT JSON SCHEMA. JSON Schema is strictly more expressive and completely unauthorable in
+ * a form: nobody designing a workflow is going to hand-write `{"type":"object","properties":{...}}`, and a UI
+ * that generates it becomes a schema editor, which is a product of its own. Four scalar types plus a string
+ * list covers what one session actually hands another — a verdict, a count, a list of paths, a summary — and
+ * anything past that is better carried as a file the next step reads.
+ *
+ * `description` IS REQUIRED, and that is the field that decides whether this works at all. `{name: "risk"}`
+ * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low — how
+ * likely this change is to break something at runtime"}` gets you the answer to the question you asked.
+ */
+
+// Restricted to a JS-identifier-ish shape: these become object keys the prompt spells out literally, and a
+// name with a quote or a newline in it produces a prompt that cannot be complied with.
+const FIELD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]{0,39}$/;
+
+export const OutputFieldSchema = z.object({
+    name: z.string().regex(FIELD_NAME),
+    type: z.enum(["string", "number", "boolean", "string[]"]),
+    // What the field means, in the words the model is given. Not optional — see the note above.
+    description: z.string().min(1),
+    // An absent optional field validates; an absent required one does not, and the iteration is told which.
+    required: z.boolean(),
+});
+export type OutputField = z.infer<typeof OutputFieldSchema>;
+
+// How many fields one output may declare. A shape past this is not a handoff, it is a report — and a report is
+// what the prose half of the document is for.
+export const OUTPUT_FIELDS_MAX = 16;
+
+/* Repeated names make the declaration internally contradictory: object validation can only keep one rule for
+ * a key, while a consumer looking the field up sees whichever copy it happens to ask for first. Reject them at
+ * the declaration boundary, before either interpretation gets a chance to exist. Exported because graph-level
+ * validation uses the same fact to explain the fault in the designer before a save is attempted. */
+export const duplicateOutputFieldNames = (fields: readonly Pick<OutputField, "name">[]): string[] => {
+    const seen = new Set<string>();
+    const repeated = new Set<string>();
+    for (const field of fields) {
+        if (seen.has(field.name)) {
+            repeated.add(field.name);
+        }
+        seen.add(field.name);
+    }
+    return [...repeated];
+};
+
+export const OutputFieldsSchema = z
+    .array(OutputFieldSchema)
+    .min(1)
+    .max(OUTPUT_FIELDS_MAX)
+    .superRefine((fields, context) => {
+        for (const name of duplicateOutputFieldNames(fields)) {
+            context.addIssue({ code: "custom", message: `Output field names must be unique; "${name}" is repeated.` });
+        }
+    });
+
+const validatorFor = (field: OutputField): z.ZodType => {
+    if (field.type === "number") {
+        return z.number();
+    }
+    if (field.type === "boolean") {
+        return z.boolean();
+    }
+    if (field.type === "string[]") {
+        return z.array(z.string());
+    }
+    return z.string();
+};
+
+/* The declared shape as a validator. Unknown keys are ALLOWED THROUGH: a model that answered everything asked
+ * of it and then added a `notes` key has complied, and failing it there would burn an iteration teaching it to
+ * write less. What is enforced is that every required field is present and every present field has the
+ * declared type — the two things the reader downstream is entitled to assume.
+ */
+export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
+    z.looseObject(Object.fromEntries(fields.map((field) => [field.name, field.required ? validatorFor(field) : validatorFor(field).optional()])));
+
+// A worked example of the declared shape, so the prompt can show rather than describe. Values are the field's
+// own description — a model copying the example's structure has the description in front of it as it fills each
+// slot, which is where it is needed rather than in a legend three lines up.
+export const fieldsExample = (fields: readonly OutputField[]): Record<string, unknown> =>
+    Object.fromEntries(
+        fields.map((field) => {
+            const hint = `${field.description}${field.required ? "" : " (optional — omit if it does not apply)"}`;
+            if (field.type === "number") {
+                return [field.name, 0];
+            }
+            if (field.type === "boolean") {
+                return [field.name, false];
+            }
+            if (field.type === "string[]") {
+                return [field.name, [hint]];
+            }
+            return [field.name, hint];
+        }),
+    );
+
+// One line per field, for surfaces with no room to render an example: "risk (string, required) — how likely …".
+export const describeFields = (fields: readonly OutputField[]): string =>
+    fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}) — ${field.description}`).join(`\n`);