@ultimat3/ai 24.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,87 +424,6 @@ 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 `usage` replaces it after.
@@ -472,12 +434,13 @@ export function estimateTokens(request: GenerateRequest): number {
 }
 
 const completionCeiling = (request: GenerateRequest): number =>
-  Math.min(request.maxTokens, modelSpec(request.model ?? DEFAULT_MODEL).maxOutput);
+  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);
 }
 
 /**
@@ -486,7 +449,7 @@ export function estimateInputTokens(request: GenerateRequest): number {
  * optimistic estimate is a ceiling one long completion walks through.
  */
 export function estimateCost(request: GenerateRequest): Money {
-  return costOf(request.model ?? DEFAULT_MODEL, {
+  return costOf(resolveModel('provider', request.model), {
     inputTokens: estimateInputTokens(request),
     outputTokens: completionCeiling(request),
     cacheReadTokens: 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.
@@ -172,7 +173,7 @@ export async function indexDocument(input: {
   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),
@@ -188,7 +189,7 @@ export async function indexDocument(input: {
       metadata: c.metadata,
     })),
   );
-  // `source` is the chunker's own stamp (`chunk()`), so only THIS document's rows are touched.
+  // `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),
@@ -262,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,7 @@
 
 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';
@@ -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;
@@ -182,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))
@@ -204,7 +209,7 @@ export class RemoteEmbedder implements Embedder {
       }
       vector[i] = value;
     }
-    return normalize(vector);
+    return normalizeVector(vector);
   }
 
   private malformed(detail: string): AiTransportError {

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
@@ -83,7 +83,7 @@ export function installedGateway(): Gateway | undefined {
 }
 
 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. */
@@ -91,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
@@ -114,7 +107,7 @@ export function semanticCacheFor(scope: string): SemanticCache {
   return cachedFormatter(
     caches,
     scope,
-    () => runtime?.semanticCache(scope) ?? createMemorySemanticCache(),
+    () => runtime?.semanticCache(scope) ?? memorySemanticCache(),
   );
 }
 

package/src/scorers.ts

@@ -132,7 +132,7 @@ export function llmJudge(input: {
         maxTokens: finiteCount('llmJudge', 'maxTokens', input.maxTokens ?? 256, 1),
         ...(input.judge.system !== undefined ? { system: input.judge.system } : {}),
         ...(input.judge.model !== undefined ? { model: input.judge.model } : {}),
-        // The judge prompt's hash is this scorer's NAME, and `contentHash` covers `effort` and
+        // The judge prompt's hash is this scorer's NAME, and `promptHash` covers `effort` and
         // `thinking` — so dropping either measures with a judge the name does not describe.
         ...(input.judge.effort !== undefined ? { effort: input.judge.effort } : {}),
         ...(input.judge.thinking !== undefined ? { thinking: input.judge.thinking } : {}),

package/src/tool-idempotency.ts

@@ -0,0 +1,79 @@
+// The in-app half of `idempotent: true`: an agent's tool carries the reserved `idempotencyKey`
+// argument exactly as `@ultimat3/mcp`'s does, so an action an external agent may retry safely is
+// one an in-app agent may retry safely too. Restated, not imported — `mcp` is this package's own
+// tier — and held equal to `mcp/src/idempotency-arg.ts` by `scripts/ai-mcp-tool-parity.test.ts`.
+
+import { MAX_IDEMPOTENCY_KEY_LENGTH } from '@ultimat3/action';
+import { UltimateError } from '@ultimat3/core';
+import type { JsonSchema } from './tools';
+
+/** The reserved argument name on every idempotent action's tool — the one MCP reserves. */
+export const TOOL_IDEMPOTENCY_KEY_ARG = 'idempotencyKey';
+
+/** Contract text, byte-identical to MCP's: it is what the model reads on either surface. */
+const DESCRIPTION =
+  'Idempotency key. Retrying this call with the same key and the same arguments returns the ' +
+  'first result instead of running it again; the same key with different arguments is refused. ' +
+  'Any unique string, e.g. a UUID — reuse it only to retry.';
+
+const KEY_SCHEMA: JsonSchema = {
+  type: 'string',
+  description: DESCRIPTION,
+  minLength: 1,
+  maxLength: MAX_IDEMPOTENCY_KEY_LENGTH,
+};
+
+/**
+ * MCP's own refusal, raised for the same tool: an agent tool is an MCP-exposed action by
+ * construction (`X_AGENT_TOOL_UNEXPOSED`), so this is the projection `@ultimat3/mcp` refuses too,
+ * and one code for it on both surfaces is the parity. Never titled here — `mcp` registers it.
+ */
+export class ToolIdempotencyKeyShadowedError extends UltimateError {
+  constructor(input: { readonly name: string; readonly argument: string }) {
+    super({
+      code: 'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
+      cause: `${input.name} is idempotent and its input declares "${input.argument}", the MCP argument reserved for the idempotency key`,
+      fix: `rename ${input.name}'s "${input.argument}" input field — MCP clients send the Idempotency-Key as the reserved "${input.argument}" argument, and the action receives the rest`,
+      meta: { action: input.name, argument: input.argument },
+    });
+  }
+}
+
+/** `schema` with the optional key argument; a non-object input is left alone, a clash refused. */
+export function withToolIdempotencyKey(name: string, schema: JsonSchema): JsonSchema {
+  if (schema.type !== 'object') return schema;
+  const properties = schema.properties ?? {};
+  if (Object.hasOwn(properties, TOOL_IDEMPOTENCY_KEY_ARG)) {
+    throw new ToolIdempotencyKeyShadowedError({ name, argument: TOOL_IDEMPOTENCY_KEY_ARG });
+  }
+  return { ...schema, properties: { ...properties, [TOOL_IDEMPOTENCY_KEY_ARG]: KEY_SCHEMA } };
+}
+
+/**
+ * The model's arguments split into the action's input and the key. No key is an un-keyed run, as
+ * HTTP without the header; a non-string is no key. A blank or over-long one goes to `invoke`, whose
+ * `X_IDEMPOTENCY_KEY_INVALID` the model reads as a tool error naming the bound.
+ */
+export function takeToolIdempotencyKey(args: unknown): {
+  readonly input: unknown;
+  readonly idempotencyKey: string | null;
+} {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { input: args, idempotencyKey: null };
+  }
+  if (!Object.hasOwn(args, TOOL_IDEMPOTENCY_KEY_ARG)) return { input: args, idempotencyKey: null };
+  const input: Record<string, unknown> = {};
+  let key: unknown;
+  for (const [field, value] of Object.entries(args)) {
+    if (field === TOOL_IDEMPOTENCY_KEY_ARG) key = value;
+    // defineProperty, never `input[field] =`: a `__proto__` field would re-prototype the copy.
+    else
+      Object.defineProperty(input, field, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+  }
+  return { input, idempotencyKey: typeof key === 'string' ? key : null };
+}