@ultimat3/ai 29.4.0 → 30.0.0

package/src/openai-provider.ts

@@ -9,6 +9,7 @@
 
 import type { Secret } from '@ultimat3/core';
 import { isSecret, revealSecret } from '@ultimat3/core';
+import { providerFailure } from './context-overflow';
 import { costOf, exactCostOf } from './cost';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
@@ -18,7 +19,9 @@ import type { ModelId } from './models';
 import { chatCompletionBody, sessionHeaders } from './openai-body';
 import type { ChatAnswer } from './openai-wire';
 import { ChatCompletionStream, parseChatCompletion } from './openai-wire';
+import type { ProviderCacheRow, ProviderPromptCache } from './prompt-cache';
 import { promptCacheRule } from './prompt-cache';
+import { screenCacheRows } from './prompt-cache-rows';
 import type {
   GenerateRequest,
   GenerateResult,
@@ -68,6 +71,14 @@ export interface OpenAiProviderInput {
    * thing that says which of them answered.
    */
   readonly name?: string;
+  /**
+   * What this endpoint does with a cache hint, when `PROMPT_CACHE_RULES` does not name its host —
+   * a company gateway fronting a marking family:
+   * `{ rules: [{ model: 'anthropic/', marks: 'parts', session: 'x-session-id' }] }`. Read before the
+   * table, first match by model prefix. This wire speaks `parts` or `none`, and carries a session as
+   * `x-session-id`, `prompt_cache_key` or `none`; anything else is `X_AI_REQUEST_INVALID` here.
+   */
+  readonly promptCache?: ProviderPromptCache;
   /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
   readonly fetch?: AiFetch;
 }
@@ -91,6 +102,7 @@ class OpenAiProvider implements Provider {
   readonly name: string;
   readonly models: readonly ModelId[];
   private readonly config: OpenAiProviderInput;
+  private readonly cacheRows: readonly ProviderCacheRow[];
 
   // `| undefined` for the reason `AnthropicProvider`'s is: no argument at all, from plain JS or a
   // cast, is the empty-list boot mistake and gets its coded refusal, never a TypeError.
@@ -107,10 +119,11 @@ class OpenAiProvider implements Provider {
     this.name = config.name ?? 'openai';
     this.models = config.models;
     this.config = config;
+    this.cacheRows = screenCacheRows('openai', config.promptCache);
   }
 
   marksPromptCache(model: ModelId): boolean {
-    return promptCacheRule('openai', this.config.baseUrl, model).marks === 'parts';
+    return promptCacheRule('openai', this.config.baseUrl, model, this.cacheRows).marks === 'parts';
   }
 
   /**
@@ -123,12 +136,14 @@ class OpenAiProvider implements Provider {
     // this provider's first listed model — the app's three places are the only ones.
     const model = resolveModel('provider', request.model);
     if (requiresStreaming({ ...request, model })) return this.assemble(request);
-    const { baseUrl } = this.config;
+    const cache = { baseUrl: this.config.baseUrl, cacheRows: this.cacheRows };
+    const cacheRule = promptCacheRule('openai', cache.baseUrl, model, cache.cacheRows);
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: false, provider: this.name, baseUrl }),
+      model,
+      chatCompletionBody({ request, model, stream: false, provider: this.name, ...cache }),
       false,
       request.signal,
-      sessionHeaders(request, model, baseUrl),
+      sessionHeaders(request, cacheRule),
     );
     const answer = parseChatCompletion((await response.json()) as unknown, this.name);
     return this.result(request, model, answer);
@@ -136,12 +151,14 @@ class OpenAiProvider implements Provider {
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = resolveModel('provider', request.model);
-    const { baseUrl } = this.config;
+    const cache = { baseUrl: this.config.baseUrl, cacheRows: this.cacheRows };
+    const cacheRule = promptCacheRule('openai', cache.baseUrl, model, cache.cacheRows);
     const response = await this.send(
-      chatCompletionBody({ request, model, stream: true, provider: this.name, baseUrl }),
+      model,
+      chatCompletionBody({ request, model, stream: true, provider: this.name, ...cache }),
       true,
       request.signal,
-      sessionHeaders(request, model, baseUrl),
+      sessionHeaders(request, cacheRule),
     );
     if (response.body === null) {
       throw new AiTransportError({
@@ -202,6 +219,7 @@ class OpenAiProvider implements Provider {
    * if it were a message would read as an empty, successful answer.
    */
   private async send(
+    model: ModelId,
     body: Record<string, unknown>,
     streaming: boolean,
     signal: AbortSignal | undefined,
@@ -228,8 +246,10 @@ class OpenAiProvider implements Provider {
       ...(signal === undefined ? {} : { signal }),
     });
     if (!response.ok) {
-      throw new AiTransportError({
+      // An overflow or the transport's code — `context-overflow.ts` decides, for both wires.
+      throw providerFailure({
         provider: this.name,
+        model,
         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.

package/src/openai-wire.ts

@@ -436,16 +436,20 @@ export class ChatCompletionStream {
   }
 
   private payloadOf(frame: SseFrame): Record<string, unknown> {
+    const where = `unreadable "${frame.event}" frame`;
+    let parsed: unknown;
     try {
-      const record = asRecord(JSON.parse(frame.data));
-      if (record === undefined) throw new SyntaxError('frame data is not an object');
-      return record;
+      parsed = JSON.parse(frame.data);
     } catch (error) {
-      throw malformed(
-        this.provider,
-        `unreadable "${frame.event}" frame: ${renderThrowable(error)}`,
-      );
+      throw malformed(this.provider, `${where}: ${renderThrowable(error)}`);
     }
+    const record = asRecord(parsed);
+    // The same coded refusal the catch above produces, thrown where the frame is known: a bare
+    // `SyntaxError` in shipped source carries no code, no cause and no fix.
+    if (record === undefined) {
+      throw malformed(this.provider, `${where}: frame data is not an object`);
+    }
+    return record;
   }
 }
 

package/src/prompt-cache-rows.ts

@@ -0,0 +1,82 @@
+// Single responsibility: screen the prompt-cache rows an app declares on a provider, at
+// construction, against what that provider's wire can speak. A row the wire cannot honour would
+// be a 400 on every hinted call, so it is refused at boot rather than sent.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AiRequestInvalidError } from './errors';
+import type { CacheWire, ProviderCacheRow, ProviderPromptCache } from './prompt-cache';
+
+interface WireSpeaks {
+  readonly factory: string;
+  readonly marks: readonly ProviderCacheRow['marks'][];
+  readonly session: readonly ProviderCacheRow['session'][];
+}
+
+/** What each wire carries: Messages has no session carrier; chat-completions has two. */
+const SPEAKS: ReadonlyMap<CacheWire, WireSpeaks> = new Map<CacheWire, WireSpeaks>([
+  ['anthropic', { factory: 'anthropicProvider', marks: ['blocks', 'none'], session: ['none'] }],
+  [
+    'openai',
+    {
+      factory: 'openAiProvider',
+      marks: ['parts', 'none'],
+      session: ['x-session-id', 'prompt_cache_key', 'none'],
+    },
+  ],
+]);
+
+/** The rows, screened; `[]` for no option. Reads `unknown` because plain JS reaches here too. */
+export function screenCacheRows(
+  wire: CacheWire,
+  option: ProviderPromptCache | undefined,
+): readonly ProviderCacheRow[] {
+  if (option === undefined) return [];
+  const speaks = SPEAKS.get(wire);
+  if (speaks === undefined) return [];
+  const rules: unknown = (option as { rules?: unknown }).rules;
+  if (!Array.isArray(rules)) {
+    throw refusal(speaks, `promptCache.rules is ${renderCauseValue(rules)}, not an array of rows`);
+  }
+  return rules.map((row: unknown, index) => screenRow(speaks, row, index));
+}
+
+function screenRow(speaks: WireSpeaks, row: unknown, index: number): ProviderCacheRow {
+  if (typeof row !== 'object' || row === null) {
+    throw refusal(speaks, `promptCache.rules row ${index} is ${renderCauseValue(row)}, not a row`);
+  }
+  const { model, marks, session } = row as Record<'model' | 'marks' | 'session', unknown>;
+  if (typeof model !== 'string') {
+    throw refusal(
+      speaks,
+      `promptCache.rules row ${index} has model ${renderCauseValue(model)}; a model is an id prefix string ('' is every model)`,
+    );
+  }
+  const mark = speaks.marks.find((known) => known === marks);
+  if (mark === undefined) {
+    throw refusal(
+      speaks,
+      `promptCache.rules row ${index} has marks ${renderCauseValue(marks)}; ${speaks.factory}()'s wire speaks marks ${quoted(speaks.marks)}`,
+    );
+  }
+  const carrier = speaks.session.find((known) => known === session);
+  if (carrier === undefined) {
+    throw refusal(
+      speaks,
+      `promptCache.rules row ${index} has session ${renderCauseValue(session)}; ${speaks.factory}()'s wire carries a session as ${quoted(speaks.session)}`,
+    );
+  }
+  return { model, marks: mark, session: carrier };
+}
+
+function refusal(speaks: WireSpeaks, detail: string): AiRequestInvalidError {
+  const marks = speaks.marks[0] ?? 'none';
+  const session = speaks.session[0] ?? 'none';
+  return new AiRequestInvalidError({
+    detail,
+    fix: `${speaks.factory}({ …, promptCache: { rules: [{ model: '<id prefix>', marks: '${marks}', session: '${session}' }] } })   # marks ${quoted(speaks.marks)}; session ${quoted(speaks.session)}`,
+  });
+}
+
+function quoted(values: readonly string[]): string {
+  return values.map((value) => `'${value}'`).join(' or ');
+}

package/src/prompt-cache.ts

@@ -41,7 +41,8 @@
 //
 // Two limits of the rows below, stated rather than hidden:
 //   - the `anthropic` row matches ANY host an `anthropicProvider({ baseUrl })` is pointed at — a
-//     proxy speaking that wire is assumed to speak its `cache_control` too;
+//     proxy speaking that wire is assumed to speak its `cache_control` too, unless the provider
+//     declares a `marks: 'none'` row for it;
 //   - the `parts` row marks the tail only, so the next turn finds this turn's entry through the
 //     20-position lookback alone. A turn that appends more blocks than that — more than about 9
 //     tool calls in ONE turn, each a `tool_use` and a `tool_result` — misses it and is billed as a
@@ -49,6 +50,7 @@
 //
 // The table is DATA: a new host or model family is a row. Unknown endpoints get NOTHING — a field
 // a self-hosted server has never heard of is a 400 on some of them, and a mark is never worth that.
+// What the app knows about its own endpoint is a row too, on the provider (`ProviderCacheRow`).
 
 /**
  * A system prompt in two parts. `stable` is byte-identical across runs — rules, a knowledge-base
@@ -142,17 +144,37 @@ export const PROMPT_CACHE_RULES: readonly PromptCacheRule[] = [
   { wire: 'openai', host: 'api.openai.com', model: '', marks: 'none', session: 'prompt_cache_key' },
 ];
 
+/**
+ * A row an app declares on its provider (`anthropicProvider({ promptCache: { rules } })`): what
+ * this package cannot know about an endpoint the app runs — a company gateway fronting a marking
+ * family, a proxy that 400s on `cache_control`. The provider IS the wire and the host, so a row
+ * names neither. Screened at construction against what the wire speaks (./prompt-cache-rows).
+ */
+export type ProviderCacheRow = Pick<PromptCacheRule, 'model' | 'marks' | 'session'>;
+
+/** The provider option: rows read before `PROMPT_CACHE_RULES`, first match wins. */
+export interface ProviderPromptCache {
+  readonly rules: readonly ProviderCacheRow[];
+}
+
 const NO_RULE: Pick<PromptCacheRule, 'marks' | 'session'> = { marks: 'none', session: 'none' };
 
 /** OpenAI's own endpoint, which is what an `openAiProvider()` with no `baseUrl` talks to. */
 const DEFAULT_OPENAI_HOST = 'api.openai.com';
 
-/** The rule for one request. Total: a base URL that does not parse matches no host. */
+/**
+ * The rule for one request. Total: a base URL that does not parse matches no host. The provider's
+ * own `rows` come first — the app's statement about its endpoint outranks this package's guess —
+ * then the table, then nothing.
+ */
 export function promptCacheRule(
   wire: CacheWire,
   baseUrl: string | undefined,
   model: string,
+  rows: readonly ProviderCacheRow[] = [],
 ): Pick<PromptCacheRule, 'marks' | 'session'> {
+  const own = rows.find((row) => model.startsWith(row.model));
+  if (own !== undefined) return { marks: own.marks, session: own.session };
   const host = baseUrl === undefined ? DEFAULT_OPENAI_HOST : hostOf(baseUrl);
   const found = PROMPT_CACHE_RULES.find(
     (rule) =>

package/src/provider.ts

@@ -1,34 +1,19 @@
-// The `Provider` interface and `AnthropicProvider` (the real Messages API, streaming and not) —
-// `EchoProvider`, the double, is ./echo-provider's, and the money arithmetic is ./cost's
-// (`costOf` is re-exported here, where every caller has always imported it from). The REQUEST half only: ./models owns the catalogue and the per-model rules,
-// ./wire owns the response half.
+// The provider-neutral shapes — `Provider`, the request, the result, the stream chunk — and the
+// pre-flight estimates. `AnthropicProvider` is ./anthropic-provider's, the double ./echo-provider's,
+// the money arithmetic ./cost's; `costOf` and the Anthropic names are re-exported here, where every
+// caller has always imported them from. ./models owns the per-model rules, ./wire the response half.
 
 import type { Money } from '@ultimat3/money';
 import type { AiMediaBlock } from './content-blocks';
-import { assertMediaContent, blockText, mediaTokenEstimate } from './content-blocks';
-import { costOf, exactCostOf } from './cost';
-import { detailOf, withoutKey } from './error-body';
-import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
-import type { AiFetch } from './fetch-seam';
+import { blockText, mediaTokenEstimate } from './content-blocks';
+import { costOf } from './cost';
 import { resolveModel } from './model-resolve';
 import type { Effort, ModelId, ThinkingMode } from './models';
-import { modelSpec, reasoningBody } from './models';
+import { modelSpec } from './models';
 import type { PromptCacheHint, SystemPrompt } from './prompt-cache';
-import { promptCacheRule, systemText } from './prompt-cache';
-import { anthropicPrompt } from './prompt-cache-blocks';
+import { systemText } from './prompt-cache';
 import type { SamplingWire } from './sampling';
-import { samplingBody } from './sampling';
-import { readSse } from './sse';
-import { assertToolArguments } from './tool-arguments';
 import type { LlmTool, LlmToolCall } from './tools';
-import {
-  asToolInput,
-  MessageStream,
-  parseStopDetails,
-  parseStopReason,
-  parseUsage,
-  throwInBandError,
-} from './wire';
 
 /**
  * One block of a structured message. A plain string message is still the common case and still
@@ -172,6 +157,13 @@ export type StreamChunk =
   | { readonly type: 'tool-call'; readonly call: LlmToolCall }
   | { readonly type: 'done'; readonly result: GenerateResult };
 
+export type { AnthropicProvider, AnthropicProviderInput } from './anthropic-provider';
+export {
+  anthropicProvider,
+  parseMessage,
+  requiresStreaming,
+  STREAM_ONLY_MAX_TOKENS,
+} from './anthropic-provider';
 export { costOf } from './cost';
 
 export interface Provider {
@@ -195,257 +187,6 @@ export function totalTokens(usage: TokenUsage): number {
   return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
 }
 
-// ── Anthropic ────────────────────────────────────────────────────────────────
-
-export interface AnthropicProviderInput {
-  /**
-   * The ids this endpoint serves — REQUIRED, the app's list, never a built-in one: the gateway
-   * routes by membership, and each id is one the app `registerModel`-ed. A direct call names its
-   * model or is refused (`X_AI_MODEL_UNRESOLVED`), as `openAiProvider({ models })`'s is.
-   */
-  readonly models: readonly ModelId[];
-  /** Reads `ANTHROPIC_API_KEY` when omitted. Absent at call time is a labelled throw. */
-  readonly apiKey?: string;
-  readonly baseUrl?: string;
-  /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
-  readonly fetch?: AiFetch;
-}
-
-const ANTHROPIC_VERSION = '2023-06-01';
-const API_KEY_ENV = 'ANTHROPIC_API_KEY';
-
-/**
- * Above this ceiling a non-streaming request sits on an open socket past the HTTP timeout and
- * fails AFTER the completion was generated and billed. Every current model can be asked for
- * eight times this, so the limit is the transport's, not the model's.
- */
-export const STREAM_ONLY_MAX_TOKENS = 16_000;
-
-/** Whether this request has to go over the streaming transport to arrive at all. */
-export function requiresStreaming(request: GenerateRequest): boolean {
-  const model = resolveModel('provider', request.model);
-  return Math.min(request.maxTokens, modelSpec(model).maxOutput) > STREAM_ONLY_MAX_TOKENS;
-}
-
-/** The Anthropic Messages API provider — the one way to build one; the class is a type only. */
-export function anthropicProvider(input: AnthropicProviderInput): AnthropicProvider {
-  return new AnthropicProvider(input);
-}
-
-/**
- * The real Messages API shape. The request-surface rules are encoded rather than documented,
- * because getting them wrong is a 400:
- *   - `top_p`/`top_k` are never sent, and `temperature` only to a model whose row takes it
- *     (`ModelSpec.sampling`): a reasoning model rejects all three.
- *   - `thinking.budget_tokens` is REJECTED. Use `output_config.effort`.
- *   - `effort` and adaptive thinking are per-model, and ./models owns which model takes which.
- */
-export class AnthropicProvider implements Provider {
-  readonly name = 'anthropic';
-  readonly wire = 'anthropic' as const;
-  /** The app's list, never the registry's: a model served elsewhere must not be routed here. */
-  readonly models: readonly ModelId[];
-  private readonly config: AnthropicProviderInput;
-
-  // `| undefined`: plain JS (or a cast) reaches here with no argument, and that is the same boot
-  // mistake as an empty list — it gets the coded refusal, never a TypeError on `.models`.
-  constructor(config: AnthropicProviderInput | undefined) {
-    if (config === undefined || (config.models ?? []).length === 0) {
-      // A provider serving nothing can never be routed to — the same boot mistake, refused the
-      // same way, as an empty `openAiProvider({ models })`.
-      throw new AiRequestInvalidError({
-        detail:
-          'anthropicProvider() was given an empty models list, so the gateway can never route to it',
-        fix: "anthropicProvider({ models: ['<id>'] })   # the ids this endpoint serves, each one your app registerModel-ed",
-      });
-    }
-    this.models = config.models;
-    this.config = config;
-  }
-
-  /**
-   * The model this request is for. The gateway resolves one before it routes; a direct call names
-   * one or is refused — this provider's own list is never a fourth place a model comes from.
-   */
-  private modelOf(request: GenerateRequest): ModelId {
-    return resolveModel('provider', request.model);
-  }
-
-  /**
-   * Above `STREAM_ONLY_MAX_TOKENS` this runs the STREAMING transport and returns the assembled
-   * result, rather than refusing. Refusing would leak a transport limit into the API: `llm()`
-   * has no streaming path, so a declaration asking for a legal 64k completion would become
-   * undeclarable instead of merely awkward — and the caller wanting the whole answer at once is
-   * the same caller either way.
-   */
-  async generate(request: GenerateRequest): Promise<GenerateResult> {
-    const model = this.modelOf(request);
-    if (requiresStreaming({ ...request, model })) return this.assemble(request);
-    const response = await this.send({ ...this.body(request), stream: false }, request.signal);
-    const raw = (await response.json()) as Record<string, unknown>;
-    return parseMessage(model, raw);
-  }
-
-  /** 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',
-    });
-  }
-
-  /**
-   * Streaming is mandatory above ~16k `maxTokens`: a non-streaming request that large hits the
-   * HTTP timeout before the model finishes. The final `done` chunk carries the assembled
-   * result, so a consumer that only wants the answer can ignore every chunk before it.
-   */
-  async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
-    const model = this.modelOf(request);
-    const response = await this.send({ ...this.body(request), stream: true }, request.signal);
-    if (response.body === null) {
-      throw new AiTransportError({
-        provider: this.name,
-        status: response.status,
-        detail: 'a streaming response arrived with no body',
-      });
-    }
-    const message = new MessageStream();
-    for await (const frame of readSse(response.body, this.name)) {
-      for (const chunk of message.push(frame)) yield chunk;
-    }
-    // A connection cut mid-answer must fail, not resolve: the partial text reads as a complete
-    // answer, and `end_turn` would be a lie the caller has no way to detect.
-    if (!message.isComplete()) {
-      throw new AiTransportError({
-        provider: this.name,
-        detail:
-          'the stream ended before message_stop, or with a tool call still open — the answer is truncated',
-      });
-    }
-    const { malformed, ...state } = message.state();
-    const cost = costOf(model, state.usage);
-    // After usage is known, so a finished turn with unreadable arguments fails WITH its bill.
-    assertToolArguments({ provider: this.name, model, ...state, malformed, cost });
-    yield {
-      type: 'done',
-      result: { model, ...state, cost, costExact: exactCostOf(model, state.usage) },
-    };
-  }
-
-  marksPromptCache(model: ModelId): boolean {
-    return promptCacheRule('anthropic', this.config.baseUrl, model).marks === 'blocks';
-  }
-
-  /** The request body. Pure and side-effect free so a test can assert it directly. */
-  body(request: GenerateRequest): Record<string, unknown> {
-    const model = this.modelOf(request);
-    // The blocks pass through untouched below — they ARE this wire's shapes — so this is the screen.
-    assertMediaContent(request.messages, { provider: this.name, model });
-    const prompt = anthropicPrompt(
-      request,
-      request.promptCache !== undefined && this.marksPromptCache(model),
-    );
-    const body: Record<string, unknown> = {
-      model,
-      max_tokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
-      messages: prompt.messages,
-      ...reasoningBody(model, request.effort, request.thinking),
-      ...samplingBody('anthropic', model, request),
-    };
-    if (prompt.system !== undefined) body['system'] = prompt.system;
-    if (request.tools !== undefined && request.tools.length > 0) body['tools'] = request.tools;
-    if (request.stopSequences !== undefined) body['stop_sequences'] = request.stopSequences;
-    return body;
-  }
-
-  /**
-   * 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>,
-    signal: AbortSignal | undefined,
-  ): Promise<Response> {
-    const apiKey = this.config.apiKey ?? Bun.env[API_KEY_ENV];
-    if (apiKey === undefined || apiKey === '') {
-      throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
-    }
-    const doFetch: AiFetch = this.config.fetch ?? fetch;
-    const url = `${this.config.baseUrl ?? 'https://api.anthropic.com'}/v1/messages`;
-    const response = await doFetch(url, {
-      method: 'POST',
-      headers: {
-        'x-api-key': apiKey,
-        'anthropic-version': ANTHROPIC_VERSION,
-        'content-type': 'application/json',
-        accept: body['stream'] === true ? 'text/event-stream' : 'application/json',
-      },
-      body: JSON.stringify(body),
-      // Attached only when the caller has one: `exactOptionalPropertyTypes`, and an explicit
-      // `signal: undefined` is a different value to some fetch implementations.
-      ...(signal === undefined ? {} : { signal }),
-    });
-    if (!response.ok) {
-      throw new AiTransportError({
-        provider: this.name,
-        status: response.status,
-        // The endpoint's own message, with the credential scrubbed out of it — the same rule the
-        // OpenAI-format provider follows, and for the same reason: a proxy echoing the request
-        // headers into its 4xx body is the one path by which `x-api-key` reaches an error.
-        detail: withoutKey(await detailOf(response), apiKey),
-        envVar: API_KEY_ENV,
-      });
-    }
-    return response;
-  }
-}
-
-/** Map a Messages API response onto `GenerateResult`. Exported so tests can drive it. */
-export function parseMessage(model: ModelId, raw: Record<string, unknown>): GenerateResult {
-  // A 200 carrying an `error` object instead of an answer — how a gateway in front of a model
-  // reports a fault it noticed after the headers were sent. Read as a message it is an empty,
-  // successful answer, which is the one outcome nothing downstream can detect; the STREAMED half
-  // of this same provider has always refused it.
-  throwInBandError(raw);
-  const content = Array.isArray(raw['content']) ? raw['content'] : [];
-  let text = '';
-  const toolCalls: LlmToolCall[] = [];
-  for (const block of content) {
-    if (typeof block !== 'object' || block === null) continue;
-    const b = block as Record<string, unknown>;
-    if (b['type'] === 'text' && typeof b['text'] === 'string') text += b['text'];
-    if (b['type'] === 'tool_use' && typeof b['id'] === 'string' && typeof b['name'] === 'string') {
-      toolCalls.push({
-        id: b['id'],
-        name: b['name'],
-        // Parsed, never cast: `input` is untrusted, and a string under `Record<string, unknown>`
-        // is a lie every later reader indexes into. The streamed half already parses it.
-        input: asToolInput(b['input']),
-      });
-    }
-  }
-  const usage = parseUsage(raw['usage']);
-  const stopDetails = parseStopDetails(raw['stop_details']);
-  return {
-    model,
-    text,
-    toolCalls,
-    // A refusal detail is a refusal whatever the stop field says: `parseStopReason` answers
-    // `end_turn` for a spelling this build has never seen, and `llm()` branches on the REASON —
-    // `stopDetails` has no reader that can refuse — so the pair would arrive as a complete answer
-    // that happens to be empty. The OpenAI-format read has always forced it.
-    stopReason: stopDetails === undefined ? parseStopReason(raw['stop_reason']) : 'refusal',
-    stopDetails,
-    usage,
-    cost: costOf(model, usage),
-    costExact: exactCostOf(model, usage),
-  };
-}
-
 /**
  * ~4 characters per token. Deliberately an ESTIMATE and never used for billing — the gateway's
  * pre-flight budget check needs a number before the call exists, and `usage` replaces it after.

package/src/remote-embedder.ts

@@ -6,7 +6,14 @@
 // vendor: `baseUrl` selects the provider and nothing else changes. A second class per vendor
 // would be a second thing to learn for a difference that does not exist on the wire.
 
-import { finiteCount, readWithinLimit, renderThrowable } from '@ultimat3/core';
+import {
+  abandonment,
+  finiteCount,
+  isUltimateError,
+  readWithinLimit,
+  renderThrowable,
+} from '@ultimat3/core';
+import { outboundResponse } from '@ultimat3/core/outbound';
 import type { Embedder } from './embeddings';
 import { normalizeVector } from './embeddings';
 import { detailOf, withoutKey } from './error-body';
@@ -108,21 +115,41 @@ export class RemoteEmbedder implements Embedder {
     if (apiKey === undefined || apiKey === '') {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
     }
-    const doFetch: AiFetch = this.config.fetch ?? fetch;
+    const doFetch: AiFetch =
+      this.config.fetch ??
+      ((input, init) => fetch(input, { ...init, signal: init.signal ?? null }));
     const timeoutMs = this.timeoutMs;
     const url = `${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`;
     let response: Response;
     try {
-      response = await doFetch(url, {
-        method: 'POST',
-        headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
-        body: JSON.stringify({ model: this.name, input: texts }),
-        // Without this the call has no deadline at all: the per-request budget produces a
-        // `ctx.signal` that never reaches here, so a provider that accepts the connection and
-        // never answers holds a worker for as long as the socket stays open.
-        signal: AbortSignal.timeout(timeoutMs),
-      });
+      // Through core's `outbound()`: `timeoutMs` bounds the WHOLE batch, the ambient request's
+      // signal and deadline end it, and an embedding is a pure read of its input, so a 5xx or a
+      // throttle is retried inside that bound (`idempotent: true`). The body is capped as it lands.
+      response = await outboundResponse(
+        {
+          url,
+          vendor: this.name,
+          dial: 'named',
+          method: 'POST',
+          idempotent: true,
+          deadlineMs: timeoutMs,
+          maxBytes: this.maxResponseBytes,
+          headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+          body: JSON.stringify({ model: this.name, input: texts }),
+        },
+        { fetch: doFetch },
+      );
     } catch (error) {
+      // A caller gone keeps its own reason; the cap is the over-limit refusal below, said once.
+      if (abandonment() !== undefined) throw error;
+      if (isUltimateError(error) && error.code === 'X_OUTBOUND_TOO_LARGE') {
+        throw new AiTransportError({
+          provider: this.name,
+          status: 200,
+          detail: `response body is over the limit of ${this.maxResponseBytes} bytes`,
+          envVar: API_KEY_ENV,
+        });
+      }
       throw new AiTransportError({
         provider: this.name,
         // `renderThrowable`, never `error instanceof Error` and `.message`: `fetch` is injected