@ultimat3/ai 1.2.0 → 3.0.0

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();

package/src/openai-body.ts

@@ -0,0 +1,96 @@
+// Single responsibility: one chat-completions request body, assembled from a `GenerateRequest`.
+// Pure and side-effect free, so what leaves the process is asserted directly in a test.
+//
+// The per-model rules live in the model's spec, never in an `if` here — same rule as
+// `reasoningBody()`: adding a model an endpoint serves is a `registerModel` row, not a branch.
+
+import { AiRequestInvalidError } from './errors';
+import type { Effort, ModelId, ThinkingMode } from './models';
+import { modelSpec } from './models';
+import { toOpenAiMessages, toOpenAiTools, toolChoiceFor } from './openai-messages';
+import type { GenerateRequest } from './provider';
+
+export interface ChatCompletionBodyInput {
+  readonly request: GenerateRequest;
+  /** Already resolved — the gateway picks the model, the provider never guesses mid-request. */
+  readonly model: ModelId;
+  readonly stream: boolean;
+}
+
+/**
+ * The body. What is deliberately absent is as load-bearing as what is present:
+ *   - no `temperature` / `top_p` / `presence_penalty`. Steering is the prompt's job, and a sampling
+ *     knob on a reasoning model in this family is a 400.
+ *   - no `response_format`. The output schema is projected into the `respond` tool by `llm()`, and
+ *     that projection is the framework's ONE structured-output path — see the README.
+ *   - `max_completion_tokens`, never the deprecated `max_tokens`, which current reasoning models
+ *     reject outright.
+ */
+export function chatCompletionBody(input: ChatCompletionBodyInput): Record<string, unknown> {
+  const { request, model, stream } = input;
+  const spec = modelSpec(model);
+  const body: Record<string, unknown> = {
+    model,
+    messages: toOpenAiMessages(request.system, request.messages),
+    max_completion_tokens: Math.min(request.maxTokens, spec.maxOutput),
+    ...reasoningFields(model, request.effort, request.thinking),
+  };
+  if (request.tools !== undefined && request.tools.length > 0) {
+    body['tools'] = toOpenAiTools(request.tools);
+    const choice = toolChoiceFor(request.tools);
+    if (choice !== undefined) body['tool_choice'] = choice;
+  }
+  if (request.stopSequences !== undefined && request.stopSequences.length > 0) {
+    body['stop'] = request.stopSequences;
+  }
+  if (stream) {
+    body['stream'] = true;
+    // Without this the final chunk carries no `usage` and the budget reconciles against nothing —
+    // a full refund of the reservation for a call that really happened. It is one field and it is
+    // the difference between a ledger and a decoration.
+    body['stream_options'] = { include_usage: true };
+  }
+  return body;
+}
+
+/**
+ * The reasoning half, shaped for one model. Refused LOCALLY when the model's spec says the endpoint
+ * has no such control, for the reason models.ts states: a round trip to learn a rule the registry
+ * already holds costs latency and teaches nothing.
+ *
+ * `reasoning_effort` is one field carrying two of the framework's controls, so asking for both is
+ * refused rather than resolved — a declaration that reads `effort: 'max'` next to
+ * `thinking: 'disabled'` cannot have both, and picking one silently is the failure nobody sees.
+ */
+export function reasoningFields(
+  model: ModelId,
+  effort: Effort | undefined,
+  thinking: ThinkingMode | undefined,
+): Record<string, unknown> {
+  const rules = modelSpec(model).reasoning;
+  if (effort !== undefined && !rules.effort) {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" is registered with no effort control, so reasoning_effort cannot be sent to it`,
+      fix: 'drop effort from definePrompt, or re-register the model with reasoning: { effort: true } if its endpoint accepts reasoning_effort',
+    });
+  }
+  if (thinking === 'adaptive' && !rules.adaptive) {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" has no adaptive thinking; the OpenAI format's only depth control is reasoning_effort`,
+      fix: 'drop thinking from definePrompt and set effort instead, or route the prompt to a model registered with reasoning: { adaptive: true }',
+    });
+  }
+  if (thinking === 'disabled' && effort !== undefined) {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" writes both thinking and effort onto one reasoning_effort field, and the request asked for both`,
+      fix: "drop one from definePrompt: keep thinking: 'disabled', or keep effort",
+    });
+  }
+  // `none` IS the off switch on this wire, and a model with no effort control has nothing to
+  // switch off — so it sends nothing rather than a field the endpoint would reject.
+  if (thinking === 'disabled') return rules.effort ? { reasoning_effort: 'none' } : {};
+  if (effort !== undefined) return { reasoning_effort: effort };
+  // Nothing asked for, nothing sent. Adaptive depth is the server's own default here, so emitting
+  // anything for it would make a defaulted control indistinguishable from a declared one.
+  return {};
+}

package/src/openai-messages.ts

@@ -0,0 +1,174 @@
+// Single responsibility: the REQUEST half of the OpenAI chat-completions format — `AiMessage`
+// (which carries Anthropic's block names) onto OpenAI's messages, and `LlmTool` onto its functions.
+//
+// This mapping is the whole reason the provider exists: the two formats disagree about where a
+// system prompt lives, how an assistant asks for a tool, and how a tool answers. Pure functions, so
+// every disagreement is a unit test with no socket.
+
+import type { AiContentBlock, AiMessage } from './provider';
+import type { JsonSchema, LlmTool } from './tools';
+
+export interface OpenAiToolCall {
+  readonly id: string;
+  readonly type: 'function';
+  /** Arguments are a JSON STRING on this wire, not an object. The one field everybody gets wrong. */
+  readonly function: { readonly name: string; readonly arguments: string };
+}
+
+export type OpenAiMessage =
+  | { readonly role: 'system' | 'user'; readonly content: string }
+  | {
+      readonly role: 'assistant';
+      readonly content?: string | undefined;
+      readonly tool_calls?: readonly OpenAiToolCall[] | undefined;
+    }
+  | { readonly role: 'tool'; readonly tool_call_id: string; readonly content: string };
+
+export interface OpenAiFunctionTool {
+  readonly type: 'function';
+  readonly function: {
+    readonly name: string;
+    readonly description: string;
+    /** OpenAI calls it `parameters`; the JSON Schema inside is byte-identical to `input_schema`. */
+    readonly parameters: JsonSchema;
+    readonly strict?: boolean | undefined;
+  };
+}
+
+/** `tool_choice`, when the framework is forcing one. Named function, the only forcing shape. */
+export interface OpenAiToolChoice {
+  readonly type: 'function';
+  readonly function: { readonly name: string };
+}
+
+/**
+ * The conversation, translated. Three structural differences, each of which silently corrupts a
+ * transcript if it is missed:
+ *
+ *   - the system prompt is a MESSAGE here, not a top-level field, and it must lead;
+ *   - an assistant's `tool_use` blocks become `tool_calls` ON the assistant message, with their
+ *     arguments serialised to a string;
+ *   - a `tool_result` block is not a user block at all — it is its own `role: 'tool'` message,
+ *     one per result, keyed by `tool_call_id`.
+ *
+ * `system` rather than `developer`: the newer role is OpenAI's alone, and every other server
+ * speaking this format — vLLM, Ollama, LiteLLM, Together — knows only `system`. OpenAI accepts it.
+ */
+export function toOpenAiMessages(
+  system: string | undefined,
+  messages: readonly AiMessage[],
+): readonly OpenAiMessage[] {
+  const out: OpenAiMessage[] = [];
+  if (system !== undefined && system !== '') out.push({ role: 'system', content: system });
+  for (const message of messages) {
+    if (typeof message.content === 'string') {
+      out.push({ role: message.role, content: message.content });
+      continue;
+    }
+    if (message.role === 'assistant') out.push(assistantMessage(message.content));
+    else out.push(...toolTurn(message.content));
+  }
+  return out;
+}
+
+/** Text blocks concatenate; `tool_use` blocks move onto `tool_calls` with stringified arguments. */
+function assistantMessage(blocks: readonly AiContentBlock[]): OpenAiMessage {
+  let content = '';
+  const toolCalls: OpenAiToolCall[] = [];
+  for (const block of blocks) {
+    if (block.type === 'text') content += block.text;
+    if (block.type === 'tool_use') {
+      toolCalls.push({
+        id: block.id,
+        type: 'function',
+        function: { name: block.name, arguments: JSON.stringify(block.input) },
+      });
+    }
+  }
+  // Content is OMITTED, not empty-stringed, when the turn was only tool calls: an assistant message
+  // carrying both an empty string and `tool_calls` is rejected by some servers in the family.
+  return {
+    role: 'assistant',
+    ...(content === '' ? {} : { content }),
+    ...(toolCalls.length === 0 ? {} : { tool_calls: toolCalls }),
+  };
+}
+
+/**
+ * A user turn that carries tool results. Every result becomes its own `role: 'tool'` message, in
+ * order and before any prose, because OpenAI requires one tool message per `tool_call_id` the
+ * previous assistant message asked for, and requires them to come first.
+ */
+function toolTurn(blocks: readonly AiContentBlock[]): readonly OpenAiMessage[] {
+  const out: OpenAiMessage[] = [];
+  let text = '';
+  for (const block of blocks) {
+    if (block.type === 'text') text += block.text;
+    if (block.type === 'tool_result') {
+      out.push({
+        role: 'tool',
+        tool_call_id: block.tool_use_id,
+        // There is no `is_error` on this wire, and dropping the flag would hand the model a failure
+        // that reads as data. The marker is the format's only place to say so.
+        content: block.is_error === true ? `error: ${block.content}` : block.content,
+      });
+    }
+  }
+  if (text !== '') out.push({ role: 'user', content: text });
+  return out;
+}
+
+/**
+ * Tool definitions, wrapped in the `{ type: 'function', function: … }` envelope.
+ *
+ * `strict` is claimed only when the projected schema actually satisfies OpenAI's strict rules.
+ * `LlmTool.strict` is `true` on every projection the framework makes, but on THIS wire the flag is
+ * a promise the server checks: a schema with an optional field — one key in `properties` and not in
+ * `required` — is a 400 (`Invalid schema for function …`) rather than a looser check. So the flag
+ * is derived from the schema, never forwarded, and a schema that cannot keep the promise is sent
+ * without it and validated by the output schema on the way back, exactly as the Anthropic path is.
+ */
+export function toOpenAiTools(tools: readonly LlmTool[]): readonly OpenAiFunctionTool[] {
+  return tools.map((tool) => ({
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.input_schema,
+      ...(tool.strict === true && satisfiesStrictMode(tool.input_schema) ? { strict: true } : {}),
+    },
+  }));
+}
+
+/**
+ * Whether a schema keeps OpenAI's strict-mode promise: every object closed with
+ * `additionalProperties: false`, and every one of its keys listed in `required`. Recursive, because
+ * the server checks it recursively.
+ */
+export function satisfiesStrictMode(schema: JsonSchema): boolean {
+  if (schema.items !== undefined && !satisfiesStrictMode(schema.items)) return false;
+  if (schema.type !== 'object' && schema.properties === undefined) return true;
+  if (schema.additionalProperties !== false) return false;
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  for (const [key, child] of Object.entries(properties)) {
+    if (!required.has(key)) return false;
+    if (!satisfiesStrictMode(child)) return false;
+  }
+  return true;
+}
+
+/**
+ * `tool_choice`, or nothing. Forced when the request offers EXACTLY ONE tool, which is precisely
+ * the shape `llm()` builds: the `respond` projection of the output schema, with the instruction to
+ * answer through it. One tool is nothing to choose between, and left to `auto` the family answers
+ * in prose often enough that structured output becomes a repair turn on every second call.
+ *
+ * Never forced when a tool loop is running: `agent()` offers the app's tools alongside `respond`,
+ * and forcing a name there would decide the loop's next step for the model.
+ */
+export function toolChoiceFor(tools: readonly LlmTool[]): OpenAiToolChoice | undefined {
+  const only = tools.length === 1 ? tools[0] : undefined;
+  if (only === undefined) return undefined;
+  return { type: 'function', function: { name: only.name } };
+}

package/src/openai-models.ts

@@ -0,0 +1,84 @@
+// The OpenAI-format built-in catalogue: the vendor's own list prices, registered through the same
+// public `registerModel` the Anthropic built-ins use. Here rather than in models.ts because these
+// rows belong to a PROVIDER — models.ts owns the registry mechanism, never one vendor's price list.
+
+import type { Money } from '@ultimat3/money';
+import type { ModelId } from './models';
+import { registerModel } from './models';
+
+/** A price per million tokens, in INTEGER MINOR UNITS. Same rule as models.ts: never a float. */
+const usd = (minor: number): Money => ({ minor, currency: 'USD' });
+
+/**
+ * The ids this package prices, in ladder order (most capable first). A provider's `models` list is
+ * still its own — an endpoint speaking this format serves whatever ids it was deployed with, and
+ * `openAiProvider({ models })` is where those are named.
+ */
+export const OPENAI_MODEL_IDS: readonly ModelId[] = [
+  'gpt-5.6-sol',
+  'gpt-5.6-terra',
+  'gpt-5.6-luna',
+];
+
+/**
+ * Shared by the whole 5.6 family: a 1.05M context, a 128k output ceiling, and `reasoning_effort`
+ * over exactly the five rungs `EFFORTS` declares (the endpoint also takes `none`, which is what
+ * `thinking: 'disabled'` maps onto). `adaptive` is false because the format has no
+ * adaptive-thinking control at all — depth is `reasoning_effort` and nothing else.
+ */
+const FAMILY = {
+  /** One ladder: `moreCapableThan` compares these three with each other and with nothing else. */
+  family: 'openai',
+  contextWindow: 1_050_000,
+  maxOutput: 128_000,
+  /** Automatic caching starts at a 1024-token prefix; a shorter one silently does not cache. */
+  cacheMinimumTokens: 1_024,
+  reasoning: { effort: true, adaptive: false, disableThinkingUpTo: undefined },
+} as const;
+
+/**
+ * The three models this package is confident enough to price, and no more.
+ *
+ * Prices are the vendor's published list, read from developers.openai.com/api/docs/pricing on
+ * **2026-08-16**, in USD per million tokens:
+ *
+ * | id | input | cached input | output |
+ * |---|---|---|---|
+ * | `gpt-5.6-sol` | $5.00 | $0.50 | $30.00 |
+ * | `gpt-5.6-terra` | $2.00 | $0.20 | $12.00 |
+ * | `gpt-5.6-luna` | $0.20 | $0.02 | $1.20 |
+ *
+ * Deliberately not registered: `gpt-4o`, `gpt-4o-mini` and the `o1` family, whose cached input is
+ * **0.5x** their input rate rather than the 0.1x `costOf` assumes — a spec that prices them would
+ * under-report a cache-heavy workload by four fifths, and `costOf` answers confidently either way.
+ * `gpt-5.5-pro` and `o1-pro` are out for the same class of reason: they publish no cached rate.
+ * A wrong price is worse than no entry, so an app wanting one of those registers it itself, with
+ * the rate its own contract names.
+ */
+export function registerOpenAiModels(): void {
+  registerModel({
+    id: 'gpt-5.6-sol',
+    ...FAMILY,
+    inputPerMillion: usd(500),
+    outputPerMillion: usd(3_000),
+  });
+  registerModel({
+    id: 'gpt-5.6-terra',
+    ...FAMILY,
+    inputPerMillion: usd(200),
+    outputPerMillion: usd(1_200),
+  });
+  registerModel({
+    id: 'gpt-5.6-luna',
+    ...FAMILY,
+    inputPerMillion: usd(20),
+    outputPerMillion: usd(120),
+  });
+}
+
+// The same shape models.ts uses for its built-ins: registration is a module side effect, so the
+// default path is the app's path and importing the provider is enough to price what it serves.
+// Exported as well as called, because the registry is module state and a suite that clears it with
+// `resetModels()` otherwise leaves this provider serving ids nothing can price. Re-registering
+// REPLACES, so an app with a negotiated rate calls `registerModel` after this one and wins.
+registerOpenAiModels();