Skip to content

feat(gateway): recognize native client conversation identities - #2419

Merged
frf12 merged 2 commits into
oceanbase:masterfrom
jasper-yl:fix/gateway-codex-thread-identity
Nov 2, 2026
Merged

frf12 merged 2 commits into
oceanbase:masterfrom
jasper-yl:fix/gateway-codex-thread-identity

Conversation

@jasper-yl

@jasper-yl jasper-yl commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Which issue or RFC does this PR close?

Closes #2418. Refs #2406.

Rationale for this change

The gateway prepares once per user message and replays the exact injection within a conversation (#2416), but it identified the conversation only from X-PowerContext-Conversation-ID, which no current coding client sends. An unmodified Codex, Claude Code or OpenCode therefore prepared on every request of its tool loop. Each client already sends a native per-thread or per-session identity; the headers it shares between a parent and its subagents must not be used, or a subagent would replay its parent's injection.

What changes are included in this PR?

conversation_id(headers, format) in ingress.rs takes the first of these that is present and valid (1–256 visible ASCII characters):

Source Header Conversation
PowerContext host X-PowerContext-Conversation-ID the value; overrides every native source
Claude Code x-claude-code-session-id, plus x-claude-code-agent-id when present the session for the main agent, session + agent for each subagent (subagents share the session ID)
OpenCode x-opencode-session-id the session; a child session has its own ID. x-opencode-session / x-session-affinity are ignored because they may carry the parent's value
Codex, Responses route only thread-id the thread; a subagent has its own thread ID. session-id and prompt_cache_key are shared with the parent and ignored. thread-id has no client prefix, so it is not read on the Chat route

Each source has its own prefix (powercontext:, claude-code:, opencode:, codex-thread:), so IDs from different sources never share replay state. Claude Code's session and agent are joined with a space, which a valid value cannot contain, so a combination never equals another session ID.

gateway/README.md and the "Gateway context injection" section of deploy-server.md (English and Chinese) document the table. The replay lifecycle from #2416 and the default policy from #2417 are unchanged; a request identified by a native header counts as a conversation for the combined-deployment default.

Claude Code limitation: Claude Code speaks the Anthropic Messages API (/v1/messages), and the gateway serves only the Chat and Responses routes. Its headers therefore take effect only behind a proxy that translates its requests to one of those routes and forwards the headers. The docs say so.

Are there any user-facing changes?

Yes, for deployments with injection enabled (including the combined-deployment default): Codex, OpenCode, and translated Claude Code requests now prepare once per user message per thread or session and replay within the tool loop, instead of preparing at every step or, under the combined default, not being injected at all. Subagents and child sessions prepare separately. Requests with X-PowerContext-Conversation-ID behave as before.

How was this change tested?

  • cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings and cargo test in gateway/: 112 passed.

  • New ingress tests, one per adapter plus precedence:

    • codex_threads_are_separate_conversations_on_the_responses_route: Codex 0.145 headers; a subagent thread with the parent's session-id is a separate conversation; the Chat route ignores thread-id.
    • claude_code_subagents_are_separate_conversations: main agent, subagent and nested subagent on both routes; a session ID containing / cannot collide with a session + agent pair.
    • opencode_child_sessions_are_separate_conversations: a child session with the parent's affinity headers is separate; affinity headers alone are not a conversation.
    • the_powercontext_header_overrides_every_native_identity.

    Tool continuations, isolation by conversation and concurrent commits for a given conversation are covered by the executor tests from fix(gateway): prepare once per user message within a conversation and replay it #2416.

  • End to end with unmodified clients, a master Server in enforcing mode, a gateway on this branch with injection on, and a scripted Responses upstream that makes the parent start a subagent or child session. A pass-through shim between the client and the gateway logged the client headers and added max_output_tokens when absent (Codex never sends it; bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420). For the control runs the shim also removed the identity header.

    Client Requests Threads / sessions prepare_context with this branch without the identity header
    Codex CLI 0.145.0 (spawn_agent, wait_agent) 10 2 2 10
    OpenCode 1.19.5 (task tool, built-in openai provider) 5 2 3 5

    In the OpenCode run the parent's session-title request has different messages from the task, so it prepares separately from the task's first request; the parent's tool continuations replayed. The child session sent its own x-opencode-session-id and x-opencode-parent-session-id. Codex's subagent requests were withheld by Core for an unrelated reason (bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420); their retries replayed the subagent's own preparation.

  • Claude Code was not run end to end, because the gateway has no Messages route; its adapter is covered by the unit test against the documented headers.

AI usage statement

Built with Claude Code (Claude Opus 5.5), which read the client sources and documentation, wrote the change, the tests and the docs, and ran the checks above.

🤖 Generated with Claude Code

@frf12

frf12 commented Nov 2, 2026

Copy link
Copy Markdown
Member

I reviewed commit 43d3938. No blocking findings. Please rebase this branch onto master after PR #2417 is merged, push the rebased branch, and I will re-check and merge it.

@frf12

frf12 commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Please extend this PR to implement the native conversation identity adapters listed in #2418: Codex thread-id, Claude Code x-claude-code-session-id, and OpenCode x-opencode-session-id, with the documented parent/subagent isolation semantics. Keep X-PowerContext-Conversation-ID as the highest-priority override, and add focused tests and documentation for each adapter.

jasper-yl and others added 2 commits November 2, 2026 12:17
…ponses route

Codex 0.145 sends a native thread-id header on every request of a thread and
gives each subagent its own thread ID, while parent and subagent share
session-id and prompt_cache_key. Without X-PowerContext-Conversation-ID, the
Responses route now takes the conversation from thread-id, so an unmodified
Codex prepares once per user message and replays within its tool loop. The two
sources are prefixed so they never share replay state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…conversations

Claude Code identifies a conversation by x-claude-code-session-id plus
x-claude-code-agent-id, since its subagents share the session ID. OpenCode
uses x-opencode-session-id, which differs for a child session; its affinity
headers can be shared with the parent and are ignored. Each source has its own
prefix, and X-PowerContext-Conversation-ID still overrides all of them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jasper-yl
jasper-yl force-pushed the fix/gateway-codex-thread-identity branch from 43d3938 to ff8f280 Compare November 2, 2026 20:19
@jasper-yl jasper-yl changed the title feat(gateway): use the Codex thread ID as the conversation on the Responses route feat(gateway): recognize native client conversation identities Nov 2, 2026
@jasper-yl

Copy link
Copy Markdown
Contributor Author

@frf12 done; the branch is rebased onto master (after #2417) and extended to the three adapters from #2418:

  • Claude Code: x-claude-code-session-id, combined with x-claude-code-agent-id so each subagent is its own conversation.
  • OpenCode: x-opencode-session-id; the affinity headers are ignored.
  • Codex: thread-id, on the Responses route only.

X-PowerContext-Conversation-ID overrides all of them, each source has its own prefix, and there is a focused test per adapter plus one for precedence. The docs in gateway/README.md and both locales of deploy-server.md list the headers.

Besides Codex, OpenCode 1.19.5 is now verified end to end with an unmodified client: 3 preparations with this branch against 5 without the header (parent title request, parent task, child session). One limitation, also in the docs: Claude Code only speaks the Anthropic Messages API, which the gateway does not serve, so its adapter takes effect only behind a proxy that translates to the Chat or Responses route. I covered it with a unit test against the documented headers, not an end-to-end run. The PR description has the details.

@frf12 frf12 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed commit ff8f280. The native identity adapters preserve the PowerContext override, isolate parent and subagent conversations, restrict Codex thread-id recognition to Responses, and keep unrecognized requests from inheriting replay state. CI and gateway validation are green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1.5.0 v1.5.0 release tracking

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(gateway): recognize native client conversation identity for prepare/replay

3 participants