mirror of
https://github.com/harivansh-afk/sandbox-agent.git
synced 2026-04-21 20:04:59 +00:00
acp spec (#155)
This commit is contained in:
NathanFlurry
parent
70287ec471
commit
e72eb9f611
264 changed files with 18559 additions and 51021 deletions
126
research/acp/extensibility-status.md
Normal file
126
research/acp/extensibility-status.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
# ACP Session Extensibility Status
|
||||
|
||||
Status date: 2026-02-10
|
||||
|
||||
This document tracks v1 session-surface parity against ACP and defines the recommended extension strategy for features not covered by ACP stable methods.
|
||||
|
||||
Primary references:
|
||||
|
||||
- `research/acp/v1-schema-to-acp-mapping.md`
|
||||
- `~/misc/acp-docs/schema/meta.json` (stable methods)
|
||||
- `~/misc/acp-docs/schema/meta.unstable.json` (unstable methods)
|
||||
- `~/misc/acp-docs/docs/protocol/extensibility.mdx`
|
||||
|
||||
## 1) Status Matrix (Session-Centric)
|
||||
|
||||
| v1 capability (session-related) | ACP stable | ACP unstable | Status in v2 | Recommendation |
|
||||
|---|---|---|---|---|
|
||||
| Create session | `session/new` | N/A | Covered | Use ACP standard only. |
|
||||
| Load/replay prior session | `session/load` (capability-gated) | N/A | Covered when agent process supports `loadSession` | Keep standard behavior. |
|
||||
| Send message | `session/prompt` | N/A | Covered | Use ACP standard only. |
|
||||
| Stream updates | `session/update` | N/A | Covered | Use ACP standard only. |
|
||||
| Cancel in-flight turn | `session/cancel` | N/A | Covered | Use ACP standard only. |
|
||||
| Permission request/reply | `session/request_permission` | N/A | Covered | Use ACP standard only; map `once/always/reject` to option kinds. |
|
||||
| Session list | Not in stable | `session/list` | Agent-process-dependent | Prefer unstable when supported; fallback to `_sandboxagent/session/list`. |
|
||||
| Fork session | Not in stable | `session/fork` | Agent-process-dependent | Prefer unstable when supported; fallback extension only if needed. |
|
||||
| Resume session | Not in stable | `session/resume` | Agent-process-dependent | Prefer unstable when supported; fallback extension only if needed. |
|
||||
| Set session model | Not in stable | `session/set_model` | Agent-process-dependent | Prefer unstable when supported; otherwise use `session/set_config_option` when model config exists. |
|
||||
| Terminate session object | No direct method | N/A | Not covered | Add `_sandboxagent/session/terminate` only if product requires explicit termination semantics beyond turn cancel. |
|
||||
| Poll events/log (`/events`) | No direct method | N/A | Not covered | Avoid as primary flow; if required for compat tooling, add `_sandboxagent/session/events` as derived view over stream. |
|
||||
| Question request/reply/reject (generic HITL) | No generic question method | N/A | Not covered | Add `_sandboxagent/session/request_question` request/response extension. |
|
||||
| `skills` in create-session payload | No first-class field | N/A | Not covered | Carry in `_meta["sandboxagent.dev"].skills`; optionally add metadata patch extension for updates. |
|
||||
| `title` in create-session payload | No first-class field | N/A | Not covered | Carry in `_meta["sandboxagent.dev"].title`. |
|
||||
| `agentVersion` requested in create-session payload | No first-class field | N/A | Not covered | Carry in `_meta["sandboxagent.dev"].agentVersionRequested`. |
|
||||
| Client-chosen session ID alias | Agent returns canonical `sessionId` | N/A | Not covered | Carry in `_meta["sandboxagent.dev"].requestedSessionId`. |
|
||||
| `agentMode` | `session/set_mode` and `current_mode_update` | N/A | Covered when exposed by agent process | Prefer standard `session/set_mode`; fallback to config options. |
|
||||
| `model` field | `session/set_config_option` (category `model`) | `session/set_model` | Partially covered | Prefer config options, then unstable `session/set_model`, then `_meta` hint if agent process lacks both. |
|
||||
| `variant` field | `session/set_config_option` (category `thought_level` or custom) | N/A | Partially covered | Prefer config option category; fallback `_meta["sandboxagent.dev"].variant`. |
|
||||
| `permissionMode` field | No dedicated standard field | N/A | Partially covered | Represent as config option (category `mode` or custom category), else `_meta` hint. |
|
||||
| Attachments (`path`, `mime`, `filename`) | Prompt content blocks support resource/resource_link/mime | N/A | Mostly covered | Use content blocks; preserve `filename` in `_meta` when not represented natively. |
|
||||
|
||||
## 2) Recommended ACP Extension Strategy
|
||||
|
||||
Use ACP stable/unstable methods first, then extension methods (`_...`) and `_meta` per ACP extensibility rules.
|
||||
|
||||
Rules:
|
||||
|
||||
1. Prefer ACP standard methods and capability negotiation.
|
||||
2. Prefer ACP unstable method names where available and supported by agent process.
|
||||
3. Only add custom methods for product semantics ACP does not define.
|
||||
4. Keep custom data in `_meta["sandboxagent.dev"]`; do not add custom root fields.
|
||||
5. Advertise extension support in `initialize` capability `_meta`.
|
||||
|
||||
## 3) Recommended Extension Surface
|
||||
|
||||
### 3.1 Session metadata extension (for skills/title/version/aliases)
|
||||
|
||||
Use metadata first in `session/new.params._meta["sandboxagent.dev"]`:
|
||||
|
||||
```json
|
||||
{
|
||||
"requestedSessionId": "my-session-alias",
|
||||
"title": "Bugfix run",
|
||||
"skills": ["repo:vercel-labs/skills/nextjs"],
|
||||
"agentVersionRequested": "latest",
|
||||
"permissionMode": "ask",
|
||||
"variant": "high"
|
||||
}
|
||||
```
|
||||
|
||||
If runtime updates are needed after session creation, add:
|
||||
|
||||
- `_sandboxagent/session/set_metadata` (request)
|
||||
- `_sandboxagent/session/metadata_update` (notification)
|
||||
|
||||
### 3.2 Generic question HITL extension
|
||||
|
||||
Add:
|
||||
|
||||
- `_sandboxagent/session/request_question` (agent -> client request)
|
||||
- JSON-RPC response with `{ "outcome": "answered" | "rejected" | "cancelled", ... }`
|
||||
|
||||
Keep legacy bridge data in `_meta["sandboxagent.dev"]`:
|
||||
|
||||
- `questionId`
|
||||
- original option list
|
||||
- legacy status mapping
|
||||
|
||||
### 3.3 Session lifecycle extension (only where needed)
|
||||
|
||||
Add only if required by product UX:
|
||||
|
||||
- `_sandboxagent/session/terminate`
|
||||
- `_sandboxagent/session/events` (poll/read model over stream buffer)
|
||||
|
||||
Avoid treating these as primary data paths; ACP stream remains canonical.
|
||||
|
||||
### 3.4 Capability advertisement for extensions
|
||||
|
||||
Advertise extension support in `initialize.result.agentCapabilities._meta["sandboxagent.dev"]`:
|
||||
|
||||
```json
|
||||
{
|
||||
"extensions": {
|
||||
"sessionMetadata": true,
|
||||
"requestQuestion": true,
|
||||
"sessionTerminate": true,
|
||||
"sessionEventsPoll": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Clients must feature-detect and degrade gracefully.
|
||||
|
||||
## 4) Recommendation for Current v2
|
||||
|
||||
Recommended implementation order:
|
||||
|
||||
1. Keep core session flow strictly ACP standard: `session/new`, `session/prompt`, `session/update`, `session/cancel`, `session/request_permission`.
|
||||
2. Use ACP unstable methods when agent processes advertise support (`session/list|fork|resume|set_model`).
|
||||
3. For `skills`, `title`, `requestedSessionId`, `agentVersion`, store and forward under `_meta["sandboxagent.dev"]`.
|
||||
4. Implement only two custom session extensions now:
|
||||
- `_sandboxagent/session/request_question`
|
||||
- `_sandboxagent/session/set_metadata` (if post-create metadata updates are required)
|
||||
5. Defer `_sandboxagent/session/terminate` and `_sandboxagent/session/events` unless a concrete consumer requires them.
|
||||
|
||||
This keeps the custom surface small while preserving v1-era product behavior.
|
||||
Loading…
Add table
Add a link
Reference in a new issue