feat: structured codex agents in labs, driven through codex's app server

[sean-brydon]

Stacked on #78 (base resume-conversations). Merge #78 first, and GitHub retargets this PR to main.

Phase 5 of design/structured-agents/plan.md: the Codex driver, behind the same Labs switch, now called Structured agents.

Driver (internal/box/codexdriver.go)

codex app-server runs under berthd agent-host, and berthd speaks its JSON-RPC (shapes from the spike's recordings and the generated schema):

• Handshake: initialize / initialized, then thread/start (cwd, approval policy, sandbox, model), or thread/resume with the conversation's thread id (from meta.json or the log) when carried on. It runs again whenever its host starts.

• Turns: each prompt is turn/start, carrying the session's mode, model and effort. Modes:

  Mode	Approval policy	Sandbox
  default	on-request	workspace-write
  untrusted	untrusted	workspace-write
  readOnly	on-request	read-only
  bypassPermissions	never	danger-full-access

  SetMode takes effect from the next turn. Interrupt is turn/interrupt.

• Server requests:

  • item/commandExecution/requestApproval and item/fileChange/requestApproval produce ask.choices and the usual Allow (accept) / Always allow (acceptForSession) / Deny (decline) buttons.
  • item/tool/requestUserInput becomes a question card, answered via /answer.
  • Anything else gets a JSON-RPC error, so a turn never hangs.

• Turn state: item/started userMessage (after AwaitSent), approvals, serverRequest/resolved and turn/completed (interrupted / failed). Codex's own berthd hooks stay quiet (BERTH_DRIVER).

• Draft: from item/agentMessage/delta.

• Conversation: read from the host's log by a new parser (internal/transcript/codexhost.go) that maps app-server items onto the existing conversation helpers: user messages, replies, commands as Run/Read/Search, file changes as edits, MCP calls, and questions with their answers. Detail gives a command and its output.

• Resume and the conversation list (feat: a structured claude agent's conversation can be resumed, after its agent ends or its session is gone #78) work for Codex conversations: relaunch chooses the agent from meta.json. Codex has no terminal switch (switch stays empty).

App

The Labs switch is now Structured agents and covers Codex picks on boxes listing driver.codex. Structured Codex sessions open as conversations. Resumed panes show the right agent.

Tests

• TestAStructuredCodexSessionIsDrivenThroughItsAppServer, with a stand-in app server (python3) following the recorded protocol:
  • the thread opens and its id reaches the ledger
  • an approval with choices is answered by key
  • bypass carries approvalPolicy: never so nothing is asked
  • a question is answered from the chat
  • draft, then interrupt
  • the host stops, the session resumes onto the same thread, and it comes back in bypass
• All structured tests passed 4/4 under -race.
• TestAStructuredCodexSessionsLogReadsAsItsConversation uses a recorded, anonymised app-server log, plus a command's details.
• TestALiveCodexSessionWorks (opt-in BERTH_LIVE_CODEX=1, BERTH_LIVE_CODEX_MODEL): real Codex replies, then runs a shell command under bypass. It passed locally in 9.6s.
• Full go test -race ./..., go vet ./..., app checks and build, tsc -p e2e and the docs build all pass.

Next: phase 6, the generic ACP driver (opencode, Gemini, Cursor).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
berth	Ready	Preview	Oct 13, 2026 1:09pm UTC
berth-docs	Ready	Preview	Oct 13, 2026 1:09pm UTC

[linear-code]

ENG-6007