harivansh-afk/sandbox-agent
1
0
Fork 0
mirror of https://github.com/harivansh-afk/sandbox-agent.git synced 2026-04-16 14:01:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat: acp http adapter

Browse source
This commit is contained in:
Nathan Flurry 2026-02-10 16:05:56 -08:00
parent 2ba630c180
commit b4c8564cb2
217 changed files with 18785 additions and 17400 deletions
Download patch file Download diff file Expand all files Collapse all files

4
research/acp/missing-features-spec/01-questions.md
View file

@ -4,9 +4,9 @@
## Summary
v1 had a full question subsystem: agent requests a question from the user, client replies with an answer or rejection, and the system tracks question status. v2 has partial stub implementation in mock only.
v1 had a full question subsystem: agent requests a question from the user, client replies with an answer or rejection, and the system tracks question status. v1 has partial stub implementation in mock only.
## Current v2 State
## Current v1 State
- `_sandboxagent/session/request_question` is declared as a constant in `acp_runtime/mod.rs:33`
- Advertised in capability injection (`extensions.sessionRequestQuestion: true`)

30
research/acp/missing-features-spec/04-filesystem-api.md
View file

@ -4,13 +4,13 @@
## Summary
v1 had 8 filesystem endpoints. v2 has only ACP `fs/read_text_file` + `fs/write_text_file` (text-only, agent->client direction). The full filesystem API should be re-implemented as Sandbox Agent-specific HTTP contracts at `/v2/fs/*`.
v1 had 8 filesystem endpoints. v1 has only ACP `fs/read_text_file` + `fs/write_text_file` (text-only, agent->client direction). The full filesystem API should be re-implemented as Sandbox Agent-specific HTTP contracts at `/v1/fs/*`.
## Current v2 State
## Current v1 State
- ACP stable: `fs/read_text_file`, `fs/write_text_file` (client methods invoked by agents, text-only)
- No HTTP filesystem endpoints exist in current `router.rs`
- `rfds-vs-extensions.md` confirms: "Already extension (`/v2/fs/*` custom HTTP surface)"
- `rfds-vs-extensions.md` confirms: "Already extension (`/v1/fs/*` custom HTTP surface)"
- CLAUDE.md: "Filesystem and terminal APIs remain Sandbox Agent-specific HTTP contracts and are not ACP"
## v1 Reference (source commit)
@ -356,32 +356,32 @@ async fn fs_upload_batch(
## Implementation Plan
### New v2 Endpoints
### New v1 Endpoints
| Method | Path | Description |
|--------|------|-------------|
| GET | `/v2/fs/entries` | List directory entries |
| GET | `/v2/fs/file` | Read file raw bytes |
| PUT | `/v2/fs/file` | Write file raw bytes |
| DELETE | `/v2/fs/entry` | Delete file or directory |
| POST | `/v2/fs/mkdir` | Create directory |
| POST | `/v2/fs/move` | Move/rename |
| GET | `/v2/fs/stat` | File metadata |
| POST | `/v2/fs/upload-batch` | Upload tar archive |
| GET | `/v1/fs/entries` | List directory entries |
| GET | `/v1/fs/file` | Read file raw bytes |
| PUT | `/v1/fs/file` | Write file raw bytes |
| DELETE | `/v1/fs/entry` | Delete file or directory |
| POST | `/v1/fs/mkdir` | Create directory |
| POST | `/v1/fs/move` | Move/rename |
| GET | `/v1/fs/stat` | File metadata |
| POST | `/v1/fs/upload-batch` | Upload tar archive |
### Files to Modify
| File | Change |
|------|--------|
| `server/packages/sandbox-agent/src/router.rs` | Add all 8 `/v2/fs/*` endpoints with handlers (port from v1 with v2 path prefix) |
| `server/packages/sandbox-agent/src/router.rs` | Add all 8 `/v1/fs/*` endpoints with handlers (port from v1 with v1 path prefix) |
| `server/packages/sandbox-agent/src/cli.rs` | Add CLI `fs` subcommands (list, read, write, delete, mkdir, move, stat) |
| `sdks/typescript/src/client.ts` | Add filesystem methods to SDK |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add filesystem endpoint tests |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add filesystem endpoint tests |
### Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Add `/v2/fs/*` endpoint specs |
| `docs/openapi.json` | Add `/v1/fs/*` endpoint specs |
| `docs/cli.mdx` | Add `fs` subcommand documentation |
| `docs/sdks/typescript.mdx` | Document filesystem SDK methods |

18
research/acp/missing-features-spec/05-health-endpoint.md
View file

@ -1,12 +1,12 @@
# Feature 5: Health Endpoint
**Implementation approach:** Enhance existing `GET /v2/health`
**Implementation approach:** Enhance existing `GET /v1/health`
## Summary
v1 had a typed `HealthResponse` with detailed status. v2 `GET /v2/health` exists but returns only `{ status: "ok", api_version: "v2" }`. Needs enrichment.
v1 had a typed `HealthResponse` with detailed status. v1 `GET /v1/health` exists but returns only `{ status: "ok", api_version: "v1" }`. Needs enrichment.
## Current v2 State
## Current v1 State
From `router.rs:332-346`:
@ -17,10 +17,10 @@ pub struct HealthResponse {
pub api_version: String,
}
async fn get_v2_health() -> Json<HealthResponse> {
async fn get_v1_health() -> Json<HealthResponse> {
Json(HealthResponse {
status: "ok".to_string(),
api_version: "v2".to_string(),
api_version: "v1".to_string(),
})
}
```
@ -72,19 +72,19 @@ pub struct HealthResponse {
}
```
`GET /v2/health` should mirror v1 semantics and response shape (ported from commit `8ecd27bc24e62505d7aa4c50cbdd1c9dbb09f836`), while keeping the v2 route path.
`GET /v1/health` should mirror v1 semantics and response shape (ported from commit `8ecd27bc24e62505d7aa4c50cbdd1c9dbb09f836`), while keeping the v1 route path.
### Files to Modify
| File | Change |
|------|--------|
| `server/packages/sandbox-agent/src/router.rs` | Port v1 health response types/logic onto `GET /v2/health` |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Update health endpoint test for full v1-parity payload |
| `server/packages/sandbox-agent/src/router.rs` | Port v1 health response types/logic onto `GET /v1/health` |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Update health endpoint test for full v1-parity payload |
| `sdks/typescript/src/client.ts` | Update `HealthResponse` type |
### Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Update `/v2/health` response schema |
| `docs/openapi.json` | Update `/v1/health` response schema |
| `docs/sdks/typescript.mdx` | Document enriched health response |

14
research/acp/missing-features-spec/06-server-status.md
View file

@ -1,14 +1,14 @@
# Feature 6: Server Status
**Implementation approach:** Extension fields on `GET /v2/agents` and `GET /v2/health`
**Implementation approach:** Extension fields on `GET /v1/agents` and `GET /v1/health`
## Summary
v1 had `ServerStatus` (Running/Stopped/Error) and `ServerStatusInfo` (baseUrl, lastError, restartCount, uptimeMs) per agent. v2 has none of this. Add server/agent process status tracking.
v1 had `ServerStatus` (Running/Stopped/Error) and `ServerStatusInfo` (baseUrl, lastError, restartCount, uptimeMs) per agent. v1 has none of this. Add server/agent process status tracking.
## Current v2 State
## Current v1 State
`GET /v2/agents` returns `AgentInfo` with install state only:
`GET /v1/agents` returns `AgentInfo` with install state only:
```rust
pub struct AgentInfo {
@ -132,13 +132,13 @@ Only include `server_status` for agents that use shared processes (Codex, OpenCo
| File | Change |
|------|--------|
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Track agent process lifecycle (start/stop/error/restart count) per `AgentId`; expose `status_snapshot()` method |
| `server/packages/sandbox-agent/src/router.rs` | Add `ServerStatus`, `ServerStatusInfo` types; add `server_status` to `AgentInfo`; query runtime for status in `get_v2_agents` |
| `server/packages/sandbox-agent/src/router.rs` | Add `ServerStatus`, `ServerStatusInfo` types; add `server_status` to `AgentInfo`; query runtime for status in `get_v1_agents` |
| `sdks/typescript/src/client.ts` | Update `AgentInfo` type with `serverStatus` |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Test server status in agent listing |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Test server status in agent listing |
### Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Update `/v2/agents` response with `server_status` |
| `docs/openapi.json` | Update `/v1/agents` response with `server_status` |
| `docs/sdks/typescript.mdx` | Document `serverStatus` field |

8
research/acp/missing-features-spec/07-session-termination.md
View file

@ -4,12 +4,12 @@
## Summary
v1 had explicit session termination (`POST /v1/sessions/{id}/terminate`). v2 only has `session/cancel` (turn cancellation, not session kill) and `DELETE /v2/rpc` (connection close, not session termination). Need explicit session destroy/terminate semantics.
v1 had explicit session termination (`POST /v1/sessions/{id}/terminate`). v1 only has `session/cancel` (turn cancellation, not session kill) and `DELETE /v1/rpc` (connection close, not session termination). Need explicit session destroy/terminate semantics.
## Current v2 State
## Current v1 State
- `session/cancel` — cancels an in-flight prompt turn only
- `DELETE /v2/rpc` — closes the HTTP connection, does **not** terminate the session
- `DELETE /v1/rpc` — closes the HTTP connection, does **not** terminate the session
- `_sandboxagent/session/detach` — detaches a session from a connection (multi-client visibility)
- No session termination/deletion exists
- `rfds-vs-extensions.md`: "Session Termination: Not covered by ACP. Only implement if product explicitly requires termination semantics beyond session/cancel"
@ -112,7 +112,7 @@ Response:
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Add `_sandboxagent/session/terminate` handler; add session removal from registry; add process kill logic |
| `server/packages/sandbox-agent/src/acp_runtime/mock.rs` | Add mock terminate support |
| `sdks/typescript/src/client.ts` | Add `terminateSession(sessionId)` method |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add session termination test |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add session termination test |
### Docs to Update

6
research/acp/missing-features-spec/08-model-variants.md
View file

@ -6,9 +6,9 @@
## Summary
v1 had `AgentModelInfo.variants`, `AgentModelInfo.defaultVariant`, and `CreateSessionRequest.variant`. v2 already has `_sandboxagent/session/list_models` but the variant fields need to be verified and the session-creation variant selection needs to work end-to-end.
v1 had `AgentModelInfo.variants`, `AgentModelInfo.defaultVariant`, and `CreateSessionRequest.variant`. v1 already has `_sandboxagent/session/list_models` but the variant fields need to be verified and the session-creation variant selection needs to work end-to-end.
## Current v2 State
## Current v1 State
From `acp_runtime/mod.rs`, `_sandboxagent/session/list_models` is implemented and returns:
- `availableModels[]` with `modelId`, `name`, `description`
@ -120,7 +120,7 @@ The runtime should forward this variant to the agent process (e.g., as a model p
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Verify `list_models` response includes `variants`/`defaultVariant`; extract and forward `variant` from `session/new` `_meta` |
| `server/packages/sandbox-agent/src/acp_runtime/mock.rs` | Add variant support to mock model listing |
| `sdks/typescript/src/client.ts` | Update `listModels` return type to include variants |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add model variants test |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add model variants test |
### Docs to Update

6
research/acp/missing-features-spec/10-include-raw.md
View file

@ -6,9 +6,9 @@
## Summary
v1 had an `include_raw` option that preserved the original agent JSON alongside normalized events. The `UniversalEvent.raw` field held the verbatim agent output. v2 has `_sandboxagent/agent/unparsed` for parse errors but no mechanism for clients to request raw agent payloads alongside normalized ACP events.
v1 had an `include_raw` option that preserved the original agent JSON alongside normalized events. The `UniversalEvent.raw` field held the verbatim agent output. v1 has `_sandboxagent/agent/unparsed` for parse errors but no mechanism for clients to request raw agent payloads alongside normalized ACP events.
## Current v2 State
## Current v1 State
- `_sandboxagent/agent/unparsed` — sends notifications when the runtime fails to parse agent output (error recovery only)
- No option for clients to request raw agent JSON alongside normal ACP events
@ -43,7 +43,7 @@ When `include_raw=true`, each `UniversalEvent` included the verbatim JSON the ag
### Extension Design
Since v2 agents speak ACP natively (JSON-RPC), the "raw" concept changes:
Since v1 agents speak ACP natively (JSON-RPC), the "raw" concept changes:
- For ACP-native agents: raw = the ACP JSON-RPC envelope itself (which clients already see)
- For non-native agents or runtime-synthesized events: raw = the original agent output before transformation

24
research/acp/missing-features-spec/12-agent-listing.md
View file

@ -1,14 +1,14 @@
# Feature 12: Agent Listing (Typed Response)
**Implementation approach:** Enhance existing `GET /v2/agents`
**Implementation approach:** Enhance existing `GET /v1/agents`
## Summary
v1 `GET /v1/agents` returned a typed `AgentListResponse` with `installed`, `credentialsAvailable`, `path`, `capabilities`, `serverStatus`. v2 `GET /v2/agents` returns a basic `AgentInfo` with only install state. Needs enrichment.
v1 `GET /v1/agents` returned a typed `AgentListResponse` with `installed`, `credentialsAvailable`, `path`, `capabilities`, `serverStatus`. v1 `GET /v1/agents` returns a basic `AgentInfo` with only install state. Needs enrichment.
This feature also carries pre-session models/modes as optional fields when the agent is installed (Feature #13), rather than using separate model/mode endpoints.
## Current v2 State
## Current v1 State
From `router.rs:265-275`:
@ -183,19 +183,19 @@ fn agent_capabilities_for(agent: AgentId) -> AgentCapabilities {
### Enriched AgentInfo
Merge v2 install fields with v1 richness:
Merge v1 install fields with v1 richness:
```rust
pub struct AgentInfo {
pub id: String,
pub installed: bool, // convenience: is fully installed
pub credentials_available: bool, // from credential extraction
pub native_required: bool, // keep from v2
pub native_installed: bool, // keep from v2
pub native_version: Option<String>, // keep from v2
pub agent_process_installed: bool, // keep from v2
pub agent_process_source: Option<String>, // keep from v2
pub agent_process_version: Option<String>, // keep from v2
pub native_required: bool, // keep from v1
pub native_installed: bool, // keep from v1
pub native_version: Option<String>, // keep from v1
pub agent_process_installed: bool, // keep from v1
pub agent_process_source: Option<String>, // keep from v1
pub agent_process_version: Option<String>, // keep from v1
pub path: Option<String>, // from resolve_binary()
pub capabilities: AgentCapabilities, // full v1 capability set
pub server_status: Option<AgentServerStatus>, // from Feature #6
@ -212,11 +212,11 @@ pub struct AgentInfo {
| `server/packages/sandbox-agent/src/router.rs` | Enrich `AgentInfo` and `AgentCapabilities` structs; add `agent_capabilities_for()` static mapping; add credential check; add convenience `installed` field; add optional `models`/`modes` for installed agents |
| `server/packages/agent-management/src/agents.rs` | Expose credential availability check and `resolve_binary()` if not already present |
| `sdks/typescript/src/client.ts` | Update `AgentInfo` and `AgentCapabilities` types |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Update agent listing test assertions |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Update agent listing test assertions |
### Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Update `/v2/agents` response schema with full `AgentCapabilities` |
| `docs/openapi.json` | Update `/v1/agents` response schema with full `AgentCapabilities` |
| `docs/sdks/typescript.mdx` | Document enriched agent listing |

10
research/acp/missing-features-spec/13-models-modes-listing.md
View file

@ -4,12 +4,12 @@
## Summary
v1 exposed pre-session model/mode discovery via separate endpoints. For v2, models and modes should be optional fields on the agent response payload (only when the agent is installed), with lazy population for dynamic agents.
v1 exposed pre-session model/mode discovery via separate endpoints. For v1, models and modes should be optional fields on the agent response payload (only when the agent is installed), with lazy population for dynamic agents.
## Current v2 State
## Current v1 State
- `_sandboxagent/session/list_models` works but requires an active ACP connection and session
- `GET /v2/agents` does not include pre-session model/mode metadata
- `GET /v1/agents` does not include pre-session model/mode metadata
- v1 had static per-agent mode definitions (`agent_modes_for()` in `router.rs`)
- v1 had dynamic model fetching (Claude/Codex/OpenCode), plus static model lists for Amp/Mock
@ -57,11 +57,11 @@ Model variants are explicitly out of scope for this implementation pass.
| `server/packages/sandbox-agent/src/router.rs` | Enrich agent response type/handlers to optionally include models + modes |
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Expose model query support for control-plane enrichment without requiring an active session |
| `sdks/typescript/src/client.ts` | Extend `AgentInfo` type with optional `models`, `defaultModel`, `modes` |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add assertions for installed vs non-installed agent response shapes |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add assertions for installed vs non-installed agent response shapes |
## Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Update `/v2/agents` (and agent detail endpoint if present) schema with optional `models`/`modes` |
| `docs/openapi.json` | Update `/v1/agents` (and agent detail endpoint if present) schema with optional `models`/`modes` |
| `docs/sdks/typescript.mdx` | Document optional model/mode fields on agent response |

6
research/acp/missing-features-spec/14-message-attachments.md
View file

@ -4,9 +4,9 @@
## Summary
v1 `MessageRequest.attachments` allowed sending file attachments (path, mime, filename) with prompts. v2 ACP `embeddedContext` is only partial. Need to support file attachments in prompt messages.
v1 `MessageRequest.attachments` allowed sending file attachments (path, mime, filename) with prompts. v1 ACP `embeddedContext` is only partial. Need to support file attachments in prompt messages.
## Current v2 State
## Current v1 State
- ACP `session/prompt` accepts `params.content` as the prompt text
- No attachment mechanism in the current ACP prompt flow
@ -122,7 +122,7 @@ The runtime extracts attachments from `_meta` and transforms them per agent:
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Extract `attachments` from `session/prompt` `_meta`; transform per agent before forwarding |
| `server/packages/sandbox-agent/src/acp_runtime/mock.rs` | Add mock handling for attachments |
| `sdks/typescript/src/client.ts` | Add `attachments` option to prompt method |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add attachment prompt test |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add attachment prompt test |
### Docs to Update

6
research/acp/missing-features-spec/15-session-creation-richness.md
View file

@ -4,13 +4,13 @@
## Summary
v1 `CreateSessionRequest` had `mcp` (full MCP server config with OAuth, env headers, bearer tokens), `skills` (sources with git refs), `agent_version`, `directory`. v2 needs to support these at session creation time.
v1 `CreateSessionRequest` had `mcp` (full MCP server config with OAuth, env headers, bearer tokens), `skills` (sources with git refs), `agent_version`, `directory`. v1 needs to support these at session creation time.
## Current v2 State — MOSTLY IMPLEMENTED
## Current v1 State — MOSTLY IMPLEMENTED
Investigation shows that **most of these are already supported** via `_meta.sandboxagent.dev` passthrough in `session/new`:
| Field | v1 | v2 Status | v2 Mechanism |
| Field | v1 | v1 Status | v1 Mechanism |
|-------|-----|-----------|-------------|
| `directory` | `CreateSessionRequest.directory` | **Implemented** | `cwd` parameter extracted from payload |
| `agent_version` | `CreateSessionRequest.agent_version` | **Implemented** | `_meta.sandboxagent.dev.agentVersionRequested` (stored, forwarded) |

18
research/acp/missing-features-spec/16-session-info.md
View file

@ -1,12 +1,12 @@
# Feature 16: Session Info
**Implementation approach:** New HTTP endpoints (`GET /v2/sessions`, `GET /v2/sessions/{id}`)
**Implementation approach:** New HTTP endpoints (`GET /v1/sessions`, `GET /v1/sessions/{id}`)
## Summary
v1 `SessionInfo` tracked `event_count`, `created_at`, `updated_at`, and full `mcp` config. v2 has session data in the ACP runtime's `MetaSession` struct but no HTTP endpoints to query it. Add REST endpoints for session listing and detail.
v1 `SessionInfo` tracked `event_count`, `created_at`, `updated_at`, and full `mcp` config. v1 has session data in the ACP runtime's `MetaSession` struct but no HTTP endpoints to query it. Add REST endpoints for session listing and detail.
## Current v2 State
## Current v1 State
### Internal Session Tracking
@ -117,15 +117,15 @@ fn build_session_info(state: &SessionState) -> SessionInfo {
### New HTTP Endpoints
```
GET /v2/sessions -> SessionListResponse
GET /v2/sessions/{id} -> SessionInfo
GET /v1/sessions -> SessionListResponse
GET /v1/sessions/{id} -> SessionInfo
```
These are control-plane HTTP endpoints (not ACP), providing session visibility without requiring an active ACP connection.
### Response Types
The v2 `SessionInfo` should be a superset of v1 fields, adapted for ACP:
The v1 `SessionInfo` should be a superset of v1 fields, adapted for ACP:
```rust
#[derive(Debug, Serialize, JsonSchema, ToSchema)]
@ -156,15 +156,15 @@ Need to add:
| File | Change |
|------|--------|
| `server/packages/sandbox-agent/src/router.rs` | Add `GET /v2/sessions` and `GET /v2/sessions/{id}` handlers; add response types |
| `server/packages/sandbox-agent/src/router.rs` | Add `GET /v1/sessions` and `GET /v1/sessions/{id}` handlers; add response types |
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Add `created_at` to `MetaSession`; add `ended` tracking; expose `list_sessions()` and `get_session()` public methods |
| `sdks/typescript/src/client.ts` | Add `listSessions()` and `getSession(id)` methods |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add session listing and detail tests |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add session listing and detail tests |
### Docs to Update
| Doc | Change |
|-----|--------|
| `docs/openapi.json` | Add `/v2/sessions` and `/v2/sessions/{id}` endpoint specs |
| `docs/openapi.json` | Add `/v1/sessions` and `/v1/sessions/{id}` endpoint specs |
| `docs/cli.mdx` | Add CLI `sessions list` and `sessions info` commands |
| `docs/sdks/typescript.mdx` | Document session listing SDK methods |

8
research/acp/missing-features-spec/17-error-termination-metadata.md
View file

@ -4,9 +4,9 @@
## Summary
v1 captured `exit_code`, structured `StderrOutput` (head/tail/truncated) when a session ended due to error. v2 loses this metadata. Need to capture and expose process termination details.
v1 captured `exit_code`, structured `StderrOutput` (head/tail/truncated) when a session ended due to error. v1 loses this metadata. Need to capture and expose process termination details.
## Current v2 State
## Current v1 State
- Agent process lifecycle is managed in `acp_runtime/mod.rs`
- Process exit is detected but error metadata (exit code, stderr) is not captured or forwarded
@ -171,7 +171,7 @@ When an agent process terminates with an error:
### Session Info Integration
Termination metadata should be accessible via:
- `GET /v2/sessions/{id}` (Feature #16) — include `terminationInfo` in response when session has ended
- `GET /v1/sessions/{id}` (Feature #16) — include `terminationInfo` in response when session has ended
- `session/list` ACP response — include termination status in session entries
### Files to Modify
@ -181,7 +181,7 @@ Termination metadata should be accessible via:
| `server/packages/sandbox-agent/src/acp_runtime/mod.rs` | Add stderr capture (head/tail buffer) on agent process; capture exit code; emit `_sandboxagent/session/ended`; store v1-shaped termination info in `MetaSession` |
| `server/packages/sandbox-agent/src/acp_runtime/mock.rs` | Add mock error termination scenario (e.g., when prompt contains "crash") |
| `sdks/typescript/src/client.ts` | Add `TerminationInfo` type; expose on session events and session info |
| `server/packages/sandbox-agent/tests/v2_api.rs` | Add error termination metadata test |
| `server/packages/sandbox-agent/tests/v1_api.rs` | Add error termination metadata test |
### Docs to Update

12
research/acp/missing-features-spec/feature-index.md
View file

@ -1,8 +1,8 @@
# Missing Features Index
Features selected for implementation from the v1-to-v2 gap analysis.
Features selected for implementation from the v1-to-v1 gap analysis.
## Completely UNIMPLEMENTED in v2
## Completely UNIMPLEMENTED in v1
| # | Feature | Implementation notes |
|---|---------|---------------------|
@ -12,19 +12,19 @@ Features selected for implementation from the v1-to-v2 gap analysis.
| 4 | **Filesystem API** -- all 8 endpoints (list, read, write, delete, mkdir, move, stat, upload-batch). ACP only has text-only `fs/read_text_file` + `fs/write_text_file` (agent->client direction). | |
| 5 | **Health endpoint** -- typed `HealthResponse` with status. | |
| 6 | **Server status** -- `ServerStatus` (Running/Stopped/Error), `ServerStatusInfo` (baseUrl, lastError, restartCount, uptimeMs). | |
| 7 | **Session termination** -- v1 had full `terminate`. v2 only has `session/cancel` (turn cancellation, not session kill). No explicit close/delete. | See existing ACP RFD |
| 7 | **Session termination** -- v1 had full `terminate`. v1 only has `session/cancel` (turn cancellation, not session kill). No explicit close/delete. | See existing ACP RFD |
| 8 | ~~Model variants~~ -- deferred for now. | Out of scope |
| 9 | ~~Agent capability flags~~ | Not selected |
| 10 | ~~`include_raw`~~ -- deferred for now. | Out of scope |
## Downgraded / Partial in v2
## Downgraded / Partial in v1
| # | Feature | Implementation notes |
|---|---------|---------------------|
| 11 | ~~Permission reply granularity~~ | Not selected |
| 12 | **Agent listing** -- v1 `GET /v1/agents` returned typed `AgentListResponse` with `installed`, `credentialsAvailable`, `path`, `capabilities`, `serverStatus`. v2 returns generic JSON. | |
| 12 | **Agent listing** -- v1 `GET /v1/agents` returned typed `AgentListResponse` with `installed`, `credentialsAvailable`, `path`, `capabilities`, `serverStatus`. v1 returns generic JSON. | |
| 13 | **Models/modes listing** -- expose as optional `models`/`modes` fields on agent response payloads (installed agents only), lazily populated. | No separate `/models` or `/modes` endpoints |
| 14 | **Message attachments** -- v1 `MessageRequest.attachments` (path, mime, filename). v2 ACP `embeddedContext` is only partial. | |
| 14 | **Message attachments** -- v1 `MessageRequest.attachments` (path, mime, filename). v1 ACP `embeddedContext` is only partial. | |
| 15 | **Session creation richness** -- v1 `CreateSessionRequest` had `mcp` (full MCP server config with OAuth, env headers, bearer tokens), `skills` (sources with git refs), `agent_version`, `directory`. Most have no ACP equivalent. | Check with our extensions, do not implement if already done |
| 16 | **Session info** -- v1 `SessionInfo` tracked `event_count`, `created_at`, `updated_at`, full `mcp` config. Mostly lost. | Add as sessions HTTP endpoint |
| 17 | **Error termination metadata** -- v1 captured `exit_code`, structured `StderrOutput` (head/tail/truncated). Gone. | |

18
research/acp/missing-features-spec/plan.md
View file

@ -1,14 +1,14 @@
# Missing Features Implementation Plan
Features selected from the v1-to-v2 gap analysis, ordered for implementation.
Features selected from the v1-to-v1 gap analysis, ordered for implementation.
## Confirmed Decisions (Locked)
- Canonical extension naming is `_sandboxagent/...` and `_meta["sandboxagent.dev"]`; remove/ignore `_sandboxagent/*`.
- Control-plane discovery/status/session APIs are HTTP-only under `/v2/*` (no ACP control-plane equivalents).
- Control-plane discovery/status/session APIs are HTTP-only under `/v1/*` (no ACP control-plane equivalents).
- For Health, Filesystem, and Attachments, implementation should port behavior from v1 using commit `8ecd27bc24e62505d7aa4c50cbdd1c9dbb09f836`.
- Session termination via `_sandboxagent/session/terminate` is idempotent.
- `DELETE /v2/rpc` is transport detach only; it must not replace explicit termination semantics.
- `DELETE /v1/rpc` is transport detach only; it must not replace explicit termination semantics.
- Model variants (#8) are removed from current scope.
- `include_raw` (#10) is removed from current scope.
- Models/modes should be optional properties on agent response payloads (only when the agent is installed) and lazily populated.
@ -24,9 +24,9 @@ These features enrich existing endpoints and have no dependencies on each other.
| Order | Feature | Spec | Approach | Effort |
|:-----:|----------------------------------------------|:----:|--------------------------------------------|:------:|
| A1 | [Health Endpoint](./05-health-endpoint.md) | #5 | Port v1 health behavior to `GET /v2/health` | Small |
| A1 | [Health Endpoint](./05-health-endpoint.md) | #5 | Port v1 health behavior to `GET /v1/health` | Small |
| A2 | [Server Status](./06-server-status.md) | #6 | Add process tracking to ACP runtime | Medium |
| A3 | [Agent Listing](./12-agent-listing.md) | #12 | Enrich `GET /v2/agents` with v1-parity data | Medium |
| A3 | [Agent Listing](./12-agent-listing.md) | #12 | Enrich `GET /v1/agents` with v1-parity data | Medium |
**A2 blocks A3** — agent listing includes server status from Feature #6.
@ -36,7 +36,7 @@ Session-level features that build on Phase A runtime tracking.
| Order | Feature | Spec | Approach | Effort |
|:-----:|--------------------------------------------------------------|:----:|------------------------------------------------------|:------:|
| B1 | [Session Info](./16-session-info.md) | #16 | New `GET /v2/sessions` and `GET /v2/sessions/{id}` | Medium |
| B1 | [Session Info](./16-session-info.md) | #16 | New `GET /v1/sessions` and `GET /v1/sessions/{id}` | Medium |
| B2 | [Session Termination](./07-session-termination.md) | #7 | Idempotent `_sandboxagent/session/terminate` | Medium |
| B3 | [Error Termination Metadata](./17-error-termination-metadata.md) | #17 | Stderr capture + `_sandboxagent/session/ended` event | Medium |
@ -72,7 +72,7 @@ Standalone platform-level API.
| Order | Feature | Spec | Approach | Effort |
|:-----:|---------------------------------------|:----:|----------------------------------|:------:|
| E1 | [Filesystem API](./04-filesystem-api.md) | #4 | Port v1 behavior to `/v2/fs/*` | Large |
| E1 | [Filesystem API](./04-filesystem-api.md) | #4 | Port v1 behavior to `/v1/fs/*` | Large |
No dependencies on other features. Can be implemented at any time but is the largest single feature.
@ -97,7 +97,7 @@ E1 (Filesystem) [independent]
| # | Feature | Spec File | Status | Approach |
|:--:|---------------------------------|-------------------------------------------------------|---------------------------------|-------------------------------------------------|
| 1 | ~~Questions~~ | [01-questions.md](./01-questions.md) | Deferred ([#156](https://github.com/rivet-dev/sandbox-agent/issues/156)) | Agent process side |
| 4 | Filesystem API | [04-filesystem-api.md](./04-filesystem-api.md) | Not implemented | Port v1 behavior onto `/v2/fs/*` |
| 4 | Filesystem API | [04-filesystem-api.md](./04-filesystem-api.md) | Not implemented | Port v1 behavior onto `/v1/fs/*` |
| 5 | Health Endpoint | [05-health-endpoint.md](./05-health-endpoint.md) | Partial (basic only) | Port v1 health behavior |
| 6 | Server Status | [06-server-status.md](./06-server-status.md) | Not implemented | Runtime tracking |
| 7 | Session Termination | [07-session-termination.md](./07-session-termination.md) | Not implemented | Idempotent ACP extension |
@ -121,7 +121,7 @@ E1 (Filesystem) [independent]
| `sdks/typescript/src/client.ts` | All in-scope features |
| `docs/openapi.json` | #4, #5, #6, #12, #13, #16 |
| `docs/sdks/typescript.mdx` | All in-scope features |
| `server/packages/sandbox-agent/tests/v2_api.rs` | All in-scope features |
| `server/packages/sandbox-agent/tests/v1_api.rs` | All in-scope features |
### Docs update checklist