@ultimat3/ai 29.4.0 → 30.0.0

package/src/agent-send.ts

@@ -0,0 +1,82 @@
+// Single responsibility: sending one `agent()` turn — and, when the provider refuses it as over
+// the window (`X_AI_CONTEXT_OVERFLOW`), compacting once and sending it again. The loop still holds
+// the transcript after that 400, so the refusal is recoverable; a second one, or `compact: 'off'`,
+// is `X_AGENT_CONTEXT_EXHAUSTED` with the provider's own words as its reason.
+
+import { isUltimateError, renderThrowable, stringField } from '@ultimat3/core';
+import type { Compactor } from './agent-compact';
+import { promptTokens, roomOf } from './agent-compact';
+import { AgentContextExhaustedError } from './agent-errors';
+import type { ModelId } from './models';
+import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
+
+const OVERFLOW = 'X_AI_CONTEXT_OVERFLOW';
+
+export interface TurnSend {
+  readonly agent: string;
+  readonly model: ModelId;
+  /** The run's request with no messages. */
+  readonly base: GenerateRequest;
+  /** `undefined` under `compact: 'off'`: an overflow then ends the run. */
+  readonly compacting: Compactor | undefined;
+  /** One metered, deadline-guarded, cost-checked provider call. */
+  readonly send: (request: GenerateRequest) => Promise<GenerateResult>;
+}
+
+export interface SentTurn {
+  readonly result: GenerateResult;
+  /** What was sent: the messages given, or their forced compaction. */
+  readonly messages: readonly AiMessage[];
+}
+
+/** The provider's text, read totally: the value came out of a `catch`. */
+const refusalOf = (error: unknown): string =>
+  (isUltimateError(error) ? stringField(error.meta, 'detail') : undefined) ??
+  renderThrowable(error);
+
+const isOverflow = (error: unknown): boolean => stringField(error, 'code') === OVERFLOW;
+
+/**
+ * Send `messages` as turn `turn`. `onCompacted` hears the forced compaction before the re-send, so
+ * a failure after it resumes from the shorter transcript.
+ */
+export async function sendTurn(
+  input: TurnSend,
+  messages: readonly AiMessage[],
+  turn: number,
+  onCompacted: (messages: readonly AiMessage[]) => void,
+): Promise<SentTurn> {
+  const { base, compacting } = input;
+  const exhausted = (sent: readonly AiMessage[], error: unknown, reason: string): never => {
+    throw new AgentContextExhaustedError({
+      agent: input.agent,
+      model: input.model,
+      estimate: promptTokens({ ...base, messages: sent }),
+      limit: roomOf(input.model, base.maxTokens),
+      reason,
+      refused: refusalOf(error),
+    });
+  };
+  const observed = async (sent: readonly AiMessage[]): Promise<SentTurn> => {
+    const request: GenerateRequest = { ...base, messages: sent };
+    const result = await input.send(request);
+    compacting?.observe(result.usage, request);
+    return { result, messages: sent };
+  };
+  try {
+    return await observed(messages);
+  } catch (error) {
+    if (!isOverflow(error)) throw error;
+    if (compacting === undefined) {
+      return exhausted(messages, error, "compact is 'off', so nothing could shorten it");
+    }
+    const compacted = await compacting.force(messages, turn, refusalOf(error));
+    onCompacted(compacted);
+    try {
+      return await observed(compacted);
+    } catch (again) {
+      if (!isOverflow(again)) throw again;
+      return exhausted(compacted, again, 'the compacted request was refused as well');
+    }
+  }
+}

package/src/agent-stream.ts

@@ -0,0 +1,76 @@
+/**
+ * An agent run, streamed. `agent()` declares `stream: AgentChunk`, so a page asking its route for
+ * `text/event-stream` sees each turn as it lands — the turn's text, each tool call and its outcome,
+ * the turn's end — instead of a spinner for the whole loop. Facts only: no arguments, no tool
+ * output, no transcript, the same line `onTurn` holds. `done` is the action's own final frame.
+ */
+
+import { t } from '@ultimat3/schema';
+
+export const AgentChunk = t.discriminatedUnion(
+  'type',
+  t.object({ type: t.literal('text'), turn: t.number, text: t.string }),
+  t.object({ type: t.literal('tool_call'), turn: t.number, id: t.string, name: t.string }),
+  t.object({
+    type: t.literal('tool_result'),
+    turn: t.number,
+    id: t.string,
+    name: t.string,
+    isError: t.boolean,
+  }),
+  t.object({ type: t.literal('turn'), turn: t.number, maxTurns: t.number }),
+);
+
+export type AgentChunkValue =
+  | { readonly type: 'text'; readonly turn: number; readonly text: string }
+  | {
+      readonly type: 'tool_call';
+      readonly turn: number;
+      readonly id: string;
+      readonly name: string;
+    }
+  | {
+      readonly type: 'tool_result';
+      readonly turn: number;
+      readonly id: string;
+      readonly name: string;
+      readonly isError: boolean;
+    }
+  | { readonly type: 'turn'; readonly turn: number; readonly maxTurns: number };
+
+export type EmitChunk = (chunk: AgentChunkValue) => void;
+
+/**
+ * A callback-driven run as the async generator a stream-declaring action's `handle` is: chunks are
+ * queued as `run` emits them and yielded in order; the run's answer is the generator's return.
+ * A consumer that stops early (`return()`) leaves `run` to the context's own abort.
+ */
+export async function* streamOf<T>(
+  run: (emit: EmitChunk) => Promise<T>,
+): AsyncGenerator<AgentChunkValue, T, undefined> {
+  const queue: AgentChunkValue[] = [];
+  let wake: (() => void) | undefined;
+  const emit: EmitChunk = (chunk) => {
+    queue.push(chunk);
+    wake?.();
+  };
+  let settled = false;
+  const finished = run(emit).finally(() => {
+    settled = true;
+    wake?.();
+  });
+  // Observed here so a failure is never unhandled while the loop is waiting; rethrown below.
+  finished.catch(() => undefined);
+  for (;;) {
+    const next = queue.shift();
+    if (next !== undefined) {
+      yield next;
+      continue;
+    }
+    if (settled) return await finished;
+    await new Promise<void>((resolve) => {
+      wake = resolve;
+    });
+    wake = undefined;
+  }
+}

package/src/agent.ts

@@ -21,11 +21,12 @@
  */
 
 import type { Action } from '@ultimat3/action';
-import { action } from '@ultimat3/action';
+import { action, noteToolNames } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
 import { throwIfAborted, withSpan } from '@ultimat3/core';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
+import { checkpointer } from './agent-checkpoint';
 import type { Compactor } from './agent-compact';
 import { compactor } from './agent-compact';
 import type { CompactPlan } from './agent-compact-def';
@@ -47,6 +48,10 @@ import { runDeadline, toolLoopGuard } from './agent-guards';
 import type { Adapted, PerRun } from './agent-per-run';
 import { project, resolvePerRun } from './agent-per-run';
 import { assertRunCost } from './agent-run-limits';
+import type { TurnSend } from './agent-send';
+import { sendTurn } from './agent-send';
+import type { EmitChunk } from './agent-stream';
+import { AgentChunk, streamOf } from './agent-stream';
 import { sameSystem, systemOf } from './agent-system';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import { assertAnswerable, observeTurn } from './agent-turn';
@@ -96,6 +101,9 @@ export function agent<
       tools: unexposed.map(toolLabel),
     });
   }
+  // An in-process tool is in no registry: the `manifest` step reads this to tell a gate on one from
+  // a gate on a typo. An action beside this one may have no name yet, and its registry answers it.
+  noteToolNames(def.tools.map((tool) => tool.name).filter((name) => name !== ''));
   const bounds = screenBounds(def);
   // What every run is held under; a run's `limits()` may only lower it (`narrowCeilings`).
   const declared = { bounds, deadlineMs: def.deadlineMs, budget: def.budget };
@@ -116,13 +124,17 @@ export function agent<
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
-    handle: async (args) =>
-      run(
-        def,
-        respond,
-        await resolvePerRun(def, { ...declared, adapted: adapt() }, args),
-        { sampling, owner, compact },
-        args,
+    // Streamed: an ordinary call drains it to the answer; `accept: text/event-stream` sees each turn.
+    stream: AgentChunk,
+    handle: (args) =>
+      streamOf(async (emit) =>
+        run(
+          def,
+          respond,
+          await resolvePerRun(def, { ...declared, adapted: adapt() }, args),
+          { sampling, owner, compact, emit },
+          args,
+        ),
       ),
   });
   // A thunk, resolved when the manifest asks: every name in the row is stamped at boot, and this
@@ -159,6 +171,7 @@ async function run<
     readonly sampling: Sampling;
     readonly owner: object;
     readonly compact: CompactPlan | undefined;
+    readonly emit: EmitChunk;
   },
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
@@ -201,7 +214,7 @@ async function run<
   const system = systemOf(prompt.system, extra, redact);
   const promptCache = promptCacheHint(def.promptCache, 'auto', args);
   const repeated = toolLoopGuard(name, bounds.maxRepeatedToolCalls);
-  const sampling = fixed.sampling;
+  const { sampling, emit } = fixed;
   const { maxTurns, maxToolResultChars: chars } = bounds;
 
   return withSpan('ai.agent', async (span) => {
@@ -277,6 +290,30 @@ async function run<
       const count = compacting?.count() ?? prior?.compacted ?? 0;
       return count > 0 ? { compacted: count } : {};
     };
+    const turnSend: TurnSend = {
+      agent: name,
+      model,
+      base,
+      compacting,
+      send: (request) => {
+        assertCost(request);
+        return deadline.guard(meter.call(gateway.generate(request))).catch((error: unknown) => {
+          // The caller left mid-call: the aborted socket reads as a provider failure, which is
+          // RETRYABLE. Say what happened instead.
+          throwIfAborted(args.ctx);
+          throw error;
+        });
+      },
+    };
+    // Seals and hands over a handle between turns — `undefined`, and free, without the hook.
+    const checkpoint = checkpointer(def.onCheckpoint?.bind(def), args, binding, span);
+    const landed = (turn: number, messages: readonly AiMessage[], model: string) =>
+      checkpoint?.({
+        turn,
+        messages,
+        run: runTotal(model, prior?.usage, meter.total(), meter.below()),
+        compacted: compacting?.count() ?? prior?.compacted ?? 0,
+      });
     // Where a failure would resume from: the request in flight, and the turns answered so far.
     const at = { messages: [] as readonly AiMessage[], turns: prior?.turns ?? 0 };
     const loop = async (): Promise<InferOutput<TOutput>> => {
@@ -299,20 +336,16 @@ async function run<
         // budget, runs every remaining tool's side effects, and discards the answer.
         throwIfAborted(args.ctx);
         deadline.check();
-        // Before the request exists, never after a 400: a turn the window cannot take is
-        // compacted first, or refused (`X_AGENT_CONTEXT_EXHAUSTED`) without being sent.
+        // Before the request exists: a turn the window cannot take is compacted first, or refused
+        // (`X_AGENT_CONTEXT_EXHAUSTED`) without being sent. A provider that refuses it anyway
+        // gets one forced compaction and a re-send (`sendTurn`).
         if (compacting !== undefined) messages = await compacting.fit(messages, turn);
         at.messages = messages;
-        const request: GenerateRequest = { ...base, messages };
-        assertCost(request);
-        const result = await deadline
-          .guard(meter.call(gateway.generate(request)))
-          .catch((error: unknown) => {
-            // The caller left mid-call: the aborted socket reads as a provider failure, which is
-            // RETRYABLE. Say what happened instead.
-            throwIfAborted(args.ctx);
-            throw error;
-          });
+        const sent = await sendTurn(turnSend, messages, turn, (shorter) => {
+          at.messages = shorter;
+        });
+        messages = sent.messages;
+        const { result } = sent;
         at.turns = turn;
         const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
         // The same turn's `respond` calls, kept rather than forgotten: they are never RUN, but
@@ -335,6 +368,7 @@ async function run<
           ...(rejected === undefined ? {} : { repairOf: rejected }),
           run: runTotal(result.model, prior?.usage, meter.total(), meter.below()),
         });
+        if (result.text !== '') emit({ type: 'text', turn, text: result.text });
         assertAnswerable(result, name, base);
         // Before a tool runs and before the answer is read: a turn cut off at the ceiling carries
         // arguments that stop wherever the ceiling fell — `{}` on both wires for a call that never
@@ -361,6 +395,8 @@ async function run<
           // first cannot be paired with a slow tool's call.
           throwIfAborted(args.ctx);
           deadline.check();
+          for (const call of requested)
+            emit({ type: 'tool_call', turn, id: call.id, name: call.name });
           const results: readonly LlmToolResult[] = await deadline.guard(
             // Inside the deadline's scope, so each tool's own `ctx.signal` carries it.
             deadline.scope(() =>
@@ -370,6 +406,17 @@ async function run<
             ),
           );
           calls += requested.length;
+          results.forEach((done, index) => {
+            const name = requested[index]?.name ?? '';
+            emit({
+              type: 'tool_result',
+              turn,
+              id: done.toolUseId,
+              name,
+              isError: done.isError === true,
+            });
+          });
+          emit({ type: 'turn', turn, maxTurns });
           rejected = undefined;
           // Before the next turn is bought: the same calls with the same results cannot lead
           // anywhere a further turn would not also lead.
@@ -384,6 +431,7 @@ async function run<
             // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
             toolResultTurn(results, chars, answers, redact),
           ];
+          await landed(turn, messages, result.model);
           continue;
         }
 
@@ -407,9 +455,11 @@ async function run<
         }
         // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
         // turns left by construction — and unlike a tool result, the correction is the message.
+        emit({ type: 'turn', turn, maxTurns });
         rejected = formatIssues(parsed.issues);
         issues = rejected.join('; ');
         messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];
+        await landed(turn, messages, result.model);
       }
 
       at.messages = messages;

package/src/answer-errors.ts

@@ -1,7 +1,7 @@
 // The two failures of an answer that ARRIVED and cannot be used: cut off at the ceiling, or a tool
 // call whose arguments do not parse. Apart from ./errors only because one file has one job and
 // that catalogue is at its line ceiling — the split `hive-errors.ts` and `agent-errors.ts` made.
-// The codes, their titles and the single `registerErrorCodes` call stay in ./errors.
+// The codes, their titles and the single `registerErrorCodes` call stay in ./error-codes.
 
 import { UltimateError } from '@ultimat3/core';
 import type { Billed } from './billed';

package/src/anthropic-provider.ts

@@ -0,0 +1,291 @@
+// The Anthropic Messages API provider, streaming and not: `anthropicProvider()`, the request body,
+// the one `fetch` it sends, and `parseMessage` for a non-streamed answer. The shared shapes are
+// ./provider's; ./models owns the per-model rules and ./wire the streamed response half.
+
+import { assertMediaContent } from './content-blocks';
+import { providerFailure } from './context-overflow';
+import { costOf, exactCostOf } from './cost';
+import { detailOf, withoutKey } from './error-body';
+import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
+import type { AiFetch } from './fetch-seam';
+import { resolveModel } from './model-resolve';
+import type { ModelId } from './models';
+import { modelSpec, reasoningBody } from './models';
+import type { ProviderCacheRow, ProviderPromptCache } from './prompt-cache';
+import { promptCacheRule } from './prompt-cache';
+import { anthropicPrompt } from './prompt-cache-blocks';
+import { screenCacheRows } from './prompt-cache-rows';
+import type { GenerateRequest, GenerateResult, Provider, StreamChunk } from './provider';
+import { samplingBody } from './sampling';
+import { readSse } from './sse';
+import { assertToolArguments } from './tool-arguments';
+import type { LlmToolCall } from './tools';
+import {
+  asToolInput,
+  MessageStream,
+  parseStopDetails,
+  parseStopReason,
+  parseUsage,
+  throwInBandError,
+} from './wire';
+
+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;
+  /**
+   * What this endpoint does with a `cache_control` mark, when `PROMPT_CACHE_RULES` guesses wrong —
+   * a proxy that rejects the field: `{ rules: [{ model: '', marks: 'none', session: 'none' }] }`.
+   * Read before the table, first match by model prefix. This wire speaks `blocks` or `none`, and
+   * carries no session; 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;
+}
+
+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;
+  private readonly cacheRows: readonly ProviderCacheRow[];
+
+  // `| 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;
+    this.cacheRows = screenCacheRows('anthropic', config.promptCache);
+  }
+
+  /**
+   * 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(model, request, false);
+    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(model, request, true);
+    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, this.cacheRows).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(model: ModelId, request: GenerateRequest, stream: boolean): Promise<Response> {
+    const body = { ...this.body(request), stream };
+    const { signal } = request;
+    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) {
+      // 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 — 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),
+  };
+}

package/src/content-errors.ts

@@ -1,6 +1,6 @@
 // The X_AI_CONTENT_UNSUPPORTED class, apart from ./errors because that catalogue is at its ceiling —
 // the split `hive-errors.ts` and `eval-errors.ts` made. Its code and title are registered in
-// ./errors with the rest: one owner, one registration, one place a duplicate can surface.
+// ./error-codes with the rest: one owner, one registration, one place a duplicate can surface.
 
 import { UltimateError } from '@ultimat3/core';