@ultimat3/ai 1.2.0 → 2.0.0

package/src/openai-wire.ts

@@ -0,0 +1,339 @@
+// Single responsibility: reading what an OpenAI-format endpoint sends back — one chat completion,
+// and the SSE stream of the same answer arriving in pieces.
+//
+// Split from the provider for the reason wire.ts is: the assembler can then be driven frame by
+// frame with no socket, which is the only way to cover a stream that arrives fragmented, out of
+// order, or stops half way. An LLM response is untrusted input, so every field is parsed and
+// nothing is cast.
+
+import { AiTransportError } from './errors';
+import type { StopDetails, StopReason, StreamChunk, TokenUsage } from './provider';
+import type { SseFrame } from './sse';
+import type { LlmToolCall } from './tools';
+
+/**
+ * What one answer amounts to. `usage` is optional and that is the format's fault, not a laxity:
+ * a streamed answer reports usage only in a final chunk, and only when the request asked for it.
+ * The provider decides what to do with an absent one — never this file, which reports what arrived.
+ */
+export interface ChatAnswer {
+  readonly text: string;
+  readonly toolCalls: readonly LlmToolCall[];
+  readonly stopReason: StopReason;
+  readonly stopDetails: StopDetails | undefined;
+  readonly usage: TokenUsage | undefined;
+}
+
+const FINISH_REASONS: Readonly<Record<string, StopReason>> = {
+  stop: 'end_turn',
+  length: 'max_tokens',
+  tool_calls: 'tool_use',
+  // The legacy name for the same event; LiteLLM and older self-hosted servers still send it.
+  function_call: 'tool_use',
+  content_filter: 'refusal',
+};
+
+/**
+ * In-band error frames carry a type, not a status, and the gateway's retry rule reads a status.
+ * Same mapping job as wire.ts's, over this format's own vocabulary.
+ */
+const ERROR_STATUS: Readonly<Record<string, number>> = {
+  invalid_request_error: 400,
+  authentication_error: 401,
+  permission_error: 403,
+  not_found_error: 404,
+  rate_limit_exceeded: 429,
+  insufficient_quota: 429,
+  server_error: 500,
+  api_error: 500,
+  overloaded_error: 503,
+};
+
+/** A finish reason this format knows, or `undefined` for `null` — which means "still going". */
+export function parseFinishReason(raw: unknown): StopReason | undefined {
+  return typeof raw === 'string' ? FINISH_REASONS[raw] : undefined;
+}
+
+/**
+ * `usage`, or `undefined` when the payload carried none.
+ *
+ * `prompt_tokens` INCLUDES the cached prefix on this wire, where Anthropic's `input_tokens`
+ * excludes it — so the cached half is subtracted out before it is reported as `cacheReadTokens`.
+ * Left in place it would be billed twice: once at the full input rate and again at the cache rate.
+ */
+export function parseOpenAiUsage(raw: unknown): TokenUsage | undefined {
+  const record = asRecord(raw);
+  if (record === undefined) return undefined;
+  const prompt = numberOf(record['prompt_tokens']);
+  const completion = numberOf(record['completion_tokens']);
+  if (prompt === undefined && completion === undefined) return undefined;
+  const cached = numberOf(asRecord(record['prompt_tokens_details'])?.['cached_tokens']) ?? 0;
+  return {
+    inputTokens: Math.max((prompt ?? 0) - cached, 0),
+    // `completion_tokens` already contains `reasoning_tokens`; adding them is a double count.
+    outputTokens: completion ?? 0,
+    cacheReadTokens: cached,
+    // Caching is automatic here and carries no write surcharge, so there is nothing to report.
+    cacheWriteTokens: 0,
+  };
+}
+
+/** One non-streamed chat completion. Refusal is read BEFORE anything else trusts the content. */
+export function parseChatCompletion(raw: unknown, provider: string): ChatAnswer {
+  const record = asRecord(raw);
+  if (record === undefined) throw malformed(provider, 'the response body is not a JSON object');
+  throwInBandError(record, provider);
+  const choice = asRecord(Array.isArray(record['choices']) ? record['choices'][0] : undefined);
+  if (choice === undefined) throw malformed(provider, 'the response carried no choices');
+  const message = asRecord(choice['message']) ?? {};
+  const refusal = typeof message['refusal'] === 'string' ? message['refusal'] : undefined;
+  const finish = parseFinishReason(choice['finish_reason']);
+  return {
+    text: typeof message['content'] === 'string' ? message['content'] : '',
+    toolCalls: parseToolCalls(message['tool_calls'], provider),
+    // A refusal string is a refusal whatever the finish reason says: the field only ever appears
+    // when the model declined, and `stop` beside it would read downstream as an empty answer.
+    stopReason: refusal === undefined ? (finish ?? 'end_turn') : 'refusal',
+    stopDetails: refusalDetails(finish, refusal),
+    usage: parseOpenAiUsage(record['usage']),
+  };
+}
+
+function refusalDetails(
+  finish: StopReason | undefined,
+  refusal: string | undefined,
+): StopDetails | undefined {
+  if (refusal !== undefined) return { type: 'refusal', category: 'refusal', explanation: refusal };
+  if (finish !== 'refusal') return undefined;
+  // `content_filter` is all the endpoint says. Carried as the category rather than dropped: it is
+  // the only thing that distinguishes a policy stop from a model that chose not to answer.
+  return { type: 'refusal', category: 'content_filter', explanation: undefined };
+}
+
+function parseToolCalls(raw: unknown, provider: string): readonly LlmToolCall[] {
+  if (!Array.isArray(raw)) return [];
+  const calls: LlmToolCall[] = [];
+  for (const entry of raw) {
+    const record = asRecord(entry);
+    const fn = asRecord(record?.['function']);
+    if (record === undefined || fn === undefined) continue;
+    const name = typeof fn['name'] === 'string' ? fn['name'] : '';
+    if (name === '') continue;
+    calls.push({
+      id: typeof record['id'] === 'string' ? record['id'] : '',
+      name,
+      input: parseArguments(fn['arguments'], name, provider),
+    });
+  }
+  return calls;
+}
+
+/** Arguments are a JSON string. A tool that takes none sends `''` or `'{}'`; neither is a fault. */
+function parseArguments(raw: unknown, name: string, provider: string): Record<string, unknown> {
+  if (typeof raw !== 'string' || raw.trim() === '') return {};
+  try {
+    return asRecord(JSON.parse(raw)) ?? {};
+  } catch (error) {
+    throw malformed(
+      provider,
+      `tool "${name}" returned arguments that are not JSON: ${
+        error instanceof Error ? error.message : 'unreadable'
+      }`,
+    );
+  }
+}
+
+interface PendingCall {
+  id: string;
+  name: string;
+  args: string;
+}
+
+/**
+ * One streamed chat completion, assembled frame by frame.
+ *
+ * Two things this format does that the Anthropic one does not, and both are easy to get subtly
+ * wrong: a tool call arrives FRAGMENTED and INDEXED — its id, its name and successive slices of its
+ * arguments spread across chunks, keyed only by `tool_calls[].index` — and `usage` arrives once, in
+ * a trailing chunk whose `choices` array is empty, long after the finish reason.
+ */
+export class ChatCompletionStream {
+  private text = '';
+  private refusal = '';
+  private stopReason: StopReason = 'end_turn';
+  private finished = false;
+  private done = false;
+  private usage: TokenUsage | undefined;
+  private readonly pending = new Map<number, PendingCall>();
+  private readonly toolCalls: LlmToolCall[] = [];
+  private readonly provider: string;
+
+  constructor(provider: string) {
+    this.provider = provider;
+  }
+
+  /** Chunks this frame produced, in order. An unknown field yields nothing — the format grows. */
+  push(frame: SseFrame): readonly StreamChunk[] {
+    // The sentinel is not JSON, and parsing it is how a stream reader ends in a syntax error.
+    if (frame.data.trim() === '[DONE]') {
+      this.done = true;
+      return [];
+    }
+    const payload = this.payloadOf(frame);
+    throwInBandError(payload, this.provider);
+    const usage = parseOpenAiUsage(payload['usage']);
+    if (usage !== undefined) this.usage = usage;
+    const choice = asRecord(Array.isArray(payload['choices']) ? payload['choices'][0] : undefined);
+    if (choice === undefined) return [];
+    const chunks = this.onDelta(asRecord(choice['delta']) ?? {});
+    return [...chunks, ...this.onFinish(choice['finish_reason'])];
+  }
+
+  /** True once the answer is accounted for. False means the connection died mid-answer. */
+  isComplete(): boolean {
+    // Either sentinel counts. `[DONE]` is the format's own end marker, but plenty of servers in
+    // the family close the socket straight after the finish-reason chunk — and a finish reason IS
+    // the model saying why it stopped, which is the fact a truncated stream cannot produce.
+    return this.done || this.finished;
+  }
+
+  /** What the stream accumulated. `cost` is applied by the provider, which owns prices. */
+  state(): ChatAnswer {
+    const details = this.refusalDetails();
+    return {
+      text: this.text,
+      toolCalls: [...this.toolCalls],
+      // A refusal that arrived as a `refusal` delta finishes with `stop`, so the reason alone would
+      // read as a complete answer that happens to be empty.
+      stopReason: details === undefined ? this.stopReason : 'refusal',
+      stopDetails: details,
+      usage: this.usage,
+    };
+  }
+
+  private refusalDetails(): StopDetails | undefined {
+    if (this.refusal !== '') {
+      return { type: 'refusal', category: 'refusal', explanation: this.refusal };
+    }
+    return this.stopReason === 'refusal'
+      ? { type: 'refusal', category: 'content_filter', explanation: undefined }
+      : undefined;
+  }
+
+  private onDelta(delta: Record<string, unknown>): readonly StreamChunk[] {
+    const chunks: StreamChunk[] = [];
+    const content = delta['content'];
+    if (typeof content === 'string' && content !== '') {
+      this.text += content;
+      chunks.push({ type: 'text', text: content });
+    }
+    // `reasoning_content` is vLLM's and DeepSeek's; `reasoning` is the OpenRouter spelling. Neither
+    // is ever appended to `text`, for the reason thinking deltas are not: a consumer concatenating
+    // every chunk must not end up shipping the reasoning to the user.
+    const thinking = delta['reasoning_content'] ?? delta['reasoning'];
+    if (typeof thinking === 'string' && thinking !== '') {
+      chunks.push({ type: 'thinking', text: thinking });
+    }
+    const refusal = delta['refusal'];
+    if (typeof refusal === 'string') this.refusal += refusal;
+    this.accumulate(delta['tool_calls']);
+    return chunks;
+  }
+
+  /**
+   * Merge one chunk's tool-call fragments into the calls they belong to. `index` is the only key —
+   * `id` and `name` arrive on the first fragment and are absent from every later one, so appending
+   * by array position instead would build one call per chunk and lose every argument but the last.
+   */
+  private accumulate(raw: unknown): void {
+    if (!Array.isArray(raw)) return;
+    for (const entry of raw) {
+      const record = asRecord(entry);
+      if (record === undefined) continue;
+      const index = numberOf(record['index']) ?? 0;
+      const call = this.pending.get(index) ?? { id: '', name: '', args: '' };
+      const id = record['id'];
+      if (typeof id === 'string' && id !== '') call.id = id;
+      const fn = asRecord(record['function']);
+      const name = fn?.['name'];
+      // Concatenated, not assigned: a server that splits the name across two frames is rare and
+      // legal, and assigning would keep only the tail.
+      if (typeof name === 'string') call.name += name;
+      const args = fn?.['arguments'];
+      if (typeof args === 'string') call.args += args;
+      this.pending.set(index, call);
+    }
+  }
+
+  /**
+   * The finish reason closes the turn, and it is the only close this format has: there is no
+   * per-block stop event, so pending tool calls are emitted here — whole, in index order, exactly
+   * as the Anthropic path emits them at `content_block_stop`. A fragment is never a call.
+   */
+  private onFinish(raw: unknown): readonly StreamChunk[] {
+    const reason = parseFinishReason(raw);
+    if (reason === undefined) return [];
+    this.stopReason = reason;
+    this.finished = true;
+    const chunks: StreamChunk[] = [];
+    for (const index of [...this.pending.keys()].sort((a, b) => a - b)) {
+      const pending = this.pending.get(index);
+      if (pending === undefined || pending.name === '') continue;
+      const call: LlmToolCall = {
+        id: pending.id,
+        name: pending.name,
+        input: parseArguments(pending.args, pending.name, this.provider),
+      };
+      this.toolCalls.push(call);
+      chunks.push({ type: 'tool-call', call });
+    }
+    this.pending.clear();
+    return chunks;
+  }
+
+  private payloadOf(frame: SseFrame): Record<string, unknown> {
+    try {
+      const record = asRecord(JSON.parse(frame.data));
+      if (record === undefined) throw new SyntaxError('frame data is not an object');
+      return record;
+    } catch (error) {
+      throw malformed(
+        this.provider,
+        `unreadable "${frame.event}" frame: ${
+          error instanceof Error ? error.message : 'unreadable'
+        }`,
+      );
+    }
+  }
+}
+
+/**
+ * A 200 that carries 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. Parsed as a message it would read as an
+ * empty, successful answer, which is the one outcome nothing downstream can detect.
+ */
+function throwInBandError(payload: Record<string, unknown>, provider: string): void {
+  const error = asRecord(payload['error']);
+  if (error === undefined) return;
+  const type = typeof error['type'] === 'string' ? error['type'] : 'api_error';
+  const code = typeof error['code'] === 'string' ? error['code'] : undefined;
+  const message = typeof error['message'] === 'string' ? error['message'] : type;
+  throw new AiTransportError({
+    provider,
+    status: ERROR_STATUS[type] ?? (code === undefined ? undefined : ERROR_STATUS[code]) ?? 500,
+    detail: message,
+  });
+}
+
+function malformed(provider: string, detail: string): AiTransportError {
+  return new AiTransportError({ provider, detail });
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function numberOf(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/src/pg-vector-sql.ts

@@ -45,7 +45,11 @@ export function conditionsSql(scope: VectorScope, filter?: MetadataFilter): SqlF
 }
 
 /**
- * `x db gen` emits this. The primary key is `(tenant, id)`, not `id`: it makes a cross-tenant
+ * The store's whole schema as one string, for an app to split across migration files. **No
+ * command emits it** — `x db gen` diffs `describeEntities()` and a vector store is not an
+ * `entity()`, so no CLI file references this at all.
+ *
+ * The primary key is `(tenant, id)`, not `id`: it makes a cross-tenant
  * overwrite impossible at the storage layer instead of relying on every upsert remembering to
  * check. An unscoped store writes the empty tenant, which is a tenant like any other.
  */

package/src/pg-vector.ts

@@ -63,7 +63,8 @@ export class PgVectorStore implements VectorStore {
     };
   }
 
-  /** `x db gen` emits this; kept next to the queries so the index choice is reviewable. */
+  /** An app pastes this into migrations — no command emits it. Beside the queries so the index
+   * choice is reviewable against the reads that depend on it. */
   ddl(): string {
     return ddlSql(this.target);
   }

package/src/prompt.ts

@@ -24,7 +24,7 @@ export interface DefinePromptInput<V extends PromptVars> {
   readonly template: string;
   /** Optional system prompt. Part of the hash — it changes behaviour. */
   readonly system?: string;
-  /** Schema of the variables, for the manifest and for `x ai prompts`. */
+  /** Schema of the variables, for the manifest. */
   readonly input?: JsonSchema;
   /** Expected output shape, fed to `output_config.format` when the caller opts in. */
   readonly output?: JsonSchema;

package/src/provider.ts

@@ -4,16 +4,63 @@
 // catalogue and the per-model rules, ./wire owns the response half.
 
 import type { Money } from '@ultimat3/money';
+import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiTransportError } from './errors';
 import type { Effort, ModelId, ThinkingMode } from './models';
-import { DEFAULT_MODEL, MODEL_IDS, MODELS, reasoningBody } from './models';
+import { ANTHROPIC_MODEL_IDS, DEFAULT_MODEL, modelIds, modelSpec, reasoningBody } from './models';
 import { readSse } from './sse';
 import type { LlmTool, LlmToolCall } from './tools';
-import { MessageStream, parseStopDetails, parseStopReason, parseUsage } from './wire';
+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
+ * legal; blocks exist because a tool loop cannot be expressed without them — a `tool_result` has
+ * to name the `tool_use` it answers, and a string has nowhere to put the id.
+ *
+ * The field names are the Messages API's, not a translated set, so `body()` passes a block
+ * through untouched. A second vocabulary here would be a mapping table to keep in step with a
+ * wire format we do not own.
+ */
+export type AiContentBlock =
+  | { readonly type: 'text'; readonly text: string }
+  | {
+      readonly type: 'tool_use';
+      readonly id: string;
+      readonly name: string;
+      readonly input: Record<string, unknown>;
+    }
+  | {
+      readonly type: 'tool_result';
+      readonly tool_use_id: string;
+      readonly content: string;
+      readonly is_error?: boolean;
+    };
 
 export interface AiMessage {
   readonly role: 'user' | 'assistant';
-  readonly content: string;
+  readonly content: string | readonly AiContentBlock[];
+}
+
+/**
+ * The readable text of a message, blocks flattened. For ESTIMATING and for the echo provider —
+ * never for building a request, which sends `content` as it stands.
+ */
+export function messageText(message: AiMessage): string {
+  if (typeof message.content === 'string') return message.content;
+  return message.content
+    .map((block) => {
+      if (block.type === 'text') return block.text;
+      if (block.type === 'tool_result') return block.content;
+      return JSON.stringify(block.input);
+    })
+    .join(' ');
 }
 
 export interface GenerateRequest {
@@ -61,6 +108,14 @@ export interface StopDetails {
 
 export interface GenerateResult {
   readonly model: ModelId;
+  /**
+   * Which provider actually answered. Stamped by the GATEWAY, not by the provider: falling back
+   * from one provider to the next is a gateway concept, and a `Provider` implementation an app
+   * wrote cannot be asked to report on a decision it did not make. Optional for exactly that
+   * reason — a provider's own result has not been through the router yet. `llm()` puts it on the
+   * span as `llm.provider`, which is what makes a fallback visible rather than silent.
+   */
+  readonly provider?: string;
   readonly text: string;
   readonly toolCalls: readonly LlmToolCall[];
   readonly stopReason: StopReason;
@@ -91,7 +146,7 @@ export interface Provider {
  * away is money the framework silently absorbs, and under-reporting spend defeats a budget.
  */
 export function costOf(model: ModelId, usage: TokenUsage): Money {
-  const spec = MODELS[model];
+  const spec = modelSpec(model);
   // Cache reads are ~0.1x input; cache writes ~1.25x. Scaled by 10 to stay integral.
   const inputUnits =
     usage.inputTokens * 10 + usage.cacheReadTokens * 1 + Math.ceil(usage.cacheWriteTokens * 12.5);
@@ -121,8 +176,6 @@ export interface AnthropicProviderInput {
 
 const ANTHROPIC_VERSION = '2023-06-01';
 const API_KEY_ENV = 'ANTHROPIC_API_KEY';
-/** Enough of an error body to name the field that was wrong, not enough to fill a log. */
-const DETAIL_LIMIT = 300;
 
 /**
  * Above this ceiling a non-streaming request sits on an open socket past the HTTP timeout and
@@ -134,7 +187,7 @@ 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 = request.model ?? DEFAULT_MODEL;
-  return Math.min(request.maxTokens, MODELS[model].maxOutput) > STREAM_ONLY_MAX_TOKENS;
+  return Math.min(request.maxTokens, modelSpec(model).maxOutput) > STREAM_ONLY_MAX_TOKENS;
 }
 
 /**
@@ -146,7 +199,8 @@ export function requiresStreaming(request: GenerateRequest): boolean {
  */
 export class AnthropicProvider implements Provider {
   readonly name = 'anthropic';
-  readonly models = MODEL_IDS;
+  /** Its own list, never the registry's: an app's internal model must not be routed here. */
+  readonly models: readonly ModelId[] = ANTHROPIC_MODEL_IDS;
   private readonly config: AnthropicProviderInput;
 
   constructor(config: AnthropicProviderInput = {}) {
@@ -217,7 +271,7 @@ export class AnthropicProvider implements Provider {
     const model = request.model ?? DEFAULT_MODEL;
     const body: Record<string, unknown> = {
       model,
-      max_tokens: Math.min(request.maxTokens, MODELS[model].maxOutput),
+      max_tokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
       messages: request.messages.map((m) => ({ role: m.role, content: m.content })),
       ...reasoningBody(model, request.effort, request.thinking),
     };
@@ -253,33 +307,24 @@ export class AnthropicProvider implements Provider {
       throw new AiTransportError({
         provider: this.name,
         status: response.status,
-        detail: await detailOf(response),
+        // 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;
   }
 }
 
-/** The provider's own message, when it sent one — it names the offending field, we name the fix. */
-async function detailOf(response: Response): Promise<string> {
-  const body = await response.text().catch(() => '');
-  try {
-    const parsed: unknown = JSON.parse(body);
-    if (typeof parsed === 'object' && parsed !== null) {
-      const error = (parsed as Record<string, unknown>)['error'];
-      if (typeof error === 'object' && error !== null) {
-        const message = (error as Record<string, unknown>)['message'];
-        if (typeof message === 'string') return message.slice(0, DETAIL_LIMIT);
-      }
-    }
-  } catch {
-    // Not JSON — a proxy or a gateway timeout page. The raw text is still the best evidence.
-  }
-  return body === '' ? response.statusText : body.slice(0, DETAIL_LIMIT);
-}
-
 /** 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[] = [];
@@ -291,17 +336,24 @@ export function parseMessage(model: ModelId, raw: Record<string, unknown>): Gene
       toolCalls.push({
         id: b['id'],
         name: b['name'],
-        input: (b['input'] ?? {}) as Record<string, unknown>,
+        // 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,
-    stopReason: parseStopReason(raw['stop_reason']),
-    stopDetails: parseStopDetails(raw['stop_details']),
+    // 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),
   };
@@ -324,7 +376,14 @@ export interface EchoProviderInput {
  */
 export class EchoProvider implements Provider {
   readonly name = 'echo';
-  readonly models = MODEL_IDS;
+  /**
+   * A getter over the whole registry, not a snapshot: the test double has to serve whatever the
+   * test registered, and a field read at construction time would miss a model registered after.
+   */
+  get models(): readonly ModelId[] {
+    return modelIds();
+  }
+
   private readonly config: EchoProviderInput;
 
   constructor(config: EchoProviderInput = {}) {
@@ -365,7 +424,7 @@ export class EchoProvider implements Provider {
 function lastUserMessage(messages: readonly AiMessage[]): string {
   for (let i = messages.length - 1; i >= 0; i -= 1) {
     const message = messages[i];
-    if (message !== undefined && message.role === 'user') return message.content;
+    if (message !== undefined && message.role === 'user') return messageText(message);
   }
   return '';
 }
@@ -381,7 +440,7 @@ export function estimateTokens(request: GenerateRequest): number {
 
 /** The prompt half alone — what the provider bills at the input rate. */
 export function estimateInputTokens(request: GenerateRequest): number {
-  const body = request.messages.map((m) => m.content).join(' ');
+  const body = request.messages.map(messageText).join(' ');
   return estimateTextTokens(body) + estimateTextTokens(request.system ?? '');
 }
 
@@ -394,7 +453,7 @@ export function estimateCost(request: GenerateRequest): Money {
   const model = request.model ?? DEFAULT_MODEL;
   return costOf(model, {
     inputTokens: estimateInputTokens(request),
-    outputTokens: Math.min(request.maxTokens, MODELS[model].maxOutput),
+    outputTokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
   });

package/src/rag.ts

@@ -156,6 +156,28 @@ export interface AssembledContext {
   readonly dropped: readonly string[];
 }
 
+const BLOCK_OPEN = '<document id=';
+const BLOCK_CLOSE = '</document>';
+
+/**
+ * One retrieved document, fenced and labelled with the id it came from. A bare separator was not
+ * a boundary: it is a string a document can simply contain, and the assembled text lands in the
+ * `user` message indistinguishable from the author's own instructions — while a tool RESULT
+ * carries provenance and this carried none. So the fence is neutralised inside the payload, the
+ * shape `cdata()` uses in `@ultimat3/seo`'s `xml.ts`: the marker is broken, never deleted, so the
+ * model still reads every word the document actually said.
+ *
+ * Influence only, and deliberately not sold as more: the actor is `ctx.actor` and tool dispatch is
+ * matched against `def.tools`, so retrieved text can persuade a model and can never authorise it.
+ */
+function documentBlock(id: string, text: string): string {
+  const label = id.replaceAll('"', "'").replaceAll('>', ')').replaceAll('<', '(');
+  const body = text
+    .replaceAll(BLOCK_CLOSE, '<\\/document>')
+    .replaceAll(BLOCK_OPEN, '<\\document id=');
+  return `${BLOCK_OPEN}"${label}">\n${body}\n${BLOCK_CLOSE}`;
+}
+
 /**
  * Fill a context window in rank order until the budget is reached. Skips oversized hits
  * rather than stopping, so one long chunk does not starve every shorter one behind it.
@@ -163,9 +185,10 @@ export interface AssembledContext {
 export function assembleContext(input: {
   readonly hits: readonly SearchHit[];
   readonly maxTokens: number;
+  /** Between BLOCKS, never inside one — the block fence is what separates documents. */
   readonly separator?: string;
 }): AssembledContext {
-  const separator = input.separator ?? '\n\n---\n\n';
+  const separator = input.separator ?? '\n\n';
   const separatorTokens = estimateChunkTokens(separator);
   const parts: string[] = [];
   const used: string[] = [];
@@ -173,12 +196,13 @@ export function assembleContext(input: {
   let tokens = 0;
 
   for (const hit of input.hits) {
-    const cost = estimateChunkTokens(hit.text) + (parts.length === 0 ? 0 : separatorTokens);
+    const block = documentBlock(hit.id, hit.text);
+    const cost = estimateChunkTokens(block) + (parts.length === 0 ? 0 : separatorTokens);
     if (tokens + cost > input.maxTokens) {
       dropped.push(hit.id);
       continue;
     }
-    parts.push(hit.text);
+    parts.push(block);
     used.push(hit.id);
     tokens += cost;
   }