fix(codex): recover truncated HTTP tool streams before tool commit - #120

Summary

• keep provisional Codex function-call events private until an authoritative response.output_item.done arrives with the complete call;
• retry a truncated HTTP response when only provisional tool arguments were received, without leaking the abandoned tool ID, name, or partial JSON to Claude Code;
• translate a completed function call into one atomic Anthropic tool block, including standalone output_item.done events without output_index or a preceding output_item.added;
• validate authoritative function arguments as a bounded JSON object before emitting content_block_stop, normalizing empty input to {};
• preserve completed tool calls while dropping any unrelated provisional call left behind by a later body failure or terminal response;
• prohibit exact request replay after non-empty reasoning/text or a completed hosted/function tool;
• keep the stalled-Read recovery as a narrow bounded compatibility exception;
• map policy, quota, permission, context-window, and payload-size failures into stable Anthropic client statuses/types while preserving the upstream message and applicable retry metadata.

Problem

The incremental Codex HTTP reader previously treated every non-empty response.function_call_arguments.delta as committed semantic output.

If the upstream HTTP body was reset while a function-call JSON object was still being streamed, CCP had already emitted an Anthropic tool_use start and partial input_json_delta. The retry window was therefore closed even though Claude Code could not execute the incomplete tool. The request ended with an in-stream API error and the agent terminated early.

The deterministic raw-TCP fixture reproduces this by advertising a larger Content-Length, sending a partial function call, and closing the first connection before the body is complete.

Protocol boundary

This change follows the current native Codex lifecycle rather than treating argument deltas as authoritative:

• the Codex Responses parser does not require output_index in its stream event structure;
• response.function_call_arguments.delta and .done are not used as the executable function call;
• response.output_item.done is deserialized as the final ResponseItem;
• native Codex persists and schedules the tool from that completed item before response.completed;
• official function-call fixtures contain a standalone output_item.done with full call_id, name, and arguments.

Sources:

• Codex Responses stream event shape
• Responses event parsing and ignored argument deltas
• Official standalone function-call fixture
• Tool dispatch from OutputItemDone
• Persistence and tool future creation
• Parallel tool lifecycle test

The downstream side uses Anthropic's normal stream contract: an incomplete input_json_delta is not a complete tool, while the emitted content_block_stop finalizes the tool block. CCP therefore releases the start, complete JSON delta, and stop atomically with respect to the replay decision.

• Anthropic streaming events
• Anthropic Python SDK stream parser

Comparison with other proxies

This implementation deliberately uses a stricter recovery boundary than the other current open-source Codex/Claude proxy paths we reviewed.

Primary-source references:

• CLIProxyAPI emits tool_use at item-added time and forwards partial arguments immediately: item added, argument deltas.
• CLIProxyAPI turns a truncated Codex stream into a request-scoped incomplete error instead of replaying the pre-commit attempt: terminal error, retry exclusion.
• auth2api also exposes function-call start/deltas before the final item and only retries failures before the successful response body is handed off: translator, HTTP retry loop, stream completion/accounting.
• OpenCode independently confirms that a tool becomes executable only from the completed call and parses final input as JSON: Responses completion, tool finalization.
• OpenCode publishes provisional tool-input events and may retry while partial output remains in session state: provisional events, unbounded argument accumulation, session retry.
• Claude Code Router's own retry/fallback loop ends once a successful response object has been returned; body-level conversion is delegated to an external gateway package: executor, stream EOF handling, gateway dependency.

CLIProxyAPI's translator has richer interleaving queues but no aggregate byte bound for deferred events and accumulated arguments: parallel call resolution, unbounded argument accumulation, 50 MB scanner-token bound.

CLIProxyAPI has a useful stronger ordering policy for interleaved blocks: it preserves first-added order by delaying a completed later tool behind an older partial one. This change intentionally follows native Codex completion order instead: an authoritative completed tool is released immediately so an unrelated stalled provisional call cannot block it. CLIProxyAPI tests its first-added ordering; this change separately tests its completion-order policy: CLIProxyAPI parallel-order tests.

Retry and safety invariants

1. Provisional function-call events never reach Claude Code.
2. A body/decode/EOF/idle failure may restart the exact HTTP request only while no non-empty reasoning/text or completed function/hosted-tool item has been committed.
3. A complete function call is emitted as a single valid Anthropic block and immediately closes the replay window.
4. Non-empty reasoning and text retain the existing no-replay boundary. Native Codex can rebuild a retry from its persisted turn history; CCP cannot safely emulate that by replaying the same request body.
5. Completed tools remain visible if a later provisional tool is truncated; the incomplete tool remains invisible.
6. Provisional state is attempt-local and cleared on retry or terminal response.
7. Buffered state is bounded by a combined byte budget. Large ordinary Bash deltas are discarded rather than accumulated; only the special Read repair keeps bounded argument state.
8. Missing or ambiguous optional aliases cannot merge two provisional calls.
9. Authoritative arguments must be a bounded JSON object. Malformed or non-object values cannot cross content_block_stop; empty input is normalized to {}.
10. Upstream failures preserve their message; status and error type are normalized into the stable Anthropic client contract (including the intentional context-window 413 mapping). Retryable errors retain Retry-After while an HTTP response can still carry that header.
11. Downstream cancellation still aborts active reads and retry backoff.

Prevented failure modes

Stalled Read compatibility

The existing whitespace-stalled Read repair remains intentionally separate from the normal Codex function-call lifecycle.

It can finish locally only when:

• exactly one provisional function call exists;
• it is a Read call with valid recoverable JSON;
• no other output item remains open;
• the accumulated argument state is within the configured bounds.

The speculative probe is side-effect free. Read-offset rewrite metadata is recorded only when the repaired tool is actually committed downstream.

Verification

Deterministic regressions cover:

• raw HTTP truncation during one and multiple provisional tool calls;
• no leakage from an abandoned attempt;
• standalone and multiple completed function calls without output_index;
• empty, malformed, nested, oversized, and non-object authoritative arguments;
• call-ID-aware resolution when an indexed call is already open;
• completed tool plus later provisional truncation;
• terminal response with unfinished provisional tools;
• reasoning/text before and during provisional calls;
• no replay after non-empty reasoning/text or completed tool output;
• sole and parallel stalled-Read cases;
• speculative stalled-Read rewrite-state isolation;
• aggregate pending-event/retained-Read and per-tool argument bounds;
• typed permanent and retryable failures;
• cancellation and retry exhaustion.

Executed checks:

• cargo +1.96.0 fmt --all -- --check
• cargo +1.96.0 clippy --locked --offline --all-targets -- -D warnings
• cargo test --locked --offline --all-targets -- --skip cancellation_while_replacement_startup_is_blocked_aborts_request_state
• focused Codex HTTP, live translator, and continuation tests
• cargo build --release --locked --offline

The full test suite completed with 1,067 passed, 0 failed, and the one known baseline timing test filtered as described below.

A live Core compatibility matrix also exercised every currently listed model: 9 Codex models and 22 OpenCode Go models. Of the 31 routes:

• 14 passed the strict harness (including three models whose only distinction was that no visible thinking block was emitted);
• 8 completed the full file/classifier/tool flow but reported the bare upstream model ID in Claude assistant events;
• 4 completed the full flow and final marker but made additional diagnostic or repeated Bash calls beyond the harness's exact-one-call expectation;
• 5 were rejected before agent execution for provider-side reasons: two legacy Codex IDs are unsupported with ChatGPT accounts, two DeepSeek routes require the provider's China opt-in, and Grok returned a temporary endpoint-unavailable 502.

Every model that reached agent execution completed the file mutation/readback and final marker. The expensive final group was run last: kimi-k3 passed the strict harness, qwen3.8-max completed the full flow with the bare-ID reporting distinction above, and grok-4.5 hit the provider-side 502.

The skipped WebSocket cancellation timing test also times out on the unchanged PR base when run in isolation; it is not affected by this HTTP change.

Compatibility notes

• This is an HTTP recovery refinement on top of the incremental streaming and stream-state semantics introduced by PRs Stream Codex HTTP responses incrementally #51 and fix(codex): unify live stream commit and terminal semantics #103 .
• The WebSocket transport keeps its existing retry policy.
• Codex's default terminal and post-terminal validation remains strict.
• OpenCode Responses reuses the shared live translator, so its completed-call path also receives the call-ID-aware standalone output_item.done handling; the existing OpenCode Responses compatibility tests remain green.