Wayfinder: a faster Codex path, replacing the app-server transport

[chuks-qua]

Destination

A locked decision plus a handoff-ready spec for a flag-gated replacement of the codex app-server transport. Requirements already settled by the user: durable Codex threads must be preserved; the new path must measurably beat the current ~30s average time-to-first-token and per-turn token spend; the flag lives in app settings; the app-server implementation is removed once the replacement proves stable.

Notes

• Domain: the Codex provider adapter in packages/providers/src/private/codex/. Layering today is CodexRpcClient (NDJSON transport) -> CodexAppServer (protocol/session) -> CodexEventMapper (~1600 lines, app-server notification schema -> AgentEvents) -> CodexProvider (contract surface). A new transport must reproduce the CodexAppServer surface or an equivalent notification source.
• Reference implementation to study: NousResearch/hermes-agent (open source). Its speed comes from codex exec one-shot subprocesses and a codex mcp-server MCP preset; its own app-server runtime exists but is opt-in and not its fast path. It also has an openai-codex provider that drives chatgpt.com/backend-api/codex (Responses API) directly with OAuth and runs its own tool loop.
• Key docs: docs/guides/provider-architecture.md, docs/guides/codex-app-server-trace.md, docs/adr/0018-codex-app-server-owns-capability-catalogs.md, CONTEXT.md.
• Skills every session should consult: research for research tickets, grilling + domain-modeling for decision tickets.
• Success metrics the user named: tokens per second and time to first token per turn, both currently averaging ~30s.
• Standing preferences: smallest model that makes behavior unsurprising; measure, do not guess; conventional commits.

Decisions so far

• codex mcp-server: surface, thread continuity, events, approvals: Dead end. codex mcp-server was removed from openai/codex main (PR #42993); only pinned older releases ship it. Findings

Not yet specified

• Authoring the implementation spec itself. Graduates once the transport decision closes.
• Whether existing Codex threads migrate/resume onto the new transport or are abandoned at the flag boundary.
• Whether CodexEventMapper is reused, adapted, or replaced; depends on the chosen transport's event schema.
• Sandbox enforcement story if the own-the-loop (Responses API) path wins.
• Post-swap perf guardrails, e.g. a CI budget for TTFT and tokens per turn.

Out of scope

• Non-Codex providers (Claude, Cursor) and the provider-neutral contract, unless a ticket explicitly pulls them in.
• Building a Hermes-style delegate_task subagent orchestration system. Using Codex CLI subprocesses as the transport is in scope; a subagent product feature is not.
• codex exec --json: event parity gap vs the narration contract: Lossy projection. Exec emits an 8-type JSONL subset; all delta channels, mid-run approvals, compaction, goals, and child-thread narration are dropped (~94% of wire traffic). Turn lifecycle, tool rows, plan todos, and end-of-turn tokens survive. Findings
• Responses API direct: auth reuse, thread state, streaming surface: Viable. CLI auth tokens drive backend-api/codex directly (shared client_id; refresh tokens are single-use, needs import-and-recover). No durable server-side threads on HTTP (store:false, client replay + encrypted reasoning echo); full response.* SSE covers every AgentEvent. Findings
• Own-the-loop scope: the tool surface we would rebuild: Medium project, not a rewrite. Flagged v1 is ~9 small + ~6 medium items, zero large: the tool loop, re-owned approvals, item replay, minimal compaction, patch tool, plan tools. Sandbox OS enforcement and sub-agents are later; imagegen/plugins/dynamic tools dropped. Findings
• Benchmark: where the ~30s TTFT and token spend go on the app-server path: Protocol is ~1s. Per-turn cost is a ~32k static prefix plus growing thread context; TTFT floor 1.2-4.7s with rare ~16s cold spikes; generation time at high effort dominates real turns. Transport swap alone cannot fix 30s; the token lever is owning the instructions prefix. Findings