# Plan

## Context

We need a **new parallel Codex MCP provider** that lives side‑by‑side with the existing Codex SDK provider in `packages/server/src/server/agent/providers/codex-agent.ts`. The new provider should be implemented as `packages/server/src/server/agent/providers/codex-mcp-agent.ts` and selected via a new provider id (e.g. `codex-mcp`). It must use Codex MCP (elicitation-based permissions), not the SDK JSON stream. It must support the same capabilities (streaming events, permissions, session lifecycle, cancellation/abort, persistence metadata) without breaking the existing provider. Work must be TDD with full e2e verification against real Codex agents in multiple modes. **All tests must be end-to-end: no mocks, no fakes.**

Reference implementation: `/Users/moboudra/dev/voice-dev/.tmp/happy-cli` (see `src/codex/` for MCP + elicitation flow).

## Guiding Principles

- TDD: write failing tests first, then implement
- All tests must be e2e (no mocks/fakes)
- Keep providers parallel (no breaking changes to existing Codex SDK provider)
- Verify with real Codex MCP server runs in multiple modes
- Cover edge cases explicitly (permission requests, denial, abort, resume, teardown)

## Tasks

- [⏳] **Plan**: MCP provider behavior matrix and interface mapping.

  - Enumerate required behaviors: start session, continue session, stream events, permission request/response, abort, close.
  - Map each to MCP primitives: `codex` tool, `codex-reply` tool, `codex/event` notifications, elicitation handler.
  - Define the new provider file path: `packages/server/src/server/agent/providers/codex-mcp-agent.ts` and exported classes.
  - Define provider id (`codex-mcp`) and how it will be chosen vs existing `codex` provider.
  - Identify gaps vs `codex-agent.ts` (timeline event types, runtime model info, persistence handles).
  - Insert test tasks immediately after this task.

- [ ] **Plan**: E2E test plan (no mocks).

  - Define how tests start a real `codex mcp-server` (stdio transport) and verify teardown.
  - Define e2e fixtures (temp cwd, temp codex session dir, prompt script).
  - Define expected MCP events and permission elicitation behavior per mode.
  - Insert failing test tasks and review task immediately after this task.

- [ ] **Test (E2E)**: Create failing e2e tests for MCP provider basic flow.

  - Start provider with Codex MCP server and call `createSession`.
  - Send a prompt that writes a file and assert file exists after approval.
  - Assert timeline events include tool call + agent message.
  - Assert session metadata (sessionId/conversationId) is persisted.
  - Ensure tests fail before implementation.

- [ ] **Review**: Review failing e2e tests for coverage and correctness.

  - Check for gaps: permission denied path, abort path, missing event coverage.
  - Add fix tasks if test coverage is insufficient.

- [ ] **Test (E2E)**: Create failing e2e tests for permission handling.

  - read-only + approval on-request: expect elicitation request with command details.
  - deny approval: ensure command does not run; verify agent response indicates refusal.
  - approve once: ensure command runs and file is written.
  - Ensure tests fail before implementation.

- [ ] **Test (E2E)**: Create failing e2e tests for cancellation/abort.

  - Start a long-running command (sleep) and abort; verify turn ends and no output after abort.
  - Verify provider can accept a new prompt after abort.
  - Ensure tests fail before implementation.

- [ ] **Implement**: `codex-mcp-agent.ts` provider skeleton.

  - Implement MCP stdio client (modelcontextprotocol `StdioClientTransport`).
  - Implement start/continue session (`codex` / `codex-reply`).
  - Implement event stream subscription (`codex/event` notifications).
  - Map MCP events to existing AgentStreamEvent + timeline items.

- [ ] **Implement**: Permission elicitation integration.

  - Register `ElicitRequestSchema` handler and emit permission requests into AgentStreamEvent.
  - Maintain pending permission map (id → request) and implement `respondToPermission`.
  - Ensure permission decisions flow back to MCP handler.

- [ ] **Implement**: Runtime info + persistence metadata.

  - Capture runtime model from MCP events if available; fallback to configured model.
  - Provide `describePersistence()` with sessionId/conversationId and any MCP metadata.

- [ ] **Implement**: Abort/cancel and cleanup.

  - Abort in-flight turn via AbortController (or transport cancellation).
  - Reset pending permissions + event processors after abort.
  - Close: terminate MCP transport and child process reliably.

- [ ] **Test (E2E)**: Run MCP provider tests (basic flow + permissions + abort).

  - Verify all previously failing e2e tests now pass.
  - Add fix tasks + retest tasks immediately after if any fail.

- [ ] **Implement**: Provider registration/selection wiring.

  - Add `codex-mcp` to provider manifest and any UI or config selection path.
  - Ensure existing `codex` provider remains default/unchanged.

- [ ] **Test (E2E)**: Full scenario matrix with real Codex MCP server.

  - read-only + on-request (elicitation should fire).
  - read-only + deny (no file write).
  - workspace-write + untrusted (permission prompt present).
  - full-access (no prompt, command executes).
  - Verify file output and agent completion in each scenario.

- [ ] **Review**: Review implementation and edge case coverage.

  - Confirm event mapping parity vs `codex-agent.ts`.
  - Confirm permission request/response lifecycle is robust.
  - Add fix tasks and re-review if needed.

- [ ] **Test (E2E)**: Full server test suite relevant to agent providers.

  - Run focused tests and document results.
  - Add fix tasks if failures found.

- [ ] **Plan**: Re-audit and add follow-up tasks.

  - Verify all required scenarios covered.
  - Add any new tasks discovered during e2e runs.