@ultimat3/ai 24.0.0 → 25.1.0

package/src/models.ts

@@ -1,39 +1,22 @@
 // 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.
+// request surface actually accepts. Mechanism only — the framework registers NO row: an app brings
+// its models (`registerModel`, dated and sourced in its own repo) and picks its provider, so no
+// vendor's id, price or ladder ships here to go stale or to be chosen for it (M12, 25.0.0).
 
-import { finiteCount } from '@ultimat3/core';
+import { assert, finiteCount, renderCauseValue, renderFixLiteral } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { AiModelUnknownError, AiRequestInvalidError } from './errors';
 
 /**
- * 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.
+ * A model id. A plain `string`, deliberately: the routing seam (`Provider`, `gateway`) has
+ * always been open, and a closed union over it made a company's own model untypeable.
  *
- * What replaces the union as the guard is `modelSpec()`: an id nothing registered is
+ * What replaces the union as the guard is `modelSpec()`: an id the app never 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 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
@@ -49,18 +32,31 @@ export type Effort = (typeof EFFORTS)[number];
  */
 export type ThinkingMode = 'adaptive' | 'disabled';
 
+/** A non-text content block kind a model may accept (`AiContentBlock`'s `image` / `document`). */
+export type ContentKind = 'image' | 'document';
+
 /**
  * What one model's request surface accepts. Every field here is a 400 when it is sent to a model
  * that does not take it, which is why it is data on the spec rather than a rule in the request
  * builder: adding a fourth model is a row, not an `if`.
  */
 export interface ModelReasoning {
-  /** `output_config.effort`. Models older than 4.6 reject it outright. */
+  /** `output_config.effort`. A model without the control rejects it outright. */
   readonly effort: boolean;
   /** `thinking: {type:'adaptive'}`. Older models take a token budget this package never sends. */
   readonly adaptive: boolean;
-  /** Deepest effort that still accepts `thinking: 'disabled'`; `undefined` = every effort does. */
-  readonly disableThinkingUpTo: Effort | undefined;
+  /**
+   * Deepest effort at which thinking may be switched off; `undefined` = every effort, `'never'` =
+   * none. `'never'` is a row, not an absence: on a model whose thinking is always on, an off switch
+   * is a 400 at every effort, and refusing it locally names `effort` as the knob that replaced it.
+   */
+  readonly disableThinkingUpTo: Effort | 'never' | undefined;
+  /**
+   * How this model SPELLS "no up-front thinking" on the wire. Absent is `'disabled'`. A model that
+   * answers `disabled` with a 400 pointing at `between_tools` (its lowest setting) states it here,
+   * so the one `thinking: 'disabled'` stays one declaration rather than a per-model vocabulary.
+   */
+  readonly disabledThinking?: 'disabled' | 'between_tools';
 }
 
 export interface ModelSpec {
@@ -71,9 +67,27 @@ export interface ModelSpec {
   readonly inputPerMillion: Money;
   /** Cost of one million output tokens, in minor units. */
   readonly outputPerMillion: Money;
+  /**
+   * Cost of one million cache-READ tokens, in minor units. Absent is 0.1x `inputPerMillion`, the
+   * standard multiplier — which is wrong for exactly the models whose vendor publishes its own (0.05x
+   * and 0.025x exist), so a row with a vendor rate states it.
+   */
+  readonly cacheReadPerMillion?: Money;
+  /**
+   * Cost of one million cache-WRITE tokens at the 5-minute TTL, in minor units; absent is 1.25x
+   * input. The 5-minute rate because it is the API's default TTL and this package never asks for
+   * the 1-hour one (2x), and `usage` does not split the two.
+   */
+  readonly cacheWritePerMillion?: Money;
   /** Minimum cacheable prefix; a shorter prefix silently does not cache. */
   readonly cacheMinimumTokens: number;
   readonly reasoning: ModelReasoning;
+  /**
+   * The non-text blocks a message to this model may carry. Absent is TEXT ONLY, deliberately: an
+   * app's own row for a text-only endpoint must not have an image sent to it, and the refusal
+   * (`X_AI_CONTENT_UNSUPPORTED`) names this field, so a row that does take images is one edit.
+   */
+  readonly input?: readonly ContentKind[];
   /**
    * 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`
@@ -81,20 +95,13 @@ export interface ModelSpec {
    * 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.
+   * An app registering two vendors' rows is what makes this load-bearing: without it, the rung
+   * above one vendor's top model is the other vendor's cheapest, and `X_LLM_REFUSED`'s fix line
+   * tells an operator to paste a weaker model from a list their gateway may not serve at all.
    */
   readonly family?: string;
 }
 
-/**
- * A price per million tokens, in INTEGER MINOR UNITS. Token spend is money, and the house rule
- * applies to money wherever it comes from: never a float.
- */
-const usd = (minor: number): Money => ({ minor, currency: 'USD' });
-
 /**
  * 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.
@@ -108,19 +115,16 @@ const registry = new Map<ModelId, ModelSpec>();
 const SUBJECT = 'registerModel';
 
 /**
- * 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.
+ * Add a model to the catalogue, or restate one that is already in it — the ONE way a model enters
+ * it. The framework calls it for nothing: every row is the app's, written at boot (by convention in
+ * the app's own `models.ts`, with the source and the date beside each number).
  *
- * 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.
+ * Re-registering an id replaces its spec and keeps its rung. That is the negotiated-rate mechanism:
+ * same id, new prices, and every `costOf`, every budget reservation and every recorded cost is that
+ * number from then on.
  *
- * 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.
+ * Registration order within a `family` is the capability ladder, most capable first: a model
+ * appended to a family is its LEAST capable rung.
  */
 export function registerModel(spec: ModelSpec): ModelSpec {
   // Screened at the ONE seam every model in the catalogue passes through, and at boot, which is
@@ -136,10 +140,38 @@ export function registerModel(spec: ModelSpec): ModelSpec {
   finiteCount(SUBJECT, `${spec.id} cacheMinimumTokens`, spec.cacheMinimumTokens);
   finiteCount(SUBJECT, `${spec.id} inputPerMillion.minor`, spec.inputPerMillion.minor);
   finiteCount(SUBJECT, `${spec.id} outputPerMillion.minor`, spec.outputPerMillion.minor);
+  assertOneCurrency(spec);
+  if (spec.cacheReadPerMillion !== undefined) {
+    finiteCount(SUBJECT, `${spec.id} cacheReadPerMillion.minor`, spec.cacheReadPerMillion.minor);
+  }
+  if (spec.cacheWritePerMillion !== undefined) {
+    finiteCount(SUBJECT, `${spec.id} cacheWritePerMillion.minor`, spec.cacheWritePerMillion.minor);
+  }
   registry.set(spec.id, spec);
   return spec;
 }
 
+/**
+ * Every price on a row in ONE currency. `costOf` sums them into a single `Money` stamped with the
+ * input price's currency, so a cache rate in another one would be added as if it were the same.
+ */
+function assertOneCurrency(spec: ModelSpec): void {
+  const currency = spec.inputPerMillion.currency;
+  const prices = {
+    outputPerMillion: spec.outputPerMillion,
+    cacheReadPerMillion: spec.cacheReadPerMillion,
+    cacheWritePerMillion: spec.cacheWritePerMillion,
+  };
+  for (const [field, price] of Object.entries(prices)) {
+    // X_INVARIANT, as `finiteCount`'s refusals of the same row are: a bad row, caught at boot.
+    assert(
+      price === undefined || price.currency === currency,
+      `${SUBJECT} row "${spec.id}" prices ${field} in ${renderCauseValue(price?.currency)} and inputPerMillion in ${renderCauseValue(currency)}; costOf sums every price into one Money`,
+      `registerModel({ ...spec, ${field}: { minor, currency: ${renderFixLiteral(currency, '<input currency>')} } })   # every price on a row in one currency`,
+    );
+  }
+}
+
 /** Every registered id, in ladder order. */
 export function modelIds(): readonly ModelId[] {
   return [...registry.keys()];
@@ -181,37 +213,61 @@ export function assertModel(id: ModelId): void {
   modelSpec(id);
 }
 
-/** Test-only reset back to the built-in catalogue. Module state otherwise leaks between files. */
+/** Test-only: empty the 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.
+ * The model one rung ABOVE `model` IN ITS OWN FAMILY, among the rows the APP registered, or
+ * `undefined` when it is already the most capable one that family holds — or nothing above it was
+ * registered at all. The framework holds no rung of its own, so it never suggests a model the app
+ * did not choose. Registration order is most-capable-first, so the ladder needs no second list;
+ * `family` stops the walk at the boundary between two 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 {
+export function moreCapableThan(
+  model: ModelId,
+  declared: DeclaredReasoning = {},
+): 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.
+  // Up, but only within the model's own family: the entry before another family's top rung is the
+  // previous family's bottom one, which is not a rung above anything.
   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;
+    if (above === undefined || registry.get(above)?.family !== spec.family) continue;
+    // A rung the SAME declaration cannot run on is not an answer: from a model with
+    // `thinking: 'disabled'`, pasting one whose thinking is always on turns a refusal into an
+    // `X_AI_REQUEST_INVALID` on every call. Skip it and keep climbing.
+    if (acceptsReasoning(above, declared)) return above;
   }
   return undefined;
 }
 
+/** The reasoning controls a declaration named — what a suggested rung must also accept. */
+export interface DeclaredReasoning {
+  readonly effort?: Effort | undefined;
+  readonly thinking?: ThinkingMode | undefined;
+}
+
+/** Whether `reasoningBody` would build this declaration's reasoning half for `model`. */
+function acceptsReasoning(model: ModelId, declared: DeclaredReasoning): boolean {
+  try {
+    reasoningBody(model, declared.effort, declared.thinking);
+    return true;
+  } catch (error) {
+    if (error instanceof AiRequestInvalidError) return false;
+    throw error;
+  }
+}
+
 /**
  * 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
@@ -231,8 +287,8 @@ export function reasoningBody(
 
   if (effort !== undefined && !rules.effort) {
     throw new AiRequestInvalidError({
-      detail: `model "${model}" has no effort control; output_config.effort is a 400 on it`,
-      fix: `drop effort from definePrompt, or set model: '${DEFAULT_MODEL}' on the llm() declaration`,
+      detail: `model "${model}" has no effort control; output_config.effort is a 400 on it (modelId: a registered id whose registerModel row has reasoning.effort: true)`,
+      fix: 'agent({ …, model: modelId })   # or the llm() declaration, or definePrompt — or drop effort from definePrompt',
     });
   }
   // Only what the caller asked for. `output_config`, not a top-level `effort` — a top-level one
@@ -243,8 +299,8 @@ export function reasoningBody(
   if (!rules.adaptive) {
     if (thinking === 'adaptive') {
       throw new AiRequestInvalidError({
-        detail: `model "${model}" predates adaptive thinking; a thinking block is a 400 on it`,
-        fix: `set model: '${DEFAULT_MODEL}' on the llm() declaration, or drop thinking from definePrompt`,
+        detail: `model "${model}" predates adaptive thinking; a thinking block is a 400 on it (modelId: a registered id whose registerModel row has reasoning.adaptive: true)`,
+        fix: 'agent({ …, model: modelId })   # or the llm() declaration, or definePrompt — or drop thinking from definePrompt',
       });
     }
     // No `thinking` field at all is exactly "no thinking" on a pre-4.6 model, so `disabled`
@@ -254,7 +310,7 @@ export function reasoningBody(
 
   if (thinking === 'disabled') {
     assertDisableAllowed(model, rules, effort ?? 'high');
-    body['thinking'] = { type: 'disabled' };
+    body['thinking'] = { type: rules.disabledThinking ?? 'disabled' };
     return body;
   }
   // Nothing asked for, nothing sent — the rule this file states, now the rule it follows.
@@ -268,57 +324,15 @@ export function reasoningBody(
 /** Some models cap the effort at which thinking may be switched off. Above the cap it is a 400. */
 function assertDisableAllowed(model: ModelId, rules: ModelReasoning, effort: Effort): void {
   const cap = rules.disableThinkingUpTo;
+  if (cap === 'never') {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" has thinking always on; thinking: 'disabled' is a 400 on it at every effort (modelId: a registered id whose registerModel row lets thinking be disabled)`,
+      fix: `effort: 'low'   # in definePrompt, in place of thinking: 'disabled' — or model: modelId on the agent() or llm() declaration`,
+    });
+  }
   if (cap === undefined || rankOf(effort) <= rankOf(cap)) return;
   throw new AiRequestInvalidError({
     detail: `model "${model}" allows thinking: 'disabled' only at effort '${cap}' or below, not '${effort}'`,
     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

@@ -4,6 +4,7 @@
 // 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 { assertMediaContent } from './content-blocks';
 import { AiRequestInvalidError } from './errors';
 import type { Effort, ModelId, ThinkingMode } from './models';
 import { modelSpec } from './models';
@@ -14,6 +15,8 @@ export interface ChatCompletionBodyInput {
   readonly request: GenerateRequest;
   /** Already resolved — the gateway picks the model, the provider never guesses mid-request. */
   readonly model: ModelId;
+  /** The provider's `name`, so a content refusal names the endpoint that cannot take the block. */
+  readonly provider: string;
   readonly stream: boolean;
 }
 
@@ -27,11 +30,12 @@ export interface ChatCompletionBodyInput {
  *     reject outright.
  */
 export function chatCompletionBody(input: ChatCompletionBodyInput): Record<string, unknown> {
-  const { request, model, stream } = input;
+  const { request, model, stream, provider } = input;
   const spec = modelSpec(model);
+  assertMediaContent(request.messages, { provider, model });
   const body: Record<string, unknown> = {
     model,
-    messages: toOpenAiMessages(request.system, request.messages),
+    messages: toOpenAiMessages(request.system, request.messages, { provider, model }),
     max_completion_tokens: Math.min(request.maxTokens, spec.maxOutput),
     ...reasoningFields(model, request.effort, request.thinking),
   };
@@ -80,6 +84,13 @@ export function reasoningFields(
       fix: 'drop thinking from definePrompt and set effort instead, or route the prompt to a model registered with reasoning: { adaptive: true }',
     });
   }
+  // The row says reasoning cannot be switched off, whatever the wire would spell the switch as.
+  if (thinking === 'disabled' && rules.disableThinkingUpTo === 'never') {
+    throw new AiRequestInvalidError({
+      detail: `model "${model}" is registered with reasoning always on (disableThinkingUpTo: 'never'), so reasoning_effort: 'none' cannot be sent to it`,
+      fix: "effort: 'low'   # in definePrompt, in place of thinking: 'disabled'",
+    });
+  }
   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`,

package/src/openai-messages.ts

@@ -5,6 +5,9 @@
 // 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 { AiMediaBlock } from './content-blocks';
+import { isMediaBlock } from './content-blocks';
+import { AiContentUnsupportedError } from './content-errors';
 import type { AiContentBlock, AiMessage } from './provider';
 import type { JsonSchema, LlmTool } from './tools';
 
@@ -15,8 +18,18 @@ export interface OpenAiToolCall {
   readonly function: { readonly name: string; readonly arguments: string };
 }
 
+/** A user message's parts, when it carries more than prose. Field names are the format's own. */
+export type OpenAiContentPart =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'image_url'; readonly image_url: { readonly url: string } }
+  | {
+      readonly type: 'file';
+      readonly file: { readonly filename: string; readonly file_data: string };
+    };
+
 export type OpenAiMessage =
-  | { readonly role: 'system' | 'user'; readonly content: string }
+  | { readonly role: 'system'; readonly content: string }
+  | { readonly role: 'user'; readonly content: string | readonly OpenAiContentPart[] }
   | {
       readonly role: 'assistant';
       readonly content?: string | undefined;
@@ -57,21 +70,33 @@ export interface OpenAiToolChoice {
 export function toOpenAiMessages(
   system: string | undefined,
   messages: readonly AiMessage[],
+  target: MediaTarget,
 ): readonly OpenAiMessage[] {
   const out: OpenAiMessage[] = [];
   if (system !== undefined && system !== '') out.push({ role: 'system', content: system });
-  for (const message of messages) {
+  messages.forEach((message, m) => {
     if (typeof message.content === 'string') {
       out.push({ role: message.role, content: message.content });
-      continue;
+    } else if (message.role === 'assistant') {
+      out.push(assistantMessage(message.content));
+    } else {
+      // `m` is the index in the CALLER's list, so a refusal's path matches `assertMediaContent`'s.
+      out.push(...userTurn(message.content, m, target));
     }
-    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. */
+/** Who a media refusal names: this provider, and the model the request is for. */
+export interface MediaTarget {
+  readonly provider: string;
+  readonly model: string;
+}
+
+/**
+ * Text blocks concatenate; `tool_use` blocks move onto `tool_calls` with stringified arguments.
+ * A media block never reaches here: `assertMediaContent` refuses one outside a user turn first.
+ */
 function assistantMessage(blocks: readonly AiContentBlock[]): OpenAiMessage {
   let content = '';
   const toolCalls: OpenAiToolCall[] = [];
@@ -95,15 +120,23 @@ function assistantMessage(blocks: readonly AiContentBlock[]): OpenAiMessage {
 }
 
 /**
- * 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.
+ * A user turn. Every tool 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. What remains is ONE user message: a plain
+ * string when it is only prose — the shape every server in the family takes — and parts, in
+ * block order, the moment it carries an image or a document.
  */
-function toolTurn(blocks: readonly AiContentBlock[]): readonly OpenAiMessage[] {
+function userTurn(
+  blocks: readonly AiContentBlock[],
+  index: number,
+  target: MediaTarget,
+): readonly OpenAiMessage[] {
   const out: OpenAiMessage[] = [];
-  let text = '';
-  for (const block of blocks) {
-    if (block.type === 'text') text += block.text;
+  const parts: OpenAiContentPart[] = [];
+  blocks.forEach((block, b) => {
+    if (block.type === 'text') parts.push({ type: 'text', text: block.text });
+    if (isMediaBlock(block))
+      parts.push(mediaPart(block, `messages[${index}].content[${b}]`, target));
     if (block.type === 'tool_result') {
       out.push({
         role: 'tool',
@@ -113,11 +146,49 @@ function toolTurn(blocks: readonly AiContentBlock[]): readonly OpenAiMessage[] {
         content: block.is_error === true ? `error: ${block.content}` : block.content,
       });
     }
+  });
+  if (parts.some((part) => part.type !== 'text')) out.push({ role: 'user', content: parts });
+  else {
+    const text = parts.map((part) => (part.type === 'text' ? part.text : '')).join('');
+    if (text !== '') out.push({ role: 'user', content: text });
   }
-  if (text !== '') out.push({ role: 'user', content: text });
   return out;
 }
 
+/**
+ * One media block as a content part. An image goes as `image_url` either way — a data URL for
+ * base64, the URL itself otherwise. A PDF goes as a `file` part with a base64 data URL. Chat
+ * completions has no shape for a document by URL ("not supported" — URL files are the Responses
+ * API's) and takes only PDFs as files, so those two are refused here rather than approximated.
+ */
+function mediaPart(block: AiMediaBlock, at: string, target: MediaTarget): OpenAiContentPart {
+  const { source } = block;
+  if (block.type === 'image') {
+    const url =
+      source.type === 'url' ? source.url : `data:${source.media_type};base64,${source.data}`;
+    return { type: 'image_url', image_url: { url } };
+  }
+  if (source.type === 'base64') {
+    const file_data = `data:${source.media_type};base64,${source.data}`;
+    return { type: 'file', file: { filename: block.title ?? 'document.pdf', file_data } };
+  }
+  const refusal =
+    source.type === 'url'
+      ? {
+          why: 'the chat-completions format has no document-by-URL part',
+          fix: "source: { type: 'base64', media_type: 'application/pdf', data }   # fetch the PDF and send its bytes",
+        }
+      : {
+          why: 'the chat-completions format takes only PDF files, never a text/plain document',
+          fix: "{ type: 'text', text }   # the document's text, as a block in the same user turn",
+        };
+  throw new AiContentUnsupportedError({
+    kind: 'document',
+    at,
+    refusal: { by: 'provider', ...target, ...refusal },
+  });
+}
+
 /**
  * Tool definitions, wrapped in the `{ type: 'function', function: … }` envelope.
  *