V48 Gate 3 (implementation-only): write raw LLM wire I/O to ~/.bitcode/logs/executions/ID for every call, including failures

A larger repo (6274 files) hit a 413 request_too_large on the very first
Setup-phase call, but there was no way to see the literal request that
triggered it: the existing prompt sidecar (writePromptIO) only fires on
success and writes a flattened/truncated prompt string under /tmp.

writeRawLLMIO writes the literal request (system+user messages, config) at
call time and the literal response or raw error at completion, one JSON
file per LLM call, under ~/.bitcode/logs/executions/{runId}/ so it survives
past /tmp getting cleared. Wired into logLLMSubstepStart/Success/Error so
every call is covered regardless of the DIAG_* verbosity flags — the error
path especially, since that's exactly when you need to see what was sent
over the wire. Guarded off under NODE_ENV=test so jest's mocked LLM calls
don't litter the developer's home directory.

Author: geraldarthurdavis

packages/agent-generics/src/diagnostics/instrumentation.ts

@@ -1,6 +1,6 @@
 // Diagnostics instrumentation utilities (formerly named hooks)
 import type { Execution } from '@bitcode/execution-generics/Execution';
-import { log, writePromptIO, writeStepTraceJSON } from '@bitcode/logger';
+import { log, writePromptIO, writeStepTraceJSON, writeRawLLMIO } from '@bitcode/logger';
 import { DIAG_ENABLED, DIAG_TRACES, DIAG_FULL_TRACES, DIAG_FULL_PROMPTS, DIAG_TRACE_MAX, DIAG_WRITE_PROMPT_IO, DIAG_WRITE_STEP_TRACES } from './config';
 import { collectExecutionTrace, summarizeExecutionTrace } from './trace';
 
@@ -45,6 +45,14 @@ function maybeLogDiagnosticsBanner() {
   } catch {}
 }
 
+// The literal wire-call correlation key for the raw LLM I/O sidecar — the
+// full execution path (which already encodes phase/agent/step/failsafe/
+// gen-N/generation) plus the sequence, so concurrent or repeated calls
+// within the same agent never collide.
+function rawLLMPathKey(ctx: ReturnType<typeof getCtx>): string {
+  return [...(ctx.path || []), ctx.sequence].filter(Boolean).join(':');
+}
+
 export async function logLLMSubstepStart(
   execution: Execution,
   sequence: string,
@@ -54,8 +62,21 @@ export async function logLLMSubstepStart(
   llmConfig?: { model?: string; provider?: string }
 ) {
   maybeLogDiagnosticsBanner();
-  if (!(DIAG_ENABLED || DIAG_FULL_PROMPTS || DIAG_TRACES)) return;
   const ctx = getCtx(execution, sequence);
+
+  // Always attempt the raw wire-exchange sidecar (its own env gate, default
+  // on) — independent of the DIAG_* verbosity flags below, since this is a
+  // local-debugging artifact meant to survive even when nothing else logs.
+  writeRawLLMIO({
+    executionId: String(ctx.correlationId || ''),
+    pathKey: rawLLMPathKey(ctx),
+    kind: 'request',
+    provider: (llmConfig as any)?.provider,
+    model: llmConfig?.model,
+    content: { systemPrompt, userPrompt, combinedPrompt, ...ctx },
+  }).catch(() => {});
+
+  if (!(DIAG_ENABLED || DIAG_FULL_PROMPTS || DIAG_TRACES)) return;
   log('[llm substep] start', 'debug', {
     ...ctx,
     systemLen: systemPrompt.length,
@@ -83,6 +104,16 @@ export async function logLLMSubstepSuccess(
 ) {
   maybeLogDiagnosticsBanner();
   const ctx = getCtx(execution, sequence);
+
+  writeRawLLMIO({
+    executionId: String(ctx.correlationId || ''),
+    pathKey: rawLLMPathKey(ctx),
+    kind: 'response',
+    provider: output?.metadata?.provider,
+    model: output?.metadata?.model,
+    content: { content: output?.content, usage: output?.usage, metadata: output?.metadata },
+  }).catch(() => {});
+
   if (DIAG_ENABLED || DIAG_FULL_PROMPTS || DIAG_TRACES) {
     log('[llm substep] success', 'debug', {
       ...ctx,
@@ -138,8 +169,22 @@ export function logLLMSubstepError(
   err: unknown,
   durationMs?: number
 ) {
-  if (!DIAG_ENABLED) return;
   const ctx = getCtx(execution, sequence);
+
+  // The raw sidecar is the whole point on the failure path — a 413/400/etc.
+  // from the provider is exactly the case where you need to see the literal
+  // request that triggered it, and DIAG_ENABLED (verbose console logging)
+  // being off shouldn't suppress that.
+  writeRawLLMIO({
+    executionId: String(ctx.correlationId || ''),
+    pathKey: rawLLMPathKey(ctx),
+    kind: 'error',
+    provider: ctx.provider,
+    model: ctx.model,
+    content: err,
+  }).catch(() => {});
+
+  if (!DIAG_ENABLED) return;
   const message = err instanceof Error ? err.message : String(err);
   log('[llm substep] error', 'error', {
     ...ctx,

packages/logger/src/index.ts

@@ -1 +1 @@
-export { log, writePromptIO, writeStepTraceJSON } from './logger';
+export { log, writePromptIO, writeStepTraceJSON, writeRawLLMIO } from './logger';

packages/logger/src/logger.ts

@@ -237,6 +237,64 @@ export async function writePromptIO(opts: {
   }
 }
 
+// ------------------------------------------------------------
+// Raw LLM wire I/O writer (local debugging utility)
+//
+// Unlike writePromptIO (a flattened-prompt sidecar under /tmp, success-only,
+// intended for quick tailing), this writes the literal request payload and
+// the literal response/error for every LLM call — including failures like a
+// 413 request_too_large — to a per-run directory under the user's home
+// directory, so it survives past /tmp getting cleared and is easy to find.
+// ------------------------------------------------------------
+
+const RAW_LLM_LOG_BASE_DIR = joinPath(os.homedir(), '.bitcode', 'logs', 'executions');
+let __rawLLMIOSeq = 0;
+
+export async function writeRawLLMIO(opts: {
+  executionId?: string;
+  pathKey: string;
+  kind: 'request' | 'response' | 'error';
+  provider?: string;
+  model?: string;
+  content: unknown;
+}): Promise<string | undefined> {
+  try {
+    const enabledEnv = String(process?.env?.BITCODE_WRITE_RAW_LLM_IO ?? '1').toLowerCase();
+    if (enabledEnv === '0' || enabledEnv === 'false') return undefined;
+    // Never litter the developer's home directory from a test run — jest
+    // exercises this same LLM-substep code path with mocked LLMs.
+    if (process?.env?.NODE_ENV === 'test') return undefined;
+
+    const runDir = joinPath(RAW_LLM_LOG_BASE_DIR, sanitizeId(opts.executionId || 'run'));
+    try { await fs.mkdir(runDir, { recursive: true }); } catch {}
+
+    const safe = (s: any) => String(s || '').toLowerCase().replace(/[^a-z0-9-_]+/g, '-').slice(0, 160) || 'na';
+    const seq = String(++__rawLLMIOSeq).padStart(5, '0');
+    const filename = joinPath(runDir, `${seq}-${safe(opts.pathKey)}.${opts.kind}.json`);
+
+    const payload = opts.kind === 'error'
+      ? {
+          timestamp: new Date().toISOString(),
+          provider: opts.provider,
+          model: opts.model,
+          error: opts.content instanceof Error
+            ? { name: opts.content.name, message: opts.content.message, stack: opts.content.stack }
+            : opts.content,
+        }
+      : {
+          timestamp: new Date().toISOString(),
+          provider: opts.provider,
+          model: opts.model,
+          content: opts.content,
+        };
+
+    await fs.writeFile(filename, JSON.stringify(payload, null, 2), 'utf8');
+    return filename;
+  } catch {
+    return undefined;
+  }
+}
+
 // ------------------------------------------------------------
 // Step Trace sidecar writer (debug utility)
 // ------------------------------------------------------------