sandbox-agent/research/acp/simplify-server.md

# ACP Simplified Server Spec

## 1) Scope and Intent

This spec replaces the current ACP runtime model with a simple stdio proxy model:

- Sandbox Agent becomes a **dumb ACP HTTP <-> stdio proxy**.
- ACP transport moves from `/v1/rpc` to `/v1/acp/{server_id}`.
- `server_id` is client-provided and is the only ACP transport identity.
- No server-side ACP extensions and no custom metadata processing.
- Session metadata/state moves to clients.
- Non-ACP functionality is exposed as HTTP endpoints.

Backwards compatibility is explicitly out of scope.

## 2) Hard Breaking Changes

- Remove `/v1/rpc` (`POST`, `GET`, `DELETE`) completely.
- Remove ACP extension support (`_sandboxagent/*`) completely.
- Remove ACP metadata contract (`params._meta["sandboxagent.dev"]`) from runtime behavior.
- Disable OpenCode compatibility completely (`/opencode/*` not mounted).
- Remove server-side session registry semantics tied to ACP transport.

## 3) ACP Transport

### 3.1 Endpoints

For each client-defined `{server_id}`:

- `POST /v1/acp/{server_id}`
- `GET /v1/acp/{server_id}` (SSE)
- `DELETE /v1/acp/{server_id}`

Control-plane ACP transport endpoint:

- `GET /v1/acp` (list active ACP transport instances)

No connection-id header is used.

### 3.2 Bootstrap / Creation

A transport instance is created lazily on first `POST`.

- First `POST` to a new `{server_id}` **must include `agent`** as query parameter:
  - `POST /v1/acp/{server_id}?agent=claude`
- Server behavior on first `POST`:
  1. Validate agent id.
  2. Lazy-install binaries if missing (current install policy retained).
  3. Lazy-start one ACP stdio process for this `{server_id}`.
  4. Forward JSON-RPC payload to that process.

Behavior for existing `{server_id}`:

- `agent` query param is optional.
- If provided and mismatched with existing bound agent, return `409 Conflict`.

If `{server_id}` does not exist and no `agent` is provided, return `400 Bad Request`.

### 3.3 Message Semantics

Sandbox Agent does not inspect ACP method semantics.

- `POST` accepts one JSON-RPC envelope.
- If envelope is request (`method` + `id`): wait for matching stdio response and return `200` + JSON body.
- If envelope is notification or response without `method`: forward and return `202` empty.
- `GET` streams agent->client messages as SSE.
- Replay semantics remain: `Last-Event-ID` supported using in-memory ring buffer per `{server_id}`.
- `DELETE` closes `{server_id}` transport instance and terminates subprocess.

### 3.4 SSE Framing

Same framing as current transport profile:

- `event: message`
- `id: <monotonic sequence per server_id>`
- `data: <single JSON-RPC object>`
- keepalive comment heartbeat every 15s

### 3.5 Process Model

- One ACP process per `{server_id}`.
- Multiple `{server_id}` can target the same agent type.
- Each `{server_id}` has isolated pending requests and replay buffer.

### 3.6 Error Mapping

- Invalid JSON envelope: `400 application/problem+json`
- Missing/invalid content type: `415`
- Unknown agent: `400`
- Unknown `{server_id}` for `GET`/`DELETE`/non-bootstrap `POST`: `404`
- Agent mismatch on existing `{server_id}`: `409`
- Timeout waiting for request response: `504`
- Subprocess spawn/write/read failures: `502`
- Successful `DELETE`: `204` (idempotent)

## 4) ACP Adapter Integration

Sandbox Agent reuses `acp-http-adapter` runtime internals for per-server stdio bridging.

- ACP stdio framing follows ACP docs (UTF-8, newline-delimited JSON-RPC).
- No synthetic `_sandboxagent/*` ACP messages are emitted.
- No transport-level metadata injection or translation.
- Sandbox Agent only performs HTTP routing/lifecycle and subprocess orchestration.

## 5) HTTP Endpoints for Non-ACP Features

These are the proposed HTTP surfaces to review.

### 5.1 Agents

- `GET /v1/agents`
  - List known agents + install/runtime status.
- `POST /v1/agents/{agent}/install`
  - Trigger install/reinstall with existing options.

### 5.2 Filesystem

All filesystem operations are HTTP-only (no ACP extension mirrors):

- `GET /v1/fs/entries`
- `GET /v1/fs/file`
- `PUT /v1/fs/file`
- `DELETE /v1/fs/entry`
- `POST /v1/fs/mkdir`
- `POST /v1/fs/move`
- `GET /v1/fs/stat`
- `POST /v1/fs/upload-batch`

### 5.3 MCP Config (HTTP)

Directory-scoped MCP config endpoints (copy v1 `mcp` config shape, but bind to `directory` instead of session init):

- `GET /v1/config/mcp?directory=<...>&mcpName=<name>`
  - Returns one MCP entry by name.
- `PUT /v1/config/mcp?directory=<...>&mcpName=<name>`
  - Upserts one MCP entry by name.
- `DELETE /v1/config/mcp?directory=<...>&mcpName=<name>`
  - Deletes one MCP entry by name.

Notes:

- Entry payload schema is v1-compatible MCP server config:
  - same as one value from legacy `CreateSessionRequest.mcp[<name>]`.
  - supports both local (stdio) and remote (http/sse) server forms.
- `directory` is required on all MCP config operations.
- `mcpName` is required on all MCP config operations.
- Server stores/retrieves config only and does not inject ACP payload metadata.

### 5.4 Skills Config (HTTP)

Directory-scoped Skills config endpoints (copy v1 skills config shape, but bind to `directory` instead of session init):

- `GET /v1/config/skills?directory=<...>&skillName=<name>`
  - Returns one skill entry by name.
- `PUT /v1/config/skills?directory=<...>&skillName=<name>`
  - Upserts one skill entry by name.
- `DELETE /v1/config/skills?directory=<...>&skillName=<name>`
  - Deletes one skill entry by name.

Notes:

- Entry payload schema is v1-compatible skills config:
  - same source object semantics as legacy `CreateSessionRequest.skills`.
  - includes `sources` behavior and compatible source options.
- `directory` is required on all skill config operations.
- `skillName` is required on all skill config operations.
- No ACP-side mutation/injection by server.

## 6) Session Metadata Ownership

Server no longer owns ACP session metadata.

- No `_sandboxagent/session/set_metadata`.
- No `_sandboxagent/session/list` / `_sandboxagent/session/get`.
- Client owns session indexing, labels, and metadata persistence.

- `GET /v1/acp`
  - Required endpoint.
  - Returns active `{server_id}` instances and process status only.

## 7) Security/Auth

- Existing bearer token auth remains for `/v1/*` when enabled.
- Auth is enforced at HTTP layer only.
- No extra principal scoping inside ACP runtime beyond route auth.

## 8) Testing Requirements

Minimum required coverage:

- ACP proxy e2e for request/response/notification/SSE replay on `/v1/acp/{server_id}`.
- Multi-instance isolation (`server-a`, `server-b`, same agent).
- Lazy install/start on first POST bootstrap.
- Idempotent `DELETE` + cleanup.
- Explicit regression test that `_sandboxagent/*` methods are not handled specially.

## 9) Implementation Checklist

1. Add new router surface `/v1/acp/{server_id}` and remove `/v1/rpc`.
2. Replace current ACP runtime method handling with per-server dumb proxy runtime.
3. Remove extension metadata advertisement/handlers.
4. Remove OpenCode router mount.
5. Keep/add HTTP endpoints listed in section 5.
6. Update OpenAPI/docs to reflect new transport and removed ACP extensions.

## 10) Final HTTP Endpoint Inventory

Expected HTTP endpoints after migration:

- `GET /`
- `GET /v1/health`

- `GET /v1/acp`
- `POST /v1/acp/{server_id}`
- `GET /v1/acp/{server_id}`
- `DELETE /v1/acp/{server_id}`

- `GET /v1/agents`
- `POST /v1/agents/{agent}/install`

- `GET /v1/fs/entries`
- `GET /v1/fs/file`
- `PUT /v1/fs/file`
- `DELETE /v1/fs/entry`
- `POST /v1/fs/mkdir`
- `POST /v1/fs/move`
- `GET /v1/fs/stat`
- `POST /v1/fs/upload-batch`

- `GET /v1/config/mcp?directory=...&mcpName=...`
- `PUT /v1/config/mcp?directory=...&mcpName=...`
- `DELETE /v1/config/mcp?directory=...&mcpName=...`

- `GET /v1/config/skills?directory=...&skillName=...`
- `PUT /v1/config/skills?directory=...&skillName=...`
- `DELETE /v1/config/skills?directory=...&skillName=...`

Removed/disabled surfaces:

- `/v1/rpc` removed.
- `/opencode/*` disabled/unmounted.
- No `_sandboxagent/*` ACP extension behavior.