The adapter follows the official Codex App Server documentation and, more importantly, checks in types and JSON Schema generated by the currently installed CLI:
codex app-server generate-ts --experimental --out packages/codex-adapter/generated
codex app-server generate-json-schema --experimental --out packages/codex-adapter/schema
For the version validated with this repository (codex-cli 0.145.0-alpha.18), Agent launches codex app-server --stdio, sends initialize with experimentalApi: true, then the initialized notification. It uses thread/list, thread/read with includeTurns, thread/start, thread/fork, turn/start, turn/steer, and turn/interrupt. Text, localImage, and local-file mention inputs are produced only inside the adapter. Server notifications are normalized to the stable v2 network protocol. Approval server requests remain inside the adapter and are referenced remotely by a newly generated opaque approval ID.
The adapter does not read or write local JSONL or SQLite session storage and never exposes the App Server's experimental network transport. Regenerate and review the schema for each Codex CLI release before publishing an Agent release.
App Server subscriptions and loaded-thread state belong to one transport connection. A desktop Codex host and an Agent-launched stdio App Server can share persisted history, but neither process can see that the other has the same thread loaded. Concurrent turn/start calls can therefore produce overlapping or interleaved turns instead of a synchronized desktop transcript.
Agent v0.2.1 treats the desktop process as the active writer. Read methods remain available while Codex desktop is running; every mutating method is rejected with a retryable Codex-unavailable response. After the desktop closes, continuing an existing thread restarts the Agent App Server before thread/resume, ensuring the next turn loads the latest persisted history. A future native-live mode must use a supported desktop-host Remote Control connection or another official shared-host transport; it must not attach to private desktop IPC or edit Codex storage files.