Codex on chat-completions endpoints: LiteLLM bridge and stream shim

[renmengye]

The codex backend could not author or judge on a self-hosted model: codex speaks only the Responses API, and vLLM's Responses endpoint drops these models' tool calls. Claude Code and Hermes already could (endpoint profiles, #438).

What changes

• An endpoint profile whose API list has chat but not responses is now valid for codex roles; the kernel then runs a bridge. A profile with responses keeps today's direct path, and codex roles without a chat-only endpoint are unchanged.
• Bridge: per codex session, a supervisor inside the session's container starts two local sidecars, codex → LiteLLM (Responses → Chat Completions) → stream shim → endpoint, and runs codex against LiteLLM:
  • both listeners are pre-bound to 127.0.0.1, with an ephemeral token on each hop (compute nodes are shared);
  • the endpoint key reaches only the shim, through the environment; configs reference env vars, never keys; no payload logging;
  • every child is reaped on exit, timeout, cancellation, a sidecar's death or the scheduler's SIGTERM.
• Stream shim: the endpoint opens each stream with an empty chunk, and LiteLLM picks the output item type from the first chunk only, so without the shim it never opens a reasoning item and codex never replays its reasoning. The shim drops that chunk and moves its role onto the next (whole-event SSE handling, per-choice state, strict opener test).
• LiteLLM runtime: pinned (1.103.1) with transitive dependencies locked and hash-checked, installed by outerloop harness upgrade as its own runtime (like pre-installed Hermes) under the cache/state root, bound read-only into sessions; --used installs it only when a codex role selects a chat-only endpoint. The codex CLI pin is unchanged (tested against 0.130.0).
• Authors and panel codex lenses, resume included. docs/endpoints.md has a "codex on a chat-completions endpoint" section.

Compatibility (RELEASING.md)

Existing run and session formats are unchanged; no backfill. Codex roles without a chat-only endpoint behave as before. Before rolling back, finish sessions on chat-only endpoints or select a Responses-capable profile.

Tests

Real codex CLI and proxy against a fake chat-completions upstream: tool calls (parallel, stable ids), an apply_patch round trip with bytes preserved, reasoning replayed on every later turn including after resume, local compaction, empty-opener / tool-first / text-only streams, truncation and cancellation, supervisor cleanup after a forced child failure, keys never in argv, files or logs, profile validation, runtime default placement, interrupt handling scoped to the bridge, and harness upgrade --used surviving a misconfigured role. Gate after folding in main: 2722 passed, 10 skipped (four skips need the installed runtime); ruff, format, mypy clean.

Not yet run: a live session in the cluster container against a real endpoint. That is the fleet test after merge (one author slot on a chat-only endpoint, watched through its first attempt).

Built by codex from my brief (design consult first); reviewed by an on-prem open model (three findings: runtime defaulting into the home directory, interrupt cleanup scope, upgrade robustness, all fixed) and by me.

🤖 Generated with Claude Code

[github-actions]

Round 1 — reviewed head 87a914f0 — reviewer summarizer:hermes/gpt-5.6-terra over coverage+credentials+deployment+general+lifecycle+prose.

terra
Advisory findings from outerloop — the code owner decides. Reply to disagree; the outerloop:no-review label opts this PR out.

Verdict: nothing blocking — 2 advisory notes.

2 findings attached to the lines below.

Merged two non-blocking findings. No duplicate claims were submitted. Rejected: none; the target source files were not present in this review workspace for independent code verification, but neither supplied finding conflicted with another opinion.

[github-actions]

Round 1 — reviewed head 4c0d8149 — reviewer hermes/gpt-5.6-terra.

terra
Advisory findings from outerloop — the code owner decides. Reply to disagree; the outerloop:no-review label opts this PR out.

Verdict: no defects found.

[github-actions]

Round 2 — reviewed head 619e641c — reviewer hermes/gpt-5.6-terra.

terra
Advisory findings from outerloop — the code owner decides. Reply to disagree; the outerloop:no-review label opts this PR out.

Verdict: no defects found.