| name | megacode-app-server-dev |
| description | Guidance for building the Codex app-server runner adapter — thread lifecycle, event parsing, session resume, and version isolation. Use when working on packages/runner-codex or app-server integration. |
MegaCode App-Server Development
Patterns for the primary Codex worker transport: JSON-RPC app-server (thread/start, turn/start, streamed notifications). Use exec-json only for non-interactive shell phases.
Architecture boundaries
| Layer | Owns |
|---|
runner-codex (app-server adapter) | RPC calls, event stream parsing, thread/turn IDs, reconnect |
| Supervisor | Run registry, pause/resume policy, worktree cwd injection |
| Profiles | Model, skills, MCP scope — not transport details |
Do not parse TUI output. Do not embed supervisor state inside the adapter.
Thread lifecycle
- Start —
thread/start with profile-compiled config (model, cwd, permissions).
- Turn —
turn/start with user prompt; stream events until turn complete.
- Persist — save
thread_id, last turn_id, run_id, profile, worktree path to .megacode/runs/<run_id>/session.json.
- Resume — reconnect RPC,
thread/list or stored thread_id, continue turns.
- Stop — graceful turn cancel; update run status; do not delete worktree here.
Event handling
- Parse notification stream into normalized events:
message, tool_call, tool_result, error, turn_complete.
- Write append-only JSONL log per run for audit (
session.jsonl).
- Surface approval prompts to supervisor — adapter blocks until policy resolves.
- Version-schema per installed Codex — isolate breaking RPC changes in adapter module.
Session persistence sketch
{
"run_id": "run_abc123",
"transport": "app-server",
"thread_id": "...",
"last_turn_id": "...",
"codex_version": "...",
"cwd": ".megacode/worktrees/run_abc123",
"status": "running | paused | completed | failed"
}
Resume patterns
- TUI detach — supervisor keeps app-server connection or child process; launcher reattaches via run_id.
- Crash recovery — load
session.json; if thread still exists, resume; else mark failed and require user decision.
- Worktree binding — never resume a thread against a different
cwd without explicit migration.
Testing
- Use
openai/codex@test-tui patterns for integration smoke tests (study-only external skill).
- Unit-test event normalizers with fixture JSONL from recorded sessions.
- Mock RPC for state transition tests; one live app-server test in CI optional when monorepo exists.
Locked constraints
- ChatGPT subscription / app-server auth — no OpenAI API key path in this adapter.
- No Agents SDK orchestration layer.
- Local verification after code changes (
pnpm verify).
References
