@ultimat3/ai 1.2.0 → 2.0.0

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

package/src/openai-provider.ts

@@ -0,0 +1,260 @@
+// Single responsibility: `openAiProvider()` — a `Provider` speaking the OpenAI chat-completions
+// wire FORMAT, against whatever endpoint is configured.
+//
+// The format matters more than the vendor: Azure OpenAI, vLLM, Ollama, LiteLLM, OpenRouter,
+// Together and most self-hosted company gateways serve it, so one provider plus a `baseUrl` is the
+// difference between "Ultimate talks to models" and "Ultimate talks to OUR models". The request
+// half is ./openai-body, the response half is ./openai-wire; this file owns the socket, the
+// credential and the errors.
+
+import type { Secret } from '@ultimat3/core';
+import { isSecret, revealSecret } from '@ultimat3/core';
+import { detailOf, withoutKey } from './error-body';
+import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
+import type { ModelId } from './models';
+import { chatCompletionBody } from './openai-body';
+// Imported for its registration side effect: a provider that cannot price what it serves throws
+// X_AI_MODEL_UNKNOWN at the first call, and the specs belong with the format that names them.
+import './openai-models';
+import type { ChatAnswer } from './openai-wire';
+import { ChatCompletionStream, parseChatCompletion } from './openai-wire';
+import type {
+  GenerateRequest,
+  GenerateResult,
+  Provider,
+  StreamChunk,
+  TokenUsage,
+} from './provider';
+import { costOf, estimateInputTokens, estimateTextTokens, requiresStreaming } from './provider';
+import { readSse } from './sse';
+
+const API_KEY_ENV = 'OPENAI_API_KEY';
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+
+export interface OpenAiProviderInput {
+  /**
+   * A `Secret` for preference — it redacts by value, so the same key is safe in a log line, an
+   * error `meta` and a snapshot. A plain string is accepted because an env var already is one.
+   * Reads `OPENAI_API_KEY` when omitted; absent at call time is a labelled throw.
+   */
+  readonly apiKey?: Secret | string;
+  /**
+   * The endpoint, minus `/chat/completions`. THIS is what makes the provider vendor-neutral —
+   * `http://localhost:11434/v1` is Ollama, `http://vllm:8000/v1` is vLLM, and an Azure deployment
+   * URL with its `?api-version=` query works as written: a query on the base is carried onto the
+   * request rather than swallowed by the path.
+   */
+  readonly baseUrl?: string;
+  /**
+   * The ids this endpoint serves. Required, and the provider's OWN list rather than the registry's,
+   * for the reason `AnthropicProvider.models` is: an app's internal model must not be routed
+   * somewhere that has never heard of it. On Azure these are DEPLOYMENT names, not model names.
+   */
+  readonly models: readonly ModelId[];
+  /** Extra headers — OpenRouter's attribution pair, a gateway's tenant header. Merged last. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Which header carries the key. `bearer` is `Authorization: Bearer …`, the format's default;
+   * `api-key` is Azure's. One knob rather than two ways to pass a credential, so the key stays
+   * boxed in a `Secret` until the header is built.
+   */
+  readonly auth?: 'bearer' | 'api-key';
+  /**
+   * What this provider is called on a span and in a failure list. Default `openai`. Worth setting
+   * when two endpoints speaking this format serve one model — `provider` on the result is the only
+   * thing that says which of them answered.
+   */
+  readonly name?: string;
+  /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+
+/**
+ * A provider for any endpoint speaking the OpenAI chat-completions format.
+ *
+ * ```ts
+ * // OpenAI
+ * openAiProvider({ apiKey: openAiKey, models: [...OPENAI_MODEL_IDS] })
+ * // a company gateway, vLLM, Ollama — same class, one different field
+ * openAiProvider({ apiKey: gatewayKey, baseUrl: 'https://llm.acme.internal/v1', models: ['acme-70b'] })
+ * ```
+ */
+export function openAiProvider(input: OpenAiProviderInput): Provider {
+  return new OpenAiProvider(input);
+}
+
+class OpenAiProvider implements Provider {
+  readonly name: string;
+  readonly models: readonly ModelId[];
+  private readonly defaultModel: ModelId;
+  private readonly config: OpenAiProviderInput;
+
+  constructor(config: OpenAiProviderInput) {
+    const [first] = config.models;
+    if (first === undefined) {
+      // A provider serving nothing can never be routed to, so it is a boot mistake that would
+      // otherwise surface as "no provider serves <model>" — a true statement about the wrong thing.
+      throw new AiRequestInvalidError({
+        detail:
+          'openAiProvider was given an empty models list, so the gateway can never route to it',
+        fix: 'pass models: [...OPENAI_MODEL_IDS] to openAiProvider, or the ids your endpoint serves',
+      });
+    }
+    this.name = config.name ?? 'openai';
+    this.models = config.models;
+    this.defaultModel = first;
+    this.config = config;
+  }
+
+  /**
+   * Above `STREAM_ONLY_MAX_TOKENS` this runs the streaming transport and assembles the result,
+   * for the reason the Anthropic provider does: a non-streaming request that large sits on an
+   * open socket past the HTTP timeout and fails after the completion was generated and billed.
+   */
+  async generate(request: GenerateRequest): Promise<GenerateResult> {
+    if (requiresStreaming(request)) return this.assemble(request);
+    const model = this.modelOf(request);
+    const response = await this.send(chatCompletionBody({ request, model, stream: false }), false);
+    const answer = parseChatCompletion((await response.json()) as unknown, this.name);
+    return this.result(request, model, answer);
+  }
+
+  async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
+    const model = this.modelOf(request);
+    const response = await this.send(chatCompletionBody({ request, model, stream: true }), true);
+    if (response.body === null) {
+      throw new AiTransportError({
+        provider: this.name,
+        status: response.status,
+        detail: 'a streaming response arrived with no body',
+      });
+    }
+    const completion = new ChatCompletionStream(this.name);
+    for await (const frame of readSse(response.body)) {
+      for (const chunk of completion.push(frame)) yield chunk;
+    }
+    // A connection cut mid-answer must fail, not resolve: partial text reads as a complete answer,
+    // and `end_turn` would be a lie the caller has no way to detect.
+    if (!completion.isComplete()) {
+      throw new AiTransportError({
+        provider: this.name,
+        detail: 'the stream ended before a finish reason — the answer is truncated',
+      });
+    }
+    yield { type: 'done', result: this.result(request, model, completion.state()) };
+  }
+
+  /** Drive `stream()` to its `done` chunk. It throws on a cut stream, so a partial never lands. */
+  private async assemble(request: GenerateRequest): Promise<GenerateResult> {
+    for await (const chunk of this.stream(request)) {
+      if (chunk.type === 'done') return chunk.result;
+    }
+    throw new AiTransportError({
+      provider: this.name,
+      detail: 'the stream completed without a result',
+    });
+  }
+
+  /** One parsed answer, priced. The only place `cost` is applied — the provider owns prices. */
+  private result(request: GenerateRequest, model: ModelId, answer: ChatAnswer): GenerateResult {
+    const usage = answer.usage ?? estimatedUsage(request, answer.text);
+    return {
+      model,
+      text: answer.text,
+      toolCalls: answer.toolCalls,
+      stopReason: answer.stopReason,
+      stopDetails: answer.stopDetails,
+      usage,
+      cost: costOf(model, usage),
+    };
+  }
+
+  /**
+   * The model this request is for. The gateway resolves one before it routes, so the fallback is
+   * only ever reached by a direct call — and it is this provider's first model, never the
+   * framework's `DEFAULT_MODEL`, which names a Claude id no OpenAI-format endpoint serves.
+   */
+  private modelOf(request: GenerateRequest): ModelId {
+    return request.model ?? this.defaultModel;
+  }
+
+  /**
+   * The one place a request leaves the process. A non-2xx becomes an `AiTransportError` carrying
+   * its status, because the gateway decides whether to retry from that status and a body parsed as
+   * if it were a message would read as an empty, successful answer.
+   */
+  private async send(body: Record<string, unknown>, streaming: boolean): Promise<Response> {
+    const apiKey = this.apiKey();
+    const doFetch = this.config.fetch ?? fetch;
+    const response = await doFetch(this.url(), {
+      method: 'POST',
+      headers: {
+        ...(this.config.auth === 'api-key'
+          ? { 'api-key': apiKey }
+          : { authorization: `Bearer ${apiKey}` }),
+        'content-type': 'application/json',
+        accept: streaming ? 'text/event-stream' : 'application/json',
+        // Last, so a caller can replace the credential header outright for a gateway that wants
+        // its own scheme. Nothing here is ever logged.
+        ...this.config.headers,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      throw new AiTransportError({
+        provider: this.name,
+        status: response.status,
+        // The endpoint's own message, with the credential scrubbed out of it — `error-body.ts`
+        // says why, and both providers call the same pair.
+        detail: withoutKey(await detailOf(response), apiKey),
+        envVar: API_KEY_ENV,
+      });
+    }
+    return response;
+  }
+
+  /**
+   * The credential, revealed as late as possible and never stored on the instance. Returned rather
+   * than kept, so the only string that exists is the local one `send` puts in a header.
+   */
+  private apiKey(): string {
+    const configured = this.config.apiKey;
+    const value = isSecret(configured)
+      ? revealSecret(configured)
+      : (configured ?? Bun.env[API_KEY_ENV]);
+    if (value === undefined || value === '') {
+      throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
+    }
+    return value;
+  }
+
+  /**
+   * `<baseUrl>/chat/completions`, with any query on the base preserved. Azure's deployment URL
+   * carries `?api-version=…`, and appending the path after it would send the version as part of a
+   * path segment — a 404 whose cause reads like a wrong deployment name.
+   */
+  private url(): string {
+    const base = this.config.baseUrl ?? DEFAULT_BASE_URL;
+    const cut = base.indexOf('?');
+    const path = (cut === -1 ? base : base.slice(0, cut)).replace(/\/+$/, '');
+    return `${path}/chat/completions${cut === -1 ? '' : base.slice(cut)}`;
+  }
+}
+
+/**
+ * What a call cost when the endpoint reported nothing.
+ *
+ * Every streamed request asks for usage (`stream_options.include_usage`), and every non-streamed
+ * response carries it — but a compatible server that ignores the field leaves the budget
+ * reconciling a real call against zero, which refunds the reservation in full and turns the ledger
+ * into a decoration. An estimate is wrong by a few percent in the safe direction; zero is wrong by
+ * all of it.
+ */
+export function estimatedUsage(request: GenerateRequest, text: string): TokenUsage {
+  return {
+    inputTokens: estimateInputTokens(request),
+    outputTokens: estimateTextTokens(text),
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+  };
+}