Codebase hardening: bucket (c) sweep from dual-context header CR (#179)

## Summary

Addresses 14 of 16 pre-existing issues from the dual-context header CR
bucket (c) list, plus 12 additional issues discovered during CR fix
rounds (26 total fixes across 23 files).

**Core hardening** — readBody size limit (10MB) + double-settlement
guard, matchesPattern lastIndex reset for global/sticky regex, tightened
isErrorResponse type guard, deep-copy toolCalls in
normalizeFactoryResponse, deduplicated DEFAULT_TEST_ID constant

**WebSocket handlers** — ContentWithToolCallsResponse support for
ws-responses + ws-realtime (was 500 error), isClosed guards on
post-streaming sends, interruption timer cleanup, per-response
instructions passthrough, consistent journal header capture

**Bedrock** — forward max_tokens in request conversion, use || null for
empty-string content (tool-call-only messages), type-safe event removal
replacing fragile pop()

**Double-journal prevention** — added handled_by_hook guard to all 14
proxy handler sites across 11 files (ollama, cohere, speech, messages,
images, embeddings, gemini, responses, transcription, bedrock,
bedrock-converse)

**Endpoint hardening** — journal headers captured in all 47
ElevenLabs/fal/WS sites, proactive TTL sweep for video + fal job maps
with proper lifecycle (clear preserves timer, destroy stops it), atomic
video getEntry() for consistent TTL check, persistent created_at across
status polls, fal queue 409 journal entry, boundary-based multipart
parsing, cli help text

## Test plan

- [x] 2891 tests pass (80 files, 37 skipped)
- [x] TypeScript typecheck clean
- [x] Prettier + ESLint clean
- [x] 3 CR rounds with 7 agents each (21 agent-rounds)

Author: jpr5

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- **Helper utilities and error serialization** — hardened helper functions and error serialization paths for correctness and robustness
+- **Journal and fixture-loader correctness** — fixed journal entry handling and fixture-loader edge cases
+- **WebSocket handler consistency and strict-mode journal** — aligned WebSocket handler behavior and ensured strict-mode journal entries are recorded correctly
+- **Provider handler consistency and proxy outcomes** — unified provider handler error paths and proxy outcome reporting
+- **Media handler hardening and chaos injection** — strengthened media handler validation and chaos injection reliability
+
+### Tests
+
+- **Bedrock mock consistency and CLI help text** — corrected Bedrock mock test assertions and CLI `--help` output coverage
+
 ## [1.22.0] - 2026-05-11
 
 ### Added

src/__tests__/bedrock-stream.test.ts

@@ -187,9 +187,6 @@ function postPartialBinary(
         res.on("error", () => {
           aborted = true;
         });
-        res.on("aborted", () => {
-          aborted = true;
-        });
         res.on("close", () => {
           safeResolve({ body: Buffer.concat(chunks), aborted });
         });
@@ -1747,7 +1744,7 @@ describe("converseToCompletionRequest (edge cases)", () => {
       },
       "model",
     );
-    expect(result.messages[0]).toEqual({ role: "assistant", content: "" });
+    expect(result.messages[0]).toEqual({ role: "assistant", content: null });
   });
 
   it("handles user tool result with missing text in content items (text ?? '' fallback)", () => {
@@ -1859,8 +1856,8 @@ describe("converseToCompletionRequest (edge cases)", () => {
       "model",
     );
     expect(result.messages[0].tool_calls).toHaveLength(1);
-    // Empty text → content is "" (nullish coalescing preserves empty string)
-    expect(result.messages[0].content).toBe("");
+    // Empty text → content is null (|| coerces empty string to null)
+    expect(result.messages[0].content).toBe(null);
   });
 });
 

src/__tests__/bedrock.test.ts

@@ -751,8 +751,8 @@ describe("bedrockToCompletionRequest (edge cases)", () => {
       },
       "model",
     );
-    // Empty array → no tool_use blocks, textContent is "" → preserved as "" (not coerced to null via ??)
-    expect(result.messages[0]).toEqual({ role: "assistant", content: "" });
+    // Empty array → no tool_use blocks, textContent is "" → coerced to null via ||
+    expect(result.messages[0]).toEqual({ role: "assistant", content: null });
   });
 
   it("handles user message with content blocks but no tool_results (text extraction)", () => {
@@ -1650,31 +1650,8 @@ describe("Bedrock webSearches warning", () => {
       response: { content: "Result.", webSearches: ["test"] },
     };
     const journal = new Journal();
-    const req = {
-      method: undefined,
-      url: undefined,
-      headers: {},
-    } as unknown as http.IncomingMessage;
-    const res = {
-      _written: "",
-      writableEnded: false,
-      statusCode: 0,
-      writeHead(s: number) {
-        this.statusCode = s;
-      },
-      setHeader() {},
-      write(d: string) {
-        this._written += d;
-        return true;
-      },
-      end(d?: string) {
-        if (d) this._written += d;
-        this.writableEnded = true;
-      },
-      destroy() {
-        this.writableEnded = true;
-      },
-    } as unknown as http.ServerResponse;
+    const req = createMockReq();
+    const res = createMockRes();
 
     await handleBedrock(
       req,

src/bedrock-converse.ts

@@ -180,8 +180,12 @@ function buildBedrockStreamContentWithToolCallsEvents(
 ): Array<{ eventType: string; payload: object }> {
   const events = buildBedrockStreamTextEvents(content, chunkSize, reasoning, overrides);
   // Remove trailing metadata + messageStop events — we re-emit them after tool blocks
-  events.pop(); // metadata
-  events.pop(); // messageStop
+  for (let i = events.length - 1; i >= 0; i--) {
+    const et = (events[i] as { eventType: string }).eventType;
+    if (et === "metadata" || et === "messageStop") {
+      events.splice(i, 1);
+    }
+  }
   let blockIndex = reasoning ? 2 : 1;
 
   for (const tc of toolCalls) {
@@ -336,7 +340,7 @@ export function converseToCompletionRequest(
       if (toolUseBlocks.length > 0) {
         messages.push({
           role: "assistant",
-          content: textContent ?? null,
+          content: textContent || null,
           tool_calls: toolUseBlocks.map((b) => ({
             id: b.toolUse!.toolUseId,
             type: "function" as const,
@@ -347,7 +351,7 @@ export function converseToCompletionRequest(
           })),
         });
       } else {
-        messages.push({ role: "assistant", content: textContent ?? null });
+        messages.push({ role: "assistant", content: textContent || null });
       }
     } else {
       const warnMsg = `Unexpected message role "${msg.role}" in Converse request — skipping`;
@@ -607,6 +611,7 @@ export async function handleConverse(
         defaults,
         raw,
       );
+      if (outcome === "handled_by_hook") return;
       if (outcome !== "not_configured") {
         journal.add({
           method: req.method ?? "POST",
@@ -723,7 +728,7 @@ export async function handleConverse(
 
   // Tool call response
   if (isToolCallResponse(response)) {
-    if ("webSearches" in response) {
+    if (response.webSearches?.length) {
       logger.warn(
         "webSearches in fixture response are not supported for Bedrock Converse API — ignoring",
       );
@@ -877,6 +882,7 @@ export async function handleConverseStream(
         defaults,
         raw,
       );
+      if (outcome === "handled_by_hook") return;
       if (outcome !== "not_configured") {
         journal.add({
           method: req.method ?? "POST",
@@ -1023,7 +1029,7 @@ export async function handleConverseStream(
 
   // Tool call response — stream as Event Stream
   if (isToolCallResponse(response)) {
-    if ("webSearches" in response) {
+    if (response.webSearches?.length) {
       logger.warn(
         "webSearches in fixture response are not supported for Bedrock Converse API — ignoring",
       );

src/bedrock.ts

@@ -207,7 +207,7 @@ export function bedrockToCompletionRequest(
         if (toolUseBlocks.length > 0) {
           messages.push({
             role: "assistant",
-            content: textContent ?? null,
+            content: textContent || null,
             tool_calls: toolUseBlocks.map((b, index) => {
               if (!b.id && logger) {
                 logger.warn(
@@ -225,7 +225,7 @@ export function bedrockToCompletionRequest(
             }),
           });
         } else {
-          messages.push({ role: "assistant", content: textContent ?? null });
+          messages.push({ role: "assistant", content: textContent || null });
         }
       } else {
         messages.push({ role: "assistant", content: null });
@@ -257,6 +257,7 @@ export function bedrockToCompletionRequest(
     messages,
     stream: false,
     temperature: req.temperature,
+    max_tokens: req.max_tokens,
     tools,
   };
 }
@@ -438,6 +439,7 @@ export async function handleBedrock(
         defaults,
         raw,
       );
+      if (outcome === "handled_by_hook") return;
       if (outcome !== "not_configured") {
         journal.add({
           method: req.method ?? "POST",
@@ -571,7 +573,7 @@ export async function handleBedrock(
 
   // Tool call response
   if (isToolCallResponse(response)) {
-    if ("webSearches" in response) {
+    if (response.webSearches?.length) {
       logger.warn("webSearches in fixture response are not supported for Bedrock API — ignoring");
     }
     const overrides = extractOverrides(response);
@@ -1058,6 +1060,7 @@ export async function handleBedrockStream(
         defaults,
         raw,
       );
+      if (outcome === "handled_by_hook") return;
       if (outcome !== "not_configured") {
         journal.add({
           method: req.method ?? "POST",
@@ -1204,7 +1207,7 @@ export async function handleBedrockStream(
 
   // Tool call response — stream as Event Stream
   if (isToolCallResponse(response)) {
-    if ("webSearches" in response) {
+    if (response.webSearches?.length) {
       logger.warn("webSearches in fixture response are not supported for Bedrock API — ignoring");
     }
     const overrides = extractOverrides(response);

src/cli.ts

@@ -22,7 +22,7 @@ Options:
   -l, --latency <ms>        Latency in ms between SSE chunks (default: 0)
   -c, --chunk-size <chars>  Chunk size in characters (default: 20)
   -w, --watch               Watch fixture path for changes and reload
-      --log-level <level>   Log verbosity: silent, info, debug (default: info)
+      --log-level <level>   Log verbosity: silent, warn, info, debug (default: info)
       --validate-on-load    Validate fixture schemas at startup
       --metrics             Enable Prometheus metrics at GET /metrics
       --record              Record mode: proxy unmatched requests and save fixtures

src/cohere.ts

@@ -28,6 +28,7 @@ import {
   isToolCallResponse,
   isContentWithToolCallsResponse,
   isErrorResponse,
+  serializeErrorResponse,
   flattenHeaders,
   getTestId,
   resolveResponse,
@@ -874,6 +875,7 @@ export async function handleCohere(
         defaults,
         raw,
       );
+      if (outcome === "handled_by_hook") return;
       if (outcome !== "not_configured") {
         journal.add({
           method: req.method ?? "POST",
@@ -933,7 +935,7 @@ export async function handleCohere(
       body: completionReq,
       response: { status, fixture },
     });
-    writeErrorResponse(res, status, JSON.stringify(response));
+    writeErrorResponse(res, status, serializeErrorResponse(response));
     return;
   }
 
@@ -1033,6 +1035,11 @@ export async function handleCohere(
 
   // Tool call response
   if (isToolCallResponse(response)) {
+    if (response.webSearches?.length) {
+      logger.warn(
+        "webSearches in fixture response are not supported for Cohere v2 Chat API — ignoring",
+      );
+    }
     const overrides = extractOverrides(response);
     const journalEntry = journal.add({
       method: req.method ?? "POST",

src/constants.ts

@@ -0,0 +1,2 @@
+/** Sentinel testId used when no explicit test scope is provided. */
+export const DEFAULT_TEST_ID = "__default__";