feat(agent-client): Codex process owner + per-surface views + pool

[huntharo]

What

A Codex process owner/pool for @pwrdrvr/agent-client, equivalent in spirit to the ACP pool — so a host stops accidentally spawning multiple codex app-server processes (one for chat, another for one-shot, another for a model-picker refresh).

New API

• CodexProcessOwner — owns ONE codex app-server process + JSON-RPC connection. Hands out lightweight per-surface **CodexBackendView**s (each an AgentBackend, drop-in for ChatThreadController). Inbound notifications and tool-call/approval server-requests are demultiplexed by threadId to the view that owns that thread — so multiple chat surfaces share one process without clobbering each other's handlers. Also exposes:
  • listModels() over the shared connection (no extra process, no one-shot client needed) — req docs: the zod 3/4 split is intentional — don't dedupe it #4.
  • runOneShot() structured turn over a persistent worker thread on the same connection: outputSchema, local image inputs, per-turn thread/rollback, token-usage capture, abort/interrupt — req fix(agent-acp): send session/set_config_option without the _ extension prefix #5.
  • connect() (warm) and close() (tear down the process) — req Version Packages #6.
• CodexProcessOwnerPool — mirrors AcpAgentClientPool: acquire / warm / has / release / closeAll, keyed by the host on connection identity (command, CODEX_HOME/env) — reqs AcpSessionNormalizer drops tool-call file locations (path) on NormalizedToolCall #1, Version Packages #6.

Why per-thread routing works

Every Codex notification and every server-request carries a threadId: DynamicToolCallParams (item/tool/call) and the v2 *RequestApprovalParams all have threadId+turnId; legacy v1 approvals carry conversationId. Plain CodexThreadClient just never used it — it routes server-requests by method into one global handler slot. That's the clobber this fixes (req #3).

Fold (no breaking changes)

CodexThreadClient and CodexOneShotClient are now thin shims:

• CodexThreadClient → an owner + a single default view (its historical single-global-handler behavior, preserved).
• CodexOneShotClient → owner.runOneShot() / owner.listModels().

Their public APIs and behavior are unchanged; all pre-existing tests stay green. This deletes PwrSnap's need to reach into CodexThreadClient internals (getConnection()/initialize()/handleNotification()) for model-listing and structured one-shot — those are now supported owner API.

Tests

agent-client 49 passing (40 prior + 9 new). New coverage: per-view event/tool/approval routing isolation; view close() detaches routing without killing the process; one-shot structured turn + outputSchema + rollback + no leak to surface views; listModels() without opening a thread; pool dedup/keying/release/closeAll. Full workspace: typecheck (7), boundaries (no violations), all package tests green.

Consumer migration (PwrSnap)

Replace the local codex-agent-pool.ts compat layer:

const pool = new CodexProcessOwnerPool();
const key = `${command}::${codexHome ?? "default"}`;
const owner = await pool.acquire(key, () => new CodexProcessOwner({ command, env }));
const view = owner.createBackendView();        // per chat surface; drive with ChatThreadController
const models = await owner.listModels();       // model picker — no new process
const out = await owner.runOneShot({ prompt, outputSchema, imagePaths }); // enrichment — same process

🤖 Generated with Claude Code