Codex Phone HLD and LLD

Context

Codex Phone is a remote control, not a second agent product. It does not host a model, copy chats to a cloud, or replace the CLIs. A Mac (or Linux host) that already has the CLIs signed in runs one Node bridge. Phones reach that bridge over verified HTTPS.

Containers

Remote browsers go through HTTPS. Native apps on the host skip the bridge and read the same files. That split is why a phone send and a later codex resume are one session.

Runtime flows

A send the bridge owns

The client request id is the idempotency key. The same id cannot post twice. If the bridge dies after the CLI may already have the prompt, the row is uncertain and is never auto-replayed. Sending twice is worse than asking the user to check.

A turn something else owns

Codex Desktop, a terminal, or an IDE can already hold the writer. The phone queues or waits. It does not kill that process. While a browser has the thread on screen, watch.mjs follows the session file and clients refetch. There is no second live stream and no sync protocol: devices agree because they share the host.

Open, then reconnect

History is GET /api/thread. Live deltas are GET /api/thread/delta plus SSE. The shell does not paint those frames itself. It hands each one to message-view-state.ts, which accepts, ignores, or invalidates it, and Vue redraws the keyed rows. On reconnect the canonical read is authoritative. A delta the view cannot place asks the shell for that read. It never invents the missing rows.

Trust boundaries

Processes

Setup (bin/codex-phone.mjs) owns Tailscale Funnel/Serve, public verification, and the pairing QR. A healthy supervised bridge is not restarted by a later setup, so an in-flight turn keeps running. Code updates load on stop then start.

Reliability kernel

Four ownership rules. Adapters observe provider protocol and emit capabilities and events. They do not invent browser state. The bridge owns turn lifecycle, delivery, queue order, recovery, and the projection inputs it broadcasts. The browser owns draft text and view state. It must not infer delivery or liveness. One lifecycle decision governs send, steer, queue, interrupt, compact, and recover.

Dispatch

decideDispatch is the only policy. POST /api/message, /api/steer, /api/queue, /api/interrupt, /api/resume, and compact all consume it. The browser asks the bridge which route is legal. state.busy is a chip hint. A session-file “still open” marker never gates the user’s own verb: that marker is true after every interrupt and every failed turn.

Grok sets nativeSteer false. Claude steers by injecting into the live stream-json process. Codex steers on the holder it spawned. An explicit false is the only “cannot steer.” Missing capability is treated as able, and the adapter still refuses a write it cannot make.

Turn lifecycle

Replaces a boolean session.busy that send and steer asserted in opposite directions, and that a silent turn could latch forever. A phase cannot be entered unless something can leave it. Illegal transitions are refused.

Failure exits, from any non-terminal phase: uncertain then failed, or interrupted. busy is true for dispatching, awaiting_ack, working, and uncertain.

BaseProvider.settleTurnDeadlines is the one sweep. A turn that ends because nothing was heard is reported as interrupted work, not as a clean provider failure.

Ledger and identity

Send ledger

File ~/.codex-phone/send-ledger.json. One row per request: dispatching → accepted, or uncertain / failed. A dispatching row loaded after restart has lost the process that owned it, so it is settled on load instead of hanging forever. The ledger announces an intent only after the durable write. SSE intent frames carry provider, thread, request id, method, public state, text, revision. A resolved intent is a tombstone. Newest revision wins. /api/thread remains authoritative on reconnect.

Thread identity

A first send has no provider thread id yet. It runs under a provisional id (often draft-…). Codex and Grok allocate the real id in their response; Claude may be given one. thread-identities.json is the only map. adoptThreadIdentity in the server is one transaction: registry first, then every store and the ledger, correlated by request id so a null-thread row can be placed. Routes, decideFor, and sendOnce consult the registry. They do not copy the alias into each store’s own key forever. Identity comes from provider metadata (session_meta.id, history base, fork parent), never from a filename shape.

Settings on the first send

Model, effort, and permission mode are recorded against the provisional id and adopted with the thread. The exact resolved dispatch is what crosses into the provider. If the installed CLI’s help cannot prove a flag, the send is refused with an upgrade or reload instruction. Provider-default stays available. A restrictive mode is never silently widened.

Transcript view

This is the migration. Before it, eleven functions in public/index.html could each append into #messages. A user message existed as an optimistic bubble, browser pending state, a bridge intent, and a canonical row, and each had its own paint path. message-view-state.ts is the single answer: inputs in, one ordered keyed list out. Vue is only the thing that places those keys.

What the pure module owns

Request-id and revision folding. The local-to-bridge handoff. Whether a snapshot is newer than the cursor the view already holds (generation plus revision, with sourceVersion so an evicted bridge LRU cannot look older). Whether a delta’s ops may be applied, must be ignored, or invalidate the view. Resolved tombstones. Provisional rows watched on the live stream before the provider file contains them. Stable row keys. Which affordance a held message may show. It must not infer delivery, parse a provider, call an API, touch the DOM, or become a second lifecycle.

What a row may offer

Only a bridge intent carries a verdict. not_sent may retry and dismiss. uncertain may dismiss and must not retry, because the provider may already have accepted it. A local copy may not claim failure. transport-uncertain may retry under the same request id, which the send ledger deduplicates, so a second provider message cannot be produced. A resend under a new id is the bug.

Who draws it

Build and upgrade

Vite compiles the slice with @vitejs/plugin-vue. No Vue runtime compiler ships. Output is public/assets/transcript-[hash].js plus manifest.json. frontend-build.mjs fingerprints frontend/* and message-view-state.ts into build.json. On a checkout, the bridge refuses to start if that stamp does not match the sources, so a stale bundle cannot pretend to be the tree. A published package ships the built assets without the .vue sources, and is not checked. The service worker precaches the manifest’s file list and upgrades all-or-nothing: an old document and a new one never share a mixed set of hashed files. The rest of index.html is still read from disk on each navigation.

Provider adapters

Every adapter is constructed with emit(event, data). The server stamps provider and broadcasts. Shared contract: init, listThreads, readThread, newThread, forkThread, send, interrupt, models, usage, projects, plus queue and resumeInterrupted where the CLI has them. Streaming events are notify (params always include threadId), approval, and bridge.

Provider discovery (provider-detect.mjs) looks on PATH and the official installer locations, including the codex binary inside ChatGPT.app. Credentials are read from each CLI’s auth file, the Claude keychain item, or the usual API-key variables. A provider that is missing or explicitly signed out is omitted from the picker until the bridge restarts. sign-in unverified stays enabled: the first real send is a better test than a setup-time guess.

Durable stores

Home is ~/.codex-phone (REMOTE_AGENTS_HOME overrides). Directory mode 0700, secret-bearing JSON 0600. Writes that must survive a crash are atomic (write aside, then rename). Loaders parse through Zod and skip damaged rows.

HTTP and SSE

Routes are a method-plus-path table inside server.mjs. Bodies for dispatch go through one dispatchRequestSchema; a bad body is HTTP 400 invalid_body naming the field. Unparseable input must not surface as 500, because the phone reads 500 as “maybe delivered.”

Static responses (HTML, sw.js, icons, math fonts, highlight.js, xterm) are also behind the pairing cookie. /internal/terminal-admin and /internal/local-proof are for the host CLI, not the phone.

Terminal

remote-agents terminal enable mints a five-minute enrollment code. The browser creates a passkey (WebAuthn, @simplewebauthn/server). Later, /api/terminal/auth/* checks a fresh assertion and /api/terminal/ticket issues a short unlock. public/terminal.html is xterm.js over /api/terminal/ws. The PTY is node-pty inside terminal-worker.mjs. If the native addon is missing, the page offers passkey-protected one-shot commands and never automatically repeats a command whose result is uncertain.

The working directory is resolved again on the server from the thread’s provider-reported project folder before every new session. Revoke or disable invalidates unlocks and tickets and stops both interactive and one-shot processes. Revocation is accepted only from the bridge machine.