fix(claude): avoid reusing content_block indexes in Codex SSE

[fuguiKz]

What

When translating OpenAI/Codex streaming (/v1/responses) into Claude streaming (/v1/messages), we previously reused Codex output_index as Claude content_block.index.

If a single output_index produces multiple block types (e.g. thinking + text + tool_use), this causes index/type collisions and some Claude clients fail with errors like:

• Mismatched content block type content_block_delta thinking

Fix

• Allocate sequential, unique Claude content_block.index values per logical block key (per stream).
• Ensure content_block_start is emitted before any content_block_delta for that block.
• Close any still-open blocks before emitting message_delta/message_stop on completion.

Tests

• Add a regression test to ensure indices are not reused across types and that deltas match the type started for the given index.

(Notes: go test ./internal/translator/codex/claude passes; go test ./... currently has unrelated failures upstream.)

[gemini-code-assist]

Summary of Changes

Hello @fuguiKz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves a critical bug in the translation of OpenAI/Codex streaming responses to Claude-compatible Server-Sent Events (SSE). Previously, the system could incorrectly reuse content block indexes across different types of content (like thinking, text, or tool use), leading to client-side errors. The fix introduces a sophisticated state management system to ensure each unique content block type receives its own sequential index, guaranteeing proper event sequencing and preventing type mismatches in the Claude streaming format. This significantly enhances the robustness and reliability of the streaming conversion process.

Highlights

• Unique Content Block Indexing: Implemented a new mechanism to assign sequential and unique "content_block.index" values for each distinct logical block key (e.g., "thinking", "text", "tool_use") within a Claude streaming response, resolving previous index/type collision issues.
• Stateful Stream Management: Introduced a "ConvertCodexResponseToClaudeParams" struct to maintain the state of content blocks, tracking started and stopped blocks, and ensuring "content_block_start" events are emitted before any corresponding "content_block_delta".
• Graceful Block Termination: Added logic to explicitly close any still-open content blocks by emitting "content_block_stop" events before the final "message_delta" or "message_stop" upon stream completion.
• Regression Test: A new test case was added to verify that content block indexes are not reused across different types and that delta events correctly correspond to their started block types.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively resolves a critical issue with content block index reuse in the Codex-to-Claude SSE translator, which was causing client-side errors. The introduction of a dedicated state management struct (ConvertCodexResponseToClaudeParams) to generate unique, sequential indices for each logical block is a robust solution. I appreciate the added resilience, such as ensuring content_block_start is emitted before deltas and closing all open blocks on completion. The new regression test is well-written and crucial for preventing similar issues in the future. The overall changes significantly improve the translator's correctness and reliability. I have one suggestion to refactor a small piece of duplicated logic to enhance maintainability.

[gemini-code-assist]

The logic to get a blockKey for a tool call, with a fallback for when an added event hasn't been seen, is duplicated in the handler for response.function_call_arguments.delta at lines 300-305.

This duplication can make maintenance harder. Additionally, the current implementation is inconsistent: the delta handler saves the fallback key to p.ToolKeyByOutputIndex, but this done handler does not. This could lead to subtle bugs if event ordering is unexpected.

For consistency, this handler should also save the fallback key. For example:

if blockKey == "" {
    blockKey = fmt.Sprintf("tool_use:%d", outputIndex)
    p.ToolKeyByOutputIndex[outputIndex] = blockKey // Add this line
}

Furthermore, to improve maintainability and avoid code duplication, I recommend extracting this logic into a helper method on ConvertCodexResponseToClaudeParams and using it in both places.

[fuguiKz]

FYI: this PR touches internal/translator/**, so the required translator-path-guard check will fail by design and blocks merging.

Per the workflow guidance, I opened issue #539 with repro + proposed fix and this patch for maintainers to apply: #539

If you want to cherry-pick from my fork: git fetch https://github.com/fuguiKz/CLIProxyAPI.git fix/codex-claude-sse-content-block-index && git cherry-pick a321be1 7761566

[luispater]

Please attach the failed request payload for our verification.

[fuguiKz]

Repro from Claude Code (VSCode) against CLIProxyAPI Codex→Claude /v1/messages streaming.

Client error: Mismatched content block type content_block_delta thinking (2025-12-21 ~13:40–13:50 CST).

Captured the exact failing /v1/messages request payload and SSE excerpts (log file v1-messages-2025-12-21T134753-058178319.log) here:
https://gist.github.com/fuguiKz/7dd2e3039e8878f66e2b49565c62ec42

Observation: upstream /v1/responses emits multiple response.reasoning_summary_part.added events with the same output_index: 0 but increasing summary_index (0..4). The current translator maps Claude content_block.index = output_index, so it reuses index 0 for multiple thinking blocks (stop → start again at index 0), e.g.:

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}

This appears to violate Claude SSE expectations (unique content_block.index per block) and triggers the client-side mismatch error.

(Full payload + upstream reasoning_summary indices + outgoing snippet are included in the gist files.)