fix(responses): preserve Codex namespace tool calls

[dcadenas]

TLDR

Problem this solves:

• Codex groups MCP tools under type=namespace tools
• The Responses to Chat Completions bridge silently dropped them
• Models on chat-only providers never saw any MCP tool
• Even with the tools flattened, the follow-up turn died with a provider 400 because Codex echoes history as function_call, assistant message, function_call_output, and the bridge emitted the assistant message between the tool_calls message and its tool result

How it solves it:

• Flattens nested namespace members into chat function tools
• Restores name plus namespace on output, streaming and non-streaming
• Preserves and validates allowed_callers on namespace tools
• Rejects flattened names that collide with top-level functions
• Builds the streaming restoration map once per iterator
• Preserves encrypted content input blocks as text
• Serializes flattened tool parameters as plain dicts so outbound JSON encoding succeeds
• Folds an assistant message that lands between a function_call and its output into the preceding tool_calls message, keeping the tool result immediately after it as DeepSeek and Anthropic require
• Requalifies echoed function_call history items (short name plus namespace) back to the flattened namespace__tool name, so replayed history matches the tool names the provider was given
• Sets namespace on non-streaming output items only when one was restored, matching the streaming path

User Flow

Before: a developer points the Codex CLI at a LiteLLM model backed by a chat-completions-only provider and their MCP tools are unusable

1. They configure the Codex CLI with an MCP server (for example a Slack one) and a LiteLLM model backed by a chat-completions-only provider such as a Baseten-hosted model
2. Codex sends POST https://litellm-domain/v1/responses with a tool like {"type": "namespace", "name": "mcp__slack", "tools": [{"type": "function", "name": "slack_add_reaction", ...}, ...]}
3. The call returns 200, but when they ask the agent to use a Slack tool it answers that no such tool is available or the turn fails with a 400, because the namespaced tools were dropped before the model ever saw them

After: the same session can call the MCP tools

1. They configure the Codex CLI the same way
2. Codex sends the same POST https://litellm-domain/v1/responses with the namespace tool
3. The response streams back a function_call output item with "name": "slack_add_reaction" and "namespace": "mcp__slack", Codex runs the MCP tool, and the agent completes the task

Relevant issues

Related to #29887

Linear ticket

Resolves LIT-4903

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

QA'd with the real Codex CLI v0.145.0 driving a live local proxy against the real DeepSeek API. The customer hit this on Baseten-hosted deepseek and glm models; deepseek/deepseek-chat rides the exact same Responses to Chat Completions bridge

Proxy config (proxy_config.yaml):

model_list:
  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Codex config ($CODEX_HOME/config.toml):

model = "deepseek-chat"
model_provider = "litellm"
preferred_auth_method = "apikey"

[model_providers.litellm]
name = "litellm"
base_url = "http://127.0.0.1:24303/v1"
env_key = "LITELLM_QA_KEY"
wire_api = "responses"

[mcp_servers.everything]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

Before, on the merge base (7e80e094c4, proxy booted with python litellm/proxy/proxy_cli.py --config proxy_config.yaml --port 24303 --detailed_debug): the model never sees the MCP tools and the turn dies with a 400

› Use the everything MCP server's add tool to add 21 and 21, then tell me the result.
• Calling codex.list_mcp_resources({})
• Calling codex.list_mcp_resource_templates({})
■ {"error":{"message":"litellm.BadRequestError: DeepseekException - {\"error\":{\"message\":\"An assistant message
with 'tool_calls' must be followed by tool messages responding to each 'tool_call_id'. (insufficient tool
messages following tool_calls message)\", ... \"code\":\"400\"}}

The proxy debug log for that run shows Codex sent {"type": "namespace", "name": "mcp__everything", "tools": [...]} on POST /v1/responses while the outbound request to DeepSeek contained zero namespace tools

After, on this PR's head (cfcd0cda8a, same configs, port 29471): the MCP tool is called, the answer comes back, and a second turn that echoes the namespaced history also completes

› Add 21 and 21 using the everything server's get-sum tool.
• Called everything.get-sum({"a":21,"b":21})
  └ The sum of 21 and 21 is 42.
• The sum of 21 and 21 is 42.

› Now add 100 and 23 with the same tool.
• Called everything.get-sum({"a":100,"b":23})
  └ The sum of 100 and 23 is 123.
• The sum of 100 and 23 is 123.

The proxy debug log for the second turn shows the replayed history went out to DeepSeek with 'tool_calls': [{..., 'function': {'name': 'mcp__everything__get_sum', 'arguments': '{"a": 21, "b": 21}'}}], matching the advertised tool name

Type

🐛 Bug Fix

Caveats (if any)

• Restoring an unqualified tool name needs it unique across namespaces
• The collision validator does not flag a top-level function deliberately named like a flattened namespace__tool; that setup surfaces as a provider-side duplicate-name error

QA runbook

1. Boot a proxy from this branch with the yaml above on a free port
2. Point Codex CLI at it with the toml above (set LITELLM_QA_KEY to the master key) and an MCP server configured
3. Ask the agent to use one of the MCP server's tools, then ask a follow-up that reuses the same tool
4. Both turns must complete with the tool called and no error banner

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[CLAassistant]

All committers have signed the CLA.

[greptile-apps]

Greptile Summary

This PR fixes the Responses-to-Chat-Completions bridge so Codex namespace tools (type=namespace) are preserved end-to-end when routing through chat-only providers like DeepSeek. It also folds the spurious assistant content message that Codex echoes between a function_call and its output, preventing 400 errors from providers that require tool results to immediately follow the tool_calls message.

• Namespace tools are now flattened into namespace__tool_name chat function tools on the way out and restored to name + namespace on the way back (both streaming and non-streaming), with a lookup map built once per request.
• function_call history items that carry a namespace field are requalified to the flat name so replayed history matches the advertised tool names; encrypted content blocks are preserved as text.
• All changes are fully covered by new mock-only unit tests; no existing test assertions were weakened.

Confidence Score: 5/5

• The bridge changes are well-guarded and thoroughly tested; the one gap in the collision validator is a narrow edge case that requires an unusual user configuration to trigger.
• The core logic — namespace flattening, name restoration, assistant-message folding — is correct and covered by targeted unit tests. The only substantive finding is that _validate_namespace_name_collisions does not include flat namespace tool names in its collision check, so a top-level function sharing a name with a flat namespace tool slips through undetected. In practice this requires the caller to deliberately register both, and the downstream effect (duplicate tool names forwarded to the provider) is a provider-level error rather than silent data corruption.
• transformation.py around _validate_namespace_name_collisions — the flat-namespace case is the one gap worth a second look before merge.

Important Files Changed

Filename	Overview
litellm/responses/litellm_completion_transformation/transformation.py	Core Responses-to-Chat-Completion bridge; adds namespace flattening, assistant-message folding, encrypted-content preservation, and history requalification — all with correct guard conditions and well-tested. One gap: the flat-namespace-tool case is not covered by the collision validator.
litellm/responses/litellm_completion_transformation/streaming_iterator.py	Namespace map now built once in init and reused for delta and final events; restoration logic is symmetric with the non-streaming path. Previously flagged per-chunk rebuild and broken fallback are both resolved.
litellm/responses/litellm_completion_transformation/custom_tools.py	Minimal change: _validated_allowed_callers renamed to validated_allowed_callers to make it importable by the new namespace flattening code. No logic changes.
tests/test_litellm/responses/litellm_completion_transformation/test_litellm_completion_responses.py	Large addition of new unit tests covering nested/flat namespace flattening, JSON serializability, allowed_callers validation, name-collision detection, history requalification, and streaming restoration — no weakening of existing assertions detected.
tests/test_litellm/responses/litellm_completion_transformation/test_tool_output_order_preserved_for_gemini.py	Adds regression test for the Codex echo pattern (function_call → assistant message → function_call_output); verifies the assistant message is folded so the tool result immediately follows the tool_calls message.

_{Reviews (6): Last reviewed commit: "fix(responses): leave namespace unset on..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 97.36842% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...itellm_completion_transformation/transformation.py	96.70%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 3 · PR risk: 0/10

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing dcadenas:litellm_fix_codex_responses_namespace_tools (cfcd0cd) with litellm_internal_staging (9cc5a81)}

[dcadenas]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a64a83b. Configure here.}

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit cfcd0cd. Configure here.}

[mateo-berri]

LGTM