@ultimat3/ai 23.0.0 → 25.0.0

package/src/provider.ts

@@ -1,14 +1,17 @@
-// The `Provider` interface, its two implementations — `AnthropicProvider` (the real Messages API,
-// streaming and not) and `EchoProvider` (deterministic, for tests and `x dev` without a key) —
-// and the money arithmetic over a call's reported usage. The REQUEST half only: ./models owns the
-// catalogue and the per-model rules, ./wire owns the response half.
+// The `Provider` interface, `AnthropicProvider` (the real Messages API, streaming and not) and
+// the money arithmetic over a call's reported usage — `EchoProvider`, the double, is
+// ./echo-provider's. The REQUEST half only: ./models owns the catalogue and the per-model rules,
+// ./wire owns the response half.
 
 import type { Money } from '@ultimat3/money';
+import type { AiMediaBlock } from './content-blocks';
+import { assertMediaContent, blockText, mediaTokenEstimate } from './content-blocks';
 import { detailOf, withoutKey } from './error-body';
-import { AiKeyMissingError, AiTransportError } from './errors';
+import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
 import type { AiFetch } from './fetch-seam';
+import { resolveModel } from './model-resolve';
 import type { Effort, ModelId, ThinkingMode } from './models';
-import { ANTHROPIC_MODEL_IDS, DEFAULT_MODEL, modelIds, modelSpec, reasoningBody } from './models';
+import { modelSpec, reasoningBody } from './models';
 import { readSse } from './sse';
 import type { LlmTool, LlmToolCall } from './tools';
 import {
@@ -23,7 +26,8 @@ import {
 /**
  * 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.
+ * to name the `tool_use` it answers, and a string has nowhere to put the id — and because an image
+ * or a PDF is not a string at all (`./content-blocks` owns those two and screens them).
  *
  * 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
@@ -42,7 +46,8 @@ export type AiContentBlock =
       readonly tool_use_id: string;
       readonly content: string;
       readonly is_error?: boolean;
-    };
+    }
+  | AiMediaBlock;
 
 export interface AiMessage {
   readonly role: 'user' | 'assistant';
@@ -55,13 +60,7 @@ export interface AiMessage {
  */
 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(' ');
+  return message.content.map(blockText).join(' ');
 }
 
 export interface GenerateRequest {
@@ -77,7 +76,7 @@ export interface GenerateRequest {
   /**
    * The caller's abort signal, forwarded to the socket by every provider in this package.
    *
-   * Deliberately absent from `cacheKeyFor` and from every estimate: it says whether a request was
+   * Deliberately absent from `promptCacheKey` and from every estimate: it says whether a request was
    * ABANDONED, never what it asked for, so two calls that differ only in it are the same call and
    * must share a cache entry. Omitted means the call runs to completion — there is no ambient
    * default, because a timeout the caller did not ask for is a truncated answer nothing reports.
@@ -162,11 +161,20 @@ 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 {
+  // The one price lookup: a model the app never `registerModel`-ed is `X_AI_MODEL_UNKNOWN` here,
+  // so no call is priced — and no budget reserved — against a number nobody chose.
   const spec = modelSpec(model);
-  // Cache reads are ~0.1x input; cache writes ~1.25x. Scaled by 10 to stay integral.
+  const input = spec.inputPerMillion.minor;
+  // In TWENTIETHS of a minor unit, so the standard multipliers stay integral on any whole price:
+  // a cache read is 0.1x input (2/20) and a 5-minute write 1.25x (25/20) unless the row states
+  // its own — Opus 5.5 reads at 0.05x and Fable 5.1 at 0.025x, which a fixed 0.1x overstated.
+  const read =
+    spec.cacheReadPerMillion === undefined ? input * 2 : spec.cacheReadPerMillion.minor * 20;
+  const write =
+    spec.cacheWritePerMillion === undefined ? input * 25 : spec.cacheWritePerMillion.minor * 20;
   const inputUnits =
-    usage.inputTokens * 10 + usage.cacheReadTokens * 1 + Math.ceil(usage.cacheWriteTokens * 12.5);
-  const inputMinor = divideCeil(inputUnits * spec.inputPerMillion.minor, 10_000_000);
+    usage.inputTokens * input * 20 + usage.cacheReadTokens * read + usage.cacheWriteTokens * write;
+  const inputMinor = divideCeil(inputUnits, 20_000_000);
   const outputMinor = divideCeil(usage.outputTokens * spec.outputPerMillion.minor, 1_000_000);
   return { minor: inputMinor + outputMinor, currency: spec.inputPerMillion.currency };
 }
@@ -183,6 +191,12 @@ export function totalTokens(usage: TokenUsage): number {
 // ── 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;
@@ -202,10 +216,15 @@ 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;
+  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:
@@ -215,14 +234,34 @@ export function requiresStreaming(request: GenerateRequest): boolean {
  */
 export class AnthropicProvider implements Provider {
   readonly name = 'anthropic';
-  /** Its own list, never the registry's: an app's internal model must not be routed here. */
-  readonly models: readonly ModelId[] = ANTHROPIC_MODEL_IDS;
+  /** 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;
 
-  constructor(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()`
@@ -231,10 +270,11 @@ export class AnthropicProvider implements Provider {
    * the same caller either way.
    */
   async generate(request: GenerateRequest): Promise<GenerateResult> {
-    if (requiresStreaming(request)) return this.assemble(request);
+    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(request.model ?? DEFAULT_MODEL, raw);
+    return parseMessage(model, raw);
   }
 
   /** Drive `stream()` to its `done` chunk. It throws on a cut stream, so a partial never lands. */
@@ -254,7 +294,7 @@ export class AnthropicProvider implements Provider {
    * result, so a consumer that only wants the answer can ignore every chunk before it.
    */
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
-    const model = request.model ?? DEFAULT_MODEL;
+    const model = this.modelOf(request);
     const response = await this.send({ ...this.body(request), stream: true }, request.signal);
     if (response.body === null) {
       throw new AiTransportError({
@@ -272,7 +312,8 @@ export class AnthropicProvider implements Provider {
     if (!message.isComplete()) {
       throw new AiTransportError({
         provider: this.name,
-        detail: 'the stream ended before message_stop — the answer is truncated',
+        detail:
+          'the stream ended before message_stop, or with a tool call still open — the answer is truncated',
       });
     }
     const state = message.state();
@@ -284,7 +325,9 @@ export class AnthropicProvider implements Provider {
 
   /** The request body. Pure and side-effect free so a test can assert it directly. */
   body(request: GenerateRequest): Record<string, unknown> {
-    const model = request.model ?? DEFAULT_MODEL;
+    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 body: Record<string, unknown> = {
       model,
       max_tokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
@@ -381,100 +424,23 @@ export function parseMessage(model: ModelId, raw: Record<string, unknown>): Gene
   };
 }
 
-// ── Echo ─────────────────────────────────────────────────────────────────────
-
-export interface EchoProviderInput {
-  /** Fixed replies keyed by the last user message, for eval fixtures. */
-  readonly replies?: Readonly<Record<string, string>>;
-  /** Fallback when no key matches. Defaults to echoing the last user message. */
-  readonly fallback?: (prompt: string) => string;
-  readonly tokensPerCall?: number;
-}
-
-/**
- * Deterministic provider. Same input, same output, same usage — which is what makes an eval
- * suite a test rather than a sample. Token counts are derived from length, so a budget test
- * can assert a refusal without a network.
- */
-export class EchoProvider implements Provider {
-  readonly name = 'echo';
-  /**
-   * 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 = {}) {
-    this.config = config;
-  }
-
-  async generate(request: GenerateRequest): Promise<GenerateResult> {
-    const model = request.model ?? DEFAULT_MODEL;
-    const prompt = lastUserMessage(request.messages);
-    const text = this.fixedReply(prompt) ?? this.config.fallback?.(prompt) ?? prompt;
-    const usage: TokenUsage = {
-      inputTokens: this.config.tokensPerCall ?? estimateTokens(request),
-      outputTokens: estimateTextTokens(text),
-      cacheReadTokens: 0,
-      cacheWriteTokens: 0,
-    };
-    return {
-      model,
-      text,
-      toolCalls: [],
-      stopReason: 'end_turn',
-      stopDetails: undefined,
-      usage,
-      cost: costOf(model, usage),
-    };
-  }
-
-  /**
-   * The fixture reply for this prompt. `Object.hasOwn`, never `replies?.[prompt]`: the key is
-   * MESSAGE TEXT, so a prompt of `toString` read a function off the prototype chain and returned
-   * it as the model's answer — a double that answers with JS source is worse than one that cannot.
-   */
-  private fixedReply(prompt: string): string | undefined {
-    const { replies } = this.config;
-    if (replies === undefined || !Object.hasOwn(replies, prompt)) return undefined;
-    return replies[prompt];
-  }
-
-  async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
-    const result = await this.generate(request);
-    // One word per chunk: enough to exercise a consumer's assembly logic.
-    for (const word of result.text.split(' ')) {
-      if (word !== '') yield { type: 'text', text: `${word} ` };
-    }
-    yield { type: 'done', result };
-  }
-}
-
-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 messageText(message);
-  }
-  return '';
-}
-
 /**
- * ~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 the real
- * count from `usage` replaces it afterwards.
+ * ~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.
+ * The completion is clamped to what the model can write, exactly as `estimateCost` clamps it.
  */
 export function estimateTokens(request: GenerateRequest): number {
-  return estimateInputTokens(request) + request.maxTokens;
+  return estimateInputTokens(request) + completionCeiling(request);
 }
 
+const completionCeiling = (request: GenerateRequest): number =>
+  Math.min(request.maxTokens, modelSpec(resolveModel('provider', request.model)).maxOutput);
+
 /** The prompt half alone — what the provider bills at the input rate. */
 export function estimateInputTokens(request: GenerateRequest): number {
   const body = request.messages.map(messageText).join(' ');
-  return estimateTextTokens(body) + estimateTextTokens(request.system ?? '');
+  const text = estimateTextTokens(body) + estimateTextTokens(request.system ?? '');
+  return text + mediaTokenEstimate(request.messages);
 }
 
 /**
@@ -483,10 +449,9 @@ export function estimateInputTokens(request: GenerateRequest): number {
  * optimistic estimate is a ceiling one long completion walks through.
  */
 export function estimateCost(request: GenerateRequest): Money {
-  const model = request.model ?? DEFAULT_MODEL;
-  return costOf(model, {
+  return costOf(resolveModel('provider', request.model), {
     inputTokens: estimateInputTokens(request),
-    outputTokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
+    outputTokens: completionCeiling(request),
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
   });

package/src/rag.ts

@@ -7,6 +7,7 @@
 import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { embedBatched, embedOne } from './embeddings';
+import { neutraliseFences } from './prompt-fence';
 import { estimateTextTokens as estimateChunkTokens } from './provider';
 import type { SearchHit, VectorStore } from './vector';
 
@@ -31,7 +32,7 @@ export interface ChunkInput {
  * Token-aware chunker. Splits on paragraph, then sentence, then hard-wraps — so a chunk
  * boundary lands at a meaning boundary whenever one is available within the budget.
  */
-export function chunk(input: ChunkInput): readonly Chunk[] {
+export function chunkDocument(input: ChunkInput): readonly Chunk[] {
   // Floored at one token: `size: 0` makes every comparison below meaningless and the wrap's cut
   // point zero-width, which is a loop that never advances rather than a chunker that produces
   // nothing. A budget under one token is not a budget.
@@ -56,7 +57,9 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
         id: `${input.id}#${chunks.length}`,
         text,
         tokens: estimateChunkTokens(text),
-        metadata: { source: input.id, ...(input.metadata ?? {}) },
+        // Written AFTER the spread: `source` is the framework's stamp, and `indexDocument` prunes by
+        // it — a caller's own `source` replaced it, and a re-index pruned the wrong rows or none.
+        metadata: { ...(input.metadata ?? {}), source: input.id },
       });
     }
     // Carry the tail forward as the overlap for the next chunk — at most every unit BUT THE
@@ -78,6 +81,11 @@ export function chunk(input: ChunkInput): readonly Chunk[] {
   for (const unit of units) {
     const unitTokens = estimateChunkTokens(unit);
     if (tokens + unitTokens > size && buffer.length > 0) flush();
+    // The carried overlap yields to the unit, oldest first: a carry the unit does not fit beside
+    // made a chunk past `size` — the one promise this function makes.
+    while (buffer.length > 0 && tokens + unitTokens > size) {
+      tokens -= estimateChunkTokens(buffer.shift() ?? '');
+    }
     buffer.push(unit);
     tokens += unitTokens;
   }
@@ -158,14 +166,14 @@ function cutToBudget(run: string, size: number): readonly string[] {
  * Index a document: chunk, embed, upsert, prune. One call so no step is skipped by accident. The
  * prune is what re-indexing a SHORTER document needs: chunk ids are `<doc>#<n>`, so the upsert
  * overwrote the first chunks and left the old tail retrievable. Upsert first, prune after, so the
- * document is never absent from a search in between. A store without `prune` cannot clean up.
+ * document is never absent from a search in between.
  */
 export async function indexDocument(input: {
   readonly store: VectorStore;
   readonly embedder: Embedder;
   readonly document: ChunkInput;
 }): Promise<readonly Chunk[]> {
-  const chunks = chunk(input.document);
+  const chunks = chunkDocument(input.document);
   const vectors = await embedBatched(
     input.embedder,
     chunks.map((c) => c.text),
@@ -181,8 +189,8 @@ export async function indexDocument(input: {
       metadata: c.metadata,
     })),
   );
-  // `source` is the chunker's own stamp (`chunk()`), so only THIS document's rows are touched.
-  await input.store.prune?.(
+  // `source` is the chunker's own stamp (`chunkDocument()`), so only THIS document's rows are touched.
+  await input.store.prune(
     { source: input.document.id },
     chunks.map((c) => c.id),
   );
@@ -255,9 +263,9 @@ const BLOCK_CLOSE = '</document>';
  */
 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=');
+  // The closer through the one neutraliser `render` uses (any case, any whitespace, whatever
+  // follows the name); the opener is broken here, because a forged label is this fence's alone.
+  const body = neutraliseFences(text, ['document']).replaceAll(BLOCK_OPEN, '<\\document id=');
   return `${BLOCK_OPEN}"${label}">\n${body}\n${BLOCK_CLOSE}`;
 }
 

package/src/remote-embedder.ts

@@ -8,7 +8,8 @@
 
 import { finiteCount, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
-import { normalize } from './embeddings';
+import { normalizeVector } from './embeddings';
+import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
 import type { AiFetch } from './fetch-seam';
 
@@ -16,7 +17,6 @@ const API_KEY_ENV = 'EMBEDDINGS_API_KEY';
 const DEFAULT_BASE_URL = 'https://api.voyageai.com/v1';
 /** Providers cap a batch around 128 inputs; 96 leaves headroom for long texts. */
 const DEFAULT_BATCH_SIZE = 96;
-const DETAIL_LIMIT = 300;
 /**
  * A hosted endpoint is a third party and `baseUrl` is app config, so neither its latency nor its
  * response size is ours to assume. 30s is longer than any healthy embedding batch and shorter than
@@ -50,6 +50,11 @@ export interface RemoteEmbedderInput {
   readonly fetch?: AiFetch;
 }
 
+/** An HTTP embeddings endpoint — the one way to build one; the class is a type only. */
+export function remoteEmbedder(input: RemoteEmbedderInput): RemoteEmbedder {
+  return new RemoteEmbedder(input);
+}
+
 export class RemoteEmbedder implements Embedder {
   readonly name: string;
   readonly dimension: number;
@@ -124,7 +129,7 @@ export class RemoteEmbedder implements Embedder {
         // and the endpoint is app config, so the rejection is a value this package did not build —
         // and `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap, whose throw escapes this very
         // `catch` and replaces a coded refusal with an uncoded crash.
-        detail: `${renderThrowable(error)} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
+        detail: `${withoutKey(renderThrowable(error), apiKey)} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
         envVar: API_KEY_ENV,
       });
     }
@@ -132,7 +137,9 @@ export class RemoteEmbedder implements Embedder {
       throw new AiTransportError({
         provider: this.name,
         status: response.status,
-        detail: await detailOf(response.body),
+        // The shared reader and the shared scrub: a proxy echoing the bearer header into its 4xx
+        // body put the key into an error that reaches a log, a span and a problem document.
+        detail: withoutKey(await detailOf(response), apiKey),
         envVar: API_KEY_ENV,
       });
     }
@@ -180,9 +187,9 @@ export class RemoteEmbedder implements Embedder {
   }
 
   /**
-   * L2 normalised on the way in, like every other embedder here, so `cosine` stays a dot
-   * product. Providers already return unit vectors, which makes this a no-op — but "already"
-   * is a property of today's provider, not of the interface.
+   * L2 normalised on the way in, like every other embedder here, so a vector's scale is never the
+   * provider's choice. Providers already return unit vectors, which makes this a no-op — but
+   * "already" is a property of today's provider, not of the interface.
    */
   private vectorOf(raw: unknown, position: number): Float32Array {
     if (!Array.isArray(raw))
@@ -202,7 +209,7 @@ export class RemoteEmbedder implements Embedder {
       }
       vector[i] = value;
     }
-    return normalize(vector);
+    return normalizeVector(vector);
   }
 
   private malformed(detail: string): AiTransportError {
@@ -218,36 +225,3 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 function countOf(data: unknown): string {
   return Array.isArray(data) ? String(data.length) : 'no data array';
 }
-
-/**
- * The start of an error body, and never more. `response.text()` read it WHOLE — outside
- * `maxResponseBytes`, which bounds a success only — so a provider streaming an endless 5xx body
- * held the call and its memory forever. Capped through the same counting reader, and decoded from
- * the bytes it kept: `over` still has a detail worth showing.
- */
-async function detailOf(body: ReadableStream<Uint8Array> | null): Promise<string> {
-  if (body === null) return '';
-  const reader = body.getReader();
-  const kept: Uint8Array[] = [];
-  let total = 0;
-  try {
-    while (total < DETAIL_LIMIT) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      kept.push(value);
-      total += value.byteLength;
-    }
-  } catch {
-    // A body that fails mid-read still has whatever arrived; the status is the error's substance.
-  } finally {
-    await reader.cancel().catch(() => undefined);
-    reader.releaseLock();
-  }
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of kept) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return new TextDecoder().decode(bytes).slice(0, DETAIL_LIMIT);
-}

package/src/respond.ts

@@ -0,0 +1,86 @@
+// The `respond` tool an `llm()` / `agent()` answers through, and the reader that gets the answer
+// back out of a turn: the tool call's arguments, or the prose parsed as JSON. One file so the
+// envelope a non-object `output` is wrapped in and its unwrapping cannot drift apart.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { toWireSchema } from '@ultimat3/schema';
+import type { GenerateResult } from './provider';
+import type { LlmTool } from './tools';
+
+/**
+ * The tool the model answers through. One name, so the reader never has to guess — and shared
+ * with `agent()`, which offers the app's tools alongside it and needs the same name to tell an
+ * answer from a tool call.
+ */
+export const RESPOND = 'respond';
+
+/** The one property a non-object `output` travels under. */
+const ENVELOPE = 'value';
+
+/** The tool for one `output`, and the reader that undoes whatever the tool did to it. */
+export interface Respond {
+  readonly tool: LlmTool;
+  /** The answer in `result`, unwrapped — or `undefined` when there is none to validate. */
+  read(result: GenerateResult): unknown;
+}
+
+/**
+ * The output schema as the only tool the model may answer through — the spec's "structured
+ * output drives tool use". `toWireSchema` is the projection an MCP client is served, so a model
+ * and an agent are shown one shape, and a schema it cannot express throws HERE, at declaration
+ * time.
+ *
+ * A tool's `input_schema` must be an OBJECT, so any other `output` (`t.string`, `t.number`, an
+ * array) is wrapped in `{ value }` and unwrapped on the way back — never refused: `.stream()` is
+ * documented for `output: t.string`, and the same declaration must work called plainly.
+ */
+export function respondFor(output: StandardSchemaV1): Respond {
+  const schema = toWireSchema(output);
+  const wrapped = schema.type !== 'object';
+  return {
+    tool: {
+      name: RESPOND,
+      description: 'Return the result. Call this exactly once; do not answer in prose.',
+      input_schema: wrapped
+        ? {
+            type: 'object',
+            properties: { [ENVELOPE]: schema },
+            required: [ENVELOPE],
+            additionalProperties: false,
+          }
+        : schema,
+      strict: true,
+    },
+    read(result) {
+      const call = result.toolCalls.find((c) => c.name === RESPOND);
+      if (call !== undefined) return wrapped ? call.input[ENVELOPE] : call.input;
+      // A model that answers in prose is a schema failure, not a crash, so it flows into the
+      // repair turn. For a wrapped output the prose itself may BE the answer (`t.string`), the
+      // rule `.stream()` already applies.
+      const parsed = parseJsonish(result.text);
+      return parsed === undefined && wrapped && result.text !== '' ? result.text : parsed;
+    },
+  };
+}
+
+const FENCE = '```';
+
+/**
+ * The JSON in a prose answer: the first fenced block when there is a closed one, else the whole
+ * text. Two `indexOf` scans, never a backtracking pattern: the regex this replaced re-scanned the
+ * tail from every whitespace position after an unterminated fence — quadratic on model output.
+ */
+export function parseJsonish(text: string): unknown {
+  const open = text.indexOf(FENCE);
+  const close = open === -1 ? -1 : text.indexOf(FENCE, open + FENCE.length);
+  let body = text;
+  if (close !== -1) {
+    body = text.slice(open + FENCE.length, close);
+    if (body.startsWith('json')) body = body.slice('json'.length);
+  }
+  try {
+    return JSON.parse(body.trim());
+  } catch {
+    return undefined;
+  }
+}

package/src/runtime.ts

@@ -8,10 +8,10 @@
 // un-bypassable rather than merely recommended.
 
 import type { SemanticCache } from '@ultimat3/cache';
-import { createMemorySemanticCache } from '@ultimat3/cache';
-import { cachedFormatter, MAX_CACHED_FORMATTERS } from '@ultimat3/core';
+import { memorySemanticCache } from '@ultimat3/cache';
+import { cachedFormatter } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
-import { HashEmbedder } from './embeddings';
+import { hashEmbedder } from './embeddings';
 import { AiGatewayMissingError } from './errors';
 import type { Gateway } from './gateway';
 
@@ -62,8 +62,8 @@ const caches = new Map<string, SemanticCache>();
 export function configureAi(input: AiRuntimeInput): void {
   runtime = {
     gateway: input.gateway,
-    embedder: input.embedder ?? new HashEmbedder(),
-    semanticCache: input.semanticCache ?? (() => createMemorySemanticCache()),
+    embedder: input.embedder ?? hashEmbedder(),
+    semanticCache: input.semanticCache ?? (() => memorySemanticCache()),
     redact: input.redact ?? noRedaction,
   };
   // A new runtime means a new embedder and a new gateway; vectors from the old one are not
@@ -77,8 +77,13 @@ export function aiGateway(prompt: string): Gateway {
   return runtime.gateway;
 }
 
+/** The installed gateway, or `undefined` — for a caller that may run without one (`hive()`). */
+export function installedGateway(): Gateway | undefined {
+  return runtime?.gateway;
+}
+
 export function aiEmbedder(): Embedder {
-  return runtime?.embedder ?? new HashEmbedder();
+  return runtime?.embedder ?? hashEmbedder();
 }
 
 /** The installed redactor, or the identity. Never absent, so the call site has no branch. */
@@ -86,13 +91,6 @@ export function aiRedactor(): Redactor {
   return runtime?.redact ?? noRedaction;
 }
 
-/**
- * How many scopes hold a live cache instance at once. Core's bound, not a second one — the name
- * `MAX_CACHED_FORMATTERS` is about `cachedFormatter`'s first caller, never about its contract,
- * and a second FIFO map written here would be two answers to one question (axiom 1).
- */
-export const MAX_SEMANTIC_CACHE_SCOPES = MAX_CACHED_FORMATTERS;
-
 /**
  * The cache for one scope. Scopes are separate CACHE INSTANCES, never a filter over a shared
  * one: cosine similarity has no notion of a tenant, so two tenants asking near-identical
@@ -109,7 +107,7 @@ export function semanticCacheFor(scope: string): SemanticCache {
   return cachedFormatter(
     caches,
     scope,
-    () => runtime?.semanticCache(scope) ?? createMemorySemanticCache(),
+    () => runtime?.semanticCache(scope) ?? memorySemanticCache(),
   );
 }