@sorbetai/acp 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/COMPATIBILITY.md +231 -0
- package/README.md +270 -2
- package/agent.json +15 -0
- package/dist/LICENSE.pi +21 -0
- package/dist/agent-B7PnGaB0.js +1600 -0
- package/dist/agent-B7PnGaB0.js.map +1 -0
- package/dist/agent-DfScvNX2.d.ts +43 -0
- package/dist/authentication-CraYYCai.js +132 -0
- package/dist/authentication-CraYYCai.js.map +1 -0
- package/dist/compatibility-B1ZA8Wvn.d.ts +606 -0
- package/dist/compatibility-Cmomxq8E.js +728 -0
- package/dist/compatibility-Cmomxq8E.js.map +1 -0
- package/dist/compatibility.d.ts +2 -0
- package/dist/compatibility.js +3 -0
- package/dist/experimental-v2-CB_5NMax.d.ts +35 -0
- package/dist/experimental-v2-DH1LLn_I.js +1088 -0
- package/dist/experimental-v2-DH1LLn_I.js.map +1 -0
- package/dist/experimental-v2.d.ts +3 -0
- package/dist/experimental-v2.js +4 -0
- package/dist/extensions-czICN7yK.js +10 -0
- package/dist/extensions-czICN7yK.js.map +1 -0
- package/dist/extensions.d.ts +29 -0
- package/dist/extensions.js +3 -0
- package/dist/filesystem-worker.js +10445 -0
- package/dist/filesystem-worker.js.map +1 -0
- package/dist/index-BzGG36Gz.d.ts +8248 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.js +7 -0
- package/dist/session-attachments-DXvfzXfV.js +23124 -0
- package/dist/session-attachments-DXvfzXfV.js.map +1 -0
- package/dist/stdio-Bwi2cEOV.js +38 -0
- package/dist/stdio-Bwi2cEOV.js.map +1 -0
- package/dist/stdio-cli.d.ts +1 -0
- package/dist/stdio-cli.js +91 -0
- package/dist/stdio-cli.js.map +1 -0
- package/dist/stdio.d.ts +20 -0
- package/dist/stdio.js +7 -0
- package/package.json +85 -3
package/COMPATIBILITY.md
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Sorbet ACP Compatibility
|
|
2
|
+
|
|
3
|
+
> Generated from the SDK and extension inventory in
|
|
4
|
+
> [`src/compatibility.gen.ts`](./src/compatibility.gen.ts)
|
|
5
|
+
> and Sorbet classifications in [`src/compatibility.ts`](./src/compatibility.ts). Do not
|
|
6
|
+
> edit this file manually. Run `pnpm --filter @sorbetai/acp compatibility:write` to
|
|
7
|
+
> regenerate both generated artifacts.
|
|
8
|
+
|
|
9
|
+
This report separates protocol presence from operational support. Every method and Session
|
|
10
|
+
update in the pinned ACP schemas, plus every capability and method in the pinned Lody
|
|
11
|
+
extension package, must have a classification. Sorbet advertises only capabilities whose
|
|
12
|
+
supported behavior is connected and operational.
|
|
13
|
+
|
|
14
|
+
## Protocol baselines
|
|
15
|
+
|
|
16
|
+
| Surface | Protocol | Schema | SDK | Stability |
|
|
17
|
+
| --------------- | -------: | --------------- | ------- | ------------ |
|
|
18
|
+
| Stable v1 | 1 | `1.20.0` | `1.4.0` | stable |
|
|
19
|
+
| Experimental v2 | 2 | `2.0.0-alpha.2` | `1.4.0` | experimental |
|
|
20
|
+
|
|
21
|
+
| Extension package | Version |
|
|
22
|
+
| -------------------- | ------- |
|
|
23
|
+
| `acp-extension-core` | `0.1.7` |
|
|
24
|
+
|
|
25
|
+
## Summary
|
|
26
|
+
|
|
27
|
+
| Surface | Supported | Partial | Unsupported | Total |
|
|
28
|
+
| ------------------------------- | --------: | ------: | ----------: | ----: |
|
|
29
|
+
| Stable v1 Agent methods | 17 | 0 | 11 | 28 |
|
|
30
|
+
| Stable v1 Client methods | 11 | 0 | 3 | 14 |
|
|
31
|
+
| Stable v1 Session updates | 12 | 0 | 3 | 15 |
|
|
32
|
+
| Experimental v2 Agent methods | 15 | 1 | 10 | 26 |
|
|
33
|
+
| Experimental v2 Client methods | 7 | 0 | 0 | 7 |
|
|
34
|
+
| Experimental v2 Session updates | 14 | 0 | 5 | 19 |
|
|
35
|
+
| Shared protocol methods | 1 | 0 | 0 | 1 |
|
|
36
|
+
| Lody extension capabilities | 8 | 0 | 3 | 11 |
|
|
37
|
+
| Lody custom methods | 8 | 0 | 2 | 10 |
|
|
38
|
+
| Sorbet extensions | 3 | 0 | 1 | 4 |
|
|
39
|
+
|
|
40
|
+
## Status definitions
|
|
41
|
+
|
|
42
|
+
| Status | Contract |
|
|
43
|
+
| -------------- | ------------------------------------------------------------------------ |
|
|
44
|
+
| ✅ Supported | Implemented end to end for the capability Sorbet advertises. |
|
|
45
|
+
| ⚠️ Partial | A real subset is operational; the missing behavior is stated in the row. |
|
|
46
|
+
| ❌ Unsupported | Present in the pinned protocol, but neither handled nor advertised. |
|
|
47
|
+
|
|
48
|
+
## Stable v1 Agent methods
|
|
49
|
+
|
|
50
|
+
| Protocol item | Status | Notes |
|
|
51
|
+
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
52
|
+
| `initialize` | ✅ Supported | Negotiates ACP v1, Client capabilities, Sorbet extensions, and advertised features. |
|
|
53
|
+
| `authenticate` | ✅ Supported | Dispatches only authentication methods supplied by the injected authentication port. |
|
|
54
|
+
| `logout` | ✅ Supported | Uses the injected authentication port or logs out NodeAgent provider credentials. |
|
|
55
|
+
| `providers/list` | ✅ Supported | Lists stable Pi Provider slots with non-secret process-local endpoint state. |
|
|
56
|
+
| `providers/set` | ✅ Supported | Fully replaces a known Provider endpoint without persisting headers or routing state. |
|
|
57
|
+
| `providers/disable` | ✅ Supported | Disables a Provider endpoint while preserving its stable discoverable definition. |
|
|
58
|
+
| `session/new` | ✅ Supported | Creates a durable Sorbet Session with workspace, MCP, and model bindings. |
|
|
59
|
+
| `session/load` | ✅ Supported | Reopens an unattached Session and replays its durable conversation and Plan projections with connection-scoped bindings. |
|
|
60
|
+
| `session/list` | ✅ Supported | Provides cwd filtering and opaque cursor pagination. |
|
|
61
|
+
| `session/delete` | ✅ Supported | Closes connection state and idempotently deletes the Session catalog entry. |
|
|
62
|
+
| `session/fork` | ✅ Supported | Creates an independent durable Session from a committed conversation boundary. |
|
|
63
|
+
| `session/resume` | ✅ Supported | Reopens an unattached durable Session with new connection-scoped bindings. |
|
|
64
|
+
| `session/close` | ✅ Supported | Aborts active work and releases Session, MCP, and connection resources. |
|
|
65
|
+
| `session/set_mode` | ✅ Supported | Keeps ACP v1 Session mode at its sole advertised default; permissions use permission_mode. |
|
|
66
|
+
| `session/set_config_option` | ✅ Supported | Applies advertised model, thinking-level, and permission selectors and publishes updated option state. |
|
|
67
|
+
| `session/prompt` | ✅ Supported | Runs prompts and, in Plan permission mode, reviews the proposal before an idempotent implementation Run. |
|
|
68
|
+
| `session/cancel` | ✅ Supported | Aborts the active Sorbet Run and propagates cancellation to Pi. |
|
|
69
|
+
| `mcp/message` | ❌ Unsupported | Stable v1 supports stdio, HTTP, and SSE MCP, but not MCP-over-ACP. |
|
|
70
|
+
| `nes/start` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
71
|
+
| `nes/suggest` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
72
|
+
| `nes/accept` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
73
|
+
| `nes/reject` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
74
|
+
| `nes/close` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
75
|
+
| `document/didOpen` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
76
|
+
| `document/didChange` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
77
|
+
| `document/didClose` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
78
|
+
| `document/didSave` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
79
|
+
| `document/didFocus` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
80
|
+
|
|
81
|
+
## Stable v1 Client methods
|
|
82
|
+
|
|
83
|
+
| Protocol item | Status | Notes |
|
|
84
|
+
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
85
|
+
| `session/request_permission` | ✅ Supported | Maps Tool decisions into permission facts and rules and reviews durable Plan proposals. |
|
|
86
|
+
| `session/update` | ✅ Supported | Publishes the supported v1 Session update variants classified below. |
|
|
87
|
+
| `fs/read_text_file` | ✅ Supported | Registers a Pi Tool when the Client advertises readTextFile support. |
|
|
88
|
+
| `fs/write_text_file` | ✅ Supported | Registers a Pi Tool when the Client advertises writeTextFile support. |
|
|
89
|
+
| `terminal/create` | ✅ Supported | Registers a Pi Tool for Client terminal creation when terminal support is advertised. |
|
|
90
|
+
| `terminal/output` | ✅ Supported | Registers a Pi Tool for reading output from Client-owned terminals. |
|
|
91
|
+
| `terminal/wait_for_exit` | ✅ Supported | Registers a Pi Tool for waiting on Client-owned terminal exit. |
|
|
92
|
+
| `terminal/kill` | ✅ Supported | Registers a Pi Tool for killing Client-owned terminals. |
|
|
93
|
+
| `terminal/release` | ✅ Supported | Registers a Pi Tool for releasing Client-owned terminals. |
|
|
94
|
+
| `mcp/connect` | ❌ Unsupported | MCP-over-ACP is not advertised by the stable adapter. |
|
|
95
|
+
| `mcp/message` | ❌ Unsupported | MCP-over-ACP is not advertised by the stable adapter. |
|
|
96
|
+
| `mcp/disconnect` | ❌ Unsupported | MCP-over-ACP is not advertised by the stable adapter. |
|
|
97
|
+
| `elicitation/create` | ✅ Supported | Maps the host-neutral Runtime Elicitation contract to capability-gated request- and Session-scoped forms and URLs. |
|
|
98
|
+
| `elicitation/complete` | ✅ Supported | Completes URL Elicitations through the host-neutral Runtime contract. |
|
|
99
|
+
|
|
100
|
+
## Stable v1 Session updates
|
|
101
|
+
|
|
102
|
+
| Protocol item | Status | Notes |
|
|
103
|
+
| --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `user_message_chunk` | ✅ Supported | Emitted while replaying durable user conversation entries. |
|
|
105
|
+
| `agent_message_chunk` | ✅ Supported | Streams Pi assistant text and replays durable assistant messages. |
|
|
106
|
+
| `agent_thought_chunk` | ✅ Supported | Streams Pi thinking deltas when the model produces them. |
|
|
107
|
+
| `tool_call` | ✅ Supported | Publishes complete Pi Tool calls after argument streaming finishes. |
|
|
108
|
+
| `tool_call_update` | ✅ Supported | Publishes Tool execution status, partial results, and terminal outcomes. |
|
|
109
|
+
| `plan` | ✅ Supported | Projects durable checklist entries for Clients using the stable legacy Plan update. |
|
|
110
|
+
| `plan_update` | ✅ Supported | Projects durable item and Markdown Plans when the Client advertises Plan capability. |
|
|
111
|
+
| `plan_removed` | ✅ Supported | Removes a projected Plan when the Client advertises Plan capability. |
|
|
112
|
+
| `available_commands_update` | ❌ Unsupported | Sorbet has no ACP command catalog projection. |
|
|
113
|
+
| `compaction_summary_chunk` | ❌ Unsupported | Sorbet does not yet stream standard ACP compaction summary chunks. |
|
|
114
|
+
| `compaction_update` | ❌ Unsupported | Sorbet compaction is currently projected through the Lody extension only. |
|
|
115
|
+
| `current_mode_update` | ✅ Supported | Emitted when the Client selects the sole advertised default mode. |
|
|
116
|
+
| `config_option_update` | ✅ Supported | Emitted after an advertised Session config option changes. |
|
|
117
|
+
| `session_info_update` | ✅ Supported | Publishes durable titles with Lody titleSource provenance, activity timestamps, and MCP startup warnings. |
|
|
118
|
+
| `usage_update` | ✅ Supported | Publishes current context occupancy, model context size, and cumulative Session cost. |
|
|
119
|
+
|
|
120
|
+
## Experimental v2 Agent methods
|
|
121
|
+
|
|
122
|
+
| Protocol item | Status | Notes |
|
|
123
|
+
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
|
|
124
|
+
| `initialize` | ✅ Supported | Negotiates ACP v2 and advertises only operational draft capabilities. |
|
|
125
|
+
| `auth/login` | ✅ Supported | Dispatches only methods supplied by the injected authentication port. |
|
|
126
|
+
| `auth/logout` | ✅ Supported | Uses the injected authentication port or NodeAgent provider logout. |
|
|
127
|
+
| `providers/list` | ✅ Supported | Lists stable Pi Provider slots with non-secret process-local endpoint state. |
|
|
128
|
+
| `providers/set` | ✅ Supported | Fully replaces a known Provider endpoint without persisting headers or routing state. |
|
|
129
|
+
| `providers/disable` | ✅ Supported | Disables a Provider endpoint while preserving its stable discoverable definition. |
|
|
130
|
+
| `session/new` | ✅ Supported | Creates a durable Session with stdio, HTTP, or ACP-relayed MCP Tools. |
|
|
131
|
+
| `session/list` | ✅ Supported | Provides cwd filtering and opaque cursor pagination. |
|
|
132
|
+
| `session/delete` | ✅ Supported | Closes connection state and idempotently deletes the Session. |
|
|
133
|
+
| `session/fork` | ✅ Supported | Creates an independent durable Session from a committed conversation boundary. |
|
|
134
|
+
| `session/resume` | ⚠️ Partial | Unattached Session resume, replay-from-start, and MCP work; draft update-ID replay does not. |
|
|
135
|
+
| `session/close` | ✅ Supported | Aborts active work and releases connection-scoped Session resources. |
|
|
136
|
+
| `session/set_config_option` | ✅ Supported | Applies advertised model, thinking-level, and permission selectors and publishes updated option state. |
|
|
137
|
+
| `session/prompt` | ✅ Supported | Acknowledges before execution, reviews Plan proposals, and completes through background state updates. |
|
|
138
|
+
| `session/cancel` | ✅ Supported | Aborts the active Sorbet Run and propagates cancellation to Pi. |
|
|
139
|
+
| `mcp/message` | ✅ Supported | Routes MCP server requests and notifications over active ACP relay connections. |
|
|
140
|
+
| `nes/start` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
141
|
+
| `nes/suggest` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
142
|
+
| `nes/accept` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
143
|
+
| `nes/reject` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
144
|
+
| `nes/close` | ❌ Unsupported | No Next Edit Suggestions engine is connected or advertised. |
|
|
145
|
+
| `document/didOpen` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
146
|
+
| `document/didChange` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
147
|
+
| `document/didClose` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
148
|
+
| `document/didSave` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
149
|
+
| `document/didFocus` | ❌ Unsupported | No editor document-state port is connected or advertised. |
|
|
150
|
+
|
|
151
|
+
## Experimental v2 Client methods
|
|
152
|
+
|
|
153
|
+
| Protocol item | Status | Notes |
|
|
154
|
+
| ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
|
|
155
|
+
| `session/request_permission` | ✅ Supported | Maps v2 Tool and Plan-review outcomes into durable Sorbet decisions. |
|
|
156
|
+
| `session/update` | ✅ Supported | Publishes the supported v2 Session update variants classified below. |
|
|
157
|
+
| `mcp/connect` | ✅ Supported | Opens client-provided MCP servers and binds the returned connection identity. |
|
|
158
|
+
| `mcp/message` | ✅ Supported | Relays MCP requests, responses, and notifications in both directions. |
|
|
159
|
+
| `mcp/disconnect` | ✅ Supported | Disconnects relay transports during Session and connection cleanup. |
|
|
160
|
+
| `elicitation/create` | ✅ Supported | Maps the host-neutral Runtime Elicitation contract to capability-gated Session-scoped forms and URLs. |
|
|
161
|
+
| `elicitation/complete` | ✅ Supported | Completes v2 URL Elicitations through the host-neutral Runtime contract. |
|
|
162
|
+
|
|
163
|
+
## Experimental v2 Session updates
|
|
164
|
+
|
|
165
|
+
| Protocol item | Status | Notes |
|
|
166
|
+
| --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
|
|
167
|
+
| `user_message_chunk` | ✅ Supported | Emitted for accepted prompts and replay before the authoritative user_message upsert. |
|
|
168
|
+
| `user_message` | ✅ Supported | Emitted for accepted prompts and durable conversation replay. |
|
|
169
|
+
| `agent_message_chunk` | ✅ Supported | Streams Pi assistant text with stable message IDs. |
|
|
170
|
+
| `agent_message` | ✅ Supported | Publishes authoritative final assistant message upserts. |
|
|
171
|
+
| `agent_thought_chunk` | ✅ Supported | Streams Pi thinking deltas with stable thought message IDs. |
|
|
172
|
+
| `agent_thought` | ✅ Supported | Publishes authoritative final Pi thinking content for live runs and replay. |
|
|
173
|
+
| `state_update` | ✅ Supported | Publishes running and exactly one terminal idle transition per prompt. |
|
|
174
|
+
| `tool_call_content_chunk` | ✅ Supported | Appends proven Tool content deltas and falls back to replacement updates on rewrites. |
|
|
175
|
+
| `tool_call_update` | ✅ Supported | Publishes Tool input, execution status, progress, and terminal output. |
|
|
176
|
+
| `terminal_update` | ❌ Unsupported | The v2 adapter has no terminal projection. |
|
|
177
|
+
| `terminal_output_chunk` | ❌ Unsupported | The v2 adapter has no terminal projection. |
|
|
178
|
+
| `plan_update` | ✅ Supported | Projects durable item and Markdown Plans for live work and replay. |
|
|
179
|
+
| `plan_removed` | ✅ Supported | Removes the current durable Plan projection. |
|
|
180
|
+
| `available_commands_update` | ❌ Unsupported | Sorbet has no ACP command catalog projection. |
|
|
181
|
+
| `compaction_summary_chunk` | ❌ Unsupported | Sorbet does not yet stream standard ACP v2 compaction summary chunks. |
|
|
182
|
+
| `compaction_update` | ❌ Unsupported | Sorbet has no standard ACP v2 compaction projection yet. |
|
|
183
|
+
| `config_option_update` | ✅ Supported | Emitted after an advertised Session config option changes. |
|
|
184
|
+
| `session_info_update` | ✅ Supported | Publishes durable titles with Lody titleSource provenance, activity timestamps, and MCP startup warnings. |
|
|
185
|
+
| `usage_update` | ✅ Supported | Publishes current context occupancy, model context size, and cumulative Session cost. |
|
|
186
|
+
|
|
187
|
+
## Shared protocol methods
|
|
188
|
+
|
|
189
|
+
| Protocol item | Status | Notes |
|
|
190
|
+
| ------------------ | ------------ | ------------------------------------------------------------------------------- |
|
|
191
|
+
| `$/cancel_request` | ✅ Supported | The SDK transport propagates request cancellation through handler AbortSignals. |
|
|
192
|
+
|
|
193
|
+
## Lody extension capabilities
|
|
194
|
+
|
|
195
|
+
| Protocol item | Status | Notes |
|
|
196
|
+
| ----------------- | -------------- | ---------------------------------------------------------------------------------------- |
|
|
197
|
+
| `sessionTitle` | ✅ Supported | Advertised at version 1; generates and pushes tagged durable titles after each turn. |
|
|
198
|
+
| `usage` | ✅ Supported | Advertised at version 1 with standard and detailed per-model usage updates. |
|
|
199
|
+
| `rateLimits` | ❌ Unsupported | No rate-limit query or update source is connected or advertised. |
|
|
200
|
+
| `forkAtTurn` | ✅ Supported | Publishes durable Run ids as turn boundaries and forks the selected Journal prefix. |
|
|
201
|
+
| `steering` | ✅ Supported | Advertised at version 1 for request-based steering of the active upstream turn. |
|
|
202
|
+
| `tasks` | ❌ Unsupported | No Lody background or scheduled task lifecycle is projected or advertised. |
|
|
203
|
+
| `subagents` | ✅ Supported | Advertises lifecycle plus durable listing, cancellation, and output for Sorbet children. |
|
|
204
|
+
| `goal` | ✅ Supported | Advertised at version 1 with set, pause, resume, and clear actions. |
|
|
205
|
+
| `compaction` | ✅ Supported | Projects durable compaction start and terminal facts through Lody activity metadata. |
|
|
206
|
+
| `sessionHistory` | ✅ Supported | Advertised at version 1 and replays durable conversation and Plan projections. |
|
|
207
|
+
| `worktreeProject` | ❌ Unsupported | No logical project identity is projected beyond the ACP working directory. |
|
|
208
|
+
|
|
209
|
+
## Lody custom methods
|
|
210
|
+
|
|
211
|
+
| Protocol item | Status | Notes |
|
|
212
|
+
| ----------------------------- | -------------- | --------------------------------------------------------------------------------- |
|
|
213
|
+
| `_lody/session/usage_update` | ✅ Supported | Emits cumulative Session and per-model usage after each assistant message. |
|
|
214
|
+
| `_lody/rate_limits/get` | ❌ Unsupported | No Provider rate-limit query source is connected. |
|
|
215
|
+
| `_lody/rate_limits/update` | ❌ Unsupported | No Provider rate-limit update source is connected. |
|
|
216
|
+
| `_lody/session/steer` | ✅ Supported | Injects content into the active Run and returns failed while the Session is idle. |
|
|
217
|
+
| `_lody/session/steer_applied` | ✅ Supported | Acknowledges the exact steer identity after Runtime injection succeeds. |
|
|
218
|
+
| `_lody/session/goal` | ✅ Supported | Controls the durable Goal through set, pause, resume, and clear actions. |
|
|
219
|
+
| `_lody/session/history/read` | ✅ Supported | Replays durable user and assistant conversation through standard Session updates. |
|
|
220
|
+
| `_lody/subagents/list` | ✅ Supported | Lists durable Sorbet child-agent snapshots owned by the attached parent Session. |
|
|
221
|
+
| `_lody/subagents/cancel` | ✅ Supported | Cancels and closes the requested Sorbet child agent. |
|
|
222
|
+
| `_lody/subagents/output` | ✅ Supported | Returns the durable completed child response with optional line tailing. |
|
|
223
|
+
|
|
224
|
+
## Sorbet extensions
|
|
225
|
+
|
|
226
|
+
| Protocol item | Status | Notes |
|
|
227
|
+
| -------------------------- | -------------- | ------------------------------------------------------------------- |
|
|
228
|
+
| `_session/steering` | ✅ Supported | Stable v1 injects steering into an active Run or starts a new turn. |
|
|
229
|
+
| `_sorbet/session/run/get` | ✅ Supported | Stable v1 returns the durable Sorbet Run snapshot. |
|
|
230
|
+
| `_sorbet/session/replay` | ✅ Supported | Stable v1 returns cursor-based Journal fact summaries. |
|
|
231
|
+
| `_sorbet/session/activity` | ❌ Unsupported | The name is reserved, but no activity notification is emitted yet. |
|
package/README.md
CHANGED
|
@@ -1,3 +1,271 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@sorbetai/acp`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
ACP transport and protocol projection for the Sorbet Runtime. (🧪)
|
|
4
|
+
|
|
5
|
+
The package pins `@agentclientprotocol/sdk` and exposes stable ACP v1, the opt-in
|
|
6
|
+
ACP v2 draft, a dual-version stdio router, and versioned Sorbet extension
|
|
7
|
+
methods. Pi continues to own model turns and Tool loops. Sorbet Sessions,
|
|
8
|
+
Journal facts, permissions, durable outcomes, and replay remain the source of
|
|
9
|
+
truth behind the protocol adapter.
|
|
10
|
+
|
|
11
|
+
Tool-call notifications use the command line for `bash` and
|
|
12
|
+
`acp_terminal_create`, readable titles for Sorbet's built-in Tools, the
|
|
13
|
+
registered Tool label for connection-bound Client and MCP Tools, and the Tool
|
|
14
|
+
name only as a forward-compatible fallback. Live updates, permission prompts,
|
|
15
|
+
and replay use the same title selection.
|
|
16
|
+
|
|
17
|
+
Both adapters expose Plan exclusively as a `permission_mode`. In Plan, Node Agent applies a read-only Sandbox and
|
|
18
|
+
Runtime publishes durable checklist/Markdown Plan updates. A submitted proposal
|
|
19
|
+
normally terminates its Planning Run, is write-ahead recorded as pending review,
|
|
20
|
+
and is presented through ACP
|
|
21
|
+
`session/request_permission`, and either remains in Plan for revision or restores
|
|
22
|
+
the prior permission mode and starts a separate implementation Run keyed by the
|
|
23
|
+
review identity. Stable v1 uses the negotiated Plan updates when available and
|
|
24
|
+
falls back to the legacy `plan`/message projection; v2 uses native item and
|
|
25
|
+
Markdown Plan updates.
|
|
26
|
+
|
|
27
|
+
| Area | Entry point | Contract |
|
|
28
|
+
| -------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| Stable adapter | `@sorbetai/acp` | Creates an ACP v1 Agent backed by NodeAgent and the Sorbet Runtime. |
|
|
30
|
+
| Experimental adapter | `@sorbetai/acp/experimental/v2` | Creates the opt-in ACP v2 draft Agent. |
|
|
31
|
+
| Stdio | `@sorbetai/acp/stdio` | Serves v1 or negotiates v1/v2 over NDJSON stdio. |
|
|
32
|
+
| Extensions | `@sorbetai/acp/extensions` | Defines versioned Sorbet method and metadata names. |
|
|
33
|
+
| Generated inventory | [`src/compatibility.gen.ts`](./src/compatibility.gen.ts) | Projects ACP and Lody extension versions, methods, and Session updates from installed packages and schemas. |
|
|
34
|
+
| Support Matrix | `@sorbetai/acp/compatibility` | Adds explicit Sorbet support classifications to every generated protocol item. |
|
|
35
|
+
| Human GAP report | [`COMPATIBILITY.md`](./COMPATIBILITY.md) | Shows supported, partial, and unsupported surfaces with reasons. |
|
|
36
|
+
|
|
37
|
+
Run the packaged agent with `sorbet-acp`. The CLI stores Sorbet data according
|
|
38
|
+
to the Node Agent defaults and negotiates ACP v1 or v2 from the initialize
|
|
39
|
+
request. It uses the first available authenticated model unless the host passes
|
|
40
|
+
an explicit default:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
sorbet-acp --model openai-codex/gpt-5.6-sol
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Both protocol adapters refresh configured Provider catalogs during `initialize`
|
|
47
|
+
and before loading, resuming, or forking a Session. The refresh receives the ACP
|
|
48
|
+
request's cancellation signal and retains cached catalogs on Provider errors.
|
|
49
|
+
Model selection for a new Session also refreshes before binding its capabilities.
|
|
50
|
+
Explicit custom model overrides still take precedence over discovered metadata;
|
|
51
|
+
see [Node Agent Provider metadata](../node-agent/README.md) for cache and override semantics.
|
|
52
|
+
|
|
53
|
+
The agent advertises Lody's `sessionTitle` capability and writes Session titles
|
|
54
|
+
after each turn. Pass `--no-session-title` when the connected Client owns title
|
|
55
|
+
generation so Sorbet stays out of the way.
|
|
56
|
+
|
|
57
|
+
The executable routes Provider requests, including OAuth exchange and token
|
|
58
|
+
refresh, through `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` when configured and
|
|
59
|
+
honors `NO_PROXY`. The CLI adds `localhost`, `127.0.0.1`, and IPv6 loopback to the
|
|
60
|
+
effective exclusions, preserving configured exclusions, so local HTTP MCP
|
|
61
|
+
connections stay direct. This behavior applies to the whole Sorbet process
|
|
62
|
+
rather than one Provider implementation.
|
|
63
|
+
|
|
64
|
+
MCP startup is best effort in both protocol versions. When a server fails to
|
|
65
|
+
connect or list Tools, the adapter closes that connection, skips its Tools, and
|
|
66
|
+
continues with the remaining servers. Creating, loading, resuming, and forking
|
|
67
|
+
a Session publishes one `session_info_update` per failed server with
|
|
68
|
+
`_meta.lody.notice.level: "warning"` and `source: "configWarning"`. The notice
|
|
69
|
+
identifies the server, failing stage, and network error code when available;
|
|
70
|
+
it does not become an assistant message or conversation history. Request
|
|
71
|
+
cancellation still cancels startup.
|
|
72
|
+
|
|
73
|
+
## Packaging
|
|
74
|
+
|
|
75
|
+
Sorbet packages use a unified version. Run `pnpm release:version <version>` from
|
|
76
|
+
the repository root before building a release; see the
|
|
77
|
+
[local release guide](../../docs/operations/releases.md). ACP's CLI and protocol
|
|
78
|
+
identity versions are embedded from this package's manifest during the build.
|
|
79
|
+
|
|
80
|
+
The published package embeds its Sorbet workspace dependencies in both JavaScript
|
|
81
|
+
and type declarations. It also ships the sandbox filesystem worker.
|
|
82
|
+
Installing `@sorbetai/acp` requires no separately published Sorbet packages.
|
|
83
|
+
Third-party dependencies, including Pi and Sandbox Runtime's platform resources,
|
|
84
|
+
are installed by the package manager. Commands use the Host's shell environment;
|
|
85
|
+
install `rg` on its `PATH` when using ripgrep-based commands.
|
|
86
|
+
On Linux, Sandbox Runtime also requires system `rg` when sandboxing is enabled.
|
|
87
|
+
|
|
88
|
+
Build a release tarball from the checkout:
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
pnpm --dir packages/acp pack
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The `prepack` script builds ACP and its workspace dependency graph before packing.
|
|
95
|
+
Only the ACP tarball needs to be published. The stdio integration test extracts
|
|
96
|
+
that tarball, supplies only its third-party runtime dependencies, and exercises
|
|
97
|
+
the packaged CLI, sandboxed filesystem worker, and command execution.
|
|
98
|
+
Use pnpm for packing and publishing so catalog dependency versions are resolved.
|
|
99
|
+
The package requires Node.js 22.19.0 or later.
|
|
100
|
+
|
|
101
|
+
## Lody Setup
|
|
102
|
+
|
|
103
|
+
Lody's provider registry launches Sorbet through the `sorbet-acp` executable.
|
|
104
|
+
Build and link the executable before selecting **Sorbet** in Lody:
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
pnpm --filter @sorbetai/acp... build
|
|
108
|
+
cd packages/acp
|
|
109
|
+
pnpm link --global
|
|
110
|
+
sorbet-acp --version
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The version command must complete without starting the stdio server. Lody uses
|
|
114
|
+
it to verify the local registry entry. During development, a Custom ACP command
|
|
115
|
+
may instead launch `node packages/acp/dist/stdio-cli.js`; production configs
|
|
116
|
+
should use the PATH-resolved executable so they do not depend on a checkout's
|
|
117
|
+
absolute path.
|
|
118
|
+
|
|
119
|
+
Stable v1 advertises one ACP authentication method for each Provider OAuth or
|
|
120
|
+
API-key login supported by Pi. Lody selects a method and relays request-scoped
|
|
121
|
+
URL, device-code, secret, text, or select elicitations. Sorbet persists the
|
|
122
|
+
result in its credential store; credentials are never returned in ACP
|
|
123
|
+
capability data or Lody workspace configuration.
|
|
124
|
+
|
|
125
|
+
Session create, load, resume, and fork responses publish each advertised
|
|
126
|
+
model's model-dependent ACP config options under
|
|
127
|
+
`_meta.lody.modelConfigOptions`, keyed by the same selector used by the ACP
|
|
128
|
+
model config option. Each entry contains the real config id, category, current
|
|
129
|
+
value, and choices that apply to that model. Hosts can therefore switch the
|
|
130
|
+
visible config controls with the model without applying the current Session
|
|
131
|
+
model's options to every model or guessing Agent-specific config ids.
|
|
132
|
+
|
|
133
|
+
The standard `configOptions` and the table entry for the current model come
|
|
134
|
+
from the loaded Session's bound model configuration. Refreshing Provider models
|
|
135
|
+
changes the remaining candidate entries but does not rewrite an attached
|
|
136
|
+
Session. After a close or process restart, Node Agent normalizes an obsolete
|
|
137
|
+
thinking level against the latest model before ACP publishes the resumed state,
|
|
138
|
+
so the standard and model-specific values remain consistent.
|
|
139
|
+
|
|
140
|
+
Repeating the current model, thinking level, or Permission mode succeeds during
|
|
141
|
+
an active prompt without rebuilding the Session or interrupting its Run. Actual
|
|
142
|
+
thinking-level and Permission-mode changes require the prompt to finish.
|
|
143
|
+
|
|
144
|
+
## Connection lifecycle
|
|
145
|
+
|
|
146
|
+
Both protocol versions use one internal [attachment owner](./src/session-attachments.ts).
|
|
147
|
+
Create and fork requests can run concurrently; load, resume, close, delete, and
|
|
148
|
+
configuration changes are ordered per Session within a connection. Different
|
|
149
|
+
Sessions remain independent. Node Agent enforces ownership across connections
|
|
150
|
+
and processes; Journal Store separately protects standalone writers.
|
|
151
|
+
|
|
152
|
+
Disconnect fences new lifecycle requests, cancels attached work, waits for
|
|
153
|
+
admitted opens and configuration changes, and disposes every acquired attachment.
|
|
154
|
+
Connections returned by either Sorbet adapter include this cleanup in `closed`.
|
|
155
|
+
It rejects if resource
|
|
156
|
+
cleanup fails, with ownership retained wherever resources may still be active.
|
|
157
|
+
Call `await connection.dispose()` to close explicitly or retry failed disconnected
|
|
158
|
+
cleanup. `session/close` can likewise be retried while the connection remains open.
|
|
159
|
+
A failed close never reports success merely because the attachment left the
|
|
160
|
+
active lookup. Attachment identity prevents an old connection from closing a
|
|
161
|
+
replacement, including during cleanup retries.
|
|
162
|
+
|
|
163
|
+
Live notification failures remain observable through explicit projection refresh;
|
|
164
|
+
they do not prevent subscription disposal after disconnect. `serveSorbetAcpStdio`
|
|
165
|
+
waits for the selected adapter's cleanup after EOF; the upstream protocol router's
|
|
166
|
+
own `closed` promise only marks transport completion. The stdio CLI also closes
|
|
167
|
+
its owning Node Agent before exiting. Persistent lock files are identities,
|
|
168
|
+
not evidence that a process still holds a lock; do not delete them to force takeover.
|
|
169
|
+
See [Session ownership](../../docs/adr/0058-session-lifecycle-ownership.md) for the
|
|
170
|
+
local-filesystem contract and [lock experiments](../../docs/performance/session-locks.md)
|
|
171
|
+
for measured costs and rejected simplifications.
|
|
172
|
+
|
|
173
|
+
## Context and usage
|
|
174
|
+
|
|
175
|
+
Both protocol versions publish `usage_update.used` as current context occupancy,
|
|
176
|
+
including cached tokens, and `size` as the active Session model's context window.
|
|
177
|
+
They never sum successive requests to calculate occupancy. `cost` is cumulative
|
|
178
|
+
Session cost, including committed compaction responses and metered failed attempts.
|
|
179
|
+
Usage is reconstructed from the Journal and refreshed after compaction, restore,
|
|
180
|
+
and model changes. Before a Provider measurement is available, occupancy is an
|
|
181
|
+
estimate of the reconstructed request; no context update is sent for an empty
|
|
182
|
+
Session without request evidence. Estimates are not clamped to the window size.
|
|
183
|
+
|
|
184
|
+
The v1 detailed Lody notification contains cumulative Session and per-model
|
|
185
|
+
billing totals across Runs. A fork inherits context but starts its own billing
|
|
186
|
+
history. Model window metadata comes from the runtime model configuration;
|
|
187
|
+
custom endpoints with different limits must set `contextWindow` explicitly.
|
|
188
|
+
|
|
189
|
+
## Lody Extensions
|
|
190
|
+
|
|
191
|
+
Stable ACP v1 implements the `acp-extension-core` contracts that Sorbet can
|
|
192
|
+
satisfy end to end. `initialize` advertises usage, request-based steering,
|
|
193
|
+
historical turn forks, Session history, Goal control, compaction activity, and
|
|
194
|
+
child-agent lifecycle/list/cancel/output under `agentCapabilities._meta.lody`.
|
|
195
|
+
Runs emit detailed `_lody/session/usage_update` notifications, active turns
|
|
196
|
+
accept `_lody/session/steer` with matching `_lody/session/steer_applied`
|
|
197
|
+
acknowledgements, and every durable Run boundary is published as a Lody turn id.
|
|
198
|
+
Historical forks use that id to copy the exact Journal prefix rather than the
|
|
199
|
+
latest Session state.
|
|
200
|
+
|
|
201
|
+
Goal snapshots follow durable status and Provider-usage facts. Pausing prevents
|
|
202
|
+
future Goal continuation without cancelling an accepted Run; resuming admits
|
|
203
|
+
one Goal Run when the Session is idle. Retry and compaction lifecycles use Lody
|
|
204
|
+
activity metadata, while Sorbet child snapshots back the subagent methods and
|
|
205
|
+
task metadata. Idle steering returns `failed`; it never starts an implicit
|
|
206
|
+
turn. The generated
|
|
207
|
+
[`COMPATIBILITY.md`](./COMPATIBILITY.md#lody-extension-capabilities) classifies
|
|
208
|
+
every `acp-extension-core` capability and custom method, including contracts
|
|
209
|
+
that Sorbet does not advertise. The earlier `_session/steering` Sorbet
|
|
210
|
+
extension remains available for compatibility.
|
|
211
|
+
|
|
212
|
+
Unimplemented Lody capabilities are omitted rather than advertised. The
|
|
213
|
+
experimental ACP v2 adapter does not currently advertise this extension.
|
|
214
|
+
|
|
215
|
+
## Compatibility
|
|
216
|
+
|
|
217
|
+
Stable v1 is pinned to schema `1.20.0`. Experimental v2 is pinned to
|
|
218
|
+
`2.0.0-alpha.2`. Both currently use TypeScript SDK `1.4.0`.
|
|
219
|
+
|
|
220
|
+
The compatibility chain has three owners:
|
|
221
|
+
|
|
222
|
+
| Artifact | Source | Maintenance rule |
|
|
223
|
+
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
224
|
+
| [`compatibility.gen.ts`](./src/compatibility.gen.ts) | Installed ACP SDK and `acp-extension-core` method constants, package metadata, protocol versions, and ACP JSON Schemas. | Generated; never edit it manually. |
|
|
225
|
+
| [`compatibility.ts`](./src/compatibility.ts) | Sorbet runtime behavior and advertised capabilities. | Manually classify every generated item as supported, partial, or unsupported. |
|
|
226
|
+
| [`COMPATIBILITY.md`](./COMPATIBILITY.md) | Generated inventory plus Sorbet classifications. | Generated; use this as the human-readable GAP report. |
|
|
227
|
+
|
|
228
|
+
Protocol presence never implies Sorbet support. `initialize` advertises only
|
|
229
|
+
operational capabilities, and a method is marked supported only when its
|
|
230
|
+
end-to-end behavior is connected. Client filesystem and terminal capabilities
|
|
231
|
+
become connection-scoped Pi Tools, but Sorbet permission and effect recording
|
|
232
|
+
still apply before their effects are dispatched.
|
|
233
|
+
|
|
234
|
+
MCP Tools are assembled from every page of the server's Tool listing. They carry
|
|
235
|
+
deferred discovery metadata and a namespace named after their
|
|
236
|
+
ACP server. With Node Agent's default configuration, the model uses `tool_search`
|
|
237
|
+
before their parameter schemas become visible on the next request. Hosts can
|
|
238
|
+
override individual Tool metadata or set `toolSearch: false` when constructing
|
|
239
|
+
Node Agent; see [Node Agent Tool discovery](../node-agent/README.md#tool-discovery).
|
|
240
|
+
|
|
241
|
+
### Updating the Matrix
|
|
242
|
+
|
|
243
|
+
After updating the ACP SDK or `acp-extension-core`, or changing an implementation:
|
|
244
|
+
|
|
245
|
+
1. Generate the SDK inventory and GAP report.
|
|
246
|
+
2. Inspect `compatibility.gen.ts`; do not edit it.
|
|
247
|
+
3. Add or update every affected classification in `compatibility.ts`, including
|
|
248
|
+
a concrete explanation of any missing behavior.
|
|
249
|
+
4. Generate again so `COMPATIBILITY.md` reflects the classifications.
|
|
250
|
+
5. Run the focused compatibility check, then the complete ACP package checks.
|
|
251
|
+
|
|
252
|
+
```sh
|
|
253
|
+
pnpm --filter @sorbetai/acp compatibility:write
|
|
254
|
+
pnpm compatibility:acp
|
|
255
|
+
pnpm --filter @sorbetai/acp typecheck
|
|
256
|
+
pnpm --filter @sorbetai/acp test
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
The focused check fails in three distinct cases:
|
|
260
|
+
|
|
261
|
+
| Failure | Meaning | Required action |
|
|
262
|
+
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
263
|
+
| Generated package and schema inventory is stale | The installed ACP SDK or `acp-extension-core` version, capability or method set, protocol version, or Session update discriminator changed. | Run `compatibility:write` and review the generated diff. |
|
|
264
|
+
| A pinned protocol item has no classification | The protocol gained an item that Sorbet has not evaluated. | Implement it or add an explicit partial/unsupported classification with the missing contract. |
|
|
265
|
+
| The human GAP report is stale | Inventory or classifications changed after the last report generation. | Run `compatibility:write` and commit the report diff. |
|
|
266
|
+
|
|
267
|
+
Normal ACP tests include these checks, so CI does not require a separate Matrix
|
|
268
|
+
job. `pnpm compatibility:acp` exists for a faster local review.
|
|
269
|
+
|
|
270
|
+
Sorbet custom methods begin with `_sorbet/`. Custom fields are placed under
|
|
271
|
+
`_meta["sorbet.dev"]` and include an explicit extension version.
|
package/agent.json
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "sorbet",
|
|
3
|
+
"name": "Sorbet",
|
|
4
|
+
"version": "0.1.0",
|
|
5
|
+
"description": "A durable Pi-based Agent Harness with ACP v1 and experimental ACP v2 support.",
|
|
6
|
+
"repository": "https://github.com/lodyspeak/sorbet",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"distribution": {
|
|
9
|
+
"local": {
|
|
10
|
+
"command": "sorbet-acp",
|
|
11
|
+
"args": [],
|
|
12
|
+
"versionArgs": ["--version"]
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
}
|
package/dist/LICENSE.pi
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Mario Zechner
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|