@ultimat3/ai 1.2.0 → 2.0.0

package/src/llm.ts

@@ -11,29 +11,50 @@
  * What the factory adds is the model half: the prompt is rendered from the parsed input, the
  * `output` schema is projected into a tool the model must answer through, a per-call budget is
  * reserved before a token is spent, and a near-duplicate prompt hits the semantic cache.
+ *
+ * `.stream()` is the same action over a different transport, and it is here rather than beside
+ * the gateway for one reason: everything that makes `llm()` worth using — policy, input parse,
+ * budget scope, semantic cache, span, `.tool()` — is lost the moment a feature has to reach past
+ * it to `aiGateway()` for tokens on a screen. `./llm-stream.ts` holds the plumbing and states the
+ * two decisions a stream forces (no repair turn, budget reserved exactly as before); what a
+ * streamed answer must satisfy is decided in this file, next to the non-streaming version of the
+ * same rules.
  */
 
-import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import type { Action, ActionMcp, ActionPolicy, InvokeOptions } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
-import type { Ctx } from '@ultimat3/core';
+import type { Ctx, Span, SpanAttributes } from '@ultimat3/core';
 import { withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
-import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
 import { parseDuration } from '@ultimat3/time';
 import type { BudgetLimits } from './budget';
 import { BudgetLedger, currentBudget, withBudget } from './budget';
 import { embedOne, fnv1a } from './embeddings';
-import { LlmOutputInvalidError, LlmRefusedError, LlmTruncatedError } from './errors';
+import {
+  LlmOutputInvalidError,
+  LlmRefusedError,
+  LlmStreamInvalidError,
+  LlmTruncatedError,
+} from './errors';
+import type { Gateway } from './gateway';
+import type { LlmSink, LlmStreamChunk } from './llm-stream';
+import { currentLlmSink, llmStream, streamOneTurn, withLlmSink } from './llm-stream';
 import type { ModelId } from './models';
-import { DEFAULT_MODEL, MODEL_IDS } from './models';
+import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
-import { aiEmbedder, aiGateway, semanticCacheFor } from './runtime';
+import { assertNoSecrets } from './redaction';
+import { aiEmbedder, aiGateway, aiRedactor, semanticCacheFor } from './runtime';
 import type { LlmTool } from './tools';
 
-/** The tool the model answers through. One name, so the reader never has to guess. */
-const RESPOND = 'respond';
+/**
+ * The tool the model answers through. One name, so the reader never has to guess — and shared
+ * with `agent()`, which offers the app's tools alongside it and needs the same name to tell an
+ * answer from a tool call.
+ */
+export const RESPOND = 'respond';
 
 /** Two attempts total: the answer, then one repair turn. See `LlmOutputInvalidError`. */
 const ATTEMPTS = 2;
@@ -105,19 +126,73 @@ export interface LlmDef<
   readonly maxTokens?: number;
 }
 
+/**
+ * An `action` with one extra way to be called. Every projection an action has, it has — `.tool()`,
+ * `.openapi()`, `.client()`, `.job()`, `.contract()` — plus a transport for the case an action's
+ * single return value cannot serve: text on a screen before the answer is finished.
+ */
+export interface LlmAction<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>
+  extends Action<TInput, TOutput> {
+  /**
+   * The same call, delivered as it arrives. Runs the action's policy, input parse, budget scope,
+   * semantic cache and span exactly as calling it would — the invocation IS an ordinary one,
+   * marked so the model half streams. Yields `text` and `thinking` increments, then one `done`
+   * carrying the value that satisfied `output`.
+   *
+   * Lazy: nothing is authorised or sent until the first pull. A streamed call offers the model no
+   * `respond` tool — a tool call arrives whole, so forcing one leaves nothing to stream — which
+   * means the answer is prose, and its JSON parse is what a non-string `output` validates.
+   * Abandoning the iterator stops delivery, never the call: the budget reservation is reconciled
+   * by the chain that opened it.
+   */
+  stream(
+    input: InferInput<TInput>,
+    opts?: InvokeOptions,
+  ): AsyncIterable<LlmStreamChunk<InferOutput<TOutput>>>;
+  /** Narrowed: a renamed twin of a model call is still a model call, and still streams. */
+  named(name: string): LlmAction<TInput, TOutput>;
+}
+
 export function llm<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
->(def: LlmDef<TInput, TOutput, V>): Action<TInput, TOutput> {
+>(def: LlmDef<TInput, TOutput, V>): LlmAction<TInput, TOutput> {
   const respond = respondToolFor(def.output);
-  return action<TInput, TOutput>({
+  const built = action<TInput, TOutput>({
     input: def.input,
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     handle: (args) => generate(def, respond, args),
   });
+  return streamable(built);
+}
+
+/**
+ * Attach `.stream()` to an action IN PLACE, rather than wrapping it. One object is the point:
+ * `nameAction` stamps a name onto the very object an app exported, `invoke` reads the declaration
+ * off it, and a wrapper would leave a second action the registry never saw.
+ *
+ * `named()` is re-narrowed for the same reason. `action()`'s `named` builds a fresh twin, which
+ * would silently be a model call that cannot stream — so the twin is passed back through here.
+ * The original is captured first, or the override would call itself.
+ */
+function streamable<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+): LlmAction<TInput, TOutput> {
+  const rename = target.named.bind(target);
+  const self: LlmAction<TInput, TOutput> = Object.assign(target, {
+    stream: (
+      input: InferInput<TInput>,
+      opts?: InvokeOptions,
+    ): AsyncIterable<LlmStreamChunk<InferOutput<TOutput>>> =>
+      // `self`, not `target`: the invocation has to be of the object that carries the name the
+      // audit record, the rate-limit key and the span are filed under.
+      llmStream<InferOutput<TOutput>>((sink) => withLlmSink(sink, () => self(input, opts ?? {}))),
+    named: (next: string): LlmAction<TInput, TOutput> => streamable(rename(next)),
+  });
+  return self;
 }
 
 async function generate<
@@ -134,13 +209,27 @@ async function generate<
   // export name it exists before registration and can never twin.
   const name = prompt.ref;
   const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
-  const rendered = prompt.render(await def.vars({ input: args.input, ctx: args.ctx }));
+  // `vars()` is the one declared place a model call loads data, so it is the one place the
+  // framework can refuse a `Secret` and the one place an app's redactor can see the row before it
+  // leaves the process. Both run here, between the load and the request, and neither is optional
+  // in the sense that matters: the redactor may be absent, the Secret check never is.
+  const vars = await def.vars({ input: args.input, ctx: args.ctx });
+  assertNoSecrets(name, vars);
+  const redact = aiRedactor();
+  const rawPrompt = prompt.render(vars);
+  const rendered = redact(rawPrompt);
+  const system = prompt.system === undefined ? undefined : redact(prompt.system);
+  const redacted = rendered !== rawPrompt || system !== prompt.system;
 
   return withSpan('ai.llm', async (span) => {
     span.setAttributes({
       'llm.model': model,
       'llm.prompt': prompt.ref,
       'llm.prompt.hash': prompt.hash,
+      // Whether the installed redactor changed anything. Recorded because "we redact" is a claim
+      // an audit asks evidence for, and a redactor that silently stopped matching looks identical
+      // to one that had nothing to remove until this attribute separates them.
+      'llm.redacted': redacted,
     });
 
     // A cached answer is still data of unknown provenance, so it goes through the schema like
@@ -151,15 +240,18 @@ async function generate<
     span.setAttribute('llm.cache.hit', hit !== undefined);
     if (hit !== undefined) return hit.value;
 
-    const request: GenerateRequest = {
+    // No `tools` yet: the `respond` projection belongs to the non-streaming path alone. A tool
+    // call is emitted whole, so forcing the answer through one leaves a stream with nothing to
+    // deliver until it is already over.
+    const base: GenerateRequest = {
       model,
-      ...(prompt.system === undefined ? {} : { system: prompt.system }),
+      ...(system === undefined ? {} : { system }),
       messages: [{ role: 'user', content: rendered }],
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      tools: [respond],
     };
+    const request: GenerateRequest = { ...base, tools: [respond] };
 
     // A ledger derived from the ambient one, so a per-call budget can only TIGHTEN the actor
     // and org ceilings this call runs inside, never widen them. The gateway reserves against
@@ -168,18 +260,19 @@ async function generate<
       limitsOf(def.budget),
     );
     const gateway = aiGateway(name);
+    const sink = currentLlmSink();
 
     return withBudget(ledger, async () => {
+      if (sink !== undefined) {
+        const value = await streamedAnswer(def.output, name, gateway, base, sink, span);
+        await cache?.remember(value);
+        return value;
+      }
       let messages: readonly AiMessage[] = request.messages;
       let issues = 'no output';
       for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
         const result = await gateway.generate({ ...request, messages });
-        span.setAttributes({
-          'llm.attempts': attempt,
-          'llm.stop': result.stopReason,
-          'llm.tokens': result.usage.inputTokens + result.usage.outputTokens,
-          'llm.cost.minor': result.cost.minor,
-        });
+        span.setAttributes({ 'llm.attempts': attempt, ...answerAttributes(result) });
         // Branch on the stop reason BEFORE reading the answer. A refusal carries empty or partial
         // content, so parsing it first reports a schema disagreement — a cause that is wrong, a
         // fix that does not apply, and a repair turn spent buying the same refusal again.
@@ -187,9 +280,10 @@ async function generate<
           throw new LlmRefusedError({
             prompt: name,
             model: result.model,
-            // The fix names a model the caller can paste. `<another model>` is not one, and a
-            // refusal is exactly the moment nobody wants to go read the catalogue.
-            alternative: MODEL_IDS.find((id) => id !== result.model) ?? DEFAULT_MODEL,
+            // The fix names a model the caller can paste, and only ever a MORE capable one:
+            // "the first id that differs" answered a refusal on the default model with the next
+            // entry down the ladder, which is a retry that cannot succeed.
+            alternative: moreCapableThan(result.model),
             category: result.stopDetails?.category,
             explanation: result.stopDetails?.explanation,
           });
@@ -205,13 +299,77 @@ async function generate<
           throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
         }
         issues = formatIssues(parsed.issues).join('; ');
-        messages = [...messages, { role: 'assistant', content: result.text }, repair(issues)];
+        const echo = assistantEcho(result);
+        messages =
+          echo === undefined
+            ? [...messages, repair(issues)]
+            : [...messages, { role: 'assistant', content: echo }, repair(issues)];
       }
       throw new LlmOutputInvalidError({ prompt: name, attempts: ATTEMPTS, issues });
     });
   });
 }
 
+/**
+ * What one answered turn puts on the span. `llm.provider` is the half the LLM-gateway table
+ * called "a fallback is recorded in the span, never silent": fallback in this framework is across
+ * PROVIDERS serving one model, never across models, and until the gateway stamped the provider
+ * that answered, a fallback was exactly as silent as no fallback at all.
+ */
+export function answerAttributes(result: GenerateResult): SpanAttributes {
+  return {
+    'llm.stop': result.stopReason,
+    'llm.tokens': result.usage.inputTokens + result.usage.outputTokens,
+    'llm.cost.minor': result.cost.minor,
+    'llm.provider': result.provider ?? 'unknown',
+  };
+}
+
+/**
+ * One streamed turn, from the same declaration and under the same rules — with one difference
+ * that is forced rather than chosen: no repair turn. The tokens are already on the consumer's
+ * screen, so a second answer would be two answers to one question; a stream gets one attempt and
+ * `X_LLM_STREAM_INVALID` names the non-streaming call as the fix.
+ *
+ * The stop reason is still read BEFORE the answer, for the reason it always was: a refusal
+ * carries empty or partial content and parsing it first reports a schema disagreement that is not
+ * one. Truncation is the same call it is on the non-streaming path.
+ */
+async function streamedAnswer<TOutput extends StandardSchemaV1>(
+  output: TOutput,
+  name: string,
+  gateway: Gateway,
+  request: GenerateRequest,
+  sink: LlmSink,
+  span: Span,
+): Promise<InferOutput<TOutput>> {
+  const result = await streamOneTurn(gateway, request, sink);
+  span.setAttributes({ 'llm.attempts': 1, ...answerAttributes(result) });
+  if (result.stopReason === 'refusal') {
+    throw new LlmRefusedError({
+      prompt: name,
+      model: result.model,
+      alternative: moreCapableThan(result.model),
+      category: result.stopDetails?.category,
+      explanation: result.stopDetails?.explanation,
+    });
+  }
+  if (result.stopReason === 'max_tokens') {
+    throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens });
+  }
+  // Prose, and its JSON parse when it has one. Both, because a stream carries no `respond` tool
+  // to tell them apart: `output: t.string` is satisfied by the text itself, and an object schema
+  // by what the text parses to — trying only one of the two makes a legal declaration unusable.
+  const parsed = await accept(output, parseJsonish(result.text));
+  if (parsed !== undefined) return parsed.value;
+  const fallback = await validateAsync(output, result.text);
+  if (fallback.issues === undefined) return fallback.value;
+  throw new LlmStreamInvalidError({
+    prompt: name,
+    issues: formatIssues(fallback.issues).join('; '),
+  });
+}
+
 /** `undefined` for "does not fit". Wrapped so a legitimately falsy value is still a hit. */
 async function accept<TOutput extends StandardSchemaV1>(
   schema: TOutput,
@@ -242,7 +400,7 @@ function limitsOf(budget: LlmBudget | undefined): BudgetLimits {
  * a model and an agent are shown one shape, and a schema it cannot express throws HERE, at
  * declaration time, rather than degrading into a permissive node the model cannot satisfy.
  */
-function respondToolFor(output: StandardSchemaV1): LlmTool {
+export function respondToolFor(output: StandardSchemaV1): LlmTool {
   return {
     name: RESPOND,
     description: 'Return the result. Call this exactly once; do not answer in prose.',
@@ -251,11 +409,30 @@ function respondToolFor(output: StandardSchemaV1): LlmTool {
   };
 }
 
+/**
+ * What the model answered, as text the Messages API will accept — or nothing.
+ *
+ * `result.text` is the EMPTY STRING whenever the answer came through the `respond` tool, which
+ * is the dominant path: an empty text block is a 400 (`text content blocks must be non-empty`),
+ * so the repair turn came back as `X_AI_PROVIDER_UNAVAILABLE` and the caller never saw the
+ * `X_LLM_OUTPUT_INVALID` this loop exists to raise. The tool call's own arguments ARE the answer
+ * in that case, and replaying them is what gives the repair turn its context — `AiMessage`
+ * carries a string, so the `tool_use` block cannot survive the round trip as itself, and
+ * replaying it as text avoids the `tool_result` the API would then demand of the next message.
+ */
+function assistantEcho(result: GenerateResult): string | undefined {
+  if (result.text !== '') return result.text;
+  const call = result.toolCalls.find((c) => c.name === RESPOND) ?? result.toolCalls[0];
+  if (call === undefined) return undefined;
+  const replayed = JSON.stringify(call.input);
+  return replayed === undefined || replayed === '' ? undefined : replayed;
+}
+
 /**
  * The tool call if the model made one, otherwise the text parsed as JSON — a model that
  * answers in prose is a schema failure, not a crash, so it flows into the repair turn.
  */
-function structuredOutputOf(result: GenerateResult): unknown {
+export function structuredOutputOf(result: GenerateResult): unknown {
   const call = result.toolCalls.find((c) => c.name === RESPOND);
   if (call !== undefined) return call.input;
   return parseJsonish(result.text);

package/src/models.ts

@@ -1,20 +1,38 @@
-// The blessed models: limits, prices, and the reasoning controls each one's request surface
-// actually accepts. Apart from ./provider because those controls are NOT uniform across the
-// catalogue — one body sent to all three is a guaranteed 400 on the oldest, and a downgrade for
-// price is not a licence to send a body the provider rejects. As of 2026-08.
+// The model catalogue: an OPEN registry of limits, prices and the reasoning controls each model's
+// request surface actually accepts. Open because a company's own gateway serves ids this package
+// has never heard of — a closed union made them untypeable, so the only way past `tsc` was to
+// claim a Claude id and be billed Anthropic list prices for a model nobody ran. As of 2026-08.
 
 import type { Money } from '@ultimat3/money';
-import { AiRequestInvalidError } from './errors';
+import { AiModelUnknownError, AiRequestInvalidError } from './errors';
 
 /**
- * Blessed models. Opus 5 is the default; the others are explicit downgrades. IDs are exact alias
- * strings — never append a date suffix.
+ * A model id. A plain `string`, deliberately: the routing seam (`Provider`, `createGateway`) has
+ * always been open, and a closed union over it meant the VOCABULARY was not — `models:
+ * ['llama-internal-70b']` did not typecheck, so `costOf` charged Anthropic prices for a model the
+ * company does not use and the budget ledger reserved against the wrong number.
+ *
+ * What replaces the union as the guard is `modelSpec()`: an id nothing registered is
+ * `X_AI_MODEL_UNKNOWN` at the first read, naming the registered set. A wrong id is still caught —
+ * at the call, with a fix line, rather than by making a correct id inexpressible.
+ */
+export type ModelId = string;
+
+/**
+ * The models `AnthropicProvider` serves, in ladder order (most capable first). Its OWN list, not
+ * the registry's: an app that registers an internal model must not have it routed to Anthropic.
  */
-export const MODEL_IDS = ['claude-opus-5', 'claude-sonnet-5', 'claude-haiku-4-5'] as const;
-export type ModelId = (typeof MODEL_IDS)[number];
+export const ANTHROPIC_MODEL_IDS = [
+  'claude-opus-5',
+  'claude-sonnet-5',
+  'claude-haiku-4-5',
+] as const;
 
 export const DEFAULT_MODEL: ModelId = 'claude-opus-5';
 
+/** The built-in Anthropic rows' ladder. One `family` string, spelled once. */
+const ANTHROPIC_FAMILY = 'anthropic';
+
 /**
  * Reasoning depth, shallowest first — the order is load-bearing, because a model that caps where
  * thinking may be switched off compares against it. `xhigh` is the best setting for coding and
@@ -55,6 +73,19 @@ export interface ModelSpec {
   /** Minimum cacheable prefix; a shorter prefix silently does not cache. */
   readonly cacheMinimumTokens: number;
   readonly reasoning: ModelReasoning;
+  /**
+   * Which ladder this model is a rung on. A capability comparison only means anything inside one
+   * — registration order across vendors is arrival order, not capability — so `moreCapableThan`
+   * walks up within a family and stops at its boundary. Optional, and absent is its own family:
+   * an app that registers its whole catalogue in the order it wants keeps comparing across all of
+   * it, exactly as before this field existed.
+   *
+   * Registering the OpenAI-format rows after the Anthropic ones is what made this load-bearing:
+   * the rung above `gpt-5.6-sol` was `claude-haiku-4-5`, so `X_LLM_REFUSED`'s fix line told an
+   * operator to paste the cheapest model in the catalogue, from a vendor their gateway may not
+   * serve at all.
+   */
+  readonly family?: string;
 }
 
 /**
@@ -63,46 +94,100 @@ export interface ModelSpec {
  */
 const usd = (minor: number): Money => ({ minor, currency: 'USD' });
 
-export const MODELS: Readonly<Record<ModelId, ModelSpec>> = {
-  // $5 / $25 per MTok.
-  'claude-opus-5': {
-    id: 'claude-opus-5',
-    contextWindow: 1_000_000,
-    maxOutput: 128_000,
-    inputPerMillion: usd(500),
-    outputPerMillion: usd(2_500),
-    cacheMinimumTokens: 512,
-    // Thinking is on by default here, and switching it OFF is legal only at `high` or below.
-    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: 'high' },
-  },
-  // $3 / $15 per MTok. The introductory rate is deliberately NOT modelled: a price that lapses on
-  // a date makes every recorded cost depend on when it was read, and a budget that under-reports
-  // spend after the lapse is a budget that is not one. List price over-reserves, which is safe.
-  'claude-sonnet-5': {
-    id: 'claude-sonnet-5',
-    contextWindow: 1_000_000,
-    maxOutput: 128_000,
-    inputPerMillion: usd(300),
-    outputPerMillion: usd(1_500),
-    cacheMinimumTokens: 1_024,
-    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: undefined },
-  },
-  // $1 / $5 per MTok. Pre-4.6, so it has neither knob: an `output_config.effort` or an adaptive
-  // `thinking` block sent here is a 400 on every request, which is what made the cheap tier
-  // uncallable while the request body was one shape for the whole catalogue.
-  'claude-haiku-4-5': {
-    id: 'claude-haiku-4-5',
-    contextWindow: 200_000,
-    maxOutput: 64_000,
-    inputPerMillion: usd(100),
-    outputPerMillion: usd(500),
-    cacheMinimumTokens: 4_096,
-    reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
-  },
-};
+/**
+ * Insertion order IS the capability ladder WITHIN a `family`, most capable first —
+ * `moreCapableThan` is its only reader, exactly as it was when the ladder was a literal tuple.
+ * Across families it is arrival order and means nothing. A `Map` because re-registering
+ * an id REPLACES its spec in place without moving its rung, which is what makes a negotiated
+ * enterprise rate expressible: one call, same id, new prices, same position in the ladder.
+ */
+const registry = new Map<ModelId, ModelSpec>();
+
+/**
+ * Add a model to the catalogue, or restate one that is already in it. **The three built-ins
+ * register through this same call**, at the bottom of this file — so the default path is the
+ * app's path and there is exactly one way to put a model in the catalogue.
+ *
+ * Re-registering an id replaces its spec and keeps its rung. That is deliberate and it is the
+ * negotiated-rate mechanism: an app whose contract prices `claude-opus-5` below list registers it
+ * again with its own `inputPerMillion`/`outputPerMillion`, and every `costOf`, every budget
+ * reservation and every recorded cost is that number from then on. Boot registers after this
+ * module is imported, so the app always wins.
+ *
+ * A model appended after the built-ins is the LEAST capable rung, because that is what appending
+ * to a most-capable-first list means. An app that wants its own ladder registers its whole
+ * catalogue in the order it wants, re-registering the built-in ids it keeps.
+ */
+export function registerModel(spec: ModelSpec): ModelSpec {
+  registry.set(spec.id, spec);
+  return spec;
+}
+
+/** Every registered id, in ladder order. */
+export function modelIds(): readonly ModelId[] {
+  return [...registry.keys()];
+}
+
+/** Every registered spec, in ladder order. Consumed by `x manifest` and by doctor-style checks. */
+export function registeredModels(): readonly ModelSpec[] {
+  return [...registry.values()];
+}
+
+export function isModelRegistered(id: ModelId): boolean {
+  return registry.has(id);
+}
+
+/**
+ * The spec behind an id. The ONE read path, and the guard the closed union used to be: an
+ * unregistered id throws here — at the pricing, request-building and streaming seams that all
+ * call it — rather than silently pricing a foreign model at somebody else's rates.
+ */
+export function modelSpec(id: ModelId): ModelSpec {
+  const spec = registry.get(id);
+  if (spec === undefined) throw new AiModelUnknownError({ model: id, registered: modelIds() });
+  return spec;
+}
+
+/**
+ * Refuse an unregistered id without needing its spec. For a boot-time or `x doctor`-style check
+ * AFTER registration has run; every request path reads `modelSpec` instead, and a declaration
+ * cannot check at all — an `llm()` is evaluated at module scope, before boot registers anything.
+ */
+export function assertModel(id: ModelId): void {
+  modelSpec(id);
+}
+
+/** Test-only reset back to the built-in catalogue. Module state otherwise leaks between files. */
+export function resetModels(): void {
+  registry.clear();
+  registerBuiltInModels();
+}
 
 const rankOf = (effort: Effort): number => EFFORTS.indexOf(effort);
 
+/**
+ * The model one rung ABOVE `model` IN ITS OWN FAMILY, or `undefined` when it is already the most
+ * capable one that family holds. Registration order is most-capable-first — "the others are
+ * explicit downgrades" — so the ladder needs no second list to walk; `family` is what stops the
+ * walk at the boundary between two vendors' lists, where order is arrival, not capability.
+ *
+ * A refusal is only worth retrying UPWARD. `MODEL_IDS.find((id) => id !== refused)` answered a
+ * refusal on the default model with the next entry DOWN, which is the one retry that cannot help:
+ * the fix line told an operator to buy the same refusal from a weaker model.
+ */
+export function moreCapableThan(model: ModelId): ModelId | undefined {
+  const spec = registry.get(model);
+  if (spec === undefined) return undefined;
+  const ids = modelIds();
+  // Up, but only within the model's own family: the entry before `gpt-5.6-sol` is
+  // `claude-haiku-4-5`, which is not a rung above anything — it is the previous vendor's list.
+  for (let at = ids.indexOf(model) - 1; at >= 0; at -= 1) {
+    const above = ids[at];
+    if (above !== undefined && registry.get(above)?.family === spec.family) return above;
+  }
+  return undefined;
+}
+
 /**
  * The reasoning half of a Messages body, shaped for one model. Everything it refuses, it refuses
  * LOCALLY with a real code — a round trip to learn a rule this file already states costs latency
@@ -117,7 +202,7 @@ export function reasoningBody(
   effort: Effort | undefined,
   thinking: ThinkingMode | undefined,
 ): Record<string, unknown> {
-  const rules = MODELS[model].reasoning;
+  const rules = modelSpec(model).reasoning;
   const body: Record<string, unknown> = {};
 
   if (effort !== undefined && !rules.effort) {
@@ -143,12 +228,16 @@ export function reasoningBody(
     return body;
   }
 
-  if ((thinking ?? 'adaptive') === 'disabled') {
+  if (thinking === 'disabled') {
     assertDisableAllowed(model, rules, effort ?? 'high');
     body['thinking'] = { type: 'disabled' };
     return body;
   }
-  body['thinking'] = { type: 'adaptive', display: 'summarized' };
+  // Nothing asked for, nothing sent — the rule this file states, now the rule it follows.
+  // Adaptive is the server's own default on every model that has it, so emitting the block
+  // unrequested bought nothing and made a defaulted control indistinguishable on the wire from
+  // a declared one.
+  if (thinking === 'adaptive') body['thinking'] = { type: 'adaptive', display: 'summarized' };
   return body;
 }
 
@@ -161,3 +250,51 @@ function assertDisableAllowed(model: ModelId, rules: ModelReasoning, effort: Eff
     fix: `set effort: '${cap}' in definePrompt alongside thinking: 'disabled', or drop thinking from it`,
   });
 }
+
+/**
+ * The blessed models. Opus 5 is the default; the others are explicit downgrades. IDs are exact
+ * alias strings — never append a date suffix. Registered through the public `registerModel`, in
+ * ladder order, so nothing about the built-in path is a private door an app cannot use.
+ */
+function registerBuiltInModels(): void {
+  // $5 / $25 per MTok.
+  registerModel({
+    id: 'claude-opus-5',
+    family: ANTHROPIC_FAMILY,
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPerMillion: usd(500),
+    outputPerMillion: usd(2_500),
+    cacheMinimumTokens: 512,
+    // Thinking is on by default here, and switching it OFF is legal only at `high` or below.
+    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: 'high' },
+  });
+  // $3 / $15 per MTok. The introductory rate is deliberately NOT modelled: a price that lapses on
+  // a date makes every recorded cost depend on when it was read, and a budget that under-reports
+  // spend after the lapse is a budget that is not one. List price over-reserves, which is safe.
+  registerModel({
+    id: 'claude-sonnet-5',
+    family: ANTHROPIC_FAMILY,
+    contextWindow: 1_000_000,
+    maxOutput: 128_000,
+    inputPerMillion: usd(300),
+    outputPerMillion: usd(1_500),
+    cacheMinimumTokens: 1_024,
+    reasoning: { effort: true, adaptive: true, disableThinkingUpTo: undefined },
+  });
+  // $1 / $5 per MTok. Pre-4.6, so it has neither knob: an `output_config.effort` or an adaptive
+  // `thinking` block sent here is a 400 on every request, which is what made the cheap tier
+  // uncallable while the request body was one shape for the whole catalogue.
+  registerModel({
+    id: 'claude-haiku-4-5',
+    family: ANTHROPIC_FAMILY,
+    contextWindow: 200_000,
+    maxOutput: 64_000,
+    inputPerMillion: usd(100),
+    outputPerMillion: usd(500),
+    cacheMinimumTokens: 4_096,
+    reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
+  });
+}
+
+registerBuiltInModels();