@copilotkit/aimock 1.43.0 → 1.45.0

package/dist/types.d.ts

@@ -1,7 +1,9 @@
+import { MisbehaviorSummary } from "./misbehavior.js";
 import { Journal } from "./journal.js";
 import { LiveFixtureResponse, LiveOptions } from "./live-types.js";
 import { Logger } from "./logger.js";
 import { MetricsRegistry } from "./metrics.js";
+import { McpFakeAddOrigin, McpFakeAddResult } from "./mcp-fakes.js";
 import * as http$1 from "node:http";
 import * as net from "node:net";
 
@@ -16,6 +18,23 @@ interface Mountable {
   setJournal?(journal: Journal): void;
   setBaseUrl?(url: string): void;
   setRegistry?(registry: MetricsRegistry): void;
+  /**
+   * MCP fakes. A mount "is an MCPMock" for fakes if and only if it
+   * implements `addMcpFakes`. Always appends. `origin` picks the entry-id
+   * source and its counter: `file` keeps each block's `source` (`@<k>` load
+   * counter); `code` / `control-api` is one run-time addition (`code#<n>` /
+   * `control-api#<n>`). Returns the shadowed-entry warnings with the real
+   * entry ids. When any block is bad, or the input holds no blocks, throws one
+   * `FixtureLoadError` (an `McpFakesAddError` carrying every error found and
+   * the warnings) and adds nothing.
+   */
+  addMcpFakes?(blocks: McpFakeSource[], origin: McpFakeAddOrigin): McpFakeAddResult;
+  /** Unload every fake on this mount. The entry-id counters are kept. */
+  clearMcpFakes?(): void;
+  /** Reset fake consumption state for one test id, or for all when omitted. */
+  resetScenarioState?(testId?: string): void;
+  /** Hands an MCP mount a `Logger`. Nothing in the server calls it. */
+  setLogger?(logger: Logger): void;
 }
 interface ContentPart {
   type: string;
@@ -27,16 +46,39 @@ interface ChatMessage {
   content: string | ContentPart[] | null;
   name?: string;
   tool_calls?: ToolCallMessage[];
+  /**
+   * OpenAI Responses `custom_tool_call` history items. Set only when the
+   * server runs with `responsesTools: "extended"`; the default ignores
+   * custom tool call history, as earlier releases did.
+   */
+  custom_tool_calls?: CustomToolCallMessage[];
   tool_call_id?: string;
 }
 interface ToolCallMessage {
   id: string;
   type: "function";
+  /**
+   * OpenAI Responses namespace of the called tool. Set only with
+   * `responsesTools: "extended"`, when the history item had one.
+   */
+  namespace?: string;
   function: {
     name: string;
     arguments: string;
   };
 }
+/**
+ * An OpenAI Responses `custom_tool_call` history item, normalized for fixture
+ * matching. Produced only with `responsesTools: "extended"`.
+ */
+interface CustomToolCallMessage {
+  id: string;
+  type: "custom";
+  name: string;
+  /** Free-text input of the call ("" when the history item had none). */
+  input: string;
+  namespace?: string;
+}
 interface ChatCompletionRequest {
   model: string;
   messages: ChatMessage[];
@@ -81,6 +123,13 @@ interface ChatCompletionRequest {
   temperature?: number;
   max_tokens?: number;
   tools?: ToolDefinition[];
+  /**
+   * OpenAI Responses `custom` tools offered by the request (top level, inside
+   * a `namespace` tool, or in an `additional_tools` / `tool_search_output`
+   * input item). Set only with `responsesTools: "extended"`; `toolName`
+   * matches these as well as `tools`.
+   */
+  customTools?: CustomToolDefinition[];
   tool_choice?: string | object;
   response_format?: {
     type: string;
@@ -102,6 +151,13 @@ interface ChatCompletionRequest {
   _videoProvider?: "openrouter" | "veo" | "grok" | "byteplus";
   [key: string]: unknown;
 }
+/**
+ * aimock's normalized request function tool. The OpenAI Responses adapter
+ * keeps only top-level `function` tools here by default. With
+ * `responsesTools: "extended"` it also adds the function tools inside a
+ * `namespace` tool (with `namespace` set) and those from `additional_tools` /
+ * `tool_search_output` input items.
+ */
 interface ToolDefinition {
   type: "function";
   function: {
@@ -109,6 +165,21 @@ interface ToolDefinition {
     description?: string;
     parameters?: object;
   };
+  /** OpenAI Responses namespace the tool was offered in (extended mode only). */
+  namespace?: string;
+}
+/**
+ * An OpenAI Responses `custom` (freeform) tool offered by a request. See
+ * {@link ChatCompletionRequest.customTools}.
+ */
+interface CustomToolDefinition {
+  type: "custom";
+  name: string;
+  description?: string;
+  /** OpenAI Responses namespace the tool was offered in, when inside a `namespace` tool. */
+  namespace?: string;
+  /** Custom-tool input format (grammar or text), carried verbatim. */
+  format?: unknown;
 }
 interface FixtureMatch {
   userMessage?: string | RegExp;
@@ -138,6 +209,13 @@ interface FixtureMatch {
    */
   toolResultContains?: string;
   toolName?: string;
+  /**
+   * Exact OpenAI Responses tool namespace. Alone, it matches when any offered
+   * tool sits in this namespace; with `toolName`, a single offered tool must
+   * carry both the name and the namespace. Applies only when the server runs
+   * with `responsesTools: "extended"`; otherwise it is ignored, as in 1.44.0.
+   */
+  toolNamespace?: string;
   model?: string | RegExp;
   responseFormat?: string;
   predicate?: (req: ChatCompletionRequest) => boolean;
@@ -284,7 +362,36 @@ interface ToolCall {
   name: string;
   arguments: string;
   id?: string;
+  /**
+   * OpenAI Responses API only: emitted as `function_call.namespace` when the
+   * server runs with `responsesTools: "extended"`. Ignored otherwise, and by
+   * every other wire.
+   */
+  namespace?: string;
 }
+/**
+ * An OpenAI Responses custom (freeform) tool call, emitted as a
+ * `custom_tool_call` item. Fixtures carry it in `customToolCalls` (or as a
+ * `customToolCall` block in `responsesBlocks`). Only the Responses API (HTTP
+ * and WebSocket) can serve it; every other wire rejects it with
+ * `UnsupportedToolCallError`.
+ */
+interface CustomToolCall {
+  type: "custom";
+  name: string;
+  /** Free-text input. Never parsed, never stringified. */
+  input: string;
+  id?: string;
+  /** OpenAI Responses API only: emitted as `custom_tool_call.namespace`. */
+  namespace?: string;
+}
+/**
+ * A tool call the OpenAI Responses API serves: a function call (from
+ * `toolCalls`) or a custom tool call (from `customToolCalls`).
+ */
+type FixtureToolCall = (ToolCall & {
+  type?: undefined;
+}) | CustomToolCall;
 /**
  * A single ordered streaming block for a {@link ContentWithToolCallsResponse}.
  *
@@ -303,9 +410,30 @@ type FixtureBlock = {
   name: string;
   arguments: string;
   id?: string;
+  namespace?: string;
+};
+/**
+ * An ordered block for {@link ContentWithToolCallsResponse.responsesBlocks}:
+ * a {@link FixtureBlock}, or a `customToolCall` block that mirrors
+ * {@link CustomToolCall} (`name` + free-text `input`, optional `id` and
+ * `namespace`). Only the OpenAI Responses API serves `responsesBlocks`.
+ */
+type ResponsesFixtureBlock = FixtureBlock | {
+  type: "customToolCall";
+  name: string;
+  input: string;
+  id?: string;
+  namespace?: string;
 };
 interface ToolCallResponse extends ResponseOverrides {
   toolCalls: ToolCall[];
+  /**
+   * OpenAI Responses custom tool calls, emitted after `toolCalls`. A turn with
+   * only custom calls sets `toolCalls: []`. Every other wire rejects a fixture
+   * with a non-empty `customToolCalls` (`UnsupportedToolCallError`). Applies
+   * only with `responsesTools: "extended"`; otherwise it is ignored.
+   */
+  customToolCalls?: CustomToolCall[];
   reasoning?: string;
   /** Real Anthropic thinking-block signature; see {@link TextResponse.reasoningSignature}. */
   reasoningSignature?: string;
@@ -327,6 +455,8 @@ interface ContentWithToolCallsResponse extends ResponseOverrides {
   content?: string;
   /** See {@link ContentWithToolCallsResponse.content} — optional only for the blocks-only shape. */
   toolCalls?: ToolCall[];
+  /** OpenAI Responses custom tool calls; see {@link ToolCallResponse.customToolCalls}. */
+  customToolCalls?: CustomToolCall[];
   /**
    * Optional ordered streaming blocks. When present, builders stream these in
    * array order (tool-first / interleaved); when absent, the legacy
@@ -335,6 +465,14 @@ interface ContentWithToolCallsResponse extends ResponseOverrides {
    * response even without `content`/`toolCalls` (see those fields above).
    */
   blocks?: FixtureBlock[];
+  /**
+   * OpenAI Responses only: ordered blocks that may include `customToolCall`
+   * blocks. On the Responses API they replace `blocks`; a fixture may not set
+   * both. Every other wire rejects a `customToolCall` block here
+   * (`UnsupportedToolCallError`) and otherwise ignores this field. Applies
+   * only with `responsesTools: "extended"`; otherwise it is ignored.
+   */
+  responsesBlocks?: ResponsesFixtureBlock[];
   reasoning?: string;
   /** Real Anthropic thinking-block signature; see {@link TextResponse.reasoningSignature}. */
   reasoningSignature?: string;
@@ -592,6 +730,61 @@ interface ChaosScope {
 type ChaosDefaults = ChaosConfig | ChaosScope;
 type ChaosAction = "drop" | "malformed" | "rateLimit" | "disconnect";
 type ResponseFactory = (req: ChatCompletionRequest) => FixtureResponse | Promise<FixtureResponse>;
+/** Provider wire identifiers, independent of endpoint response families. */
+type WireId = "openai-chat" | "openai-responses" | "openai-realtime" | "anthropic" | "bedrock-invoke" | "bedrock-converse" | "gemini" | "gemini-live" | "gemini-interactions" | "cohere" | "ollama";
+interface MisbehaviorCommon {
+  rate?: number;
+  times?: number;
+  tool?: string;
+  providers?: WireId[];
+}
+type MisbehaviorFault = MisbehaviorCommon & ({
+  fault: "tool-args-invalid-json";
+  style?: "truncated" | "trailing-comma" | "single-quotes";
+} | {
+  fault: "tool-args-schema-violation";
+  violation?: "missing-required" | "wrong-type" | "extra-property" | "enum-mismatch" | "not-object";
+  property?: string;
+} | {
+  fault: "tool-unknown-name";
+  name?: string;
+} | {
+  fault: "tool-call-id-duplicate";
+} | {
+  fault: "stop-length-mid-tool";
+  at?: number;
+} | {
+  fault: "empty-response";
+} | {
+  fault: "refusal";
+  message?: string;
+  category?: string | null;
+} | {
+  fault: "content-filter";
+} | {
+  fault: "reasoning-only";
+  reasoning?: string;
+});
+type MisbehaviorFaultId = MisbehaviorFault["fault"];
+interface MisbehaviorConfig {
+  seed?: number | "random";
+  faults: MisbehaviorFault[];
+}
+interface MisbehaviorCounterKey {
+  testId: string;
+  sourceKey: string;
+  entryIndex: number;
+}
+interface MisbehaviorCounters {
+  getFiringCount(key: MisbehaviorCounterKey): number;
+  nextOrdinal(key: MisbehaviorCounterKey): number;
+  recordFiring(key: MisbehaviorCounterKey): void;
+  clearMisbehaviorCounters(testId?: string): void;
+}
+interface MisbehaviorScope {
+  baseline?: MisbehaviorConfig;
+  byTestId: Map<string, MisbehaviorConfig>;
+}
 interface Fixture {
   match: FixtureMatch;
   response: FixtureResponse | ResponseFactory;
@@ -602,6 +795,7 @@ interface Fixture {
   streamingProfile?: StreamingProfile;
   recordedTimings?: RecordedTimings;
   replaySpeed?: number;
+  misbehavior?: MisbehaviorConfig | MisbehaviorFaultId;
   chaos?: ChaosConfig;
   /**
    * Opt into OpenRouter's `: OPENROUTER PROCESSING` SSE keepalive comment
@@ -630,6 +824,18 @@ interface FixtureFileToolCall {
   /** Accepts a JSON object or array for convenience — the loader will JSON.stringify it. */
   arguments: string | Record<string, unknown> | unknown[];
   id?: string;
+  /** OpenAI Responses namespace; see {@link ToolCall.namespace}. */
+  namespace?: string;
+}
+/** On-disk counterpart of {@link CustomToolCall} (`customToolCalls` entries). */
+interface FixtureFileCustomToolCall {
+  /** Optional in a file: every `customToolCalls` entry is a custom call. */
+  type?: "custom";
+  name: string;
+  /** Free-text input, never parsed or stringified. */
+  input: string;
+  id?: string;
+  namespace?: string;
 }
 /**
  * On-disk counterpart of {@link FixtureBlock}. A `toolCall` block's
@@ -646,9 +852,20 @@ type FixtureFileBlock = {
   /** Accepts a JSON object or array for convenience — the loader will JSON.stringify it. */
   arguments: string | Record<string, unknown> | unknown[];
   id?: string;
+  namespace?: string;
+};
+/** On-disk counterpart of {@link ResponsesFixtureBlock} (`responsesBlocks` entries). */
+type FixtureFileResponsesBlock = FixtureFileBlock | {
+  type: "customToolCall";
+  name: string;
+  input: string;
+  id?: string;
+  namespace?: string;
 };
 interface FixtureFileToolCallResponse extends ResponseOverrides {
   toolCalls: FixtureFileToolCall[];
+  /** See {@link ToolCallResponse.customToolCalls}. */
+  customToolCalls?: FixtureFileCustomToolCall[];
   reasoning?: string;
   /** Real Anthropic thinking-block signature; see {@link TextResponse.reasoningSignature}. */
   reasoningSignature?: string;
@@ -676,6 +893,8 @@ interface FixtureFileContentWithToolCallsResponse extends ResponseOverrides {
   content?: string | Record<string, unknown> | unknown[];
   /** See {@link FixtureFileContentWithToolCallsResponse.content} — optional only for the blocks-only shape. */
   toolCalls?: FixtureFileToolCall[];
+  /** See {@link ToolCallResponse.customToolCalls}. */
+  customToolCalls?: FixtureFileCustomToolCall[];
   /**
    * Optional ordered streaming blocks (mirrors the in-memory
    * {@link ContentWithToolCallsResponse.blocks}). When present, builders stream
@@ -686,6 +905,8 @@ interface FixtureFileContentWithToolCallsResponse extends ResponseOverrides {
    * `blocks` array alone makes this a first-class blocks-only fixture.
    */
   blocks?: FixtureFileBlock[];
+  /** See {@link ContentWithToolCallsResponse.responsesBlocks}. */
+  responsesBlocks?: FixtureFileResponsesBlock[];
   reasoning?: string;
   /** Real Anthropic thinking-block signature; see {@link TextResponse.reasoningSignature}. */
   reasoningSignature?: string;
@@ -714,6 +935,8 @@ interface FixtureFileEntry {
      */
     toolResultContains?: string;
     toolName?: string;
+    /** Mirrors the runtime FixtureMatch.toolNamespace. */
+    toolNamespace?: string;
     model?: string;
     responseFormat?: string;
     sequenceIndex?: number;
@@ -737,6 +960,7 @@ interface FixtureFileEntry {
   streamingProfile?: StreamingProfile;
   recordedTimings?: RecordedTimings;
   replaySpeed?: number;
+  misbehavior?: MisbehaviorConfig | MisbehaviorFaultId;
   chaos?: ChaosConfig;
   /** See {@link Fixture.openRouterProcessing}. */
   openRouterProcessing?: boolean;
@@ -774,9 +998,22 @@ interface JournalEntry {
   headers: Record<string, string>;
   body: JournalBody | null;
   service?: string;
+  /**
+   * Resolved test id of an MCP request (`"__default__"` when none), for an
+   * MCP mount to set. Journal test-id filtering does not read it: it
+   * re-derives the id from the headers and path (`journalEntryTestId`).
+   */
+  testId?: string;
+  /** Resolved context of an MCP request, `null` when none; for an MCP mount to set. */
+  context?: string | null;
   response: {
     status: number;
     fixture: Fixture | null;
+    /** For an MCP mount to set on `tools/call` entries a fake answered or failed. */
+    mcpFake?: {
+      id: string | null;
+      outcome: McpFakeOutcome;
+    };
     /**
      * What was going to serve this request. "fixture" = a fixture matched (or
      * would have, before chaos intervened). "proxy" = no fixture matched and
@@ -796,14 +1033,21 @@ interface JournalEntry {
     interrupted?: boolean;
     interruptReason?: string;
     /**
-     * The handler crashed AFTER the response completed. The client received
-     * `status` in full, so this is not an interruption; the message is what
-     * the crash said.
+     * The error message of a failed request, set in two cases:
+     * - The request failed before any content was sent, and `status` is 500:
+     *   a fixture tool-call error (HTTP or WebSocket), or any builder error on
+     *   the WebSocket Responses transport.
+     * - The handler crashed AFTER the response completed. The client received
+     *   `status` in full, so this is not an interruption.
      */
     error?: string;
     chaosAction?: ChaosAction;
+    /** Full prepared fault output; interrupted delivery is recorded separately above. */
+    misbehavior?: MisbehaviorSummary;
     /** When the X-AIMock-Strict header overrode the server default. */
     strictOverride?: boolean;
+    /** MR8 / MR11 / MR14: why a forwarded MCP record-mode message was not recorded. */
+    recordSkipped?: string;
   };
 }
 /**
@@ -868,9 +1112,18 @@ interface SSEChoice {
   /** OpenRouter raw upstream finish reason, alongside the normalized one. */
   native_finish_reason?: string | null;
 }
+/** OpenRouter text reasoning detail, paired with the same logical reasoning text. */
+interface ReasoningTextDetail {
+  type: "reasoning.text";
+  text: string;
+  format: "unknown";
+  index: number;
+}
 interface SSEDelta {
   role?: string;
   content?: string | null;
+  reasoning?: string;
+  reasoning_details?: ReasoningTextDetail[];
   reasoning_content?: string;
   tool_calls?: SSEToolCallDelta[];
 }
@@ -917,6 +1170,7 @@ interface ChatCompletionMessage {
   role: string;
   content: string | null;
   refusal: string | null;
+  reasoning_details?: ReasoningTextDetail[];
   reasoning_content?: string;
   /**
    * OpenRouter emits `reasoning` (null when absent) on the response message.
@@ -1039,6 +1293,8 @@ interface FalRecordConfig {
   /** Total budget for an upstream queue walk before aborting. Default: 900000ms (15 min) to accommodate video generation. */
   timeoutMs?: number;
 }
+/** See {@link MockServerOptions.responsesTools}. */
+type ResponsesToolsMode = "legacy" | "extended";
 interface MockServerOptions {
   live?: LiveOptions;
   /** Optional inbound test-client access keys. Omit to preserve permissive behavior. */
@@ -1050,11 +1306,51 @@ interface MockServerOptions {
   replaySpeed?: number;
   /** Log verbosity. CLI default is "info"; programmatic default (when omitted) is "silent". */
   logLevel?: "silent" | "warn" | "info" | "debug";
+  /**
+   * Opt in to model misbehavior. Without it, the `misbehavior` option, a
+   * fixture's `misbehavior` key and the `X-AIMock-Misbehavior` header are
+   * ignored, as in 1.44.0. CLI: `--misbehavior`.
+   *
+   * When on, addFixture, addFixtures and prependFixture store a per-addition
+   * copy, so getFixtures()[i] is the copy. findByFixture, the match-count APIs
+   * and journal entry.response.fixture still name the caller's object. A field
+   * assigned on that object later (for example `fixture.response = ...`) has no
+   * effect; add the fixture again. When off, the caller's object is stored.
+   */
+  enableMisbehavior?: boolean;
+  /** Server-wide misbehavior baseline; read only with `enableMisbehavior: true`. */
+  misbehavior?: MisbehaviorConfig | MisbehaviorFaultId;
   chaos?: ChaosConfig;
   /** Enable Prometheus-compatible /metrics endpoint. */
   metrics?: boolean;
   /** Strict mode: return 503 instead of 404 when no fixture matches. */
   strict?: boolean;
+  /**
+   * Reject fixture tool calls whose `arguments` are not valid JSON instead of
+   * serving them as `{}`. Off by default (the 1.44.0 behavior). When on, wires
+   * that carry arguments as an object (Anthropic and Bedrock non-streaming,
+   * Converse non-streaming, Gemini, Vertex AI, Gemini Interactions
+   * non-streaming, Gemini Live, Ollama) answer 500 `aimock_invalid_tool_arguments`
+   * (Gemini Live: an error frame), and wires that carry them as a string
+   * (Cohere and the streaming Anthropic, Bedrock, Converse and Gemini
+   * Interactions paths) serve the authored text unchanged.
+   */
+  strictToolArguments?: boolean;
+  /**
+   * OpenAI Responses tool handling. `"legacy"` (the default) matches,
+   * counts and journals Responses requests exactly as earlier releases did:
+   * only top-level function tools are visible, custom tool call history is not
+   * counted, and a `namespace` on a `toolCalls` entry or `toolCall` block is
+   * not emitted. `"extended"` makes namespaced, custom and `additional_tools`
+   * / `tool_search_output` tools visible to `toolName` and predicates, counts
+   * custom tool call rounds for `turnIndex` / `hasToolResult` / `toolCallId`,
+   * emits fixture namespaces, applies `match.toolNamespace`,
+   * `customToolCalls` and `responsesBlocks` (which `"legacy"` ignores), and
+   * makes the recorder keep namespaces and custom tool calls. The mode is
+   * fixed when the server starts; changing `responsesTools` on the options
+   * object after `createServer` or `LLMock.start()` is unsupported.
+   */
+  responsesTools?: ResponsesToolsMode;
   /** Record-and-replay: proxy unmatched requests to upstream and save fixtures. */
   record?: RecordConfig;
   /**
@@ -1169,6 +1465,9 @@ interface FalQueueConfig {
   pollsBeforeCompleted?: number;
 }
 interface HandlerDefaults {
+  /** Present only when misbehavior is enabled; without it no fault is planned. */
+  misbehavior?: MisbehaviorScope;
+  misbehaviorCounters?: MisbehaviorCounters;
   latency: number;
   chunkSize: number;
   replaySpeed: number;
@@ -1186,6 +1485,10 @@ interface HandlerDefaults {
   registry?: MetricsRegistry;
   record?: RecordConfig;
   strict?: boolean;
+  /** See {@link MockServerOptions.strictToolArguments}. */
+  strictToolArguments?: boolean;
+  /** See {@link MockServerOptions.responsesTools}. Absent means `"legacy"`. */
+  responsesTools?: ResponsesToolsMode;
   requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest;
   falQueue?: FalQueueConfig;
   openRouterVideo?: FalQueueConfig;
@@ -1200,7 +1503,215 @@ interface HandlerDefaults {
    */
   bytePlusVideo?: FalQueueConfig;
 }
-//# sourceMappingURL=types.d.ts.map
+/**
+ * Block scope: `"shared"`, or exact test id and/or context (at least one;
+ * `{}` is not a scope). Readonly: validated scopes are frozen.
+ */
+type McpFakeScope = "shared" | Readonly<{
+  testId: string;
+  context?: string;
+}> | Readonly<{
+  testId?: string;
+  context: string;
+}>;
+/**
+ * `T` with every nested property and array read-only: the type of a value the
+ * MCP fakes store deep-freezes before it hands it out.
+ */
+type McpFakeDeepReadonly<T> = T extends ((...args: never[]) => unknown) ? T : T extends object ? { readonly [K in keyof T]: McpFakeDeepReadonly<T[K]> } : T;
+/** MCP `Annotations` on a content block. */
+interface McpFakeAnnotations {
+  audience?: Array<"user" | "assistant">;
+  /** From 0 (least) to 1 (most important). */
+  priority?: number;
+  /** RFC 3339 date-time with seconds and a `Z` or `±hh:mm` offset. */
+  lastModified?: string;
+}
+/** MCP `Icon` on a `resource_link` content block. */
+interface McpFakeIcon {
+  src: string;
+  mimeType?: string;
+  sizes?: string[];
+  theme?: "light" | "dark";
+}
+/** MCP `TextResourceContents` / `BlobResourceContents`: exactly one of `text` / `blob`. */
+type McpFakeResourceContents = {
+  uri: string;
+  mimeType?: string;
+  _meta?: Record<string, unknown>;
+} & ({
+  text: string;
+  blob?: never;
+} | {
+  blob: string;
+  text?: never;
+});
+type McpFakeContentCommon = {
+  annotations?: McpFakeAnnotations;
+  _meta?: Record<string, unknown>;
+};
+/** One MCP content block of a tool result (`ContentBlock`); `data` and `blob` are base64. */
+type McpFakeContentBlock = McpFakeContentCommon & ({
+  type: "text";
+  text: string;
+} | {
+  type: "image";
+  data: string;
+  mimeType: string;
+} | {
+  type: "audio";
+  data: string;
+  mimeType: string;
+} | {
+  type: "resource_link";
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType?: string;
+  size?: number;
+  icons?: McpFakeIcon[];
+} | {
+  type: "resource";
+  resource: McpFakeResourceContents;
+});
+/** A full MCP `CallToolResult`, served unchanged. No other keys. */
+interface McpFakeFullResult {
+  content: McpFakeContentBlock[];
+  isError?: boolean;
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+}
+/**
+ * Structured data: any JSON object without the `CallToolResult`
+ * keys, served as text plus `structuredContent`.
+ */
+type McpFakeStructuredResult = Record<string, unknown> & {
+  content?: never;
+  isError?: never;
+  structuredContent?: never;
+  _meta?: never;
+};
+/**
+ * A call entry's `result` value. Validation also checks what the type cannot
+ * say: base64 `data` / `blob`, `priority` from 0 to 1, the `lastModified`
+ * format, and plain JSON throughout. Unknown keys inside a content item are
+ * allowed and served as given.
+ */
+type McpFakeResult = string | McpFakeContentBlock[] | McpFakeFullResult | McpFakeStructuredResult;
+/** How a call entry matches: exactly one of `args` / `anyArgs`. */
+type McpFakeCallMatch = {
+  args: Record<string, unknown>;
+  anyArgs?: never;
+} | {
+  anyArgs: true;
+  args?: never;
+};
+/** What a call entry answers: exactly one of `result` / `error`. */
+type McpFakeCallAnswer = {
+  result: McpFakeResult;
+  error?: never;
+} | {
+  error: string;
+  result?: never;
+};
+/** One ordered answer for a tool. */
+type McpFakeCall = McpFakeCallMatch & McpFakeCallAnswer & {
+  id?: string;
+  /** FA3: the notifications the upstream sent on the call's stream before the response. */
+  notifications?: McpFakeNotification[];
+  /** FA4: the recorded response time in ms (a number >= 0). */
+  durationMs?: number;
+};
+/** One faked tool in a block. */
+interface McpFakeTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  calls: McpFakeCall[];
+}
+/** One `mcpFakes` block. */
+interface McpFakeBlock {
+  scope: McpFakeScope;
+  mount?: string;
+  undeclaredTools?: McpFakeUndeclaredPolicy;
+  tools: McpFakeTool[];
+  /** FA1: the recorded `tools/list` (MCP `Tool` objects, kept verbatim). */
+  list?: Record<string, unknown>[];
+  /** FA2: provenance of a recording. Never used for matching. */
+  recorded?: McpFakeRecorded;
+  /** FA5: `"recorded"` (default) plays FA3/FA4 timing; `"immediate"` ignores it. */
+  timing?: "recorded" | "immediate";
+}
+/** FA2 `recorded`: where and when a block was recorded. */
+interface McpFakeRecorded {
+  /** The upstream origin only. */
+  upstream: string;
+  protocolVersion: string;
+  serverInfo?: Record<string, unknown>;
+  aimockVersion: string;
+  /** ISO 8601 date-time with seconds and an offset. */
+  at: string;
+}
+/** MR1 `MCPMock.enableRecording` options. */
+interface McpRecordConfig {
+  upstream: string;
+  fixturePath?: string;
+  proxyOnly?: boolean;
+  maxRecordBufferBytes?: number;
+  /** MR14 `"Name: value"`; env AIMOCK_MCP_UPSTREAM_AUTH (AM6). */
+  upstreamAuth?: string;
+  /** S2 (d); env AIMOCK_RECORD_SECRET_VALUES (newline-separated). */
+  secretValues?: string[];
+  /** MR5 (b): the server's strict default; X-AIMock-Strict still overrides per request. */
+  strict?: boolean;
+}
+/** FA3: one recorded notification of a call entry. */
+interface McpFakeNotification {
+  atMs: number;
+  method: string;
+  params: Record<string, unknown>;
+}
+type McpFakeUndeclaredPolicy = "allow" | "deny";
+/**
+ * The resolved identity of one MCP request: test id, context and undeclared
+ * override, each from the request or else from the session.
+ * `null` means "not supplied". The identity shape the fake store's matching
+ * methods take (`applicable`, `selectTier`, `claim`, `policy`, `declaredTools`,
+ * `listTools`).
+ */
+interface McpFakeIdentity {
+  testId: string | null;
+  context: string | null;
+  undeclared: McpFakeUndeclaredPolicy | null;
+}
+/**
+ * One raw block as a loader hands it off, before validation. `source` is the
+ * entry-id source string; `blockIndex` is `null` when `mcpFakes` is a single object.
+ */
+interface McpFakeSource {
+  source: string;
+  blockIndex: number | null;
+  raw: unknown;
+}
+/**
+ * `response.mcpFake.outcome` on a `tools/call` journal entry. `evicted`:
+ * the request's test id lost its consumption state to the FIFO test-id cap.
+ */
+type McpFakeOutcome = "answered" | "mismatch" | "exhausted" | "not_declared" | "evicted";
+/**
+ * JSON-RPC error codes of the four fake failures, keyed by
+ * `error.data.aimock.code`. `-31010` and `-31011` sit outside the JSON-RPC
+ * reserved range. `MCP_FAKE_EVICTED` is for a lookup of a declared tool by a
+ * test id whose state the FIFO test-id cap evicted, until it is reset.
+ */
+declare const MCP_FAKE_ERROR_CODES: {
+  readonly MCP_FAKE_NOT_DECLARED: -32602;
+  readonly MCP_FAKE_MISMATCH: -32602;
+  readonly MCP_FAKE_EXHAUSTED: -31010;
+  readonly MCP_FAKE_EVICTED: -31011;
+};
+type McpFakeErrorCode = keyof typeof MCP_FAKE_ERROR_CODES;
 //#endregion
-export { ApiKeyAuthConfig, AudioResponse, ChaosAction, ChaosConfig, ChaosDefaults, ChatCompletion, ChatCompletionChoice, ChatCompletionMessage, ChatCompletionRequest, ChatMessage, ContentPart, ContentWithToolCallsResponse, EmbeddingFixtureOpts, EmbeddingResponse, ErrorResponse, FalQueueOpts, Fixture, FixtureBlock, FixtureFile, FixtureFileBlock, FixtureFileContentWithToolCallsResponse, FixtureFileEntry, FixtureFileResponse, FixtureFileTextResponse, FixtureFileToolCall, FixtureFileToolCallResponse, FixtureMatch, FixtureOpts, FixtureResponse, HandlerDefaults, ImageItem, ImageResponse, JournalBody, JournalEntry, MockServerOptions, Mountable, RawJSONResponse, RecordConfig, RecordProviderKey, RecordedTimings, ResponseFactory, ResponseOverrides, SSEChoice, SSEChunk, SSEDelta, SSEToolCallDelta, StreamingProfile, TextResponse, ToolCall, ToolCallMessage, ToolCallResponse, ToolDefinition, TranscriptionResponse, VideoResponse, VoiceDesignPreview, VoiceDesignResponse };
+export { ApiKeyAuthConfig, AudioResponse, ChaosAction, ChaosConfig, ChaosDefaults, ChatCompletion, ChatCompletionChoice, ChatCompletionMessage, ChatCompletionRequest, ChatMessage, ContentPart, ContentWithToolCallsResponse, CustomToolCall, CustomToolCallMessage, CustomToolDefinition, EmbeddingFixtureOpts, EmbeddingResponse, ErrorResponse, FalQueueOpts, Fixture, FixtureBlock, FixtureFile, FixtureFileBlock, FixtureFileContentWithToolCallsResponse, FixtureFileCustomToolCall, FixtureFileEntry, FixtureFileResponse, FixtureFileResponsesBlock, FixtureFileTextResponse, FixtureFileToolCall, FixtureFileToolCallResponse, FixtureMatch, FixtureOpts, FixtureResponse, FixtureToolCall, HandlerDefaults, ImageItem, ImageResponse, JournalBody, JournalEntry, MCP_FAKE_ERROR_CODES, McpFakeAnnotations, McpFakeBlock, McpFakeCall, McpFakeCallAnswer, McpFakeCallMatch, McpFakeContentBlock, McpFakeDeepReadonly, McpFakeErrorCode, McpFakeFullResult, McpFakeIcon, McpFakeIdentity, McpFakeNotification, McpFakeOutcome, McpFakeRecorded, McpFakeResourceContents, McpFakeResult, McpFakeScope, McpFakeSource, McpFakeStructuredResult, McpFakeTool, McpFakeUndeclaredPolicy, McpRecordConfig, MisbehaviorConfig, MisbehaviorCounterKey, MisbehaviorCounters, MisbehaviorFault, MisbehaviorFaultId, MockServerOptions, Mountable, RawJSONResponse, RecordConfig, RecordProviderKey, RecordedTimings, ResponseFactory, ResponseOverrides, ResponsesFixtureBlock, ResponsesToolsMode, SSEChoice, SSEChunk, SSEDelta, SSEToolCallDelta, StreamingProfile, TextResponse, ToolCall, ToolCallMessage, ToolCallResponse, ToolDefinition, TranscriptionResponse, VideoResponse, VoiceDesignPreview, VoiceDesignResponse, WireId };
 //# sourceMappingURL=types.d.ts.map