@copilotkit/aimock 1.43.0 → 1.45.0

package/dist/ws-responses.js.map

@@ -1 +1 @@
-{"version":3,"file":"ws-responses.js","names":[],"sources":["../src/ws-responses.ts"],"sourcesContent":["/**\n * WebSocket handler for OpenAI Responses API.\n *\n * Accepts `{ type: \"response.create\", model: \"...\", input: [...] }` messages over\n * WebSocket and sends back the same Responses API SSE events as the HTTP\n * handler, but as individual WebSocket text frames.\n */\n\nimport type { ChatCompletionRequest, Fixture } from \"./types.js\";\nimport { matchFixtureDiagnostic } from \"./router.js\";\nimport {\n  responsesToCompletionRequest,\n  requestIncludesEncryptedReasoning,\n  requestWantsEncryptedReasoning,\n  buildTextStreamEvents,\n  buildToolCallStreamEvents,\n  buildContentWithToolCallsStreamEvents,\n  type ResponsesSSEEvent,\n} from \"./responses.js\";\nimport {\n  isTextResponse,\n  isToolCallResponse,\n  isContentWithToolCallsResponse,\n  isErrorResponse,\n  extractOverrides,\n  resolveResponse,\n  resolveStrictMode,\n  resolveReasoningForModel,\n  strictOverrideField,\n  flattenHeaders,\n  strictNoMatchMessage,\n  strictNoMatchLogLine,\n} from \"./helpers.js\";\nimport { createInterruptionSignal } from \"./interruption.js\";\nimport { delay, calculateDelay } from \"./sse-writer.js\";\nimport { DEFAULT_TEST_ID, type Journal } from \"./journal.js\";\nimport type { Logger } from \"./logger.js\";\nimport type { WebSocketConnection } from \"./ws-framing.js\";\n\ninterface ResponseCreateMessage {\n  type: \"response.create\";\n  model?: string;\n  input?: unknown[];\n  instructions?: string;\n  tools?: unknown[];\n  tool_choice?: string | object;\n  stream?: boolean;\n  temperature?: number;\n  max_output_tokens?: number;\n  [key: string]: unknown;\n}\n\nfunction isResponseCreateMessage(msg: unknown): msg is ResponseCreateMessage {\n  return (\n    typeof msg === \"object\" &&\n    msg !== null &&\n    (msg as ResponseCreateMessage).type === \"response.create\"\n  );\n}\n\nfunction buildErrorEvent(\n  message: string,\n  type = \"invalid_request_error\",\n  code?: string,\n): ResponsesSSEEvent {\n  return {\n    type: \"error\",\n    error: { message, type, code },\n  };\n}\n\nexport function handleWebSocketResponses(\n  ws: WebSocketConnection,\n  fixtures: Fixture[],\n  journal: Journal,\n  defaults: {\n    latency: number;\n    chunkSize: number;\n    replaySpeed?: number;\n    model: string;\n    logger: Logger;\n    strict?: boolean;\n    requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest;\n    testId?: string;\n    upgradeHeaders?: import(\"node:http\").IncomingHttpHeaders;\n  },\n): void {\n  const { logger } = defaults;\n  // Serialize message processing to prevent event interleaving\n  let pending = Promise.resolve();\n  ws.on(\"message\", (raw: string) => {\n    pending = pending.then(() =>\n      processMessage(raw, ws, fixtures, journal, defaults).catch((err: unknown) => {\n        const msg = err instanceof Error ? err.message : \"Internal error\";\n        logger.error(`WebSocket responses error: ${msg}`);\n        try {\n          ws.send(JSON.stringify(buildErrorEvent(msg, \"server_error\")));\n        } catch (sendErr) {\n          defaults.logger.debug(\n            `Failed to send error to client: ${sendErr instanceof Error ? sendErr.message : \"unknown\"}`,\n          );\n        }\n      }),\n    );\n  });\n}\n\nasync function processMessage(\n  raw: string,\n  ws: WebSocketConnection,\n  fixtures: Fixture[],\n  journal: Journal,\n  defaults: {\n    latency: number;\n    chunkSize: number;\n    replaySpeed?: number;\n    model: string;\n    logger: Logger;\n    strict?: boolean;\n    requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest;\n    testId?: string;\n    upgradeHeaders?: import(\"node:http\").IncomingHttpHeaders;\n  },\n): Promise<void> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (parseErr) {\n    const detail = parseErr instanceof Error ? parseErr.message : \"unknown\";\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(`Malformed JSON: ${detail}`, \"invalid_request_error\", \"invalid_json\"),\n      ),\n    );\n    return;\n  }\n\n  if (!isResponseCreateMessage(parsed)) {\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(\n          'Expected message type \"response.create\"',\n          \"invalid_request_error\",\n          \"invalid_message_type\",\n        ),\n      ),\n    );\n    return;\n  }\n\n  const responsesReq = {\n    model: parsed.model ?? defaults.model,\n    input: (parsed.input ?? []) as {\n      role?: string;\n      type?: string;\n      content?: string | { type: string; text?: string }[];\n      call_id?: string;\n      name?: string;\n      arguments?: string;\n      output?: string;\n      id?: string;\n    }[],\n    instructions: parsed.instructions,\n    tools: parsed.tools as\n      | {\n          type: \"function\";\n          name: string;\n          description?: string;\n          parameters?: object;\n          strict?: boolean;\n        }[]\n      | undefined,\n    tool_choice: parsed.tool_choice,\n    stream: parsed.stream,\n    temperature: parsed.temperature,\n    max_output_tokens: parsed.max_output_tokens,\n    include: (parsed as { include?: string[] }).include,\n    store: (parsed as { store?: boolean }).store,\n  };\n\n  // Gate encrypted-reasoning emission identically to the HTTP transport so the\n  // agent-framework#7233 stateless-replay path works over WebSocket too.\n  const emitEncryptedReasoning = requestWantsEncryptedReasoning(responsesReq);\n  // Synthesizing a reasoning item the fixture never declared takes the NARROWER\n  // explicit-`include` gate, transport-identically to HTTP — a `store: false`\n  // request with a summary-less fixture still gets no reasoning item.\n  const synthesizeSummarylessReasoning = requestIncludesEncryptedReasoning(responsesReq);\n\n  const completionReq = responsesToCompletionRequest(responsesReq);\n  completionReq._endpointType = \"chat\";\n  const contextHeader = defaults.upgradeHeaders?.[\"x-aimock-context\"];\n  completionReq._context =\n    typeof contextHeader === \"string\"\n      ? contextHeader\n      : Array.isArray(contextHeader) && contextHeader.length > 0\n        ? contextHeader[0]\n        : undefined;\n  const testId = defaults.testId ?? DEFAULT_TEST_ID;\n  const { fixture, skippedBySequenceOrTurn } = matchFixtureDiagnostic(\n    fixtures,\n    completionReq,\n    journal.getFixtureMatchCountsForTest(testId),\n    defaults.requestTransform,\n  );\n\n  if (fixture) {\n    journal.incrementFixtureMatchCount(fixture, fixtures, testId);\n  }\n\n  if (!fixture) {\n    if (resolveStrictMode(defaults.strict, defaults.upgradeHeaders)) {\n      const strictMessage = strictNoMatchMessage(skippedBySequenceOrTurn);\n      defaults.logger.error(strictNoMatchLogLine(\"WS\", \"/v1/responses\", skippedBySequenceOrTurn));\n      journal.add({\n        method: \"WS\",\n        path: \"/v1/responses\",\n        headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n        body: completionReq,\n        response: {\n          status: 503,\n          fixture: null,\n          ...strictOverrideField(defaults.strict, defaults.upgradeHeaders),\n        },\n      });\n      ws.close(1008, strictMessage);\n      return;\n    }\n    journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: {\n        status: 404,\n        fixture: null,\n        ...strictOverrideField(defaults.strict, defaults.upgradeHeaders),\n      },\n    });\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(\"No fixture matched\", \"invalid_request_error\", \"no_fixture_match\"),\n      ),\n    );\n    return;\n  }\n\n  const response = await resolveResponse(fixture, completionReq);\n  const latency = fixture.latency ?? defaults.latency;\n  const chunkSize = Math.max(1, fixture.chunkSize ?? defaults.chunkSize);\n\n  // The WS path has no per-request `req.headers`; strict is resolved from the\n  // connection's upgrade headers (see the `!fixture` branch above). Used below\n  // to gate the synthesized reasoning channel on the requested model's capability.\n  const effectiveStrict = resolveStrictMode(defaults.strict, defaults.upgradeHeaders);\n\n  // Error response\n  if (isErrorResponse(response)) {\n    const status = response.status ?? 500;\n    journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status, fixture },\n    });\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(response.error.message, response.error.type, response.error.code),\n      ),\n    );\n    return;\n  }\n\n  // Content + tool calls response (must be checked before isTextResponse / isToolCallResponse)\n  if (isContentWithToolCallsResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n\n    const events = buildContentWithToolCallsStreamEvents(\n      response.content ?? \"\",\n      response.toolCalls ?? [],\n      completionReq.model,\n      chunkSize,\n      resolveReasoningForModel(\n        response.reasoning,\n        completionReq.model,\n        effectiveStrict,\n        defaults.logger,\n      ),\n      response.webSearches,\n      extractOverrides(response),\n      response.blocks,\n      emitEncryptedReasoning,\n      synthesizeSummarylessReasoning,\n    );\n\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Text response\n  if (isTextResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n\n    const events = buildTextStreamEvents(\n      response.content,\n      completionReq.model,\n      chunkSize,\n      resolveReasoningForModel(\n        response.reasoning,\n        completionReq.model,\n        effectiveStrict,\n        defaults.logger,\n      ),\n      response.webSearches,\n      extractOverrides(response),\n      emitEncryptedReasoning,\n      synthesizeSummarylessReasoning,\n    );\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Tool call response\n  if (isToolCallResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n    const events = buildToolCallStreamEvents(\n      response.toolCalls,\n      completionReq.model,\n      chunkSize,\n      // Gate the synthesized reasoning channel on the requested model's\n      // capability, matching the WS text / content+tool branches and the HTTP\n      // tool-only path so reasoning emission is transport-independent.\n      resolveReasoningForModel(\n        response.reasoning,\n        completionReq.model,\n        effectiveStrict,\n        defaults.logger,\n      ),\n      response.webSearches,\n      extractOverrides(response),\n      emitEncryptedReasoning,\n      synthesizeSummarylessReasoning,\n    );\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Unknown response type\n  journal.add({\n    method: \"WS\",\n    path: \"/v1/responses\",\n    headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n    body: completionReq,\n    response: { status: 500, fixture },\n  });\n  ws.send(\n    JSON.stringify(\n      buildErrorEvent(\"Fixture response did not match any known type\", \"server_error\"),\n    ),\n  );\n}\n\nasync function sendEvents(\n  ws: WebSocketConnection,\n  events: ResponsesSSEEvent[],\n  latency: number,\n  signal?: AbortSignal,\n  onChunkSent?: () => void,\n  recordedTimings?: import(\"./types.js\").RecordedTimings,\n  replaySpeed?: number,\n): Promise<boolean> {\n  let eventIndex = 0;\n  for (const event of events) {\n    if (ws.isClosed) return false;\n    const chunkDelay = calculateDelay(eventIndex, undefined, latency, recordedTimings, replaySpeed);\n    if (chunkDelay > 0) await delay(chunkDelay, signal);\n    if (signal?.aborted) return false;\n    if (ws.isClosed) return false;\n    ws.send(JSON.stringify(event));\n    eventIndex++;\n    onChunkSent?.();\n    if (signal?.aborted) return false;\n  }\n  return true;\n}\n"],"mappings":"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"}
+{"version":3,"file":"ws-responses.js","names":[],"sources":["../src/ws-responses.ts"],"sourcesContent":["/**\n * WebSocket handler for OpenAI Responses API.\n *\n * Accepts `{ type: \"response.create\", model: \"...\", input: [...] }` messages over\n * WebSocket and sends back the same Responses API SSE events as the HTTP\n * handler, but as individual WebSocket text frames.\n */\n\nimport type { Fixture, HandlerDefaults } from \"./types.js\";\nimport { planMisbehavior, recordMisbehaviorOutcome } from \"./misbehavior.js\";\nimport { matchFixtureDiagnostic } from \"./router.js\";\nimport {\n  responsesToCompletionRequest,\n  requestIncludesEncryptedReasoning,\n  requestWantsEncryptedReasoning,\n  buildTextStreamEvents,\n  toolCallStreamEvents,\n  contentWithToolCallsStreamEvents,\n  prepareResponsesMisbehavior,\n  buildResponsesMisbehavior,\n  type ResponsesSSEEvent,\n  type ResponsesInputItem,\n  type ResponsesToolDef,\n} from \"./responses.js\";\nimport {\n  fixtureToolCallErrorCode,\n  isFixtureToolCallError,\n  isTextResponse,\n  isToolCallResponse,\n  isCombinedFixtureResponse,\n  isErrorResponse,\n  extractOverrides,\n  resolveResponse,\n  resolveStrictMode,\n  resolveReasoningForModel,\n  strictOverrideField,\n  flattenHeaders,\n  strictNoMatchMessage,\n  strictNoMatchLogLine,\n  assertCustomToolCalls,\n  resolveServedBlockOutcome,\n  servedToolCalls,\n  withoutLegacyNamespaces,\n} from \"./helpers.js\";\nimport { createInterruptionSignal } from \"./interruption.js\";\nimport { delay, calculateDelay } from \"./sse-writer.js\";\nimport { DEFAULT_TEST_ID, type Journal } from \"./journal.js\";\nimport type { WebSocketConnection } from \"./ws-framing.js\";\n\ntype ResponsesWebSocketDefaults = Omit<HandlerDefaults, \"replaySpeed\"> & {\n  replaySpeed?: number;\n  model: string;\n  testId?: string;\n  upgradeHeaders?: import(\"node:http\").IncomingHttpHeaders;\n  /** @internal Called before each message is processed (the server assigns fixture positions). */\n  beforeProcessMessage?: () => void;\n};\n\ninterface ResponseCreateMessage {\n  type: \"response.create\";\n  model?: string;\n  input?: unknown[];\n  instructions?: string;\n  tools?: unknown[];\n  tool_choice?: string | object;\n  stream?: boolean;\n  temperature?: number;\n  max_output_tokens?: number;\n  [key: string]: unknown;\n}\n\nfunction isResponseCreateMessage(msg: unknown): msg is ResponseCreateMessage {\n  return (\n    typeof msg === \"object\" &&\n    msg !== null &&\n    (msg as ResponseCreateMessage).type === \"response.create\"\n  );\n}\n\nfunction buildErrorEvent(\n  message: string,\n  type = \"invalid_request_error\",\n  code?: string,\n): ResponsesSSEEvent {\n  return {\n    type: \"error\",\n    error: { message, type, code },\n  };\n}\n\nexport function handleWebSocketResponses(\n  ws: WebSocketConnection,\n  fixtures: Fixture[],\n  journal: Journal,\n  defaults: ResponsesWebSocketDefaults,\n): void {\n  const { logger } = defaults;\n  // Serialize message processing to prevent event interleaving\n  let pending = Promise.resolve();\n  ws.on(\"message\", (raw: string) => {\n    pending = pending.then(async () => {\n      try {\n        defaults.beforeProcessMessage?.();\n        await processMessage(raw, ws, fixtures, journal, defaults);\n      } catch (err: unknown) {\n        const msg = err instanceof Error ? err.message : \"Internal error\";\n        logger.error(`WebSocket responses error: ${msg}`);\n        try {\n          const code = isFixtureToolCallError(err) ? fixtureToolCallErrorCode(err) : undefined;\n          ws.send(JSON.stringify(buildErrorEvent(msg, \"server_error\", code)));\n        } catch (sendErr) {\n          defaults.logger.debug(\n            `Failed to send error to client: ${sendErr instanceof Error ? sendErr.message : \"unknown\"}`,\n          );\n        }\n      }\n    });\n  });\n}\n\nasync function processMessage(\n  raw: string,\n  ws: WebSocketConnection,\n  fixtures: Fixture[],\n  journal: Journal,\n  defaults: ResponsesWebSocketDefaults,\n): Promise<void> {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (parseErr) {\n    const detail = parseErr instanceof Error ? parseErr.message : \"unknown\";\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(`Malformed JSON: ${detail}`, \"invalid_request_error\", \"invalid_json\"),\n      ),\n    );\n    return;\n  }\n\n  if (!isResponseCreateMessage(parsed)) {\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(\n          'Expected message type \"response.create\"',\n          \"invalid_request_error\",\n          \"invalid_message_type\",\n        ),\n      ),\n    );\n    return;\n  }\n\n  const responsesReq = {\n    model: parsed.model ?? defaults.model,\n    // Same shapes as HTTP: namespace / custom tools, additional_tools items\n    // and custom tool call items reach responsesToCompletionRequest unchanged.\n    input: (parsed.input ?? []) as ResponsesInputItem[],\n    instructions: parsed.instructions,\n    tools: parsed.tools as ResponsesToolDef[] | undefined,\n    tool_choice: parsed.tool_choice,\n    stream: parsed.stream,\n    temperature: parsed.temperature,\n    max_output_tokens: parsed.max_output_tokens,\n    include: (parsed as { include?: string[] }).include,\n    store: (parsed as { store?: boolean }).store,\n  };\n\n  // Gate encrypted-reasoning emission identically to the HTTP transport so the\n  // agent-framework#7233 stateless-replay path works over WebSocket too.\n  const emitEncryptedReasoning = requestWantsEncryptedReasoning(responsesReq);\n  // Synthesizing a reasoning item the fixture never declared takes the NARROWER\n  // explicit-`include` gate, transport-identically to HTTP — a `store: false`\n  // request with a summary-less fixture still gets no reasoning item.\n  const synthesizeSummarylessReasoning = requestIncludesEncryptedReasoning(responsesReq);\n\n  const extendedTools = defaults.responsesTools === \"extended\";\n  const completionReq = responsesToCompletionRequest(responsesReq, {\n    extended: extendedTools,\n    logger: defaults.logger,\n  });\n  completionReq._endpointType = \"chat\";\n  const contextHeader = defaults.upgradeHeaders?.[\"x-aimock-context\"];\n  completionReq._context =\n    typeof contextHeader === \"string\"\n      ? contextHeader\n      : Array.isArray(contextHeader) && contextHeader.length > 0\n        ? contextHeader[0]\n        : undefined;\n  const testId = defaults.testId ?? DEFAULT_TEST_ID;\n  const { fixture, skippedBySequenceOrTurn } = matchFixtureDiagnostic(\n    fixtures,\n    completionReq,\n    journal.getFixtureMatchCountsForTest(testId),\n    defaults.requestTransform,\n  );\n\n  if (fixture) {\n    journal.incrementFixtureMatchCount(fixture, fixtures, testId);\n  }\n\n  if (!fixture) {\n    if (resolveStrictMode(defaults.strict, defaults.upgradeHeaders)) {\n      const strictMessage = strictNoMatchMessage(skippedBySequenceOrTurn);\n      defaults.logger.error(strictNoMatchLogLine(\"WS\", \"/v1/responses\", skippedBySequenceOrTurn));\n      journal.add({\n        method: \"WS\",\n        path: \"/v1/responses\",\n        headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n        body: completionReq,\n        response: {\n          status: 503,\n          fixture: null,\n          ...strictOverrideField(defaults.strict, defaults.upgradeHeaders),\n        },\n      });\n      ws.close(1008, strictMessage);\n      return;\n    }\n    journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: {\n        status: 404,\n        fixture: null,\n        ...strictOverrideField(defaults.strict, defaults.upgradeHeaders),\n      },\n    });\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(\"No fixture matched\", \"invalid_request_error\", \"no_fixture_match\"),\n      ),\n    );\n    return;\n  }\n\n  // Without responsesTools \"extended\", a namespace on a toolCalls entry or a\n  // toolCall block is not emitted, as in earlier releases.\n  const resolvedResponse = await resolveResponse(fixture, completionReq);\n  const response = extendedTools ? resolvedResponse : withoutLegacyNamespaces(resolvedResponse);\n  const misbehaviorDefaults: HandlerDefaults = {\n    ...defaults,\n    replaySpeed: defaults.replaySpeed ?? 1,\n  };\n  const misbehavior = planMisbehavior({\n    wire: \"openai-responses\",\n    fixture,\n    response,\n    request: completionReq,\n    // Responses WebSocket always emits streaming events, even with stream:false.\n    stream: true,\n    emitsToolCallIds: true,\n    defaults: misbehaviorDefaults,\n    // The server has already resolved the upgrade's header/query test ID.\n    rawHeaders: { ...defaults.upgradeHeaders, \"x-test-id\": testId },\n    url: \"/v1/responses\",\n  });\n  const recordOutcome = (entry: ReturnType<Journal[\"add\"]>) =>\n    recordMisbehaviorOutcome({\n      entry,\n      summary: misbehavior.summary,\n      defaults: misbehaviorDefaults,\n      testId,\n    });\n  if (misbehavior.kind === \"error\") {\n    const entry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: misbehavior.status, fixture },\n    });\n    recordOutcome(entry);\n    if (!misbehavior.summary?.evaluations.length) {\n      defaults.logger.error(\n        `[misbehavior] ${misbehavior.code}: ${misbehavior.message} (testId=${testId})`,\n      );\n    }\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(misbehavior.message, \"invalid_request_error\", misbehavior.code),\n      ),\n    );\n    return;\n  }\n  const latency = fixture.latency ?? defaults.latency;\n  const chunkSize = Math.max(1, fixture.chunkSize ?? defaults.chunkSize);\n\n  if (misbehavior.kind === \"applied\") {\n    const prepared = prepareResponsesMisbehavior(misbehavior);\n    const output = buildResponsesMisbehavior(\n      prepared,\n      completionReq,\n      chunkSize,\n      emitEncryptedReasoning,\n    );\n    const entry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n    recordMisbehaviorOutcome({\n      entry,\n      summary: prepared.summary,\n      defaults: misbehaviorDefaults,\n      testId,\n    });\n    const timings = fixture.recordedTimings;\n    const gaps = timings?.interChunkDelaysMs;\n    // K4 can add events; extend only its replay using the last recorded gap.\n    const appliedTimings =\n      prepared.duplicateId && timings && gaps\n        ? {\n            ...timings,\n            interChunkDelaysMs: Array.from(\n              { length: Math.max(gaps.length, output.events.length - 1) },\n              (_, index) => gaps[index] ?? gaps.at(-1) ?? 0,\n            ),\n          }\n        : timings;\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      output.events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      appliedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      entry.response.interrupted = true;\n      entry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // The WS path has no per-request `req.headers`; strict is resolved from the\n  // connection's upgrade headers (see the `!fixture` branch above). Used below\n  // to gate the synthesized reasoning channel on the requested model's capability.\n  const effectiveStrict = resolveStrictMode(defaults.strict, defaults.upgradeHeaders);\n\n  // Error response\n  if (isErrorResponse(response)) {\n    const status = response.status ?? 500;\n    const entry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status, fixture },\n    });\n    recordOutcome(entry);\n    ws.send(\n      JSON.stringify(\n        buildErrorEvent(response.error.message, response.error.type, response.error.code),\n      ),\n    );\n    return;\n  }\n\n  // Content + tool calls response (must be checked before isTextResponse / isToolCallResponse)\n  if (isCombinedFixtureResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n    recordOutcome(journalEntry);\n\n    let events: ResponsesSSEEvent[];\n    try {\n      const ordered = resolveServedBlockOutcome(response)?.ordered;\n      if (!ordered) assertCustomToolCalls(response);\n      events = contentWithToolCallsStreamEvents(\n        response.content ?? \"\",\n        servedToolCalls(response),\n        completionReq.model,\n        chunkSize,\n        resolveReasoningForModel(\n          response.reasoning,\n          completionReq.model,\n          effectiveStrict,\n          defaults.logger,\n        ),\n        response.webSearches,\n        extractOverrides(response),\n        ordered,\n        emitEncryptedReasoning,\n        synthesizeSummarylessReasoning,\n      );\n    } catch (error) {\n      journalEntry.response.status = 500;\n      if (isFixtureToolCallError(error)) journalEntry.response.error = error.message;\n      throw error;\n    }\n\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Text response\n  if (isTextResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n    recordOutcome(journalEntry);\n\n    const events = buildTextStreamEvents(\n      response.content,\n      completionReq.model,\n      chunkSize,\n      resolveReasoningForModel(\n        response.reasoning,\n        completionReq.model,\n        effectiveStrict,\n        defaults.logger,\n      ),\n      response.webSearches,\n      extractOverrides(response),\n      emitEncryptedReasoning,\n      synthesizeSummarylessReasoning,\n    );\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Tool call response\n  if (isToolCallResponse(response)) {\n    const journalEntry = journal.add({\n      method: \"WS\",\n      path: \"/v1/responses\",\n      headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n      body: completionReq,\n      response: { status: 200, fixture },\n    });\n    recordOutcome(journalEntry);\n    let events: ResponsesSSEEvent[];\n    try {\n      assertCustomToolCalls(response);\n      events = toolCallStreamEvents(\n        servedToolCalls(response),\n        completionReq.model,\n        chunkSize,\n        // Gate the synthesized reasoning channel on the requested model's\n        // capability, matching the WS text / content+tool branches and the HTTP\n        // tool-only path so reasoning emission is transport-independent.\n        resolveReasoningForModel(\n          response.reasoning,\n          completionReq.model,\n          effectiveStrict,\n          defaults.logger,\n        ),\n        response.webSearches,\n        extractOverrides(response),\n        emitEncryptedReasoning,\n        synthesizeSummarylessReasoning,\n      );\n    } catch (error) {\n      journalEntry.response.status = 500;\n      if (isFixtureToolCallError(error)) journalEntry.response.error = error.message;\n      throw error;\n    }\n    const interruption = createInterruptionSignal(fixture);\n    const completed = await sendEvents(\n      ws,\n      events,\n      latency,\n      interruption?.signal,\n      interruption?.tick,\n      fixture.recordedTimings,\n      fixture.replaySpeed ?? defaults.replaySpeed,\n    );\n    if (!completed) {\n      ws.destroy();\n      journalEntry.response.interrupted = true;\n      journalEntry.response.interruptReason = interruption?.reason();\n    }\n    interruption?.cleanup();\n    return;\n  }\n\n  // Unknown response type\n  const entry = journal.add({\n    method: \"WS\",\n    path: \"/v1/responses\",\n    headers: flattenHeaders(defaults.upgradeHeaders ?? {}),\n    body: completionReq,\n    response: { status: 500, fixture },\n  });\n  recordOutcome(entry);\n  ws.send(\n    JSON.stringify(\n      buildErrorEvent(\"Fixture response did not match any known type\", \"server_error\"),\n    ),\n  );\n}\n\nasync function sendEvents(\n  ws: WebSocketConnection,\n  events: ResponsesSSEEvent[],\n  latency: number,\n  signal?: AbortSignal,\n  onChunkSent?: () => void,\n  recordedTimings?: import(\"./types.js\").RecordedTimings,\n  replaySpeed?: number,\n): Promise<boolean> {\n  let eventIndex = 0;\n  for (const event of events) {\n    if (ws.isClosed) return false;\n    const chunkDelay = calculateDelay(eventIndex, undefined, latency, recordedTimings, replaySpeed);\n    if (chunkDelay > 0) await delay(chunkDelay, signal);\n    if (signal?.aborted) return false;\n    if (ws.isClosed) return false;\n    ws.send(JSON.stringify(event));\n    eventIndex++;\n    onChunkSent?.();\n    if (signal?.aborted) return false;\n  }\n  return true;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Mock infrastructure for AI application testing — point your SDK at one local port and every provider, protocol, and service answers deterministically.",
   "license": "MIT",
   "keywords": [
@@ -192,17 +192,27 @@
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@arethetypeswrong/cli": "^0.18.3",
+    "@aws-sdk/client-bedrock-runtime": "^3.1147.0",
+    "@aws-sdk/credential-provider-ini": "3.973.17",
     "@commitlint/cli": "^19.8.1",
     "@commitlint/config-conventional": "^19.8.0",
     "@eslint/js": "^9.30.0",
     "@google/genai": "^1.0.0",
+    "@modelcontextprotocol/client": "2.2.0",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/server-everything": "2026.8.31",
+    "@smithy/node-http-handler": "4.12.1",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "cohere-ai": "^8.1.0",
+    "entities": "^7.0.1",
     "eslint": "^9.30.0",
     "eslint-config-prettier": "^10.1.5",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.2",
+    "ollama": "^0.6.4",
     "openai": "^4.0.0",
+    "openai-current-sdk": "npm:openai@6.49.0",
     "pkg-pr-new": "0.0.86",
     "prettier": "^3.6.2",
     "publint": "^0.3.12",
@@ -210,6 +220,7 @@
     "tsx": "^4.19.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.1",
-    "vitest": "^3.2.1"
+    "vitest": "^3.2.1",
+    "ws": "8.22.0"
   }
 }

package/skills/write-fixtures/SKILL.md

@@ -19,26 +19,27 @@ aimock is a zero-dependency mock infrastructure for AI apps. Fixture-driven. Mul
 
 ## Match Field Reference
 
-| Field                | Type                                      | Matches Against                                                                                                                                                                                                                                                                                                                                                                                                    |
-| -------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `userMessage`        | `string`                                  | Substring of last `role: "user"` message text                                                                                                                                                                                                                                                                                                                                                                      |
-| `userMessage`        | `RegExp`                                  | Pattern test on last `role: "user"` message text                                                                                                                                                                                                                                                                                                                                                                   |
-| `systemMessage`      | `string`                                  | Substring of the concatenated text of every `role: "system"` message in the request. Use to gate a fixture on host-supplied context (persona, agent-context entries) so changes to that context cause the fixture to fall through instead of returning a stale baked response                                                                                                                                      |
-| `systemMessage`      | `string[]`                                | Array of substrings — ALL must be present in the joined system text (AND semantics). Use when the gate must combine multiple non-adjacent tokens whose serialisation order isn't stable                                                                                                                                                                                                                            |
-| `systemMessage`      | `RegExp`                                  | Pattern test on the concatenated system-message text                                                                                                                                                                                                                                                                                                                                                               |
-| `inputText`          | `string`                                  | Substring of embedding input text (concatenated if multiple inputs)                                                                                                                                                                                                                                                                                                                                                |
-| `inputText`          | `RegExp`                                  | Pattern test on embedding input text                                                                                                                                                                                                                                                                                                                                                                               |
-| `toolName`           | `string`                                  | Exact match on any tool in request's `tools[]` array (by `function.name`)                                                                                                                                                                                                                                                                                                                                          |
-| `toolCallId`         | `string`                                  | Exact match on `tool_call_id` of last `role: "tool"` message                                                                                                                                                                                                                                                                                                                                                       |
-| `toolResultContains` | `string`                                  | Substring of the last tool message's text content, gated on that message being the request's LAST message (same rule as `toolCallId`). Discriminates resume paths that share a `tool_call_id` and differ only inside the tool-result payload (e.g. approve `{"chosen_time": …}` vs cancel `{"cancelled": true}`)                                                                                                   |
-| `model`              | `string`                                  | Exact match on `req.model`                                                                                                                                                                                                                                                                                                                                                                                         |
-| `model`              | `RegExp`                                  | Pattern test on `req.model`                                                                                                                                                                                                                                                                                                                                                                                        |
-| `responseFormat`     | `string`                                  | Exact match on `req.response_format.type` (`"json_object"`, `"json_schema"`)                                                                                                                                                                                                                                                                                                                                       |
-| `sequenceIndex`      | `number`                                  | Matches only when this fixture's match count equals the given index (0-based)                                                                                                                                                                                                                                                                                                                                      |
-| `turnIndex`          | `number`                                  | Stateless conversation-depth matching. Counts `role: "assistant"` messages in the request; matches when that count equals the value. `turnIndex: 0` = first turn (no prior assistant messages). Use instead of `sequenceIndex` for shared/deployed instances where stateful counters break under concurrency                                                                                                       |
-| `hasToolResult`      | `boolean`                                 | Stateless tool-message presence matching, scoped to the CURRENT turn (messages after the last `role: "user"` message). `true` matches when a `role: "tool"` message appears after the last user message; `false` matches when none does. (If the request has no user message, the whole conversation is scanned.) Provider-consistent across all aimock handlers (OpenAI, Claude, Gemini, Bedrock, Ollama, Cohere) |
-| `endpoint`           | `string`                                  | Restrict to endpoint type: `"chat"`, `"image"`, `"speech"`, `"transcription"`, `"video"`, `"embedding"`                                                                                                                                                                                                                                                                                                            |
-| `predicate`          | `(req: ChatCompletionRequest) => boolean` | Custom function — full access to request                                                                                                                                                                                                                                                                                                                                                                           |
+| Field                | Type                                      | Matches Against                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userMessage`        | `string`                                  | Substring of last `role: "user"` message text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `userMessage`        | `RegExp`                                  | Pattern test on last `role: "user"` message text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `systemMessage`      | `string`                                  | Substring of the concatenated text of every `role: "system"` message in the request. Use to gate a fixture on host-supplied context (persona, agent-context entries) so changes to that context cause the fixture to fall through instead of returning a stale baked response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `systemMessage`      | `string[]`                                | Array of substrings — ALL must be present in the joined system text (AND semantics). Use when the gate must combine multiple non-adjacent tokens whose serialisation order isn't stable                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `systemMessage`      | `RegExp`                                  | Pattern test on the concatenated system-message text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `inputText`          | `string`                                  | Substring of embedding input text (concatenated if multiple inputs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `inputText`          | `RegExp`                                  | Pattern test on embedding input text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `toolName`           | `string`                                  | Exact match on any tool in request's `tools[]` array (by `function.name`). On the OpenAI Responses API, with `responsesTools: "extended"`, this also includes tools inside a `namespace` tool, `custom` tools (by `name`, in `req.customTools`), and tools in an `additional_tools` or `tool_search_output` input item; by default only top-level function tools, as in 1.44.0. Other Responses tool types (`web_search`, `mcp`, ...) are not visible                                                                                                                                                                                                                                                                                                                                   |
+| `toolNamespace`      | `string`                                  | Exact OpenAI Responses tool namespace; needs `responsesTools: "extended"` (ignored otherwise). Alone: any offered tool sits in it. With `toolName`: one offered tool must carry both (Codex routes by this exact pair). No default namespace is assumed. Chat Completions passes request tools through, so a client-sent top-level `namespace` there also matches. With `"extended"` (`aimock validate --responses-tools extended`), `aimock validate` and `--validate-on-load` warn about a file fixture with `toolNamespace` and an `endpoint` other than `"chat"`. A Responses `namespace` tool with an empty or missing `name` is dropped. Codex names an MCP server's namespace `mcp__<server>` (no trailing `__`). aimock-pytest needs aimock 1.45.0+, its default pin from 0.7.0 |
+| `toolCallId`         | `string`                                  | Exact match on `tool_call_id` of last `role: "tool"` message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `toolResultContains` | `string`                                  | Substring of the last tool message's text content, gated on that message being the request's LAST message (same rule as `toolCallId`). Discriminates resume paths that share a `tool_call_id` and differ only inside the tool-result payload (e.g. approve `{"chosen_time": …}` vs cancel `{"cancelled": true}`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `model`              | `string`                                  | Exact match on `req.model`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `model`              | `RegExp`                                  | Pattern test on `req.model`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `responseFormat`     | `string`                                  | Exact match on `req.response_format.type` (`"json_object"`, `"json_schema"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `sequenceIndex`      | `number`                                  | Matches only when this fixture's match count equals the given index (0-based)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `turnIndex`          | `number`                                  | Stateless conversation-depth matching. Counts `role: "assistant"` messages in the request; matches when that count equals the value. `turnIndex: 0` = first turn (no prior assistant messages). Use instead of `sequenceIndex` for shared/deployed instances where stateful counters break under concurrency                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `hasToolResult`      | `boolean`                                 | Stateless tool-message presence matching, scoped to the CURRENT turn (messages after the last `role: "user"` message). `true` matches when a `role: "tool"` message appears after the last user message; `false` matches when none does. (If the request has no user message, the whole conversation is scanned.) Provider-consistent across all aimock handlers (OpenAI, Claude, Gemini, Bedrock, Ollama, Cohere)                                                                                                                                                                                                                                                                                                                                                                      |
+| `endpoint`           | `string`                                  | Restrict to endpoint type: `"chat"`, `"image"`, `"speech"`, `"transcription"`, `"video"`, `"embedding"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `predicate`          | `(req: ChatCompletionRequest) => boolean` | Custom function — full access to request                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 **AND logic**: all specified fields must match. Empty match `{}` = catch-all.
 
@@ -99,9 +100,29 @@ Multi-part content (e.g., `[{type: "text", text: "hello"}]`) is automatically ex
 
 **Both object and string forms are accepted** for `arguments`. The fixture loader auto-stringifies objects via `JSON.stringify()`. Object form is preferred for readability.
 
+**OpenAI Responses API only** — namespaced and custom tool calls (used by Codex for MCP tools, sub-agents and `apply_patch`). Start the server with `responsesTools: "extended"` (`--responses-tools extended`): it makes namespaced, custom and `additional_tools` tools visible to `toolName` and predicates, counts custom tool rounds for `hasToolResult` / `toolCallId` / `turnIndex`, emits a `toolCalls` entry's `namespace`, and records namespaces and custom calls. The default (`"legacy"`) behaves exactly like 1.44.0. `toolNamespace`, `customToolCalls` and `responsesBlocks` also need `"extended"`; the default ignores them.
+
+```typescript
+const response = {
+  toolCalls: [
+    // function call to a tool offered inside a `namespace` tool
+    {
+      name: "spawn_agent",
+      namespace: "collaboration",
+      arguments: JSON.stringify({ message: "..." }),
+    },
+  ],
+  // custom (freeform) tool calls: free-text `input`, never parsed or stringified,
+  // emitted after the function calls. A custom-only turn sets `toolCalls: []`.
+  customToolCalls: [{ name: "apply_patch", input: "*** Begin Patch\n...\n*** End Patch\n" }],
+};
+```
+
+A `toolCalls` entry is always a function call; a `type` or `input` on it is ignored (as in 1.44.0). To interleave custom calls with text or function calls, use `responsesBlocks` (the `blocks` entries plus `{ "type": "customToolCall", "name", "input", "id"?, "namespace"? }`); a fixture may not set both `blocks` and `responsesBlocks`. Every other API (Chat Completions, Anthropic Messages, Gemini, Gemini Interactions, Bedrock, Ollama, Cohere, Realtime, Gemini Live) ignores `namespace` and rejects a fixture with custom calls before any content with code `aimock_unsupported_tool_call` (Ollama `/api/generate` keeps its HTTP 400 for every tool-call fixture); a `responsesBlocks` without custom calls is served there as `blocks`. A malformed `customToolCalls` entry or `responsesBlocks` tool block fails validation (`aimock validate`, `--validate-on-load`, `addFixturesFromJSON()`, `POST /__aimock/fixtures`); in a programmatic, factory or unvalidated file fixture it fails the Responses request with code `aimock_invalid_fixture_tool_call`. Fixtures that 1.44.0 accepted get no new validation finding and no new error. Where the code goes: `error.code` (OpenAI Chat / Responses, Azure, Cohere, Anthropic, Gemini Interactions); `error.metadata.reason` (OpenRouter Chat); a `google.rpc.ErrorInfo` detail (Gemini, Vertex AI, Gemini Live error frame with `code` 13); `reason` (Bedrock); `code` next to `error` (Ollama `/api/chat`); an `error` event's `error.code` (Responses WebSocket); `response.done` with `status: "failed"` and `status_details.error.code` (Realtime). For Codex, gate the turn-0 fixture with `hasToolResult: false` and the follow-up with `hasToolResult: true`, or the turn-0 fixture matches again and the agent loops. A fixture that matches only on `toolName` / `toolNamespace` loops the same way, because Codex offers the same tools on every request.
+
 ### Blocks (ordered text / tool-call streaming)
 
-The optional `blocks` array expresses an explicit, ordered sequence of stream entries — something plain `content` + `toolCalls` cannot, since those imply text-then-tools. Each entry is either `{ "type": "text", "text": "..." }` or `{ "type": "toolCall", "name": "...", "arguments": "...", "id"?: "..." }`, streamed in array order. This enables tool-first ordering (a tool call before any text) and interleaved text/tool ordering.
+The optional `blocks` array expresses an explicit, ordered sequence of stream entries — something plain `content` + `toolCalls` cannot, since those imply text-then-tools. Each entry is `{ "type": "text", "text": "..." }`, `{ "type": "toolCall", "name": "...", "arguments": "...", "id"?: "...", "namespace"?: "..." }`, streamed in array order (OpenAI Responses `responsesBlocks` also take `customToolCall` blocks). This enables tool-first ordering (a tool call before any text) and interleaved text/tool ordering.
 
 ```typescript
 // Tool-first: tool call streams before the text
@@ -192,6 +213,114 @@ The optional `chaos` field on a fixture enables probabilistic failure injection:
 
 Rates are evaluated per-request. When triggered, the chaos failure replaces the normal response.
 
+### Bad model output and retry recovery
+
+Use `misbehavior` to change a valid fixture response. Keep `chaos` for transport failures.
+Semantic fault support varies by wire, fault, and mode; consult the [support matrix](../../docs/model-misbehavior/index.html#support) before authoring a fixture. The example below uses `openai-chat`, including Azure and OpenRouter chat endpoints.
+Local support does not establish native fidelity; preserve the [modeled contracts and native capture limits](../../docs/model-misbehavior/index.html#fidelity).
+
+Save this fixture as `bad-tool.json`. Its first matching request receives invalid tool JSON; the next receives valid arguments.
+
+```json
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "weather", "endpoint": "chat" },
+      "response": {
+        "toolCalls": [{ "id": "call_weather", "name": "weather", "arguments": { "city": "Paris" } }]
+      },
+      "misbehavior": {
+        "seed": 42,
+        "faults": [
+          {
+            "fault": "tool-args-invalid-json",
+            "style": "trailing-comma",
+            "times": 1,
+            "providers": ["openai-chat"]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Check application parsing and recovery explicitly. An HTTP 200 with bad arguments does not trigger the SDK's HTTP retry logic.
+For Vitest, use the real local server and official SDK:
+
+```typescript
+import OpenAI from "openai";
+import { LLMock } from "@copilotkit/aimock";
+import { expect } from "vitest";
+
+const mock = new LLMock();
+mock.loadFixtureFile("bad-tool.json");
+await mock.start();
+try {
+  const client = new OpenAI({
+    apiKey: "local",
+    baseURL: `${mock.url}/v1`,
+    maxRetries: 0,
+    defaultHeaders: { "X-Test-Id": "retry-tool" },
+  });
+  const request = {
+    model: "gpt-4",
+    messages: [{ role: "user", content: "weather" }],
+  } as const;
+  const first = await client.chat.completions.create({
+    ...request,
+    messages: [...request.messages],
+  });
+  const bad = first.choices[0].message.tool_calls?.[0].function.arguments;
+  expect(bad).toBeDefined();
+  expect(() => JSON.parse(bad!)).toThrow(SyntaxError);
+  const second = await client.chat.completions.create({
+    ...request,
+    messages: [...request.messages],
+  });
+  expect(JSON.parse(second.choices[0].message.tool_calls![0].function.arguments)).toEqual({
+    city: "Paris",
+  });
+  expect(mock.journal.getAll()[0].response.misbehavior).toMatchObject({
+    applied: true,
+    source: "fixture",
+    wire: "openai-chat",
+    fault: "tool-args-invalid-json",
+  });
+} finally {
+  await mock.stop();
+}
+```
+
+Keep the same test ID for both attempts. `times` counts firings per source, entry and test ID, not matching requests.
+Use `mock.resetMatchCounts("retry-tool")` to restart that test's counters. Clearing journal entries alone preserves fault counters.
+
+A configuration accepts a fault ID string or `{ seed, faults }`. Use `{ faults: [] }` for an explicit opt-out.
+Only `POST /__aimock/misbehavior` accepts bare `{}` as an opt-out.
+Each entry accepts `rate` from 0 to 1, positive integer `times`, a `tool` selector and a `providers` wire list.
+The default rate is 1. An omitted `times` has no firing limit. The default seed is 0; `"random"` selects one process seed.
+
+| Fault                        | Fault-specific configuration                                                                                                  |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `tool-args-invalid-json`     | `style`: `truncated` (default), `trailing-comma`, `single-quotes`                                                             |
+| `tool-args-schema-violation` | `violation`: `missing-required` (default), `wrong-type`, `extra-property`, `enum-mismatch`, `not-object`; optional `property` |
+| `tool-unknown-name`          | Optional `name`                                                                                                               |
+| `tool-call-id-duplicate`     | No extra parameters; requires at least one call on an ID-emitting wire; duplicates the sole call when only one exists         |
+| `stop-length-mid-tool`       | `at` strictly between 0 and 1; default 0.5; emits a clean `length` stop with partial arguments                                |
+| `empty-response`             | No extra parameters                                                                                                           |
+| `refusal`                    | Optional `message`; keep `category` null or omitted on OpenAI Chat                                                            |
+| `content-filter`             | No extra parameters                                                                                                           |
+| `reasoning-only`             | Optional `reasoning`; OpenRouter emits `reasoning` with `reasoning_details`; native OpenAI exposes no reasoning               |
+
+For schema violations, send the tool schema in the request. Use direct schema constraints; do not assume `$ref` or combinator support.
+Selection order is HTTP header, fixture, runtime scope, then server baseline. Selected configurations replace one another; they do not merge.
+Fixture and header faults that cannot apply fail loudly. Runtime and server faults that cannot apply are skipped.
+Bad fixture configuration throws `FixtureLoadError` with a `misbehavior/` rule, including CLI loads without `--validate-on-load`.
+Bad server configuration or setter input throws a rule-prefixed `TypeError`.
+Check `response.misbehavior.evaluations` in the journal for skips, exhausted budgets and provider exclusions.
+Check actual SDK output too: `servedToolCalls` describes the prepared response, not proof of network delivery.
+See the [control API](https://aimock.copilotkit.dev/control-api#misbehavior) for runtime scope, validation errors and header grammar.
+
 ## Common Patterns
 
 ### Basic text fixture
@@ -518,6 +647,9 @@ mock.on(
 | Reasoning            | Yes         | Yes              | Yes    | Yes    | --          | Yes     | Yes   | --     | --     | Yes        |
 | Web Searches         | --          | Yes              | --     | --     | --          | --      | --    | --     | --     | --         |
 | Response Overrides   | Yes         | Yes              | Yes    | Yes    | Yes         | --      | Yes   | --     | --     | Yes        |
+| Custom Tool Calls    | Error       | Yes              | Error  | Error  | Error       | Error   | Error | Error  | Error  | Error      |
+
+Custom tool calls (`customToolCalls` / `customToolCall` blocks in `responsesBlocks`): "Error" means the request fails before any content with code `aimock_unsupported_tool_call`. The Ollama column is `/api/chat`; `/api/generate` rejects every tool-call fixture, custom calls included, with HTTP 400 (`invalid_request_error`) and no aimock code. The Azure column is the deployment route (`/openai/deployments/{id}/chat/completions`) and the OpenRouter column is `/api/v1/chat/completions`. aimock serves `/openai/v1/responses` and OpenRouter's `/api/v1/responses` with its OpenAI Responses handler, so custom tool calls work there. Realtime and Gemini Live WebSockets also reject them.
 
 ## Critical Gotchas
 
@@ -839,3 +971,29 @@ mock.disableRecording();
 2. **Review**: Check the recorded fixtures in `{fixturePath}/recorded/`. Edit or reorganize as needed.
 3. **Lock down**: Run your test suite with `--strict` to ensure every request hits a fixture. No network calls escape.
 4. **Maintain**: When APIs change, delete stale fixtures and re-record.
+
+## MCP Recording and Fake Reports (1.45.0+)
+
+### Record a live MCP server
+
+```bash
+npx -p @copilotkit/aimock llmock -f ./fixtures \
+  --mcp-record /mcp=http://localhost:3001/mcp
+```
+
+- `--mcp-record <mount>=<url>` (repeatable) is on the `llmock` bin and the Docker image, not on `aimock --config`. It needs a local `--fixtures` path. `--mcp-proxy-only <mount>=<url>` forwards without writing and needs no `--fixtures`.
+- With `aimock --config`, set `llm.enableMcpRecording: true` and use `llm.record.mcp`: `{ "/mcp": "http://localhost:3001/mcp" }`, or an object with `upstream`, `fixturePath`, `proxyOnly`, `upstreamAuth`, `secretValues`, `strict`, `maxRecordBufferBytes`. Without the opt-in, `llm.record.mcp` is ignored with a warning. `llm.record.mcp` alone does not turn on LLM recording.
+- In code: `mcpMock.enableRecording({ upstream, ... })` and `disableRecording()`.
+- Every MCP request needs a test id (`X-Test-Id`, percent-encoded, or `?testId=`) or a context. Without one, the call is forwarded but not written.
+- The recording lands at `<fixtures>/recorded/<slugified test id>/mcp.json`. Replay it by starting aimock with the same `--fixtures` and no `--mcp-record`. A changed call then fails with `MCP_FAKE_MISMATCH`.
+- A call the file already answers is answered from the file, not forwarded. Delete the file to re-record.
+- Secrets: headers are never written; known secrets become `[REDACTED]` with a `_warnings` pointer. Add custom secret values with `AIMOCK_RECORD_SECRET_VALUES` (newline-separated, each at least 8 characters). Set an upstream credential with `AIMOCK_MCP_UPSTREAM_AUTH="Name: value"`. OAuth is not supported through the recorder.
+- Recorded `mcpFakes` files may hold `list`, `recorded` and `timing` (block) and `notifications` and `durationMs` (call entry). Older aimock versions reject them. Replay sends recorded progress notifications (as SSE) at the recorded timing, scaled by `--replay-speed`. Recorded log notifications replay only after the client calls `logging/setLevel`.
+
+### Fail a test on a swallowed or unused fake
+
+- `GET /__aimock/mcp/fakes/report?testId=<id>` returns `{ ok, served, unconsumed, failures, unfaked, sharedUnconsumed, evicted }` for one test id.
+- `useAimock({ fixtures, fakesReport: "fail" })` (Vitest or Jest) checks each test's report in `afterEach` and throws `AimockFakesReportError` when a fake error was swallowed by the agent or a declared entry was never used. `"warn"` prints instead.
+- `mock().fakesFor()` returns `{ testId, mcpUrl, headers }` for the current test. The default test id is `<file> › <describe> › <test>` (Vitest; Jest joins the names with spaces). Scope the `mcpFakes` block to that id. Pass an explicit id for concurrent tests and, in Jest, for duplicate test names.
+- `assertFakesReport(report)` does the same check anywhere. In pytest: `aimock.fakes_for()`, `aimock.fakes_report()` and `aimock.assert_fakes_report()`; the default id is the pytest node id.
+- Fakes work for any caller over MCP HTTP: agents, Mastra Workflow steps, LangGraph nodes and plain functions.