@copilotkit/aimock 1.45.1 → 1.47.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 { 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":";;;;;;;;;;AAuEA,SAAS,wBAAwB,KAA4C;AAC3E,QACE,OAAO,QAAQ,YACf,QAAQ,QACP,IAA8B,SAAS;;AAI5C,SAAS,gBACP,SACA,OAAO,yBACP,MACmB;AACnB,QAAO;EACL,MAAM;EACN,OAAO;GAAE;GAAS;GAAM;GAAM;EAC/B;;AAGH,SAAgB,yBACd,IACA,UACA,SACA,UACM;CACN,MAAM,EAAE,WAAW;CAEnB,IAAI,UAAU,QAAQ,SAAS;AAC/B,IAAG,GAAG,YAAY,QAAgB;AAChC,YAAU,QAAQ,KAAK,YAAY;AACjC,OAAI;AACF,aAAS,wBAAwB;AACjC,UAAM,eAAe,KAAK,IAAI,UAAU,SAAS,SAAS;YACnD,KAAc;IACrB,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU;AACjD,WAAO,MAAM,8BAA8B,MAAM;AACjD,QAAI;KACF,MAAM,OAAO,uBAAuB,IAAI,GAAG,yBAAyB,IAAI,GAAG;AAC3E,QAAG,KAAK,KAAK,UAAU,gBAAgB,KAAK,gBAAgB,KAAK,CAAC,CAAC;aAC5D,SAAS;AAChB,cAAS,OAAO,MACd,mCAAmC,mBAAmB,QAAQ,QAAQ,UAAU,YACjF;;;IAGL;GACF;;AAGJ,eAAe,eACb,KACA,IACA,UACA,SACA,UACe;CACf,IAAI;AACJ,KAAI;AACF,WAAS,KAAK,MAAM,IAAI;UACjB,UAAU;EACjB,MAAM,SAAS,oBAAoB,QAAQ,SAAS,UAAU;AAC9D,KAAG,KACD,KAAK,UACH,gBAAgB,mBAAmB,UAAU,yBAAyB,eAAe,CACtF,CACF;AACD;;AAGF,KAAI,CAAC,wBAAwB,OAAO,EAAE;AACpC,KAAG,KACD,KAAK,UACH,gBACE,6CACA,yBACA,uBACD,CACF,CACF;AACD;;CAGF,MAAM,eAAe;EACnB,OAAO,OAAO,SAAS,SAAS;EAGhC,OAAQ,OAAO,SAAS,EAAE;EAC1B,cAAc,OAAO;EACrB,OAAO,OAAO;EACd,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,aAAa,OAAO;EACpB,mBAAmB,OAAO;EAC1B,SAAU,OAAkC;EAC5C,OAAQ,OAA+B;EACxC;CAID,MAAM,yBAAyB,+BAA+B,aAAa;CAI3E,MAAM,iCAAiC,kCAAkC,aAAa;CAEtF,MAAM,gBAAgB,SAAS,mBAAmB;CAClD,MAAM,gBAAgB,6BAA6B,cAAc;EAC/D,UAAU;EACV,QAAQ,SAAS;EAClB,CAAC;AACF,eAAc,gBAAgB;CAC9B,MAAM,gBAAgB,SAAS,iBAAiB;AAChD,eAAc,WACZ,OAAO,kBAAkB,WACrB,gBACA,MAAM,QAAQ,cAAc,IAAI,cAAc,SAAS,IACrD,cAAc,KACd;CACR,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,EAAE,SAAS,4BAA4B,uBAC3C,UACA,eACA,QAAQ,6BAA6B,OAAO,EAC5C,SAAS,iBACV;AAED,KAAI,QACF,SAAQ,2BAA2B,SAAS,UAAU,OAAO;AAG/D,KAAI,CAAC,SAAS;AACZ,MAAI,kBAAkB,SAAS,QAAQ,SAAS,eAAe,EAAE;GAC/D,MAAM,gBAAgB,qBAAqB,wBAAwB;AACnE,YAAS,OAAO,MAAM,qBAAqB,MAAM,iBAAiB,wBAAwB,CAAC;AAC3F,WAAQ,IAAI;IACV,QAAQ;IACR,MAAM;IACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;IACtD,MAAM;IACN,UAAU;KACR,QAAQ;KACR,SAAS;KACT,GAAG,oBAAoB,SAAS,QAAQ,SAAS,eAAe;KACjE;IACF,CAAC;AACF,MAAG,MAAM,MAAM,cAAc;AAC7B;;AAEF,UAAQ,IAAI;GACV,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IACR,QAAQ;IACR,SAAS;IACT,GAAG,oBAAoB,SAAS,QAAQ,SAAS,eAAe;IACjE;GACF,CAAC;AACF,KAAG,KACD,KAAK,UACH,gBAAgB,sBAAsB,yBAAyB,mBAAmB,CACnF,CACF;AACD;;CAKF,MAAM,mBAAmB,MAAM,gBAAgB,SAAS,cAAc;CACtE,MAAM,WAAW,gBAAgB,mBAAmB,wBAAwB,iBAAiB;CAC7F,MAAM,sBAAuC;EAC3C,GAAG;EACH,aAAa,SAAS,eAAe;EACtC;CACD,MAAM,cAAc,gBAAgB;EAClC,MAAM;EACN;EACA;EACA,SAAS;EAET,QAAQ;EACR,kBAAkB;EAClB,UAAU;EAEV,YAAY;GAAE,GAAG,SAAS;GAAgB,aAAa;GAAQ;EAC/D,KAAK;EACN,CAAC;CACF,MAAM,iBAAiB,UACrB,yBAAyB;EACvB;EACA,SAAS,YAAY;EACrB,UAAU;EACV;EACD,CAAC;AACJ,KAAI,YAAY,SAAS,SAAS;AAQhC,gBAPc,QAAQ,IAAI;GACxB,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE,QAAQ,YAAY;IAAQ;IAAS;GAClD,CAAC,CACkB;AACpB,MAAI,CAAC,YAAY,SAAS,YAAY,OACpC,UAAS,OAAO,MACd,iBAAiB,YAAY,KAAK,IAAI,YAAY,QAAQ,WAAW,OAAO,GAC7E;AAEH,KAAG,KACD,KAAK,UACH,gBAAgB,YAAY,SAAS,yBAAyB,YAAY,KAAK,CAChF,CACF;AACD;;CAEF,MAAM,UAAU,QAAQ,WAAW,SAAS;CAC5C,MAAM,YAAY,KAAK,IAAI,GAAG,QAAQ,aAAa,SAAS,UAAU;AAEtE,KAAI,YAAY,SAAS,WAAW;EAClC,MAAM,WAAW,4BAA4B,YAAY;EACzD,MAAM,SAAS,0BACb,UACA,eACA,WACA,uBACD;EACD,MAAM,QAAQ,QAAQ,IAAI;GACxB,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE,QAAQ;IAAK;IAAS;GACnC,CAAC;AACF,2BAAyB;GACvB;GACA,SAAS,SAAS;GAClB,UAAU;GACV;GACD,CAAC;EACF,MAAM,UAAU,QAAQ;EACxB,MAAM,OAAO,SAAS;EAEtB,MAAM,iBACJ,SAAS,eAAe,WAAW,OAC/B;GACE,GAAG;GACH,oBAAoB,MAAM,KACxB,EAAE,QAAQ,KAAK,IAAI,KAAK,QAAQ,OAAO,OAAO,SAAS,EAAE,EAAE,GAC1D,GAAG,UAAU,KAAK,UAAU,KAAK,GAAG,GAAG,IAAI,EAC7C;GACF,GACD;EACN,MAAM,eAAe,yBAAyB,QAAQ;AAUtD,MAAI,CATc,MAAM,WACtB,IACA,OAAO,QACP,SACA,cAAc,QACd,cAAc,MACd,gBACA,QAAQ,eAAe,SAAS,YACjC,EACe;AACd,MAAG,SAAS;AACZ,SAAM,SAAS,cAAc;AAC7B,SAAM,SAAS,kBAAkB,cAAc,QAAQ;;AAEzD,gBAAc,SAAS;AACvB;;CAMF,MAAM,kBAAkB,kBAAkB,SAAS,QAAQ,SAAS,eAAe;AAGnF,KAAI,gBAAgB,SAAS,EAAE;EAC7B,MAAM,SAAS,SAAS,UAAU;AAQlC,gBAPc,QAAQ,IAAI;GACxB,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE;IAAQ;IAAS;GAC9B,CAAC,CACkB;AACpB,KAAG,KACD,KAAK,UACH,gBAAgB,SAAS,MAAM,SAAS,SAAS,MAAM,MAAM,SAAS,MAAM,KAAK,CAClF,CACF;AACD;;AAIF,KAAI,0BAA0B,SAAS,EAAE;EACvC,MAAM,eAAe,QAAQ,IAAI;GAC/B,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE,QAAQ;IAAK;IAAS;GACnC,CAAC;AACF,gBAAc,aAAa;EAE3B,IAAI;AACJ,MAAI;GACF,MAAM,UAAU,0BAA0B,SAAS,EAAE;AACrD,OAAI,CAAC,QAAS,uBAAsB,SAAS;AAC7C,YAAS,iCACP,SAAS,WAAW,IACpB,gBAAgB,SAAS,EACzB,cAAc,OACd,WACA,yBACE,SAAS,WACT,cAAc,OACd,iBACA,SAAS,OACV,EACD,SAAS,aACT,iBAAiB,SAAS,EAC1B,SACA,wBACA,+BACD;WACM,OAAO;AACd,gBAAa,SAAS,SAAS;AAC/B,OAAI,uBAAuB,MAAM,CAAE,cAAa,SAAS,QAAQ,MAAM;AACvE,SAAM;;EAGR,MAAM,eAAe,yBAAyB,QAAQ;AAUtD,MAAI,CATc,MAAM,WACtB,IACA,QACA,SACA,cAAc,QACd,cAAc,MACd,QAAQ,iBACR,QAAQ,eAAe,SAAS,YACjC,EACe;AACd,MAAG,SAAS;AACZ,gBAAa,SAAS,cAAc;AACpC,gBAAa,SAAS,kBAAkB,cAAc,QAAQ;;AAEhE,gBAAc,SAAS;AACvB;;AAIF,KAAI,eAAe,SAAS,EAAE;EAC5B,MAAM,eAAe,QAAQ,IAAI;GAC/B,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE,QAAQ;IAAK;IAAS;GACnC,CAAC;AACF,gBAAc,aAAa;EAE3B,MAAM,SAAS,sBACb,SAAS,SACT,cAAc,OACd,WACA,yBACE,SAAS,WACT,cAAc,OACd,iBACA,SAAS,OACV,EACD,SAAS,aACT,iBAAiB,SAAS,EAC1B,wBACA,+BACD;EACD,MAAM,eAAe,yBAAyB,QAAQ;AAUtD,MAAI,CATc,MAAM,WACtB,IACA,QACA,SACA,cAAc,QACd,cAAc,MACd,QAAQ,iBACR,QAAQ,eAAe,SAAS,YACjC,EACe;AACd,MAAG,SAAS;AACZ,gBAAa,SAAS,cAAc;AACpC,gBAAa,SAAS,kBAAkB,cAAc,QAAQ;;AAEhE,gBAAc,SAAS;AACvB;;AAIF,KAAI,mBAAmB,SAAS,EAAE;EAChC,MAAM,eAAe,QAAQ,IAAI;GAC/B,QAAQ;GACR,MAAM;GACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;GACtD,MAAM;GACN,UAAU;IAAE,QAAQ;IAAK;IAAS;GACnC,CAAC;AACF,gBAAc,aAAa;EAC3B,IAAI;AACJ,MAAI;AACF,yBAAsB,SAAS;AAC/B,YAAS,qBACP,gBAAgB,SAAS,EACzB,cAAc,OACd,WAIA,yBACE,SAAS,WACT,cAAc,OACd,iBACA,SAAS,OACV,EACD,SAAS,aACT,iBAAiB,SAAS,EAC1B,wBACA,+BACD;WACM,OAAO;AACd,gBAAa,SAAS,SAAS;AAC/B,OAAI,uBAAuB,MAAM,CAAE,cAAa,SAAS,QAAQ,MAAM;AACvE,SAAM;;EAER,MAAM,eAAe,yBAAyB,QAAQ;AAUtD,MAAI,CATc,MAAM,WACtB,IACA,QACA,SACA,cAAc,QACd,cAAc,MACd,QAAQ,iBACR,QAAQ,eAAe,SAAS,YACjC,EACe;AACd,MAAG,SAAS;AACZ,gBAAa,SAAS,cAAc;AACpC,gBAAa,SAAS,kBAAkB,cAAc,QAAQ;;AAEhE,gBAAc,SAAS;AACvB;;AAWF,eAPc,QAAQ,IAAI;EACxB,QAAQ;EACR,MAAM;EACN,SAAS,eAAe,SAAS,kBAAkB,EAAE,CAAC;EACtD,MAAM;EACN,UAAU;GAAE,QAAQ;GAAK;GAAS;EACnC,CAAC,CACkB;AACpB,IAAG,KACD,KAAK,UACH,gBAAgB,iDAAiD,eAAe,CACjF,CACF;;AAGH,eAAe,WACb,IACA,QACA,SACA,QACA,aACA,iBACA,aACkB;CAClB,IAAI,aAAa;AACjB,MAAK,MAAM,SAAS,QAAQ;AAC1B,MAAI,GAAG,SAAU,QAAO;EACxB,MAAM,aAAa,eAAe,YAAY,QAAW,SAAS,iBAAiB,YAAY;AAC/F,MAAI,aAAa,EAAG,OAAM,MAAM,YAAY,OAAO;AACnD,MAAI,QAAQ,QAAS,QAAO;AAC5B,MAAI,GAAG,SAAU,QAAO;AACxB,KAAG,KAAK,KAAK,UAAU,MAAM,CAAC;AAC9B;AACA,iBAAe;AACf,MAAI,QAAQ,QAAS,QAAO;;AAE9B,QAAO"}
+{"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, JournalEntry, RecordedTimings } 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  journalFixtureToolCallError,\n  isTextResponse,\n  isToolCallResponse,\n  isCombinedFixtureResponse,\n  isErrorResponse,\n  isRawResponse,\n  extractOverrides,\n  resolveResponse,\n  resolveReasoningForModel,\n  flattenHeaders,\n  strictNoMatchMessage,\n  strictNoMatchLogLine,\n  assertCustomToolCalls,\n  resolveServedBlockOutcome,\n  servedToolCalls,\n  withoutLegacyNamespaces,\n} from \"./helpers.js\";\nimport { DEFAULT_TEST_ID, type Journal } from \"./journal.js\";\nimport type { WebSocketConnection } from \"./ws-framing.js\";\nimport { resolveRequestDecisions, strictOverrideField } from \"./response/policy.js\";\nimport { buildOpenAIError } from \"./response/errors.js\";\nimport { markWsTurnStopped, watchWsClose, wsLifecycle } from \"./response/lifecycle.js\";\nimport { runFrameLoop, wsSink, type FrameCodec } from \"./response/frame-loop.js\";\nimport { extendRecordedTimings } from \"./response/timing.js\";\nimport { RAW_MODE_UNAVAILABLE } from \"./response/raw.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: buildOpenAIError({ 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  watchWsClose(ws);\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    // Wire only: recordMatchOptions here would turn on strict turnIndex and the\n    // relaxed-turnIndex warning, which this transport has never had.\n    { wire: \"openai-responses\" },\n  );\n\n  if (fixture) {\n    journal.incrementFixtureMatchCount(fixture, fixtures, testId);\n  }\n\n  if (!fixture) {\n    if (resolveRequestDecisions(defaults.strict, defaults.upgradeHeaders).fixtureMiss) {\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    // Journal first, as HTTP /v1/responses does, so a fixture error thrown\n    // while building leaves a 500 entry that keeps the fixture. Record the\n    // fault only once the reply is built: a thrown error was not served.\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    const prepared = prepareResponsesMisbehavior(misbehavior);\n    const output = journalFixtureToolCallError(entry, () =>\n      buildResponsesMisbehavior(prepared, completionReq, chunkSize, emitEncryptedReasoning),\n    );\n    recordMisbehaviorOutcome({\n      entry,\n      summary: prepared.summary,\n      defaults: misbehaviorDefaults,\n      testId,\n    });\n    // K4 can add events; extend only its replay using the last recorded gap.\n    const appliedTimings = extendRecordedTimings(\n      fixture.recordedTimings,\n      output.events.length,\n      !!prepared.duplicateId,\n    );\n    await deliverTurn(ws, entry, fixture, output.events, {\n      latency,\n      recordedTimings: appliedTimings,\n      replaySpeed: fixture.replaySpeed ?? defaults.replaySpeed,\n    });\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 = resolveRequestDecisions(\n    defaults.strict,\n    defaults.upgradeHeaders,\n  ).reasoningSuppression;\n\n  // Raw passthrough fixtures are served over HTTP only for now. Fail loudly\n  // instead of the generic unknown-type error so the author sees why.\n  if (isRawResponse(response)) {\n    const message = \"raw fixtures are not yet supported on the WebSocket transport\";\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    entry.response.error = message;\n    recordOutcome(entry);\n    defaults.logger.error(`WebSocket responses error: ${RAW_MODE_UNAVAILABLE}: ${message}`);\n    ws.send(JSON.stringify(buildErrorEvent(message, \"server_error\", RAW_MODE_UNAVAILABLE)));\n    return;\n  }\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    await deliverTurn(ws, journalEntry, fixture, events, {\n      latency,\n      recordedTimings: fixture.recordedTimings,\n      replaySpeed: fixture.replaySpeed ?? defaults.replaySpeed,\n    });\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    // A fixture error (malformed citations, a non-image file) marks the entry\n    // a 500 carrying the message before the error event goes out.\n    const events = journalFixtureToolCallError(journalEntry, () =>\n      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    );\n    await deliverTurn(ws, journalEntry, fixture, events, {\n      latency,\n      recordedTimings: fixture.recordedTimings,\n      replaySpeed: fixture.replaySpeed ?? defaults.replaySpeed,\n    });\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    await deliverTurn(ws, journalEntry, fixture, events, {\n      latency,\n      recordedTimings: fixture.recordedTimings,\n      replaySpeed: fixture.replaySpeed ?? defaults.replaySpeed,\n    });\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\n/** WS Responses frames: one JSON text message per event, no head, no trailer. */\nconst wsEventCodec: FrameCodec<ResponsesSSEEvent> = {\n  headers: {},\n  encode: (event) => JSON.stringify(event),\n  checkGoneBeforeDelay: true,\n};\n\n/**\n * Send one turn's events under a WS lifecycle. The lifecycle owns the fixture\n * interruption and also stops the turn when the client closes, so a pending\n * delay ends at once. A stopped turn marks the entry by the shared WS rule\n * ({@link markWsTurnStopped}) and destroys the socket.\n * `streamingProfile` is not applied on this transport, as before.\n */\nasync function deliverTurn(\n  ws: WebSocketConnection,\n  entry: JournalEntry,\n  fixture: Fixture,\n  events: ResponsesSSEEvent[],\n  timing: { latency: number; recordedTimings?: RecordedTimings; replaySpeed?: number },\n): Promise<void> {\n  const lifecycle = wsLifecycle(ws, fixture);\n  try {\n    const completed = await runFrameLoop(wsSink(ws), events, wsEventCodec, timing, {\n      lifecycle,\n      onChunkSent: lifecycle.tick,\n    });\n    if (!completed) {\n      markWsTurnStopped(entry, ws, lifecycle);\n      ws.destroy();\n    }\n  } finally {\n    lifecycle.dispose();\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.45.1",
+  "version": "1.47.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": [
@@ -167,6 +167,8 @@
     "test": "vitest run",
     "test:drift": "vitest run --config vitest.config.drift.ts",
     "test:exports": "publint && attw --pack .",
+    "golden:capture": "tsx scripts/capture-golden.ts",
+    "api:report": "tsx scripts/api-report.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p scripts/tsconfig.json --noEmit",
     "lint": "eslint .",
     "format:check": "prettier --check .",
@@ -198,6 +200,7 @@
     "@commitlint/config-conventional": "^19.8.0",
     "@eslint/js": "^9.30.0",
     "@google/genai": "^1.0.0",
+    "@microsoft/api-extractor": "7.59.4",
     "@modelcontextprotocol/client": "2.2.0",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@modelcontextprotocol/server-everything": "2026.8.31",

package/skills/write-fixtures/SKILL.md

@@ -28,6 +28,7 @@ aimock is a zero-dependency mock infrastructure for AI apps. Fixture-driven. Mul
 | `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `embeddingRequest`   | `{ operation, input, dimensions? }`       | Exact operation (`/api/embed`, `/api/embeddings` or `/v1/embeddings`), input shape and requested dimensions. Recordings set it alongside `inputText` and `model` so batches and widths stay distinct; omit it for broad embedding fixtures                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -197,6 +198,38 @@ Video uses async polling — `POST /v1/videos` creates, `GET /v1/videos/{id}` ch
 { error: { message: "Rate limited", type: "rate_limit_error" }, status: 429 }
 ```
 
+### Raw passthrough (provider events as written)
+
+Prefer the typed responses above: they work on every provider and are drift-checked. Use `raw` only for an event, field or error shape aimock does not model yet (for example a new Responses event type). aimock sends `events` (streaming) or `json` (non-streaming) exactly as written and adds only the named wire's framing.
+
+```typescript
+{
+  raw: {
+    wire: "openai-responses", // required; the fixture matches only this wire
+    events: [
+      {
+        type: "response.output_text.annotation.added",
+        annotation: { type: "url_citation", url: "https://example.com" },
+      },
+    ],
+    json: { id: "resp_1", object: "response", status: "completed", output: [] },
+    status: 200, // optional, 200-599, not 204/304
+    headers: { "x-request-id": "req_1" }, // optional; no content-length/transfer-encoding/connection/content-encoding
+  },
+}
+```
+
+- `wire` is one of `openai-responses`, `openai-chat`, `anthropic`, `gemini`, `gemini-interactions`, `cohere`, `ollama` (`/api/chat`), `ollama-generate` (`/api/generate`), `bedrock-invoke`, `bedrock-converse`. The router skips a raw fixture on every other wire and keeps matching; only a factory that returns a raw fixture for another wire gets a 500.
+- Events on `openai-responses`, `anthropic` and `cohere` need a string `type`; a `bedrock-converse` event is `{ "<eventType>": { …payload } }`.
+- `done: false` (openai-chat only, a boolean) omits `data: [DONE]`.
+- Unless `headers` sets `Content-Type`, a stream gets the typed stream's default headers for its wire (`text/event-stream`, `application/x-ndjson` on Ollama, `application/vnd.amazon.eventstream` on Bedrock) and a non-streaming reply gets `application/json` on every wire. An authored header replaces the default of the same name in any letter case.
+- An error reply (`status` >= 400) is never delayed, streaming or not. With `json`, it answers JSON even to a streaming request.
+- A request whose mode has no body (`events` for streaming, `json` for non-streaming) gets the wire's 500 with `aimock_raw_mode_unavailable`. An invalid raw fixture registered with `on()` or a factory is not checked when added; it gets the same 500 with `aimock_raw_fixture_invalid`, as does a factory result for another wire. Every raw fixture is checked again when it is served. `--validate-on-load` reports invalid fixtures at load. Also invalid: events that are not plain JSON (holes, `undefined`, non-finite numbers, Dates, cycles), a CR or LF in a `type`, `customToolCalls` or `responsesBlocks` next to `raw`, and a raw fixture with its own `misbehavior`. Unknown keys inside `raw` are a warning.
+- `chunkSize` does not apply (each event is one frame). Misbehavior faults skip raw fixtures: a server-level fault is journaled as skipped, an `X-AIMock-Misbehavior` header returns 501 `aimock_misbehavior_not_applicable`, and a fixture's own `misbehavior` makes it invalid (load error, 500 `aimock_raw_fixture_invalid`). Streaming timing, `truncateAfterChunks`, `disconnectAfterMs` and chaos apply.
+- Non-streaming timing: `nonStreamingTiming: true` delays a raw `stream: false` reply on `openai-chat` only; `nonStreamingTimingAllProviders: true` on every raw wire. Either needs `streamingProfile` or `recordedTimings`; the wait is sized from the served JSON.
+- OpenRouter `models` fallback: an `openai-chat` raw fixture with `status` >= 400 fails over like a typed error fixture.
+- Not served over WebSocket Responses yet (error event with code `aimock_raw_mode_unavailable`). Docs: `/raw-passthrough`.
+
 ### Chaos (Failure Injection)
 
 The optional `chaos` field on a fixture enables probabilistic failure injection:
@@ -533,6 +566,7 @@ All providers share the same fixture pool — write fixtures once, they work for
 | `POST /v1/chat/completions`                                                              | OpenAI        | HTTP      |
 | `POST /v1/responses`                                                                     | OpenAI        | HTTP + WS |
 | `POST /v1/messages`                                                                      | Anthropic     | HTTP      |
+| `POST /v1/messages/count_tokens`                                                         | Anthropic     | HTTP      |
 | `POST /v1/embeddings`                                                                    | OpenAI        | HTTP      |
 | `POST /v1beta/models/{model}:{method}`                                                   | Google Gemini | HTTP      |
 | `POST /model/{modelId}/invoke`                                                           | AWS Bedrock   | HTTP      |
@@ -548,11 +582,13 @@ All providers share the same fixture pool — write fixtures once, they work for
 | `POST /api/chat`                                                                         | Ollama        | HTTP      |
 | `POST /api/generate`                                                                     | Ollama        | HTTP      |
 | `GET /api/tags`                                                                          | Ollama        | HTTP      |
+| `POST /api/embed` · `/api/embeddings`                                                    | Ollama        | HTTP      |
 | `POST /v2/chat`                                                                          | Cohere        | HTTP      |
 | `POST /api/v1/chat/completions`                                                          | OpenRouter    | HTTP      |
 | `GET /api/v1/models` · `/api/v1/key` · `/api/v1/credits`                                 | OpenRouter    | HTTP      |
 | `GET /metrics`                                                                           | —             | HTTP      |
-| `GET /v1/models`                                                                         | OpenAI-compat | HTTP      |
+| `GET /v1/models` · `/v1/models/{id}`                                                     | OpenAI-compat | HTTP      |
+| `GET /v1beta/models` · `/v1beta/models/{model}`                                          | Google Gemini | HTTP      |
 | `WS /v1/responses`                                                                       | OpenAI        | WebSocket |
 | `WS /v1/realtime`                                                                        | OpenAI        | WebSocket |
 | `WS /ws/google.ai...BidiGenerateContent`                                                 | Gemini Live   | WebSocket |
@@ -563,23 +599,28 @@ All providers share the same fixture pool — write fixtures once, they work for
 | `POST /v1/videos`                                                                        | OpenAI        | HTTP      |
 | `GET /v1/videos/{id}`                                                                    | OpenAI        | HTTP      |
 
+`GET /v1/models` returns the OpenAI-format list by default. With `policy.modelCatalog: "native"` (or `--policy modelCatalog=native`, or the `X-AIMock-Policy: modelCatalog=native` header), it returns the Anthropic list (native paging, `after_id` / `before_id`) when the request has `anthropic-version`, or `x-api-key` without `Authorization`; other callers still get the OpenAI format. `GET /v1/models/{id}` uses the same header selection without the opt-in. Catalogs list the fixture model IDs. Catalog and count routes (`count_tokens`, Gemini `:countTokens`) never proxy or record. Counts are a deterministic estimate of about 1 token per 4 characters of messages (plus tool definitions), minimum 1, and ignore fixture `usage`.
+
 ## Response Template Overrides
 
 Fixture responses can include optional override fields to control auto-generated envelope values. These are merged into the provider-specific response format (OpenAI, Claude, Gemini, Responses API).
 
-| Field                | Type   | Default                   | Description                                                                                                                                                                                                                                                                |
-| -------------------- | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                 | string | auto-generated            | Override response ID (e.g., `chatcmpl-custom`)                                                                                                                                                                                                                             |
-| `created`            | number | `Date.now()/1000`         | Override Unix timestamp                                                                                                                                                                                                                                                    |
-| `model`              | string | echoes request            | Override model name in response                                                                                                                                                                                                                                            |
-| `usage`              | object | zeroed                    | Override token counts: `{ prompt_tokens, completion_tokens, total_tokens }`. OpenAI Chat includes usage in response body; Responses API uses `response.usage`. When omitted, auto-computed from content length                                                             |
-| `finishReason`       | string | `"stop"` / `"tool_calls"` | Override finish reason. Mappings: `stop` -> `end_turn` (Claude), `STOP` (Gemini); `tool_calls` -> `tool_use` (Claude), `FUNCTION_CALL` (Gemini); `length` -> `max_tokens` (Claude), `MAX_TOKENS` (Gemini); `content_filter` -> `SAFETY` (Gemini), `failed` (Responses API) |
-| `role`               | string | `"assistant"`             | Override message role                                                                                                                                                                                                                                                      |
-| `systemFingerprint`  | string | (omitted)                 | Add `system_fingerprint` to response                                                                                                                                                                                                                                       |
-| `provider`           | string | slug author               | OpenRouter only: top-level serving-provider display name (default = the winning model slug's author). Override to assert who served the request                                                                                                                            |
-| `nativeFinishReason` | string | mirrors `finishReason`    | OpenRouter only: the raw upstream `native_finish_reason` alongside the normalized `finish_reason`                                                                                                                                                                          |
-| `usage.cost`         | number | (omitted)                 | OpenRouter only: per-request `usage.cost` (scriptable — powers budget-guard tests). When set, `usage.cost_details` is emitted too. Never fabricated when omitted                                                                                                           |
-| `usage.is_byok`      | bool   | (omitted)                 | OpenRouter only: emit `usage.is_byok`. Also `usage.prompt_tokens_details`, `usage.completion_tokens_details` — emitted only when set                                                                                                                                       |
+| Field                | Type                             | Default                   | Description                                                                                                                                                                                                                                                                                           |
+| -------------------- | -------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                 | string                           | auto-generated            | Override response ID (e.g., `chatcmpl-custom`)                                                                                                                                                                                                                                                        |
+| `created`            | number                           | `Date.now()/1000`         | Override Unix timestamp                                                                                                                                                                                                                                                                               |
+| `model`              | string                           | echoes request            | Override model name in response                                                                                                                                                                                                                                                                       |
+| `usage`              | object                           | zeroed                    | Override token counts: `{ prompt_tokens, completion_tokens, total_tokens }`. OpenAI Chat includes usage in response body; Responses API uses `response.usage`. When omitted, auto-computed from content length                                                                                        |
+| `finishReason`       | string                           | `"stop"` / `"tool_calls"` | Override finish reason. Mappings: `stop` -> `end_turn` (Claude), `STOP` (Gemini); `tool_calls` -> `tool_use` (Claude), `FUNCTION_CALL` (Gemini); `length` -> `max_tokens` (Claude), `MAX_TOKENS` (Gemini); `content_filter` -> `SAFETY` (Gemini), `failed` (Responses API)                            |
+| `role`               | string                           | `"assistant"`             | Override message role                                                                                                                                                                                                                                                                                 |
+| `phase`              | `"commentary" \| "final_answer"` | (omitted)                 | OpenAI Responses API (HTTP and WebSocket) only: labels each assistant `message` output item. Preserved in streaming added/done items, the completed response, and non-streaming output. Omitted by default; never inferred from content or finish reason. Does not label reasoning or tool-call items |
+| `systemFingerprint`  | string                           | (omitted)                 | Add `system_fingerprint` to response                                                                                                                                                                                                                                                                  |
+| `provider`           | string                           | slug author               | OpenRouter only: top-level serving-provider display name (default = the winning model slug's author). Override to assert who served the request                                                                                                                                                       |
+| `nativeFinishReason` | string                           | mirrors `finishReason`    | OpenRouter only: the raw upstream `native_finish_reason` alongside the normalized `finish_reason`                                                                                                                                                                                                     |
+| `usage.cost`         | number                           | (omitted)                 | OpenRouter only: per-request `usage.cost` (scriptable — powers budget-guard tests). When set, `usage.cost_details` is emitted too. Never fabricated when omitted                                                                                                                                      |
+| `usage.is_byok`      | bool                             | (omitted)                 | OpenRouter only: emit `usage.is_byok`. Also `usage.prompt_tokens_details`, `usage.completion_tokens_details` — emitted only when set                                                                                                                                                                  |
+
+Claude Messages and Bedrock Claude invoke also emit `usage.cache_read_input_tokens`, `usage.cache_creation_input_tokens` and a `usage.cache_creation` object (`ephemeral_5m_input_tokens`, `ephemeral_1h_input_tokens`) when a fixture supplies them.
 
 ### Example
 
@@ -657,9 +698,9 @@ Custom tool calls (`customToolCalls` / `customToolCall` blocks in `responsesBloc
 
 2. **`arguments` accepts both objects and strings** — `"arguments": {"key":"value"}` (preferred, auto-stringified) or `"arguments": "{\"key\":\"value\"}"` (legacy). The same applies to `content` fields that contain JSON. The fixture loader detects `typeof === "object"` and calls `JSON.stringify()` automatically.
 
-3. **Latency is per-chunk, not total** — `latency: 100` means 100ms between each SSE chunk, not 100ms total response time. Similarly, `truncateAfterChunks` and `disconnectAfterMs` are for simulating stream interruptions (added in v1.3.0).
+3. **Latency is per-chunk, not total** — `latency: 100` means 100ms between each SSE chunk, not 100ms total response time. It never delays a non-streaming (`stream: false`) response, also with `nonStreamingTiming: true` or `nonStreamingTimingAllProviders: true`. Similarly, `truncateAfterChunks` and `disconnectAfterMs` are for simulating stream interruptions (added in v1.3.0).
 
-4. **`streamingProfile` takes precedence over `latency`** — when both are set on a fixture, `streamingProfile` controls timing. Use one or the other.
+4. **`streamingProfile` takes precedence over `latency`** — when both are set on a fixture, `streamingProfile` controls timing. Use one or the other. By default, `streamingProfile` and `recordedTimings` delay only streamed replies: a `stream: false` reply returns immediately, also for recorded fixtures. Set `nonStreamingTiming: true` on the fixture to also delay `stream: false` OpenAI Chat Completions replies (text, tool calls, combined content and tool calls, and `blocks`) by the sum of the per-chunk delays a streamed reply at the same `chunkSize` would get. `nonStreamingTiming` does not delay other providers. To delay `stream: false` replies with the same formula on OpenAI Chat Completions, Anthropic Messages, OpenAI Responses, Gemini and Vertex AI `generateContent`, Gemini Interactions (`stream: false`), Cohere v2 chat, Bedrock InvokeModel and Converse, and Ollama `/api/chat` and `/api/generate`, set `nonStreamingTimingAllProviders: true` instead. Audio transcription replies are not delayed. Error replies are never delayed. If the client disconnects during the wait, nothing is written and the journal entry gets `interrupted: true`, `interruptReason: "client aborted"` and `status: 0`.
 
 5. **Tool result messages don't change the user message** — after a tool call, the client sends the same conversation + tool result. Matching on `userMessage` will hit the SAME fixture again → infinite loop. Always use `predicate` checking `role === "tool"` for tool results. Note: a whole-conversation `role === "tool"` check (e.g. `req.messages.some((m) => m.role === "tool")`) diverges from `hasToolResult`'s current-turn scoping in multi-turn flows — the built-in `hasToolResult` matcher only looks after the last user message, so a later turn whose history carries an earlier tool result still reads `false`.