sandbox-agent/research/acp/todo.md

# ACP v2 Migration TODO

Source docs:
- `research/acp/spec.md`
- `research/acp/migration-steps.md`
- `research/acp/00-delete-first.md`
- `research/acp/v1-schema-to-acp-mapping.md`
- `research/acp/friction.md`

Progress rule:
- [ ] Do not start the next phase until current phase gate is green in local + CI.
- [x] Log blockers/decisions in `research/acp/friction.md` during implementation.

## Phase 1: Teardown

Implementation:
- [x] Delete in-house protocol files/docs listed in `research/acp/00-delete-first.md`.
- [x] Remove deleted-crate deps from workspace `Cargo.toml` files.
- [x] Remove `/v1` route registration.
- [x] Add unified `/v1/*` removed handler (HTTP 410 + `application/problem+json`).
- [x] Remove/disable CLI `api` commands that target `/v1`.
- [x] Comment out/disable `/opencode/*` during ACP core bring-up.

Validation gate:
- [x] Project builds with v1 protocol code removed.
- [x] No references to `sandbox-agent-universal-agent-schema` remain.
- [x] `/v1/*` returns explicit "v1 removed" error (HTTP 410).
- [x] `/opencode/*` returns disabled/unavailable response.

## Phase 2: ACP Core Runtime

Implementation:
- [x] Add ACP runtime module + router integration.
- [x] Implement agent process process manager (spawn/supervise baseline).
- [x] Implement JSON-RPC bridge (`POST`/SSE <-> agent process stdio).
- [x] Add connection registry keyed by `X-ACP-Connection-Id`.
- [x] Implement unstable methods in v2 profile: `session/list`, `session/fork`, `session/resume`, `session/set_model`, `$/cancel_request`.
- [x] Implement explicit close path: `DELETE /v2/rpc`.

Validation gate:
- [x] End-to-end ACP flow over `/v2/rpc` (request/response + streamed notifications).
- [x] `session/cancel` behavior test passes.
- [x] HITL request/response round-trip test passes.
- [x] SSE ordering and `Last-Event-ID` replay test passes.
- [x] `DELETE /v2/rpc` idempotent double-close test passes.
- [x] Unstable method tests pass for agent processes that advertise support (mock covered).

## Phase 3: Installer Refactor

Implementation:
- [x] Replace agent-specific spawn contracts with agent process-centric spawn.
- [x] Add agent process install manifests + downloader logic.
- [x] Keep native agent installs where agent process depends on local CLI.
- [x] Add install verification command per agent process.
- [x] Integrate ACP registry metadata + fallback sources.
- [x] Expose install provenance (`registry` vs `fallback`) in API/CLI.
- [x] Implement lazy install on first `/v2/rpc` initialize.
- [x] Add per-agent install lock + idempotent install results.
- [x] Add config switch to disable lazy install for preprovisioned envs (`SANDBOX_AGENT_REQUIRE_PREINSTALL`).
- [ ] Fill out installers for all ACP registry agents (expand `AgentId` + per-agent installer mappings).

Validation gate:
- [x] Explicit install command tests pass for each supported agent.
- [x] Lazy install on first ACP initialize test passes (deterministic local-registry coverage added).
- [x] Reinstall/version/provenance assertions pass.
- [ ] Add integration coverage that every ACP registry agent has a corresponding installer mapping in `agent-management`.

## Phase 4: v2 HTTP API

Implementation:
- [x] Mount `POST /v2/rpc` and `GET /v2/rpc` (SSE).
- [x] Mount `DELETE /v2/rpc` close endpoint.
- [x] Add `GET /v2/health`, `GET /v2/agents`, `POST /v2/agents/{agent}/install`.
- [x] Integrate auth on ACP client lifecycle.
- [x] Keep `/ui/` and migrate inspector backend calls to ACP v2 transport.
- [x] Remove v1 OpenAPI surface from generated docs contract.

Validation gate:
- [x] Contract tests for `/v2` endpoints pass.
- [x] Auth tests pass (valid/missing/invalid token).
- [x] `/v1/*` removal contract test passes (HTTP 410 + stable payload).
- [x] Inspector ACP `agent-browser` flow test passes.
- [x] `DELETE /v2/rpc` close contract tests pass.
- [x] Error mapping tests are complete for every documented error path.

## Phase 5: SDK and CLI v2

Implementation:
- [x] Embed `@agentclientprotocol/sdk` in `sdks/typescript`.
- [x] Implement custom ACP-over-HTTP transport agent process in our SDK.
- [x] Wire inspector frontend client to ACP-over-HTTP primitives.
- [x] Add CLI commands for raw ACP envelopes + streaming ACP messages.
- [x] Remove or hard-fail v1-only SDK/CLI methods (`v1 removed`).
- [x] Regenerate docs for v2 ACP contract.

Validation gate:
- [x] TypeScript SDK end-to-end tests pass in embedded mode.
- [x] TypeScript SDK end-to-end tests pass in server mode.
- [x] Inspector end-to-end `agent-browser` tests pass using ACP-over-HTTP.
- [x] Add explicit parity test asserting `ClientSideConnection` usage contract.

## Phase 6: Test and Rollout

Implementation:
- [x] Replace v1 HTTP/session tests with ACP transport contract tests (core server + SDK).
- [x] Add smoke tests per supported agent process (claude/codex/opencode covered with deterministic ACP agent process stubs).
- [x] Add canary docs + migration notes.
- [x] Update docs for v2 ACP, `/v1/*` removal, inspector ACP behavior, and SDK usage.
- [x] Keep `/v1/*` hard-removed (HTTP 410).

Validation gate:
- [x] Full agent process matrix is green.
- [x] Install + prompt + stream smoke tests pass for each supported agent process.
- [x] Inspector `agent-browser` suite runs in CI path.
- [ ] Docs updates are published with rollout.

Notes:
- Remaining unchecked rollout items depend on docs publishing workflow outside this repo change set.
- Real credentialed agent process matrix runs are still environment-dependent; deterministic agent process matrix coverage is now in CI.

## Phase 7: OpenCode <-> ACP Bridge (Dedicated Step)

Implementation:
- [x] Keep `/opencode/*` disabled through Phases 1-6.
- [ ] Implement OpenCode <-> ACP bridge on top of v2 ACP runtime.
- [ ] Re-enable `server/packages/sandbox-agent/src/opencode_compat.rs` routes/tests.
- [ ] Add dedicated integration tests for OpenCode SDK/TUI flows through ACP v2 internals.

Validation gate:
- [ ] OpenCode compatibility suite passes against ACP-backed implementation.
- [ ] Regression tests confirm no dependency on removed in-house protocol runtime.

## Consolidated Test Suites (Must-Have)

- [x] ACP protocol conformance (beyond mock baseline).
- [x] `/v2/rpc` transport contract.
- [x] End-to-end agent process matrix (core + cancel + HITL + streaming).
- [x] Installer suite (explicit + lazy + provenance).
- [x] Security/auth isolation.
- [x] TypeScript SDK end-to-end (embedded + server).
- [x] v1 removal contract (`/v1/*` -> HTTP 410).
- [x] Inspector ACP suite (`agent-browser`).
- [ ] OpenCode <-> ACP bridge suite (Phase 7).

## Architecture: Connection vs Session Model

- [x] Align runtime with multi-session ACP expectations while keeping one backend process per `AgentId`.
  - ACP HTTP connections are logical client channels; server sessions are globally visible via aggregated `session/list`.
  - Backend process ownership is per agent type (shared per server), not per client connection.
  - Added connection-level session detachment extension `_sandboxagent/session/detach`.
  - Documented updated model in `research/acp/spec.md` and `research/acp/friction.md`.

## Newly discovered follow-ups

- [x] Add dedicated regression for `Last-Event-ID` handling in CLI `api acp stream`.
- [x] Add explicit test for `SANDBOX_AGENT_REQUIRE_PREINSTALL=true` behavior.
- [x] Improve server build-script invalidation for inspector embedding (avoid manual touch workaround when `dist/` appears after initial build).
- [ ] Integrate agent server logs into v2 observability surfaces (agent process/process logs available via control-plane and inspector), with redaction and end-to-end tests.

## Inspector Frontend Parity Follow-ups

- [ ] TODO: Implement session `permissionMode` preconfiguration in inspector ACP flow.
- [ ] TODO: Implement session `variant` preconfiguration in inspector ACP flow.
- [ ] TODO: Implement session `skills` source configuration in inspector ACP flow.
- [ ] TODO: Implement question request/reply/reject flow in inspector ACP flow.
- [ ] TODO: Implement agent mode discovery before session creation (replace cached/empty fallback).
- [ ] TODO: Implement agent model discovery before session creation (replace cached/empty fallback).
- [ ] TODO: Replace inspector-local session list with server/global ACP-backed session inventory.
- [ ] TODO: Replace synthesized inspector event history with canonical ACP-backed history model.