feat(debug): add content-free adapter and bridge stream diagnostics

docs-site/src/content/docs/reference/cli/agents.md

@@ -173,6 +173,9 @@ ocx debug usage on|off|status|reset
 ocx debug usage logs [-f|--follow]
 ```
 
+Provider debug also records structural adapter/bridge stream events: sequence, attempt and recovery labels, byte counts, and process-local HMAC fingerprints. Text, reasoning, tool arguments, queries, and provider state are not included in these stream diagnostic records. Fingerprints change after a proxy restart; disable provider debug after collecting a reproduction.
+
+
 With no scope, `ocx debug` prints usage and, when the proxy is stopped, the next-start environment
 defaults. Provider debug defaults from `OCX_DEBUG=1` (legacy `OCX_DEBUG_FRAMES=1` also works); usage
 debug defaults from `OPENCODEX_USAGE_DEBUG=1`.

src/bridge.ts

@@ -43,6 +43,7 @@ import {
   type TranslatorBudget,
   type TranslatorBufferKind,
 } from "./lib/translator-budget";
+import { debugFingerprint, debugStreamDiagnostic, type DebugStreamDiagnosticContext } from "./lib/debug";
 
 function uuid(): string {
   return crypto.randomUUID().replace(/-/g, "");
@@ -204,6 +205,88 @@ interface OutputItem {
 
 export type ResponsesTerminalStatus = "completed" | "failed" | "incomplete";
 
+export interface BridgeDiagnosticSequence { value: number }
+
+export interface BridgeDiagnosticContext extends DebugStreamDiagnosticContext {
+  sequence?: BridgeDiagnosticSequence;
+}
+
+export function adapterEventDiagnosticDetails(event: AdapterEvent): Record<string, unknown> {
+  switch (event.type) {
+    case "text_delta":
+      return { byteLength: Buffer.byteLength(event.text), fingerprint: debugFingerprint(event.text) };
+    case "thinking_delta":
+      return { byteLength: Buffer.byteLength(event.thinking), fingerprint: debugFingerprint(event.thinking) };
+    case "reasoning_raw_delta":
+      return { byteLength: Buffer.byteLength(event.text), fingerprint: debugFingerprint(event.text) };
+    case "thinking_signature":
+    case "redacted_thinking":
+    case "kiro_redacted_reasoning": {
+      const content = event.type === "thinking_signature" ? event.signature : event.data;
+      return { byteLength: Buffer.byteLength(content), fingerprint: debugFingerprint(content) };
+    }
+    case "tool_call_delta":
+      return { byteLength: Buffer.byteLength(event.arguments), fingerprint: debugFingerprint(event.arguments) };
+    case "tool_call_start":
+      return {
+        idByteLength: Buffer.byteLength(event.id),
+        idFingerprint: debugFingerprint(event.id),
+        nameByteLength: Buffer.byteLength(event.name),
+        nameFingerprint: debugFingerprint(event.name),
+      };
+    case "web_search_call_begin":
+      return { idByteLength: Buffer.byteLength(event.id), idFingerprint: debugFingerprint(event.id) };
+    case "web_search_call_end": {
+      const queries = JSON.stringify(event.queries);
+      return {
+        idByteLength: Buffer.byteLength(event.id),
+        idFingerprint: debugFingerprint(event.id),
+        byteLength: Buffer.byteLength(queries),
+        fingerprint: debugFingerprint(queries),
+        status: event.status,
+      };
+    }
+    case "error":
+      return {
+        byteLength: Buffer.byteLength(event.message),
+        fingerprint: debugFingerprint(event.message),
+        ...(event.status !== undefined ? { status: event.status } : {}),
+        ...(event.code !== undefined
+          ? { codeByteLength: Buffer.byteLength(event.code), codeFingerprint: debugFingerprint(event.code) }
+          : {}),
+        ...(event.retryable !== undefined ? { retryable: event.retryable } : {}),
+      };
+    case "incomplete":
+      return {
+        ...(event.message !== undefined ? { byteLength: Buffer.byteLength(event.message), fingerprint: debugFingerprint(event.message) } : {}),
+        reasonByteLength: Buffer.byteLength(event.reason),
+        reasonFingerprint: debugFingerprint(event.reason),
+        ...(event.retryable !== undefined ? { retryable: event.retryable } : {}),
+      };
+    case "done":
+      return {
+        ...(event.stopReason !== undefined
+          ? { stopReasonByteLength: Buffer.byteLength(event.stopReason), stopReasonFingerprint: debugFingerprint(event.stopReason) }
+          : {}),
+        ...(event.endTurn !== undefined ? { endTurn: event.endTurn } : {}),
+      };
+    default:
+      return {};
+  }
+}
+
+/** Emit one adapter-stage diagnostic while preserving one sequence across sidecar iterations. */
+export function diagnoseAdapterEvent(context: BridgeDiagnosticContext, event: AdapterEvent): void {
+  const sequence = context.sequence ??= { value: 0 };
+  debugStreamDiagnostic(
+    context,
+    "adapter",
+    ++sequence.value,
+    event.type,
+    adapterEventDiagnosticDetails(event),
+  );
+}
+
 export function bridgeToResponsesSSE(
   events: AsyncIterable<AdapterEvent>,
   modelId: string,
@@ -264,6 +347,8 @@ export function bridgeToResponsesSSE(
       setInterval: (handler: () => void, ms: number) => unknown;
       clearInterval: (id: unknown) => void;
     };
+    /** Internal, opt-in structural stream diagnostics. */
+    diagnostic?: BridgeDiagnosticContext;
   },
 ): ReadableStream<Uint8Array> {
   const replayCacheScope = options?.replayCacheScope;
@@ -372,6 +457,7 @@ export function bridgeToResponsesSSE(
   };
   const responseId = options?.responseId ?? `resp_${uuid()}`;
   let seq = 0;
+  let diagnosticSequence = 0;
   // Set once the client is gone (cancel) or an enqueue throws on a torn-down controller, so we
   // never enqueue again and never throw a second time inside start() — the RC2 double-throw that
   // otherwise surfaced as proxy-side stream noise on every client disconnect.
@@ -932,6 +1018,17 @@ export function bridgeToResponsesSSE(
           }
           if (next.done) { upstreamDone = true; break; }
           const event = next.value;
+          if (options?.diagnostic) {
+            debugStreamDiagnostic(
+              options.diagnostic,
+              "bridge",
+              options.diagnostic.sequence
+                ? ++options.diagnostic.sequence.value
+                : ++diagnosticSequence,
+              event.type,
+              adapterEventDiagnosticDetails(event),
+            );
+          }
           let terminalEvent = false;
           // Invisible adapter heartbeats (and buffered web-search progress) count as upstream
           // liveness only — they must not suppress wire keepalives that re-arm Codex idle timers.

src/images/loop.ts

@@ -18,7 +18,7 @@ import type { AdapterEvent, OcxMessage, OcxParsedRequest, OcxProviderContinuatio
 import { namespacedToolName, toolChoiceToolPredicate } from "../types";
 import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
 import type { AttemptRecoveryKind } from "../usage/log";
-import { bridgeToResponsesSSE } from "../bridge";
+import { bridgeToResponsesSSE, diagnoseAdapterEvent, type BridgeDiagnosticContext } from "../bridge";
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait } from "../lib/upstream-retry";
@@ -279,6 +279,8 @@ export interface ImageBridgeDeps {
   onCompletedResponse?: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => void;
   /** WebSocket Responses path only — leave response id empty for protocol compatibility. */
   forceEmptyResponseId?: boolean;
+  /** Internal, opt-in structural stream diagnostics shared with the final bridge. */
+  diagnostic?: BridgeDiagnosticContext;
 }
 
 /**
@@ -651,6 +653,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         inactivityTimeoutMs: stallTimeoutMs,
         translatorBudget,
       })) {
+        if (deps.diagnostic) {
+          deps.diagnostic.adapterName = prepared.responseAdapter.name;
+          diagnoseAdapterEvent(deps.diagnostic, event);
+        }
         if (event.type === "heartbeat") yield event;
         else events.push(event);
       }
@@ -962,6 +968,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         onUsage: (usage: OcxUsage | undefined) => deps.onUsage?.(usage),
       } : {}),
       ...(deps.onCompletedResponse ? { onCompletedResponse: deps.onCompletedResponse } : {}),
+      ...(deps.diagnostic ? { diagnostic: deps.diagnostic } : {}),
     },
   );
   return new Response(sse, { headers: SSE_HEADERS });

src/lib/debug.ts

@@ -1,7 +1,10 @@
+import { createHmac, randomBytes } from "node:crypto";
 import { appendDebugLogLine } from "./debug-log-buffer";
 import { isDebugEnabled } from "./debug-settings";
 import { redactSecrets } from "./redact";
 
+let debugFingerprintKey: Uint8Array | undefined;
+
 function emitDebugLine(line: string): void {
   if (!isDebugEnabled()) return;
   try {
@@ -29,3 +32,42 @@ export function debugProviderDiagnostic(adapter: string, event: string, details:
     /* diagnostics must never affect request handling */
   }
 }
+
+/** Process-local, content-free correlation aid for opt-in provider diagnostics. */
+export function debugFingerprint(value: string | Uint8Array): string | undefined {
+  if (!isDebugEnabled()) return undefined;
+  try {
+    debugFingerprintKey ??= randomBytes(32);
+    return createHmac("sha256", debugFingerprintKey).update(value).digest("hex");
+  } catch {
+    return undefined;
+  }
+}
+
+export interface DebugStreamDiagnosticContext {
+  requestId: string;
+  adapterName: string;
+  attempt?: number;
+  recovery?: string;
+}
+
+export type DebugStreamDiagnosticStage = "adapter" | "bridge";
+
+/** Emit one structural line for an adapter/bridge event without retaining its content. */
+export function debugStreamDiagnostic(
+  context: DebugStreamDiagnosticContext,
+  stage: DebugStreamDiagnosticStage,
+  sequence: number,
+  eventType: string,
+  details?: Record<string, unknown>,
+): void {
+  debugProviderDiagnostic(context.adapterName, "stream", {
+    stage,
+    sequence,
+    eventType,
+    ...(context.requestId !== undefined ? { requestId: context.requestId } : {}),
+    ...(context.attempt !== undefined ? { attempt: context.attempt } : {}),
+    ...(context.recovery !== undefined ? { recovery: context.recovery } : {}),
+    ...details,
+  });
+}