Support launch-only custom request headers for Codex

[andy-xu-db]

🥞 Stacked PR

Use this link to review incremental changes.

• stack/andy/custom-request-headers [Files changed] ← this PR
  • stack/andy/custom-request-headers-claude [Files changed]

---

Summary

• add repeatable ug codex --header "Name: value" support
• validate header syntax and protect authentication, routing, and transport headers
• pass values to Codex through launch-only environment variables without persisting them
• preserve headers through smart routing and reject collisions with OS-managed Codex headers

Usage

ug codex --header "X-Development-Route: test-target"

Split

Claude Code support is separated into #687.

Rebase Validation (2026-09-21)

Rebased the stack onto aa55bba from main. Preserved the current Codex provider-header cleanup and protected Databricks-Smart-Router-Recipe from custom-header overrides, with case-insensitive regression coverage.

• Codex PR: 584 focused tests passed.
• Combined stack: 2,542 passed, 41 skipped with uv run --frozen pytest -q --ignore=tests/test_e2e_user_agent.py before the final integration-test-only main update.
• After including that main update: all 89 integration contract, model discovery, and provider catalog unit tests passed.
• Ruff lint, formatting, and git diff --check passed on the final stack.
• Live integration was not run locally. The user-agent e2e exclusion follows the installed-Claude/synthetic-model limitation documented in Support temporary global custom request headers for Claude Code #687.

Previous Testing

• uv run pytest -q tests/test_cli.py tests/test_agent_codex.py tests/test_codex_smart_routing_v2.py (526 passed)
• uv run ruff check src tests
• uv run ruff format --check src tests
• git diff --check

[andy-xu-db]

Live LiteSwap + Actual TUI Validation (2026-09-21)

Validated the combined #610/#687 stack at 635dad951b3050351913a00dcdcac23ebc669741 using real Claude Code 2.1.278 and Codex 0.154.0 TUIs, driven through a PTY with the repository's terminal helpers. No mocked clients or responses, headless substitutes, sandbox overrides, or manually seeded onboarding state.

Deployed a harmless AI Gateway marker change to staging-aws-us-east-1-0 and used eng-ml-inference-staging. Both launches passed repeated --header options for x-databricks-traffic-id: testenv://liteswap/andy-ug-headers-0921 and a client-specific probe.

Actual TUI run	Assistant answer	Result
ug claude --header ... --header ...	1739 + 2846 = 4585	Swap logged /ai-gateway/anthropic/v1/messages?beta=true with both exact headers and Claude User-Agent
ug codex --header ... --header ...	1927 + 3648 = 5575	Swap logged /ai-gateway/codex/v1/responses with both exact headers and Codex User-Agent
Header-free ug claude	1839 + 2846 = 4685	No new swap markers; both temporary headers and their state entry removed
Header-free ug codex	2027 + 3648 = 5675	No new swap markers; headers never persisted in user/managed config

All four TUIs exited normally with code 0. Server marker evidence was collected at 22:18:49 UTC (Claude, request 73c97621-fea1-4a8a-8b25-04b9a208dd5c) and 22:19:12 UTC (Codex, request f093e6ee-61fe-41d9-b0f5-0f30f0c477b6). Marker logs before and after header-free controls were byte-identical.

Scope limitation: staging smart-router selection returned HTTP 400 both with and without custom headers. The TUIs fell back successfully to their current models. This verifies actual inference header propagation through that fallback path, not a successful live smart-router model switch. MCP tool execution was not exercised.

No additional header-code fix was needed. The temporary container/token were removed and LiteSwap teardown succeeded. The marker change was not added to these PRs.