Files API Chart Extraction — Code Execution Bridge Enhancement

[Number531]

Summary

Integrate Anthropic's Files API (files-api-2025-04-14 beta) into the code execution bridge to extract chart visualizations as native file_id references from containers, replacing the current base64-via-stdout pipeline.

Problem

The code execution bridge currently forces Claude to base64-encode all chart PNGs into JSON stdout:

• 33% size inflation consuming the 16K max_tokens budget
• Claude avoids producing charts entirely (see: charts_produced: 0 in every production run)
• No binary fidelity — everything round-trips through JSON string serialization

Proposed Solution — Two Phases

Phase 1: Bridge Extraction (FILES_API_CHART_EXTRACTION flag, default off)

• Comma-append files-api-2025-04-14 to beta header on client.messages.create()
• Allow plt.savefig() in system prompt (currently explicitly forbidden)
• Scan content.content[] for file_id references in response
• Download PNGs via client.beta.files.download()
• Deduplicate against base64 fallback charts
• Scope: codeExecutionBridge.js only (self-contained)

Phase 2: Chart Persistence Pipeline (CHART_PERSISTENCE flag, default off)

• Write chart PNGs to reports/{session}/charts/ on disk
• Update 5 subagent capability prompts to embed ![Chart](charts/name.png) in reports
• Add --resource-path to Pandoc invocations in documentConverter.js
• Forward chart count via SSE to frontend
• Scope: Cross-cutting (bridge, prompts, converter, hooks, frontend)

Validation

Live test (test/sdk/_live-files-api-test.mjs) confirmed both critical unknowns on 2026-03-04:

• ✅ code_execution_20260120 returns file_id in content.content[] (downloaded 46KB PNG)
• ✅ Claude produces BOTH plt.savefig() AND base64 output in the same execution

Plan Document

Full implementation spec with line-by-line edit instructions, test plan, gap analysis, and rollback procedures:

docs/pending-updates/files-api.md

Key Design Decisions

• Dual-mode extraction: Files API supplements base64, never replaces it — zero-risk fallback
• isFilesApiEnabled() function (not const): Enables per-test toggling via process.env
• Pre-existing bug fix included: end_turn success path (lines 197-205) missing finalResult.charts assignment
• Three success paths: Plan covers primary, end_turn, and alternative paths (not just two)

Files Affected

Phase 1 (self-contained)

File	Change
featureFlags.js	Add FILES_API_CHART_EXTRACTION flag
codeExecutionBridge.js	Feature flag function, beta header, prompt, extractResults, download, finalResult
code-execution-bridge.test.js	11 new test cases
.env / .env.example	Documentation entry

Phase 2 (cross-cutting)

File	Change
claude-sdk-server.js	Set CURRENT_SESSION_DIR env var
_promptConstants.js	Chart embedding instructions (5 agents)
documentConverter.js	--resource-path option plumbing
hookSSEBridge.js	chart_count in SSE events
app.js (frontend)	Chart count tag in timeline

Dependencies

• @anthropic-ai/sdk ≥ 0.70.0 (current: 0.78.0) ✅
• files-api-2025-04-14 beta header (still current as of March 2026) ✅
• CODE_EXECUTION_BRIDGE=true ✅

Labels

roadmap, enhancement, code-execution

[Number531]

Closed by PR #26 (merged). Files API chart pipeline complete:

• Phase 1 (v3.11.0): Files API chart extraction via FILES_API_CHART_EXTRACTION flag
• Phase 2/2.5 (v4.0.0): Chart persistence + memorandum integration via CHART_PERSISTENCE flag
• Phase 3 (v4.0.0): Two-layer chart reference verification gate
• Observability (v4.0.0): Per-chart error isolation + real-time SSE for validation failures

All 27 chart-verification-gate assertions pass. Full feature flag docs at docs/feature-flags.md.