@copilotkit/aimock 1.36.1 → 1.37.1

package/dist/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","names":[],"sources":["../src/router.ts"],"sourcesContent":["import type {\n  ChatCompletionRequest,\n  ChatMessage,\n  ContentPart,\n  Fixture,\n  FixtureMatch,\n} from \"./types.js\";\nimport {\n  isImageResponse,\n  isAudioResponse,\n  isTranscriptionResponse,\n  isVideoResponse,\n  isJSONResponse,\n  isErrorResponse,\n} from \"./helpers.js\";\n\nexport function getLastMessageByRole(messages: ChatMessage[], role: string): ChatMessage | null {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (messages[i].role === role) return messages[i];\n  }\n  return null;\n}\n\n/**\n * Concatenate the text content of every `system` role message in order.\n * Hosts that build a system context from multiple sources (persona, agent\n * context entries, tool guidance) often emit several system messages in one\n * request; this joins SEPARATE system messages with newlines so a substring\n * matcher sees the whole context as one body.\n *\n * Empty handling is symmetric with {@link getTextContent}: a system message\n * with no extractable text (`null`) contributes nothing, while a message that\n * extracts to an empty string is a present-but-empty body. We skip only the\n * `null` (no-text) case so a genuinely empty system message does not inject a\n * stray newline; this matches getTextContent treating \"no text\" and \"empty\n * text\" consistently.\n */\nexport function getSystemText(messages: ChatMessage[]): string {\n  const parts: string[] = [];\n  for (const m of messages) {\n    if (m.role !== \"system\") continue;\n    const text = getTextContent(m.content);\n    if (text === null) continue;\n    parts.push(text);\n  }\n  return parts.join(\"\\n\");\n}\n\n/**\n * Extract the text content from a message's content field.\n * Handles both plain string content and array-of-parts content\n * (e.g. `[{type: \"text\", text: \"...\"}]` as sent by some SDKs).\n *\n * Multi-part text is joined with `\"\"` (the parts form one logical body split\n * across segments). Empty handling is symmetric with the string path: a string\n * `\"\"` returns `\"\"`, and an array containing at least one text part whose\n * combined text is empty likewise returns `\"\"` (NOT `null`). `null` is reserved\n * for \"no text content at all\" — null content, or an array with no text parts —\n * so callers can distinguish \"absent\" from \"present but empty\" the same way for\n * both content shapes.\n */\nexport function getTextContent(content: string | ContentPart[] | null): string | null {\n  if (typeof content === \"string\") return content;\n  if (Array.isArray(content)) {\n    const texts = content\n      .filter((p) => p.type === \"text\" && typeof p.text === \"string\")\n      .map((p) => p.text as string);\n    return texts.length > 0 ? texts.join(\"\") : null;\n  }\n  return null;\n}\n\n/**\n * Result of {@link matchFixtureDiagnostic}: the matched fixture (or `null`) plus\n * the number of fixtures that matched the request SHAPE (every predicate above\n * the sequenceIndex/turnIndex gates) but were rejected ONLY by the\n * sequenceIndex/turnIndex count state.\n *\n * `skippedBySequenceOrTurn > 0` with `fixture === null` distinguishes a\n * \"sequence/turn exhausted\" miss (candidate fixtures existed but their count\n * gate had moved on) from a true \"no fixture had a matching shape\" miss — used\n * to disambiguate the strict-mode 503 message.\n */\nexport interface MatchFixtureDiagnostic {\n  fixture: Fixture | null;\n  skippedBySequenceOrTurn: number;\n  /**\n   * `true` when the served fixture was selected by relaxed content-anchored\n   * matching even though its `turnIndex` is defined and does NOT equal the\n   * request's assistant-message count — i.e. the legacy strict turnIndex gate\n   * (now opt-in via `AIMOCK_STRICT_TURN_INDEX`) WOULD HAVE rejected it. Absent /\n   * falsy on canonical-position matches, non-turnIndexed matches, and misses.\n   * Additive optional field — existing handler destructures are unaffected.\n   */\n  turnIndexRelaxed?: boolean;\n  /**\n   * How the served fixture was selected: `\"turnIndex\"` when its `turnIndex`\n   * sits exactly at the current assistant count (canonical position),\n   * `\"content\"` otherwise (a non-turnIndexed match or a relaxed off-by-N\n   * match). Absent on misses. Additive optional field.\n   */\n  matchedBy?: \"content\" | \"turnIndex\";\n}\n\n/**\n * Optional matcher tuning.\n *\n * `strictTurnIndex` restores the legacy behaviour where `turnIndex` must equal\n * the request's assistant-message count exactly (a hard reject gate). It is set\n * by the record path, where a miss proxies upstream to capture a fresh turn; an\n * earlier-turn fixture must not shadow a longer request or the new turn would\n * never be recorded. Replay (the default, `false`) treats `turnIndex` as a\n * non-fatal disambiguator instead — see {@link selectByTurnIndex}.\n */\nexport interface MatchOptions {\n  strictTurnIndex?: boolean;\n  /**\n   * Optional sink for the one-shot relaxed-turnIndex divergence warning. Handlers\n   * pass their `defaults.logger`; the structural `{ warn }` shape avoids an\n   * import cycle with logger.ts and keeps the matcher decoupled. When omitted no\n   * warning is emitted (the diagnostic fields are still populated). The Logger's\n   * own level gate keeps a passing programmatic run (silent default) quiet.\n   */\n  logger?: { warn(...args: unknown[]): void };\n}\n\n/**\n * Process-level opt-out: when `AIMOCK_STRICT_TURN_INDEX=1` (or `true`) is set,\n * REPLAY selection restores the legacy hard turnIndex gate — a content-matching\n * fixture whose `turnIndex` is defined and `!== assistantCount` is rejected,\n * reproducing origin/main semantics. Follows the `AIMOCK_ALLOW_PRIVATE_URLS`\n * precedent for parsing/precedence. Read per-call (not cached) so tests can flip\n * it. Does NOT affect the record path, which is already strict regardless.\n */\nfunction strictTurnIndexEnv(): boolean {\n  const v = process.env.AIMOCK_STRICT_TURN_INDEX;\n  return v === \"1\" || v === \"true\";\n}\n\n/**\n * Process-level set of fixtures for which the relaxed-turnIndex divergence\n * warning has already fired, so each divergent fixture warns at most ONCE per\n * process (throttle). Keyed by the selected fixture's OBJECT IDENTITY: the\n * `Fixture` references in the server's fixtures array are stable across replays\n * (the array is held by reference and only fully replaced on a fixtures reset),\n * so identity uniquely distinguishes divergent fixtures and warns each exactly\n * once. A `WeakSet` was chosen over the previous `JSON.stringify(match)` key for\n * two reasons: (1) stringifying the match DROPS `predicate` functions and\n * serialises any RegExp matcher to `{}`, so two distinct fixtures differing only\n * by a predicate/regex collided to one key and the second's warning was silently\n * suppressed; and (2) a string `Set` only grows, accumulating an entry per\n * divergent shape on a long-lived server, whereas a `WeakSet` auto-evicts when a\n * fixture object is released (e.g. after a fixtures reset drops the references).\n * `let` because `WeakSet` has no `.clear()`, so the test hook reassigns a fresh\n * one.\n */\nlet warnedRelaxedFixtures = new WeakSet<Fixture>();\n\n/**\n * Test-only hook to clear the throttle state between cases. Not part of the\n * public contract. `WeakSet` has no `.clear()`, so reassign a fresh instance.\n */\nexport function _resetTurnIndexRelaxWarnings(): void {\n  warnedRelaxedFixtures = new WeakSet<Fixture>();\n}\n\n/**\n * Build the {@link MatchOptions} a request handler must pass to\n * {@link matchFixtureDiagnostic} / {@link matchFixture}, derived from whether\n * the handler is about to record on a miss.\n *\n * EVERY record-capable handler (OpenAI chat, Anthropic messages, Responses,\n * Gemini, Bedrock, Bedrock-Converse, Cohere, Ollama, …) must build its match\n * options through THIS helper rather than hand-rolling `{ strictTurnIndex }` at\n * the call site. Recording proxies upstream on a miss to capture a fresh turn;\n * if `strictTurnIndex` is left false during recording, an earlier-turn fixture\n * can content-shadow a longer request, the `if (!fixture)` record branch never\n * fires, and the new turn is SILENTLY never recorded. Funnelling the decision\n * through one helper makes that wiring impossible for a future handler to miss:\n * pass `recording = true` whenever the handler's own record gate is satisfied\n * (i.e. it will call `proxyAndRecord` on a miss), `false` otherwise.\n */\nexport function recordMatchOptions(\n  recording: boolean,\n  logger?: { warn(...args: unknown[]): void },\n): MatchOptions {\n  return { strictTurnIndex: recording, logger };\n}\n\n/**\n * Match a fixture against a request, additionally reporting WHY a `null` result\n * occurred. Shares the exact predicate loop with {@link matchFixture}; a fixture\n * that passes every shape predicate but fails ONLY the sequenceIndex or\n * turnIndex gate increments `skippedBySequenceOrTurn`. {@link matchFixture} is a\n * thin wrapper that returns the `.fixture` field, so existing callers are\n * unaffected.\n */\nexport function matchFixtureDiagnostic(\n  fixtures: Fixture[],\n  req: ChatCompletionRequest,\n  matchCounts?: Map<Fixture, number>,\n  requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest,\n  options?: MatchOptions,\n): MatchFixtureDiagnostic {\n  // Apply transform once before matching — used for stripping dynamic data\n  const effective = requestTransform ? requestTransform(req) : req;\n  const useExactMatch = !!requestTransform;\n  // In record mode the server proxies to the upstream on a miss, so a fixture\n  // already captured for an EARLIER turn must NOT shadow a longer (later-turn)\n  // request — otherwise the new turn would never be proxied and recorded.\n  // There turnIndex stays a strict hard gate. Replay (the default) instead\n  // treats turnIndex as a non-fatal disambiguator so a canonical multi-bubble\n  // run isn't falsely rejected for an off-by-N assistant count.\n  // Strict turnIndex is in force when the record path requests it OR the\n  // process-level AIMOCK_STRICT_TURN_INDEX opt-out is set (which restores the\n  // legacy hard gate for replay too). Record mode passes `true` explicitly; the\n  // env only matters when the caller left it `false`/unset (replay).\n  const strictTurnIndex = (options?.strictTurnIndex ?? false) || strictTurnIndexEnv();\n\n  let skippedBySequenceOrTurn = 0;\n  // Every fixture whose content / shape predicates (and sequenceIndex gate)\n  // pass. turnIndex is applied afterwards as a non-fatal disambiguator.\n  const contentMatches: Fixture[] = [];\n\n  for (const fixture of fixtures) {\n    const { match } = fixture;\n\n    // predicate — if present, must return true (receives original request)\n    if (match.predicate !== undefined) {\n      if (!match.predicate(req)) continue;\n    }\n\n    // endpoint — bidirectional filtering:\n    // 1. If fixture has endpoint set, only match requests of that type\n    // 2. If request has _endpointType but fixture doesn't, skip fixtures\n    //    whose response type is incompatible (prevents generic chat fixtures\n    //    from matching image/speech/video requests and causing 500s)\n    const reqEndpoint = effective._endpointType as string | undefined;\n    if (match.endpoint !== undefined) {\n      if (match.endpoint !== reqEndpoint) continue;\n    } else if (\n      reqEndpoint &&\n      reqEndpoint !== \"chat\" &&\n      reqEndpoint !== \"embedding\" &&\n      !reqEndpoint.startsWith(\"realtime\")\n    ) {\n      // Fixture has no endpoint restriction but request is multimedia —\n      // only match if the response type is compatible.\n      // Function responses cannot be checked statically, so treat them as compatible.\n      const r = fixture.response;\n      if (typeof r !== \"function\") {\n        const compatible =\n          (reqEndpoint === \"image\" && isImageResponse(r)) ||\n          (reqEndpoint === \"speech\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"elevenlabs-tts\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"audio-gen\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"fal-audio\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"fal\" && (isJSONResponse(r) || isErrorResponse(r))) ||\n          (reqEndpoint === \"transcription\" && isTranscriptionResponse(r)) ||\n          (reqEndpoint === \"translation\" && isTranscriptionResponse(r)) ||\n          (reqEndpoint === \"video\" && isVideoResponse(r));\n        if (!compatible) continue;\n      }\n    }\n\n    // context — opt-in exact match against the request's _context field.\n    // If fixture specifies a context, only match requests with that exact context.\n    // If fixture omits context, match any request regardless of _context.\n    if (match.context !== undefined) {\n      if (effective._context !== match.context) continue;\n    }\n\n    // userMessage — case-sensitive match against the last user message content.\n    // String matching is intentionally case-sensitive so fixture authors can\n    // rely on exact string values. This differs from the case-insensitive\n    // matchesPattern() in helpers.ts, which is used for search/rerank/moderation\n    // where exact casing rarely matters.\n    if (match.userMessage !== undefined) {\n      const msg = getLastMessageByRole(effective.messages, \"user\");\n      const text = msg ? getTextContent(msg.content) : null;\n      if (!text) continue;\n      if (typeof match.userMessage === \"string\") {\n        if (useExactMatch) {\n          if (text !== match.userMessage) continue;\n        } else {\n          if (!text.includes(match.userMessage)) continue;\n        }\n      } else {\n        match.userMessage.lastIndex = 0;\n        if (!match.userMessage.test(text)) continue;\n      }\n    }\n\n    // systemMessage — case-sensitive substring, regexp, or array-of-substrings\n    // match against the joined text of every system message in the request.\n    // Use to gate a fixture on host-supplied context (e.g. agent-context\n    // entries) so that when the calling app changes that context the fixture\n    // stops matching and the request falls through to the next fixture or\n    // upstream proxy.\n    //\n    // Array form (string[]) requires ALL substrings to be present — useful\n    // when the gate must combine multiple non-adjacent tokens (e.g. a default\n    // name AND a default activity list whose positions in the serialised\n    // context JSON aren't stable).\n    if (match.systemMessage !== undefined) {\n      const sm = match.systemMessage;\n      // Empty array is treated as \"no constraint\" → matches unconditionally,\n      // INCLUDING requests with no system text at all. This is the documented\n      // contract (same permissive behaviour as not setting systemMessage), so\n      // it must be honored BEFORE the no-system-text guard below — otherwise a\n      // request without a system message would be wrongly skipped. Validation\n      // rejects [] at load time for JSON fixtures; programmatic callers that\n      // pass [] get this permissive behaviour.\n      if (Array.isArray(sm) && sm.length === 0) {\n        // no constraint — fall through to the next predicate\n      } else {\n        const text = getSystemText(effective.messages);\n        if (!text) continue;\n        if (Array.isArray(sm)) {\n          let allPresent = true;\n          for (const needle of sm) {\n            if (!text.includes(needle)) {\n              allPresent = false;\n              break;\n            }\n          }\n          if (!allPresent) continue;\n        } else if (typeof sm === \"string\") {\n          if (useExactMatch) {\n            if (text !== sm) continue;\n          } else {\n            if (!text.includes(sm)) continue;\n          }\n        } else {\n          sm.lastIndex = 0;\n          if (!sm.test(text)) continue;\n        }\n      }\n    }\n\n    // toolCallId — a toolCallId fixture answers the model's response to a tool\n    // result, which by API contract only happens when the conversation's LAST\n    // message is a tool result. If a newer user (or other) turn follows the\n    // tool message, the stale tool_call_id must not shadow userMessage matchers.\n    if (match.toolCallId !== undefined) {\n      const last = effective.messages[effective.messages.length - 1];\n      if (!last || last.role !== \"tool\" || last.tool_call_id !== match.toolCallId) continue;\n    }\n\n    // toolName — match against any tool definition by function.name\n    if (match.toolName !== undefined) {\n      const tools = effective.tools ?? [];\n      const found = tools.some((t) => t.function.name === match.toolName);\n      if (!found) continue;\n    }\n\n    // inputText — case-sensitive match against the embedding input text.\n    // Same rationale as userMessage above: fixture authors specify exact strings.\n    if (match.inputText !== undefined) {\n      const embeddingInput = effective.embeddingInput;\n      if (!embeddingInput) continue;\n      if (typeof match.inputText === \"string\") {\n        if (useExactMatch) {\n          if (embeddingInput !== match.inputText) continue;\n        } else {\n          if (!embeddingInput.includes(match.inputText)) continue;\n        }\n      } else {\n        match.inputText.lastIndex = 0;\n        if (!match.inputText.test(embeddingInput)) continue;\n      }\n    }\n\n    // responseFormat — exact string match against request response_format.type\n    if (match.responseFormat !== undefined) {\n      const reqType = effective.response_format?.type;\n      if (reqType !== match.responseFormat) continue;\n    }\n\n    // model — exact match or prefix + dash-digit boundary for strings (so that\n    // \"claude-opus-4\" matches \"claude-opus-4-20250514\" but \"gpt-4\" does NOT\n    // match \"gpt-4o\" and \"gpt-4o\" does NOT match \"gpt-4o-mini\"), regexp unchanged\n    if (match.model !== undefined) {\n      if (typeof match.model === \"string\") {\n        if (effective.model !== match.model) {\n          if (!effective.model?.startsWith(match.model)) continue;\n          const rest = effective.model.slice(match.model.length);\n          if (!/^-\\d/.test(rest)) continue;\n        }\n      } else {\n        match.model.lastIndex = 0;\n        if (!match.model.test(effective.model ?? \"\")) continue;\n      }\n    }\n\n    // hasToolResult — request-SHAPE predicate: does the conversation contain a\n    // tool result message? Must be evaluated with the other shape predicates\n    // ABOVE the sequence/turn state gates so that a fixture whose shape never\n    // matched is not miscounted as \"skipped by sequence/turn state\".\n    if (match.hasToolResult !== undefined) {\n      const hasTool = effective.messages.some((m) => m.role === \"tool\");\n      if (hasTool !== match.hasToolResult) continue;\n    }\n\n    // At this point every SHAPE / CONTENT predicate above has passed, so this\n    // fixture is a genuine CONTENT match for the request. The sequenceIndex and\n    // turnIndex constraints below are POSITION state, not request shape.\n    //\n    // sequenceIndex remains a hard, stateful gate: it consumes sequenced\n    // siblings one call at a time (and an exhausted index intentionally falls\n    // through to a later fixture). A fixture that matched the shape but fails\n    // ONLY the sequenceIndex gate is a \"candidate skipped by sequence/turn\n    // state\", counted separately so callers can disambiguate the strict-mode\n    // 503 message.\n    if (match.sequenceIndex !== undefined && matchCounts !== undefined) {\n      const count = matchCounts.get(fixture) ?? 0;\n      if (count !== match.sequenceIndex) {\n        skippedBySequenceOrTurn++;\n        continue;\n      }\n    }\n\n    // turnIndex is normally NOT a hard gate (replay). Multi-step agents emit\n    // several assistant bubbles per logical turn, so a canonical run's assistant\n    // count routinely differs from a fixture's hardcoded turnIndex even when the\n    // request content matches exactly. Rejecting a uniquely content-matching\n    // fixture on absolute position produced false \"empty assistant response\"\n    // misses. Instead we collect every content match and use turnIndex only as a\n    // non-fatal DISAMBIGUATOR to choose AMONG several content-matching fixtures\n    // (see selectByTurnIndex below). Content that does not match any fixture\n    // still matches nothing — only the position gate is relaxed.\n    //\n    // Under strictTurnIndex (record mode) turnIndex stays a hard, exact gate so\n    // an earlier-turn capture can't shadow a longer request; the miss then\n    // proxies upstream and records the new turn.\n    if (strictTurnIndex && match.turnIndex !== undefined) {\n      const assistantCount = effective.messages.filter((m) => m.role === \"assistant\").length;\n      if (assistantCount !== match.turnIndex) {\n        skippedBySequenceOrTurn++;\n        continue;\n      }\n    }\n\n    contentMatches.push(fixture);\n  }\n\n  if (contentMatches.length === 0) {\n    return { fixture: null, skippedBySequenceOrTurn };\n  }\n\n  const assistantCount = effective.messages.filter((m) => m.role === \"assistant\").length;\n  const { fixture: selected, byUniquePosition } = selectByTurnIndex(contentMatches, assistantCount);\n\n  // Divergence predicate: the served fixture carries a turnIndex that does NOT\n  // sit at the current assistant position. Under strict matching this fixture\n  // would have been rejected at the gate above, so serving it here is the (rare,\n  // off-by-N) relaxed behaviour change PR #276 introduced. Computed from values\n  // already in hand — no second matching pass.\n  const selectedTurn = selected.match.turnIndex;\n  const turnIndexRelaxed = selectedTurn !== undefined && selectedTurn !== assistantCount;\n  // `matchedBy` reports \"turnIndex\" ONLY when the selection was genuinely decided\n  // by a UNIQUE positional criterion (a single candidate whose turnIndex sits\n  // exactly at the current assistant count). A canonical-position fixture that\n  // tied with another at-position candidate, or that lost the exact-turn\n  // tie-break to an earlier fallback, was decided by REGISTRATION ORDER, not by\n  // position — those are \"content\". `selectByTurnIndex` reports which it was.\n  const matchedBy: \"content\" | \"turnIndex\" = byUniquePosition ? \"turnIndex\" : \"content\";\n\n  if (turnIndexRelaxed && options?.logger) {\n    // Throttle: warn at most once per divergent fixture per process. Keyed by\n    // the fixture's OBJECT IDENTITY so distinct fixtures whose match serialises\n    // identically (predicate/regex collisions) each warn, and entries auto-evict\n    // when the fixture is released (see warnedRelaxedFixtures above).\n    if (!warnedRelaxedFixtures.has(selected)) {\n      warnedRelaxedFixtures.add(selected);\n      // Human-readable description for the message only (NOT the throttle key,\n      // which is the fixture's object identity). `JSON.stringify(match)` is\n      // unfit here: it DROPS `predicate` functions entirely and collapses any\n      // RegExp matcher to `{}`, so a predicate/regex fixture's warning read\n      // \"served fixture {}\" / \"{\"userMessage\":{}}\". `describeMatch` instead\n      // summarizes the present matcher KEYS (annotating predicate/regex values)\n      // so the warned fixture is identifiable.\n      const idx = fixtures.indexOf(selected);\n      const desc = describeMatch(selected.match, idx);\n      options.logger.warn(\n        `turnIndex relaxed: served fixture ${desc} at assistantCount=${assistantCount} ` +\n          `(scripted turnIndex=${selectedTurn}); set AIMOCK_STRICT_TURN_INDEX=1 to restore strict matching`,\n      );\n    }\n  }\n\n  return { fixture: selected, skippedBySequenceOrTurn, turnIndexRelaxed, matchedBy };\n}\n\n/**\n * Build a stable, human-readable identifier for a fixture's match shape for the\n * relaxed-turnIndex warning. The previous `JSON.stringify(match)` was unfit: it\n * DROPS `predicate` functions (non-serialisable) and serialises any RegExp\n * matcher to `{}`, so a predicate- or regex-gated fixture's warning collapsed to\n * an uninformative \"served fixture {}\" / `{\"userMessage\":{}}` blob.\n *\n * Instead we list the PRESENT matcher keys in declaration order, annotating each\n * by VALUE KIND so predicates and regexes survive: `predicate(fn)`,\n * `userMessage(regex)`, `userMessage(\"hello\")`, `turnIndex=0`, etc. The\n * fixture's array `index` (when known, i.e. `>= 0`) is prefixed as the stable\n * positional identifier — the `Fixture` type carries no `id`/`name`, so its\n * registration index is the only stable handle. String/number values are shown\n * inline (truncated) so a content match remains recognisable; the whole string\n * is capped to keep the log line bounded.\n */\nfunction describeMatch(match: FixtureMatch, index: number): string {\n  const parts: string[] = [];\n  for (const [key, value] of Object.entries(match)) {\n    if (value === undefined) continue;\n    if (typeof value === \"function\") {\n      parts.push(`${key}(fn)`);\n    } else if (value instanceof RegExp) {\n      parts.push(`${key}(${value})`);\n    } else if (typeof value === \"string\") {\n      const v = value.length > 40 ? `${value.slice(0, 40)}…` : value;\n      parts.push(`${key}(${JSON.stringify(v)})`);\n    } else if (Array.isArray(value)) {\n      parts.push(`${key}(${value.length} item${value.length === 1 ? \"\" : \"s\"})`);\n    } else {\n      parts.push(`${key}=${String(value)}`);\n    }\n  }\n  const keys = parts.length > 0 ? parts.join(\", \") : \"no matchers\";\n  const prefix = index >= 0 ? `#${index} ` : \"\";\n  return `${prefix}{ ${keys} }`.slice(0, 160);\n}\n\n/**\n * Choose one fixture from a set that all CONTENT-matched the same request,\n * using `turnIndex` purely as a position disambiguator (never as a reject\n * gate).\n *\n * The selection rule is applied UNIFORMLY regardless of candidate count (a\n * single candidate is NOT special-cased), so the same request never flips its\n * answer just because an unrelated content-matching fixture was registered.\n * Within every tier ties are broken by REGISTRATION ORDER — the\n * earliest-registered eligible candidate wins — preserving the historical\n * greedy \"first matching fixture wins\" contract.\n *\n *  1. Prefer the turnIndexed candidate whose `turnIndex` is closest to\n *     `assistantCount` WITHOUT exceeding it (the highest `turnIndex <=\n *     assistantCount`). A behind-the-count scripted turn (turnIndex <\n *     assistantCount) beats a plain fallback — an explicit position is a\n *     stronger signal than an unpositioned default. A negative `turnIndex` such\n *     as -1 is a valid at/behind position (the seed is `-Infinity`, never a `-1`\n *     sentinel that would mis-skip it). Earlier registration breaks ties among\n *     equal turnIndexes.\n *  2. EXACT-turn tie-break: when the best at/behind scripted turn sits at the\n *     EXACT current position (`turnIndex === assistantCount`) a plain fallback\n *     also answers \"right now\", so the two are equally eligible and REGISTRATION\n *     ORDER decides — a later-registered `turnIndex:0` does NOT override an\n *     earlier-registered fallback, and vice-versa.\n *  3. Otherwise every turnIndexed candidate is still AHEAD of the conversation.\n *     An explicit future turn must NOT answer an earlier point, so a plain\n *     fallback (eligible at every position) is the better answer — applied\n *     uniformly, INCLUDING when the fallback is the sole partner of a single\n *     future-turn fixture (the single/multi asymmetry this fixes).\n *  4. Otherwise (pure script, every candidate turnIndexed and all ahead) the\n *     script genuinely has no earlier answer, so serve the lowest `turnIndex`\n *     candidate — the false-red-kill for a lone scripted turn whose run has\n *     FEWER assistant bubbles than its `turnIndex`; registration order breaks\n *     ties.\n *\n * A future-turn fixture therefore NEVER answers an earlier-point request when an\n * eligible alternative (a fallback, or an at/behind scripted turn) exists — the\n * future-turn guard is enforced uniformly for single and multiple candidates.\n *\n * Returns the selected fixture alongside `byUniquePosition`: `true` ONLY when the\n * choice was decided by a UNIQUE positional criterion — the served fixture's\n * `turnIndex` sits EXACTLY at `assistantCount`, no earlier fallback overrode it\n * (tier 2), and no other candidate shared that exact position (so registration\n * order did not break a tie). `matchFixtureDiagnostic` maps this to\n * `matchedBy === \"turnIndex\"`; every other selection path (tie-break,\n * registration order, behind/ahead scripted turn, fallback) is `\"content\"`.\n */\nfunction selectByTurnIndex(\n  candidates: Fixture[],\n  assistantCount: number,\n): { fixture: Fixture; byUniquePosition: boolean } {\n  // The first non-turnIndexed candidate is the registration-order-first plain\n  // fallback (eligible at every position). Tracked by index so the exact-turn\n  // tie-break can compare registration order against the chosen scripted turn.\n  const fallbackIdx = candidates.findIndex((f) => f.match.turnIndex === undefined);\n\n  // Tier 1: closest scripted turn at/before the current count. Strict `>`\n  // preserves registration order on equal turnIndexes; `-Infinity` seed so a\n  // negative turnIndex is a legitimate at/behind candidate, not a sentinel skip.\n  let bestIdx = -1;\n  let bestTurn = -Infinity;\n  for (let i = 0; i < candidates.length; i++) {\n    const t = candidates[i].match.turnIndex;\n    if (t === undefined) continue;\n    if (t <= assistantCount && t > bestTurn) {\n      bestIdx = i;\n      bestTurn = t;\n    }\n  }\n\n  if (bestIdx !== -1) {\n    // Tier 2: exact-turn tie with a fallback → earlier registration wins. A\n    // fallback won the tie, so position did NOT uniquely decide → content.\n    if (bestTurn === assistantCount && fallbackIdx !== -1 && fallbackIdx < bestIdx) {\n      return { fixture: candidates[fallbackIdx], byUniquePosition: false };\n    }\n    // A UNIQUE positional decision requires the chosen turn to sit EXACTLY at\n    // the current count AND to be the only candidate at that exact position —\n    // otherwise registration order, not position, broke the tie.\n    const atExactPosition =\n      bestTurn === assistantCount &&\n      candidates.filter((f) => f.match.turnIndex === assistantCount).length === 1;\n    return { fixture: candidates[bestIdx], byUniquePosition: atExactPosition };\n  }\n\n  // Tier 3: every scripted turn is ahead. A plain fallback answers this earlier\n  // point; first-registered fallback wins.\n  if (fallbackIdx !== -1) return { fixture: candidates[fallbackIdx], byUniquePosition: false };\n\n  // Tier 4: pure script, all turnIndexed and all ahead. Serve the lowest\n  // scripted turn; registration order breaks ties (first of the lowest wins).\n  let lowest = candidates[0];\n  for (const f of candidates) {\n    if ((f.match.turnIndex as number) < (lowest.match.turnIndex as number)) lowest = f;\n  }\n  return { fixture: lowest, byUniquePosition: false };\n}\n\n/**\n * Match a fixture against a request, returning the fixture or `null`. Thin\n * wrapper over {@link matchFixtureDiagnostic} that discards the skip diagnostic\n * — preserves the historical signature for all existing callers.\n */\nexport function matchFixture(\n  fixtures: Fixture[],\n  req: ChatCompletionRequest,\n  matchCounts?: Map<Fixture, number>,\n  requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest,\n  options?: MatchOptions,\n): Fixture | null {\n  return matchFixtureDiagnostic(fixtures, req, matchCounts, requestTransform, options).fixture;\n}\n"],"mappings":"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"}
+{"version":3,"file":"router.js","names":[],"sources":["../src/router.ts"],"sourcesContent":["import type {\n  ChatCompletionRequest,\n  ChatMessage,\n  ContentPart,\n  Fixture,\n  FixtureMatch,\n} from \"./types.js\";\nimport {\n  isImageResponse,\n  isAudioResponse,\n  isTranscriptionResponse,\n  isVideoResponse,\n  isJSONResponse,\n  isErrorResponse,\n} from \"./helpers.js\";\n\nexport function getLastMessageByRole(messages: ChatMessage[], role: string): ChatMessage | null {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (messages[i].role === role) return messages[i];\n  }\n  return null;\n}\n\n/**\n * Concatenate the text content of every `system` role message in order.\n * Hosts that build a system context from multiple sources (persona, agent\n * context entries, tool guidance) often emit several system messages in one\n * request; this joins SEPARATE system messages with newlines so a substring\n * matcher sees the whole context as one body.\n *\n * Empty handling is symmetric with {@link getTextContent}: a system message\n * with no extractable text (`null`) contributes nothing, while a message that\n * extracts to an empty string is a present-but-empty body. We skip only the\n * `null` (no-text) case so a genuinely empty system message does not inject a\n * stray newline; this matches getTextContent treating \"no text\" and \"empty\n * text\" consistently.\n */\nexport function getSystemText(messages: ChatMessage[]): string {\n  const parts: string[] = [];\n  for (const m of messages) {\n    if (m.role !== \"system\") continue;\n    const text = getTextContent(m.content);\n    if (text === null) continue;\n    parts.push(text);\n  }\n  return parts.join(\"\\n\");\n}\n\n/**\n * Extract the text content from a message's content field.\n * Handles both plain string content and array-of-parts content\n * (e.g. `[{type: \"text\", text: \"...\"}]` as sent by some SDKs).\n *\n * Multi-part text is joined with `\"\"` (the parts form one logical body split\n * across segments). Empty handling is symmetric with the string path: a string\n * `\"\"` returns `\"\"`, and an array containing at least one text part whose\n * combined text is empty likewise returns `\"\"` (NOT `null`). `null` is reserved\n * for \"no text content at all\" — null content, or an array with no text parts —\n * so callers can distinguish \"absent\" from \"present but empty\" the same way for\n * both content shapes.\n */\nexport function getTextContent(content: string | ContentPart[] | null): string | null {\n  if (typeof content === \"string\") return content;\n  if (Array.isArray(content)) {\n    const texts = content\n      .filter((p) => p.type === \"text\" && typeof p.text === \"string\")\n      .map((p) => p.text as string);\n    return texts.length > 0 ? texts.join(\"\") : null;\n  }\n  return null;\n}\n\n/**\n * Text of the last user message, for `userMessage` fixture matching. Normally\n * this is the text of the final `user` message. But some SDKs serialise a\n * single multimodal user turn (prompt text + attachment) into TWO consecutive\n * user messages — a text-only one FOLLOWED by an attachment-only one, e.g.\n * `[{role:\"user\", content:\"describe this\"}, {role:\"user\", content:[{type:\"image_url\",...}]}]`\n * (observed with Microsoft Agent Framework's `agent_framework_openai` image\n * path). The trailing attachment-only message has NO extractable text, so the\n * naive \"last user message\" lookup returns `null` and — because no fixture can\n * key on empty text — every such multimodal fixture misses. We therefore skip\n * trailing user messages that carry no text and use the nearest preceding user\n * message that does. This is deliberately narrow: it only skips text-LESS\n * (`null`) user messages — a message whose text extracts to an explicit empty\n * string `\"\"` is a present-but-empty body and IS returned (so a fixture can key\n * on it), while a genuine multi-message user turn (each message HAS text) is\n * unaffected and still matched on its final message. Returns the nearest\n * preceding user message whose text is non-null (including `\"\"`); returns `null`\n * only when no user message carries any text part at all.\n */\nexport function getLastUserText(messages: ChatMessage[]): string | null {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (messages[i].role !== \"user\") continue;\n    const text = getTextContent(messages[i].content);\n    if (text !== null) return text;\n  }\n  return null;\n}\n\n/**\n * Test a matcher RegExp against a string WITHOUT mutating the caller-supplied\n * regex. `RegExp.prototype.test` advances `lastIndex` as a side effect on\n * `/g` and `/y` regexes; fixtures hold caller-owned RegExp objects, so testing\n * them in place would clobber the caller's positional state (and a `/g` regex\n * reused across match calls would match intermittently). We test a fresh clone\n * (same source + flags) so the caller's object is never touched and every test\n * starts from index 0.\n */\nfunction regexTest(re: RegExp, text: string): boolean {\n  return new RegExp(re.source, re.flags).test(text);\n}\n\n/**\n * Result of {@link matchFixtureDiagnostic}: the matched fixture (or `null`) plus\n * the number of fixtures that matched the request SHAPE (every predicate above\n * the sequenceIndex/turnIndex gates) but were rejected ONLY by the\n * sequenceIndex/turnIndex count state.\n *\n * `skippedBySequenceOrTurn > 0` with `fixture === null` distinguishes a\n * \"sequence/turn exhausted\" miss (candidate fixtures existed but their count\n * gate had moved on) from a true \"no fixture had a matching shape\" miss — used\n * to disambiguate the strict-mode 503 message.\n */\nexport interface MatchFixtureDiagnostic {\n  fixture: Fixture | null;\n  skippedBySequenceOrTurn: number;\n  /**\n   * `true` when the served fixture was selected by relaxed content-anchored\n   * matching even though its `turnIndex` is defined and does NOT equal the\n   * request's assistant-message count — i.e. the legacy strict turnIndex gate\n   * (now opt-in via `AIMOCK_STRICT_TURN_INDEX`) WOULD HAVE rejected it. Absent /\n   * falsy on canonical-position matches, non-turnIndexed matches, and misses.\n   * Additive optional field — existing handler destructures are unaffected.\n   */\n  turnIndexRelaxed?: boolean;\n  /**\n   * How the served fixture was selected: `\"turnIndex\"` when its `turnIndex`\n   * sits exactly at the current assistant count (canonical position),\n   * `\"content\"` otherwise (a non-turnIndexed match or a relaxed off-by-N\n   * match). Absent on misses. Additive optional field.\n   */\n  matchedBy?: \"content\" | \"turnIndex\";\n}\n\n/**\n * Optional matcher tuning.\n *\n * `strictTurnIndex` restores the legacy behaviour where `turnIndex` must equal\n * the request's assistant-message count exactly (a hard reject gate). It is set\n * by the record path, where a miss proxies upstream to capture a fresh turn; an\n * earlier-turn fixture must not shadow a longer request or the new turn would\n * never be recorded. Replay (the default, `false`) treats `turnIndex` as a\n * non-fatal disambiguator instead — see {@link selectByTurnIndex}.\n */\nexport interface MatchOptions {\n  strictTurnIndex?: boolean;\n  /**\n   * Optional sink for the one-shot relaxed-turnIndex divergence warning. Handlers\n   * pass their `defaults.logger`; the structural `{ warn }` shape avoids an\n   * import cycle with logger.ts and keeps the matcher decoupled. When omitted no\n   * warning is emitted (the diagnostic fields are still populated). The Logger's\n   * own level gate keeps a passing programmatic run (silent default) quiet.\n   */\n  logger?: { warn(...args: unknown[]): void };\n}\n\n/**\n * Process-level opt-out: when `AIMOCK_STRICT_TURN_INDEX=1` (or `true`) is set,\n * REPLAY selection restores the legacy hard turnIndex gate — a content-matching\n * fixture whose `turnIndex` is defined and `!== assistantCount` is rejected,\n * reproducing origin/main semantics. Follows the `AIMOCK_ALLOW_PRIVATE_URLS`\n * precedent for parsing/precedence. Read per-call (not cached) so tests can flip\n * it. Does NOT affect the record path, which is already strict regardless.\n */\nfunction strictTurnIndexEnv(): boolean {\n  const v = process.env.AIMOCK_STRICT_TURN_INDEX;\n  return v === \"1\" || v === \"true\";\n}\n\n/**\n * Process-level set of fixtures for which the relaxed-turnIndex divergence\n * warning has already fired, so each divergent fixture warns at most ONCE per\n * process (throttle). Keyed by the selected fixture's OBJECT IDENTITY: the\n * `Fixture` references in the server's fixtures array are stable across replays\n * (the array is held by reference and only fully replaced on a fixtures reset),\n * so identity uniquely distinguishes divergent fixtures and warns each exactly\n * once. A `WeakSet` was chosen over the previous `JSON.stringify(match)` key for\n * two reasons: (1) stringifying the match DROPS `predicate` functions and\n * serialises any RegExp matcher to `{}`, so two distinct fixtures differing only\n * by a predicate/regex collided to one key and the second's warning was silently\n * suppressed; and (2) a string `Set` only grows, accumulating an entry per\n * divergent shape on a long-lived server, whereas a `WeakSet` auto-evicts when a\n * fixture object is released (e.g. after a fixtures reset drops the references).\n * `let` because `WeakSet` has no `.clear()`, so the test hook reassigns a fresh\n * one.\n */\nlet warnedRelaxedFixtures = new WeakSet<Fixture>();\n\n/**\n * Test-only hook to clear the throttle state between cases. Not part of the\n * public contract. `WeakSet` has no `.clear()`, so reassign a fresh instance.\n */\nexport function _resetTurnIndexRelaxWarnings(): void {\n  warnedRelaxedFixtures = new WeakSet<Fixture>();\n}\n\n/**\n * Build the {@link MatchOptions} a request handler must pass to\n * {@link matchFixtureDiagnostic} / {@link matchFixture}, derived from whether\n * the handler is about to record on a miss.\n *\n * EVERY record-capable handler (OpenAI chat, Anthropic messages, Responses,\n * Gemini, Bedrock, Bedrock-Converse, Cohere, Ollama, …) must build its match\n * options through THIS helper rather than hand-rolling `{ strictTurnIndex }` at\n * the call site. Recording proxies upstream on a miss to capture a fresh turn;\n * if `strictTurnIndex` is left false during recording, an earlier-turn fixture\n * can content-shadow a longer request, the `if (!fixture)` record branch never\n * fires, and the new turn is SILENTLY never recorded. Funnelling the decision\n * through one helper makes that wiring impossible for a future handler to miss:\n * pass `recording = true` whenever the handler's own record gate is satisfied\n * (i.e. it will call `proxyAndRecord` on a miss), `false` otherwise.\n */\nexport function recordMatchOptions(\n  recording: boolean,\n  logger?: { warn(...args: unknown[]): void },\n): MatchOptions {\n  return { strictTurnIndex: recording, logger };\n}\n\n/**\n * Match a fixture against a request, additionally reporting WHY a `null` result\n * occurred. Shares the exact predicate loop with {@link matchFixture}; a fixture\n * that passes every shape predicate but fails ONLY the sequenceIndex or\n * turnIndex gate increments `skippedBySequenceOrTurn`. {@link matchFixture} is a\n * thin wrapper that returns the `.fixture` field, so existing callers are\n * unaffected.\n */\nexport function matchFixtureDiagnostic(\n  fixtures: Fixture[],\n  req: ChatCompletionRequest,\n  matchCounts?: Map<Fixture, number>,\n  requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest,\n  options?: MatchOptions,\n): MatchFixtureDiagnostic {\n  // Apply transform once before matching — used for stripping dynamic data\n  const effective = requestTransform ? requestTransform(req) : req;\n  const useExactMatch = !!requestTransform;\n  // In record mode the server proxies to the upstream on a miss, so a fixture\n  // already captured for an EARLIER turn must NOT shadow a longer (later-turn)\n  // request — otherwise the new turn would never be proxied and recorded.\n  // There turnIndex stays a strict hard gate. Replay (the default) instead\n  // treats turnIndex as a non-fatal disambiguator so a canonical multi-bubble\n  // run isn't falsely rejected for an off-by-N assistant count.\n  // Strict turnIndex is in force when the record path requests it OR the\n  // process-level AIMOCK_STRICT_TURN_INDEX opt-out is set (which restores the\n  // legacy hard gate for replay too). Record mode passes `true` explicitly; the\n  // env only matters when the caller left it `false`/unset (replay).\n  const strictTurnIndex = (options?.strictTurnIndex ?? false) || strictTurnIndexEnv();\n\n  let skippedBySequenceOrTurn = 0;\n  // Every fixture whose content / shape predicates (and sequenceIndex gate)\n  // pass. turnIndex is applied afterwards as a non-fatal disambiguator.\n  const contentMatches: Fixture[] = [];\n\n  for (const fixture of fixtures) {\n    const { match } = fixture;\n\n    // predicate — if present, must return true (receives original request)\n    if (match.predicate !== undefined) {\n      if (!match.predicate(req)) continue;\n    }\n\n    // endpoint — bidirectional filtering:\n    // 1. If fixture has endpoint set, only match requests of that type\n    // 2. If request has _endpointType but fixture doesn't, skip fixtures\n    //    whose response type is incompatible (prevents generic chat fixtures\n    //    from matching image/speech/video requests and causing 500s)\n    const reqEndpoint = effective._endpointType as string | undefined;\n    if (match.endpoint !== undefined) {\n      if (match.endpoint !== reqEndpoint) continue;\n    } else if (\n      reqEndpoint &&\n      reqEndpoint !== \"chat\" &&\n      reqEndpoint !== \"embedding\" &&\n      !reqEndpoint.startsWith(\"realtime\")\n    ) {\n      // Fixture has no endpoint restriction but request is multimedia —\n      // only match if the response type is compatible.\n      // Function responses cannot be checked statically, so treat them as compatible.\n      const r = fixture.response;\n      if (typeof r !== \"function\") {\n        const compatible =\n          (reqEndpoint === \"image\" && isImageResponse(r)) ||\n          (reqEndpoint === \"speech\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"elevenlabs-tts\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"audio-gen\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"fal-audio\" && isAudioResponse(r)) ||\n          (reqEndpoint === \"fal\" && (isJSONResponse(r) || isErrorResponse(r))) ||\n          (reqEndpoint === \"transcription\" && isTranscriptionResponse(r)) ||\n          (reqEndpoint === \"translation\" && isTranscriptionResponse(r)) ||\n          (reqEndpoint === \"video\" && isVideoResponse(r));\n        if (!compatible) continue;\n      }\n    }\n\n    // context — opt-in exact match against the request's _context field.\n    // If fixture specifies a context, only match requests with that exact context.\n    // If fixture omits context, match any request regardless of _context.\n    if (match.context !== undefined) {\n      if (effective._context !== match.context) continue;\n    }\n\n    // userMessage — case-sensitive match against the last user message content.\n    // String matching is intentionally case-sensitive so fixture authors can\n    // rely on exact string values. This differs from the case-insensitive\n    // matchesPattern() in helpers.ts, which is used for search/rerank/moderation\n    // where exact casing rarely matters.\n    if (match.userMessage !== undefined) {\n      // Use the last user message that actually carries text — see\n      // getLastUserText for why a trailing attachment-only user message\n      // (multimodal serialisation split) must not shadow the real prompt.\n      const text = getLastUserText(effective.messages);\n      // `text === null` means no user message carried any text (e.g. a pure\n      // attachment turn) — skip. An explicit empty-string body (`\"\"`) is a\n      // present-but-empty user message and must be allowed through so a fixture\n      // keyed on empty text can match it (see getLastUserText).\n      if (text === null) continue;\n      if (typeof match.userMessage === \"string\") {\n        if (useExactMatch) {\n          if (text !== match.userMessage) continue;\n        } else {\n          if (!text.includes(match.userMessage)) continue;\n        }\n      } else {\n        if (!regexTest(match.userMessage, text)) continue;\n      }\n    }\n\n    // systemMessage — case-sensitive substring, regexp, or array-of-substrings\n    // match against the joined text of every system message in the request.\n    // Use to gate a fixture on host-supplied context (e.g. agent-context\n    // entries) so that when the calling app changes that context the fixture\n    // stops matching and the request falls through to the next fixture or\n    // upstream proxy.\n    //\n    // Array form (string[]) requires ALL substrings to be present — useful\n    // when the gate must combine multiple non-adjacent tokens (e.g. a default\n    // name AND a default activity list whose positions in the serialised\n    // context JSON aren't stable).\n    if (match.systemMessage !== undefined) {\n      const sm = match.systemMessage;\n      // Empty array is treated as \"no constraint\" → matches unconditionally,\n      // INCLUDING requests with no system text at all. This is the documented\n      // contract (same permissive behaviour as not setting systemMessage), so\n      // it must be honored BEFORE the no-system-text guard below — otherwise a\n      // request without a system message would be wrongly skipped. Validation\n      // rejects [] at load time for JSON fixtures; programmatic callers that\n      // pass [] get this permissive behaviour.\n      if (Array.isArray(sm) && sm.length === 0) {\n        // no constraint — fall through to the next predicate\n      } else {\n        const text = getSystemText(effective.messages);\n        // Deliberately `!text` (not `text === null`): unlike userMessage/inputText,\n        // getSystemText returns `\"\"` for BOTH \"a present but empty system message\"\n        // AND \"no system message at all\", so it exposes no absent-vs-empty\n        // distinction at the request level. Allowing `\"\"` through would make a\n        // `systemMessage: \"\"` / `/^$/` fixture a catch-all firing on every\n        // no-system-message request. There is no shipped-fixture demand for\n        // matching an empty system prompt, so we keep the falsy guard here. If a\n        // real need arises, add a getSystemText sibling that returns `null` when\n        // absent and `\"\"` when present-empty, then switch to `text === null`.\n        if (!text) continue;\n        if (Array.isArray(sm)) {\n          let allPresent = true;\n          for (const needle of sm) {\n            if (!text.includes(needle)) {\n              allPresent = false;\n              break;\n            }\n          }\n          if (!allPresent) continue;\n        } else if (typeof sm === \"string\") {\n          if (useExactMatch) {\n            if (text !== sm) continue;\n          } else {\n            if (!text.includes(sm)) continue;\n          }\n        } else {\n          if (!regexTest(sm, text)) continue;\n        }\n      }\n    }\n\n    // toolCallId — a toolCallId fixture answers the model's response to a tool\n    // result, which by API contract only happens when the conversation's LAST\n    // message is a tool result. If a newer user (or other) turn follows the\n    // tool message, the stale tool_call_id must not shadow userMessage matchers.\n    if (match.toolCallId !== undefined) {\n      const last = effective.messages[effective.messages.length - 1];\n      if (!last || last.role !== \"tool\" || last.tool_call_id !== match.toolCallId) continue;\n    }\n\n    // toolResultContains — substring gate on the LAST message's text content\n    // when that message is a tool result. Same last-message rule as toolCallId\n    // (a tool-result fixture answers the model's next call after a tool round),\n    // but discriminates on the result PAYLOAD instead of the call id — needed\n    // when approve/cancel resumes share the same toolCallId and differ only\n    // inside the tool-result JSON.\n    if (match.toolResultContains !== undefined) {\n      const last = effective.messages[effective.messages.length - 1];\n      if (!last || last.role !== \"tool\") continue;\n      const text = getTextContent(last.content);\n      if (text === null || !text.includes(match.toolResultContains)) continue;\n    }\n\n    // toolName — match against any tool definition by function.name\n    if (match.toolName !== undefined) {\n      const tools = effective.tools ?? [];\n      const found = tools.some((t) => t.function.name === match.toolName);\n      if (!found) continue;\n    }\n\n    // inputText — case-sensitive match against the embedding input text.\n    // Same rationale as userMessage above: fixture authors specify exact strings.\n    if (match.inputText !== undefined) {\n      const embeddingInput = effective.embeddingInput;\n      // `undefined` means the request carried no embedding input (a non-embedding\n      // request) — skip. An explicit empty string (`\"\"`) is a genuinely-empty\n      // embedding input and must be allowed through so `inputText: \"\"` can match.\n      if (embeddingInput === undefined) continue;\n      if (typeof match.inputText === \"string\") {\n        if (useExactMatch) {\n          if (embeddingInput !== match.inputText) continue;\n        } else {\n          if (!embeddingInput.includes(match.inputText)) continue;\n        }\n      } else {\n        if (!regexTest(match.inputText, embeddingInput)) continue;\n      }\n    }\n\n    // responseFormat — exact string match against request response_format.type\n    if (match.responseFormat !== undefined) {\n      const reqType = effective.response_format?.type;\n      if (reqType !== match.responseFormat) continue;\n    }\n\n    // model — exact match or prefix + dash-digit boundary for strings (so that\n    // \"claude-opus-4\" matches \"claude-opus-4-20250514\" but \"gpt-4\" does NOT\n    // match \"gpt-4o\" and \"gpt-4o\" does NOT match \"gpt-4o-mini\"), regexp unchanged\n    if (match.model !== undefined) {\n      if (typeof match.model === \"string\") {\n        if (effective.model !== match.model) {\n          if (!effective.model?.startsWith(match.model)) continue;\n          const rest = effective.model.slice(match.model.length);\n          if (!/^-\\d/.test(rest)) continue;\n        }\n      } else {\n        if (!regexTest(match.model, effective.model ?? \"\")) continue;\n      }\n    }\n\n    // hasToolResult — request-SHAPE predicate: does the conversation contain a\n    // tool result message? Must be evaluated with the other shape predicates\n    // ABOVE the sequence/turn state gates so that a fixture whose shape never\n    // matched is not miscounted as \"skipped by sequence/turn state\".\n    if (match.hasToolResult !== undefined) {\n      const hasTool = effective.messages.some((m) => m.role === \"tool\");\n      if (hasTool !== match.hasToolResult) continue;\n    }\n\n    // At this point every SHAPE / CONTENT predicate above has passed, so this\n    // fixture is a genuine CONTENT match for the request. The sequenceIndex and\n    // turnIndex constraints below are POSITION state, not request shape.\n    //\n    // sequenceIndex remains a hard, stateful gate: it consumes sequenced\n    // siblings one call at a time (and an exhausted index intentionally falls\n    // through to a later fixture). A fixture that matched the shape but fails\n    // ONLY the sequenceIndex gate is a \"candidate skipped by sequence/turn\n    // state\", counted separately so callers can disambiguate the strict-mode\n    // 503 message.\n    if (match.sequenceIndex !== undefined && matchCounts !== undefined) {\n      const count = matchCounts.get(fixture) ?? 0;\n      if (count !== match.sequenceIndex) {\n        skippedBySequenceOrTurn++;\n        continue;\n      }\n    }\n\n    // turnIndex is normally NOT a hard gate (replay). Multi-step agents emit\n    // several assistant bubbles per logical turn, so a canonical run's assistant\n    // count routinely differs from a fixture's hardcoded turnIndex even when the\n    // request content matches exactly. Rejecting a uniquely content-matching\n    // fixture on absolute position produced false \"empty assistant response\"\n    // misses. Instead we collect every content match and use turnIndex only as a\n    // non-fatal DISAMBIGUATOR to choose AMONG several content-matching fixtures\n    // (see selectByTurnIndex below). Content that does not match any fixture\n    // still matches nothing — only the position gate is relaxed.\n    //\n    // Under strictTurnIndex (record mode) turnIndex stays a hard, exact gate so\n    // an earlier-turn capture can't shadow a longer request; the miss then\n    // proxies upstream and records the new turn.\n    if (strictTurnIndex && match.turnIndex !== undefined) {\n      const assistantCount = effective.messages.filter((m) => m.role === \"assistant\").length;\n      if (assistantCount !== match.turnIndex) {\n        skippedBySequenceOrTurn++;\n        continue;\n      }\n    }\n\n    contentMatches.push(fixture);\n  }\n\n  if (contentMatches.length === 0) {\n    return { fixture: null, skippedBySequenceOrTurn };\n  }\n\n  const assistantCount = effective.messages.filter((m) => m.role === \"assistant\").length;\n  const { fixture: selected, byUniquePosition } = selectByTurnIndex(contentMatches, assistantCount);\n\n  // Divergence predicate: the served fixture carries a turnIndex that does NOT\n  // sit at the current assistant position. Under strict matching this fixture\n  // would have been rejected at the gate above, so serving it here is the (rare,\n  // off-by-N) relaxed behaviour change PR #276 introduced. Computed from values\n  // already in hand — no second matching pass.\n  const selectedTurn = selected.match.turnIndex;\n  const turnIndexRelaxed = selectedTurn !== undefined && selectedTurn !== assistantCount;\n  // `matchedBy` reports \"turnIndex\" ONLY when the selection was genuinely decided\n  // by a UNIQUE positional criterion (a single candidate whose turnIndex sits\n  // exactly at the current assistant count). A canonical-position fixture that\n  // tied with another at-position candidate, or that lost the exact-turn\n  // tie-break to an earlier fallback, was decided by REGISTRATION ORDER, not by\n  // position — those are \"content\". `selectByTurnIndex` reports which it was.\n  const matchedBy: \"content\" | \"turnIndex\" = byUniquePosition ? \"turnIndex\" : \"content\";\n\n  if (turnIndexRelaxed && options?.logger) {\n    // Throttle: warn at most once per divergent fixture per process. Keyed by\n    // the fixture's OBJECT IDENTITY so distinct fixtures whose match serialises\n    // identically (predicate/regex collisions) each warn, and entries auto-evict\n    // when the fixture is released (see warnedRelaxedFixtures above).\n    if (!warnedRelaxedFixtures.has(selected)) {\n      warnedRelaxedFixtures.add(selected);\n      // Human-readable description for the message only (NOT the throttle key,\n      // which is the fixture's object identity). `JSON.stringify(match)` is\n      // unfit here: it DROPS `predicate` functions entirely and collapses any\n      // RegExp matcher to `{}`, so a predicate/regex fixture's warning read\n      // \"served fixture {}\" / \"{\"userMessage\":{}}\". `describeMatch` instead\n      // summarizes the present matcher KEYS (annotating predicate/regex values)\n      // so the warned fixture is identifiable.\n      const idx = fixtures.indexOf(selected);\n      const desc = describeMatch(selected.match, idx);\n      options.logger.warn(\n        `turnIndex relaxed: served fixture ${desc} at assistantCount=${assistantCount} ` +\n          `(scripted turnIndex=${selectedTurn}); set AIMOCK_STRICT_TURN_INDEX=1 to restore strict matching`,\n      );\n    }\n  }\n\n  return { fixture: selected, skippedBySequenceOrTurn, turnIndexRelaxed, matchedBy };\n}\n\n/**\n * Build a stable, human-readable identifier for a fixture's match shape for the\n * relaxed-turnIndex warning. The previous `JSON.stringify(match)` was unfit: it\n * DROPS `predicate` functions (non-serialisable) and serialises any RegExp\n * matcher to `{}`, so a predicate- or regex-gated fixture's warning collapsed to\n * an uninformative \"served fixture {}\" / `{\"userMessage\":{}}` blob.\n *\n * Instead we list the PRESENT matcher keys in declaration order, annotating each\n * by VALUE KIND so predicates and regexes survive: `predicate(fn)`,\n * `userMessage(regex)`, `userMessage(\"hello\")`, `turnIndex=0`, etc. The\n * fixture's array `index` (when known, i.e. `>= 0`) is prefixed as the stable\n * positional identifier — the `Fixture` type carries no `id`/`name`, so its\n * registration index is the only stable handle. String/number values are shown\n * inline (truncated) so a content match remains recognisable; the whole string\n * is capped to keep the log line bounded.\n */\nfunction describeMatch(match: FixtureMatch, index: number): string {\n  const parts: string[] = [];\n  for (const [key, value] of Object.entries(match)) {\n    if (value === undefined) continue;\n    if (typeof value === \"function\") {\n      parts.push(`${key}(fn)`);\n    } else if (value instanceof RegExp) {\n      parts.push(`${key}(${value})`);\n    } else if (typeof value === \"string\") {\n      const v = value.length > 40 ? `${value.slice(0, 40)}…` : value;\n      parts.push(`${key}(${JSON.stringify(v)})`);\n    } else if (Array.isArray(value)) {\n      parts.push(`${key}(${value.length} item${value.length === 1 ? \"\" : \"s\"})`);\n    } else {\n      parts.push(`${key}=${String(value)}`);\n    }\n  }\n  const keys = parts.length > 0 ? parts.join(\", \") : \"no matchers\";\n  const prefix = index >= 0 ? `#${index} ` : \"\";\n  return `${prefix}{ ${keys} }`.slice(0, 160);\n}\n\n/**\n * Choose one fixture from a set that all CONTENT-matched the same request,\n * using `turnIndex` purely as a position disambiguator (never as a reject\n * gate).\n *\n * The selection rule is applied UNIFORMLY regardless of candidate count (a\n * single candidate is NOT special-cased), so the same request never flips its\n * answer just because an unrelated content-matching fixture was registered.\n * Within every tier ties are broken by REGISTRATION ORDER — the\n * earliest-registered eligible candidate wins — preserving the historical\n * greedy \"first matching fixture wins\" contract.\n *\n *  1. Prefer the turnIndexed candidate whose `turnIndex` is closest to\n *     `assistantCount` WITHOUT exceeding it (the highest `turnIndex <=\n *     assistantCount`). A behind-the-count scripted turn (turnIndex <\n *     assistantCount) beats a plain fallback — an explicit position is a\n *     stronger signal than an unpositioned default. A negative `turnIndex` such\n *     as -1 is a valid at/behind position (the seed is `-Infinity`, never a `-1`\n *     sentinel that would mis-skip it). Earlier registration breaks ties among\n *     equal turnIndexes.\n *  2. EXACT-turn tie-break: when the best at/behind scripted turn sits at the\n *     EXACT current position (`turnIndex === assistantCount`) a plain fallback\n *     also answers \"right now\", so the two are equally eligible and REGISTRATION\n *     ORDER decides — a later-registered `turnIndex:0` does NOT override an\n *     earlier-registered fallback, and vice-versa.\n *  3. Otherwise every turnIndexed candidate is still AHEAD of the conversation.\n *     An explicit future turn must NOT answer an earlier point, so a plain\n *     fallback (eligible at every position) is the better answer — applied\n *     uniformly, INCLUDING when the fallback is the sole partner of a single\n *     future-turn fixture (the single/multi asymmetry this fixes).\n *  4. Otherwise (pure script, every candidate turnIndexed and all ahead) the\n *     script genuinely has no earlier answer, so serve the lowest `turnIndex`\n *     candidate — the false-red-kill for a lone scripted turn whose run has\n *     FEWER assistant bubbles than its `turnIndex`; registration order breaks\n *     ties.\n *\n * A future-turn fixture therefore NEVER answers an earlier-point request when an\n * eligible alternative (a fallback, or an at/behind scripted turn) exists — the\n * future-turn guard is enforced uniformly for single and multiple candidates.\n *\n * Returns the selected fixture alongside `byUniquePosition`: `true` ONLY when the\n * choice was decided by a UNIQUE positional criterion — the served fixture's\n * `turnIndex` sits EXACTLY at `assistantCount`, no earlier fallback overrode it\n * (tier 2), and no other candidate shared that exact position (so registration\n * order did not break a tie). `matchFixtureDiagnostic` maps this to\n * `matchedBy === \"turnIndex\"`; every other selection path (tie-break,\n * registration order, behind/ahead scripted turn, fallback) is `\"content\"`.\n */\nfunction selectByTurnIndex(\n  candidates: Fixture[],\n  assistantCount: number,\n): { fixture: Fixture; byUniquePosition: boolean } {\n  // The first non-turnIndexed candidate is the registration-order-first plain\n  // fallback (eligible at every position). Tracked by index so the exact-turn\n  // tie-break can compare registration order against the chosen scripted turn.\n  const fallbackIdx = candidates.findIndex((f) => f.match.turnIndex === undefined);\n\n  // Tier 1: closest scripted turn at/before the current count. Strict `>`\n  // preserves registration order on equal turnIndexes; `-Infinity` seed so a\n  // negative turnIndex is a legitimate at/behind candidate, not a sentinel skip.\n  let bestIdx = -1;\n  let bestTurn = -Infinity;\n  for (let i = 0; i < candidates.length; i++) {\n    const t = candidates[i].match.turnIndex;\n    if (t === undefined) continue;\n    if (t <= assistantCount && t > bestTurn) {\n      bestIdx = i;\n      bestTurn = t;\n    }\n  }\n\n  if (bestIdx !== -1) {\n    // Tier 2: exact-turn tie with a fallback → earlier registration wins. A\n    // fallback won the tie, so position did NOT uniquely decide → content.\n    if (bestTurn === assistantCount && fallbackIdx !== -1 && fallbackIdx < bestIdx) {\n      return { fixture: candidates[fallbackIdx], byUniquePosition: false };\n    }\n    // A UNIQUE positional decision requires the chosen turn to sit EXACTLY at\n    // the current count AND to be the only candidate at that exact position —\n    // otherwise registration order, not position, broke the tie.\n    const atExactPosition =\n      bestTurn === assistantCount &&\n      candidates.filter((f) => f.match.turnIndex === assistantCount).length === 1;\n    return { fixture: candidates[bestIdx], byUniquePosition: atExactPosition };\n  }\n\n  // Tier 3: every scripted turn is ahead. A plain fallback answers this earlier\n  // point; first-registered fallback wins.\n  if (fallbackIdx !== -1) return { fixture: candidates[fallbackIdx], byUniquePosition: false };\n\n  // Tier 4: pure script, all turnIndexed and all ahead. Serve the lowest\n  // scripted turn; registration order breaks ties (first of the lowest wins).\n  let lowest = candidates[0];\n  for (const f of candidates) {\n    if ((f.match.turnIndex as number) < (lowest.match.turnIndex as number)) lowest = f;\n  }\n  return { fixture: lowest, byUniquePosition: false };\n}\n\n/**\n * Match a fixture against a request, returning the fixture or `null`. Thin\n * wrapper over {@link matchFixtureDiagnostic} that discards the skip diagnostic\n * — preserves the historical signature for all existing callers.\n */\nexport function matchFixture(\n  fixtures: Fixture[],\n  req: ChatCompletionRequest,\n  matchCounts?: Map<Fixture, number>,\n  requestTransform?: (req: ChatCompletionRequest) => ChatCompletionRequest,\n  options?: MatchOptions,\n): Fixture | null {\n  return matchFixtureDiagnostic(fixtures, req, matchCounts, requestTransform, options).fixture;\n}\n"],"mappings":"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"}

package/dist/stream-collapse.cjs

@@ -12,6 +12,75 @@ let node_zlib = require("node:zlib");
 * text followed by tool calls.
 */
 /**
+* Hard ceiling (UTF-16 code units) for any SINGLE string a collapser
+* accumulates across deltas (`content`, `reasoning`, a tool call's
+* `arguments`, `audioB64`, `argsStr`, and the coalesced text of `orderAtoms`).
+*
+* V8's maximum string length on 64-bit is 2^29 - 1 (~536.8M UTF-16 code
+* units); appending past it throws `RangeError: Invalid string length`. The
+* proxy path bounds the raw BYTE buffer under `PROXY_BUFFER_HARD_CEILING`
+* (256 MiB) before collapse, but the collapser is ALSO reachable directly
+* (exported from index.ts) and — even on the proxy path — a single accumulator
+* can approach the byte budget in code units, so it needs its own guard rather
+* than relying on the byte cap alone. 256Mi code units is comfortably below
+* V8's limit while leaving huge headroom for any real completion (whose
+* accumulated content can never exceed the total streamed body).
+*
+* When an append would cross the ceiling the accumulator keeps the ceiling's
+* worth of characters, drops the overflow, and marks itself truncated — never
+* throwing — mirroring the proxy buffer's "bound then mark truncated, never
+* fail the client" discipline.
+*/
+const MAX_COLLAPSE_STRING_LENGTH = 256 * 1024 * 1024;
+/**
+* Test-only override of {@link MAX_COLLAPSE_STRING_LENGTH}. Lets the cap suite
+* exercise the truncation path with a tiny budget instead of building a
+* multi-hundred-MB string. `undefined` (the default) uses the real ceiling.
+* NEVER set from production code.
+*/
+let collapseStringLimitOverride;
+/** @internal test-only — see {@link collapseStringLimitOverride}. */
+function setCollapseStringLimitForTests(value) {
+	collapseStringLimitOverride = value;
+}
+/** Effective accumulated-string ceiling, honoring any active test-only override. */
+function effectiveCollapseStringLimit() {
+	return collapseStringLimitOverride ?? MAX_COLLAPSE_STRING_LENGTH;
+}
+/**
+* Guard a raw collapse-input body against V8's max string length BEFORE any
+* per-delta accumulation begins. Every collapser accumulates `content` /
+* `reasoning` / a tool call's `arguments` / `audioB64` / `argsStr` (and the
+* coalesced text of `orderAtoms`) from fragments of `body`; the sum of any one
+* of those accumulators can never exceed the total input length, so bounding
+* the INPUT under the ceiling bounds EVERY accumulator at once — no per-`+=`
+* site can then build a string past the limit and throw
+* `RangeError: Invalid string length` (the ~1/sec prod crash).
+*
+* Returns the body UNCHANGED when it is within the ceiling. When it exceeds the
+* ceiling this returns a hard-truncated prefix (never throwing) — the collapse
+* result the caller builds from it is marked incomplete via `truncated: true`
+* (see {@link isCollapseInputTruncated}). This mirrors the proxy buffer's
+* "bound then mark truncated, never fail the client" discipline: on the proxy
+* path a body this large has already tripped the byte cap and skipped recording,
+* so this is a defense-in-depth backstop that also covers the direct (exported)
+* collapse callers where no byte cap ran.
+*/
+function guardCollapseBody(body) {
+	const limit = effectiveCollapseStringLimit();
+	if (body.length <= limit) return body;
+	return body.slice(0, limit);
+}
+/**
+* True when a body exceeded the accumulated-string ceiling and had to be
+* truncated by {@link guardCollapseBody}. Collapsers stamp `truncated: true` on
+* their result in this case so the recorder skips journaling a partial fixture,
+* exactly like a transport-truncated stream.
+*/
+function isCollapseInputTruncated(body) {
+	return body.length > effectiveCollapseStringLimit();
+}
+/**
 * Normalize a tool call's accumulated `arguments` into valid JSON exactly like
 * the flat-`toolCalls` recorder path: an empty / whitespace-only / missing
 * value becomes `"{}"`, never `""`. Mirrors `recorder.ts` `toToolCallArguments`
@@ -166,8 +235,9 @@ function extractSSEData(lines) {
 *   data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"Hello"}}]}\n\n
 *   data: [DONE]\n\n
 */
-function collapseOpenAISSE(body) {
-	const lines = splitSSEEvents(body);
+function collapseOpenAISSE(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const lines = splitSSEEvents(guardCollapseBody(rawBody));
 	let content = "";
 	let reasoning = "";
 	const webSearchQueries = [];
@@ -288,7 +358,8 @@ function collapseOpenAISSE(body) {
 			...droppedChunks > 0 ? { droppedChunks } : {},
 			...firstDroppedSample ? { firstDroppedSample } : {},
 			...harmonyUnparsed ? { harmonyUnparsed: true } : {},
-			...harmonyNote ? { harmonyNote } : {}
+			...harmonyNote ? { harmonyNote } : {},
+			...inputTruncated ? { truncated: true } : {}
 		};
 	}
 	return {
@@ -298,7 +369,8 @@ function collapseOpenAISSE(body) {
 		...droppedChunks > 0 ? { droppedChunks } : {},
 		...firstDroppedSample ? { firstDroppedSample } : {},
 		...harmonyUnparsed ? { harmonyUnparsed: true } : {},
-		...harmonyNote ? { harmonyNote } : {}
+		...harmonyNote ? { harmonyNote } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -308,8 +380,9 @@ function collapseOpenAISSE(body) {
 *   event: message_start\ndata: {...}\n\n
 *   event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"Hello"}}\n\n
 */
-function collapseAnthropicSSE(body) {
-	const blocks = splitSSEEvents(body);
+function collapseAnthropicSSE(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const blocks = splitSSEEvents(guardCollapseBody(rawBody));
 	let content = "";
 	let reasoning = "";
 	let reasoningSignature;
@@ -399,7 +472,8 @@ function collapseAnthropicSSE(body) {
 			...reasoningSignature ? { reasoningSignature } : {},
 			...redactedThinking.length > 0 ? { redactedThinking } : {},
 			...droppedChunks > 0 ? { droppedChunks } : {},
-			...firstDroppedSample ? { firstDroppedSample } : {}
+			...firstDroppedSample ? { firstDroppedSample } : {},
+			...inputTruncated ? { truncated: true } : {}
 		};
 	}
 	return {
@@ -408,7 +482,8 @@ function collapseAnthropicSSE(body) {
 		...reasoningSignature ? { reasoningSignature } : {},
 		...redactedThinking.length > 0 ? { redactedThinking } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -417,8 +492,9 @@ function collapseAnthropicSSE(body) {
 * Format (data-only, no event prefix, no [DONE]):
 *   data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}\n\n
 */
-function collapseGeminiSSE(body) {
-	const lines = splitSSEEvents(body);
+function collapseGeminiSSE(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const lines = splitSSEEvents(guardCollapseBody(rawBody));
 	let content = "";
 	let reasoning = "";
 	let droppedChunks = 0;
@@ -480,7 +556,8 @@ function collapseGeminiSSE(body) {
 		...reasoning ? { reasoning } : {},
 		...normalizedToolCalls.length > 0 ? { toolCalls: normalizedToolCalls } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 	if (toolCalls.length > 0) {
 		const blocks = buildOrderedBlocks(orderAtoms);
@@ -490,14 +567,16 @@ function collapseGeminiSSE(body) {
 			toolCalls: normalizedToolCalls,
 			...reasoning ? { reasoning } : {},
 			...droppedChunks > 0 ? { droppedChunks } : {},
-			...firstDroppedSample ? { firstDroppedSample } : {}
+			...firstDroppedSample ? { firstDroppedSample } : {},
+			...inputTruncated ? { truncated: true } : {}
 		};
 	}
 	return {
 		content,
 		...reasoning ? { reasoning } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -514,8 +593,9 @@ function collapseGeminiSSE(body) {
 * content is run through the same fail-safe {@link parseHarmonyContent} gate to
 * capture structured tool calls / reasoning instead of leaking raw tokens.
 */
-function collapseOllamaNDJSON(body) {
-	const lines = body.split("\n").filter((l) => l.trim().length > 0);
+function collapseOllamaNDJSON(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const lines = guardCollapseBody(rawBody).split("\n").filter((l) => l.trim().length > 0);
 	let content = "";
 	let reasoning = "";
 	let droppedChunks = 0;
@@ -589,7 +669,8 @@ function collapseOllamaNDJSON(body) {
 			...droppedChunks > 0 ? { droppedChunks } : {},
 			...firstDroppedSample ? { firstDroppedSample } : {},
 			...harmonyUnparsed ? { harmonyUnparsed: true } : {},
-			...harmonyNote ? { harmonyNote } : {}
+			...harmonyNote ? { harmonyNote } : {},
+			...inputTruncated ? { truncated: true } : {}
 		};
 	}
 	return {
@@ -598,7 +679,8 @@ function collapseOllamaNDJSON(body) {
 		...droppedChunks > 0 ? { droppedChunks } : {},
 		...firstDroppedSample ? { firstDroppedSample } : {},
 		...harmonyUnparsed ? { harmonyUnparsed: true } : {},
-		...harmonyNote ? { harmonyNote } : {}
+		...harmonyNote ? { harmonyNote } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -607,8 +689,9 @@ function collapseOllamaNDJSON(body) {
 * Format:
 *   event: content-delta\ndata: {"type":"content-delta","delta":{"message":{"content":{"text":"Hello"}}}}\n\n
 */
-function collapseCohereSSE(body) {
-	const blocks = splitSSEEvents(body);
+function collapseCohereSSE(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const blocks = splitSSEEvents(guardCollapseBody(rawBody));
 	let content = "";
 	let reasoning = "";
 	let droppedChunks = 0;
@@ -697,14 +780,16 @@ function collapseCohereSSE(body) {
 			toolCalls: orderedBlocks ? orderedToolCalls : indexSortedToolCalls,
 			...reasoning ? { reasoning } : {},
 			...droppedChunks > 0 ? { droppedChunks } : {},
-			...firstDroppedSample ? { firstDroppedSample } : {}
+			...firstDroppedSample ? { firstDroppedSample } : {},
+			...inputTruncated ? { truncated: true } : {}
 		};
 	}
 	return {
 		content,
 		...reasoning ? { reasoning } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -798,8 +883,11 @@ function decodeEventStreamFrames(buf) {
 * Each frame contains a JSON payload with event types like:
 *   contentBlockDelta, contentBlockStart, etc.
 */
-function collapseBedrockEventStream(body) {
-	const { frames, truncated } = decodeEventStreamFrames(body);
+function collapseBedrockEventStream(rawBody) {
+	const limit = effectiveCollapseStringLimit();
+	const inputTruncated = rawBody.byteLength > limit;
+	const { frames, truncated: frameTruncated } = decodeEventStreamFrames(inputTruncated ? rawBody.subarray(0, limit) : rawBody);
+	const truncated = frameTruncated || inputTruncated;
 	let content = "";
 	let reasoning = "";
 	let reasoningSignature;
@@ -954,8 +1042,9 @@ function collapseBedrockEventStream(body) {
 * delta) are still accepted for backward compatibility with previously
 * recorded fixtures.
 */
-function collapseGeminiInteractionsSSE(body) {
-	const lines = splitSSEEvents(body);
+function collapseGeminiInteractionsSSE(rawBody) {
+	const inputTruncated = isCollapseInputTruncated(rawBody);
+	const lines = splitSSEEvents(guardCollapseBody(rawBody));
 	let content = "";
 	let reasoning = "";
 	let droppedChunks = 0;
@@ -1036,13 +1125,15 @@ function collapseGeminiInteractionsSSE(body) {
 		toolCalls,
 		...reasoning ? { reasoning } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 	return {
 		content,
 		...reasoning ? { reasoning } : {},
 		...droppedChunks > 0 ? { droppedChunks } : {},
-		...firstDroppedSample ? { firstDroppedSample } : {}
+		...firstDroppedSample ? { firstDroppedSample } : {},
+		...inputTruncated ? { truncated: true } : {}
 	};
 }
 /**
@@ -1074,6 +1165,7 @@ function collapseStreamingResponse(contentType, providerKey, body, logger) {
 }
 
 //#endregion
+exports.MAX_COLLAPSE_STRING_LENGTH = MAX_COLLAPSE_STRING_LENGTH;
 exports.capturedRedactedData = capturedRedactedData;
 exports.collapseAnthropicSSE = collapseAnthropicSSE;
 exports.collapseBedrockEventStream = collapseBedrockEventStream;
@@ -1083,4 +1175,5 @@ exports.collapseGeminiSSE = collapseGeminiSSE;
 exports.collapseOllamaNDJSON = collapseOllamaNDJSON;
 exports.collapseOpenAISSE = collapseOpenAISSE;
 exports.collapseStreamingResponse = collapseStreamingResponse;
+exports.setCollapseStringLimitForTests = setCollapseStringLimitForTests;
 //# sourceMappingURL=stream-collapse.cjs.map