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.
• Log blockers/decisions in research/acp/friction.md during implementation.

Phase 1: Teardown

Implementation:

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

Validation gate:

• Project builds with v1 protocol code removed.
• No references to sandbox-agent-universal-agent-schema remain.
• /v1/* returns explicit "v1 removed" error (HTTP 410).
• /opencode/* returns disabled/unavailable response.

Phase 2: ACP Core Runtime

Implementation:

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

Validation gate:

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

Phase 3: Installer Refactor

Implementation:

• Replace agent-specific spawn contracts with agent process-centric spawn.
• Add agent process install manifests + downloader logic.
• Keep native agent installs where agent process depends on local CLI.
• Add install verification command per agent process.
• Integrate ACP registry metadata + fallback sources.
• Expose install provenance (registry vs fallback) in API/CLI.
• Implement lazy install on first /v2/rpc initialize.
• Add per-agent install lock + idempotent install results.
• 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:

• Explicit install command tests pass for each supported agent.
• Lazy install on first ACP initialize test passes (deterministic local-registry coverage added).
• 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:

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

Validation gate:

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

Phase 5: SDK and CLI v2

Implementation:

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

Validation gate:

• TypeScript SDK end-to-end tests pass in embedded mode.
• TypeScript SDK end-to-end tests pass in server mode.
• Inspector end-to-end agent-browser tests pass using ACP-over-HTTP.
• Add explicit parity test asserting ClientSideConnection usage contract.

Phase 6: Test and Rollout

Implementation:

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

Validation gate:

• Full agent process matrix is green.
• Install + prompt + stream smoke tests pass for each supported agent process.
• 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:

• 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)

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

Architecture: Connection vs Session Model

• 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

• Add dedicated regression for Last-Event-ID handling in CLI api acp stream.
• Add explicit test for SANDBOX_AGENT_REQUIRE_PREINSTALL=true behavior.
• 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.