@sorbetai/acp 0.0.0-stage → 0.1.0-alpha.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 +235 -0
- package/MCP_HOST.md +247 -0
- package/README.md +514 -2
- package/agent.json +15 -0
- package/dist/LICENSE.pi +21 -0
- package/dist/LICENSE.worker.acorn +21 -0
- package/dist/LICENSE.worker.acorn-walk +21 -0
- package/dist/LICENSE.worker.effect +21 -0
- package/dist/LICENSE.worker.ensure-error +9 -0
- package/dist/LICENSE.worker.es-toolkit +21 -0
- package/dist/LICENSE.worker.typebox +23 -0
- package/dist/agent-B7tO52_4.d.ts +50 -0
- package/dist/agent-DY9tWj9z.js +1718 -0
- package/dist/agent-DY9tWj9z.js.map +1 -0
- package/dist/authentication-pNA443FX.js +132 -0
- package/dist/authentication-pNA443FX.js.map +1 -0
- package/dist/compatibility-1QpPxK_p.js +744 -0
- package/dist/compatibility-1QpPxK_p.js.map +1 -0
- package/dist/compatibility-BD_TbVPM.d.ts +622 -0
- package/dist/compatibility.d.ts +2 -0
- package/dist/compatibility.js +3 -0
- package/dist/environment-D9j7BLR7.js +945 -0
- package/dist/environment-D9j7BLR7.js.map +1 -0
- package/dist/esm-BtdR1t_L.js +1762 -0
- package/dist/esm-BtdR1t_L.js.map +1 -0
- package/dist/execAsync-B4-X9Hoy.js +14 -0
- package/dist/execAsync-B4-X9Hoy.js.map +1 -0
- package/dist/experimental-v2-BCAb8mKD.js +1551 -0
- package/dist/experimental-v2-BCAb8mKD.js.map +1 -0
- package/dist/experimental-v2-BkVh4DI5.d.ts +71 -0
- package/dist/experimental-v2.d.ts +4 -0
- package/dist/experimental-v2.js +8 -0
- package/dist/extensions-Da4-kIik.js +14 -0
- package/dist/extensions-Da4-kIik.js.map +1 -0
- package/dist/extensions.d.ts +33 -0
- package/dist/extensions.js +3 -0
- package/dist/filesystem-worker.js +11706 -0
- package/dist/filesystem-worker.js.map +1 -0
- package/dist/getMachineId-bsd-IHzOcFWI.js +30 -0
- package/dist/getMachineId-bsd-IHzOcFWI.js.map +1 -0
- package/dist/getMachineId-darwin-BecBWon1.js +27 -0
- package/dist/getMachineId-darwin-BecBWon1.js.map +1 -0
- package/dist/getMachineId-linux-Ce7oJ7Ie.js +23 -0
- package/dist/getMachineId-linux-Ce7oJ7Ie.js.map +1 -0
- package/dist/getMachineId-unsupported-BkvLks-h.js +18 -0
- package/dist/getMachineId-unsupported-BkvLks-h.js.map +1 -0
- package/dist/getMachineId-win-DjQUtLb-.js +29 -0
- package/dist/getMachineId-win-DjQUtLb-.js.map +1 -0
- package/dist/index-fSbkxdkc.d.ts +1932 -0
- package/dist/index-zP3wkYvN.d.ts +9329 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +10 -0
- package/dist/isolate-worker.mjs +150612 -0
- package/dist/managed-worker.js +116 -0
- package/dist/managed-worker.js.map +1 -0
- package/dist/mcp-host-profile-DHnfdZNU.js +9331 -0
- package/dist/mcp-host-profile-DHnfdZNU.js.map +1 -0
- package/dist/mcp-host.d.ts +322 -0
- package/dist/mcp-host.js +388 -0
- package/dist/mcp-host.js.map +1 -0
- package/dist/metrics-BUyfNRF_-BmvM6Q32.js +694 -0
- package/dist/metrics-BUyfNRF_-BmvM6Q32.js.map +1 -0
- package/dist/otlp-BHSWLZNu.js +16144 -0
- package/dist/otlp-BHSWLZNu.js.map +1 -0
- package/dist/process-worker.js +47 -0
- package/dist/process-worker.js.map +1 -0
- package/dist/prompt-work-CiuX5Z_7.js +33337 -0
- package/dist/prompt-work-CiuX5Z_7.js.map +1 -0
- package/dist/stdio-SpFgt4YA.js +38 -0
- package/dist/stdio-SpFgt4YA.js.map +1 -0
- package/dist/stdio-cli-main-DBUMMwJi.js +7217 -0
- package/dist/stdio-cli-main-DBUMMwJi.js.map +1 -0
- package/dist/stdio-cli.d.ts +1 -0
- package/dist/stdio-cli.js +10 -0
- package/dist/stdio-cli.js.map +1 -0
- package/dist/stdio.d.ts +21 -0
- package/dist/stdio.js +10 -0
- package/dist/supervised-command-bugWwh_y-CN8RpnOM.js +123 -0
- package/dist/supervised-command-bugWwh_y-CN8RpnOM.js.map +1 -0
- package/package.json +111 -3
package/COMPATIBILITY.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
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 | 7 | 0 | 1 | 8 |
|
|
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, abandons interrupted execution without retrying effects, pauses its Goal, and replays durable conversation and Plan projections. |
|
|
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 | Pauses the active Goal and cancels and drains current work, including automatic Runs without an ACP prompt owner. |
|
|
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 | Advertises pause/clear requests and active-owner resume; prompt metadata starts or owns Goal work when idle. Goal prompts stay open across automatic continuations. |
|
|
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/plugins/query` | ✅ Supported | Negotiated v1/v2 transport reads the attached Session’s Host-bound, filtered composition facade. |
|
|
232
|
+
| `_sorbet/plugins/apply` | ✅ Supported | Submits patches to the Host-bound facade; the transport cannot supply authorization. Desired concurrency and durable command identity apply. |
|
|
233
|
+
| `_sorbet/plugins/watch` | ✅ Supported | Starts or stops one coalesced snapshot subscription per attached Session; cleanup follows the connection. |
|
|
234
|
+
| `_sorbet/plugins/changed` | ✅ Supported | Publishes initial and changed composition snapshots, including Service-driven Mount changes without a Desired edit. |
|
|
235
|
+
| `_sorbet/session/activity` | ❌ Unsupported | The name is reserved, but no activity notification is emitted yet. |
|
package/MCP_HOST.md
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# MCP consumption from SDK and ACP Hosts
|
|
2
|
+
|
|
3
|
+
Sorbet is headless. An SDK embedding or ACP Client owns presentation, credentials,
|
|
4
|
+
model access and deployment policy. The Agent owns its MCP connections and Sorbet
|
|
5
|
+
Runtime owns operation admission, permission decisions, write-ahead Effects and
|
|
6
|
+
terminal outcomes. Rendering an App or answering an elicitation requires no
|
|
7
|
+
Sorbet Web/TUI application.
|
|
8
|
+
|
|
9
|
+
| Capability | Direct SDK | ACP Client |
|
|
10
|
+
| -------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| Form / URL elicitation | `McpSessionOptions.host.elicitation` | Standard negotiated `elicitation/create` and `elicitation/complete`, v1/v2 |
|
|
12
|
+
| Native discovery, reads, prompts, completion | Public MCP Session methods | Negotiated Host profile below; admitted resource/control operations |
|
|
13
|
+
| Apps | Public `McpAppSession`, view Host and admitted actions | Same client-side Apps SDK, using the remote read/action binding |
|
|
14
|
+
| Roots / sampling | Scoped MCP Host callbacks | Optional profile requests to client-owned policy/model handlers |
|
|
15
|
+
| Media projection | `modelContent.processMedia` | Optional profile request to client-owned media processor |
|
|
16
|
+
| External Tasks | Public Task service, checkpoints and creation hook | Explicit admitted tool start, acknowledged reference handoff and scoped control |
|
|
17
|
+
| Skills / experimental Events | Explicit Host services and stores | Optional client consent/publication/withdrawal and acknowledged event routing; durable Events services/stores remain deployment-owned |
|
|
18
|
+
| MCP OAuth | Connection-owner credential store, browser and callback | Client-owned v2 relay keeps credentials local; Agent-owned direct HTTP uses Agent deployment credentials |
|
|
19
|
+
|
|
20
|
+
The profile is a versioned Sorbet ACP integration, not an official MCP extension.
|
|
21
|
+
Ordinary ACP Clients retain standard Tool and elicitation behavior without it.
|
|
22
|
+
|
|
23
|
+
## Standard elicitation
|
|
24
|
+
|
|
25
|
+
Advertise only the ACP form/URL modes the Client can actually present and register
|
|
26
|
+
the standard ACP elicitation handlers. Both Agent factories bind MCP requests to
|
|
27
|
+
those handlers unless the deployment supplied an explicit SDK override. Responses
|
|
28
|
+
are validated against the original requested schema. Accepting a URL prompt is
|
|
29
|
+
not proof that authorization or another external operation succeeded.
|
|
30
|
+
|
|
31
|
+
Before the Session-open response publishes its identity, interactions use the
|
|
32
|
+
actual enclosing ACP request scope. Later requests use the attached Session scope.
|
|
33
|
+
Origin metadata identifies the server, Session, connection and request/task; native
|
|
34
|
+
server `_meta` is not copied into standard ACP UI metadata. Legacy URL completion
|
|
35
|
+
IDs are namespaced per connection, including identical IDs from different servers.
|
|
36
|
+
|
|
37
|
+
ACP's standard form codec cannot retain every MCP schema field. Lossless standard
|
|
38
|
+
schemas use standard form mode. For the remaining protocol-defined flat primitive
|
|
39
|
+
forms, Clients may additionally offer and verify acknowledgment of
|
|
40
|
+
`_meta['sorbet.dev'].mcpElicitation = { version: 1, jsonSchema: true }`; these requests
|
|
41
|
+
use the custom `_mcp_form` mode with the complete original schema. Without that
|
|
42
|
+
agreement, an unrepresentable form fails explicitly. This is not support for
|
|
43
|
+
arbitrary nested JSON forms.
|
|
44
|
+
|
|
45
|
+
## Remote Host negotiation
|
|
46
|
+
|
|
47
|
+
The embedding must enable `mcpHost: true` on `createSorbetAcpAgent` or
|
|
48
|
+
`createSorbetAcpV2Agent`. The Client offers this initialize capability metadata:
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
const offer = {
|
|
52
|
+
'sorbet.dev': {
|
|
53
|
+
mcpHost: {
|
|
54
|
+
version: 1,
|
|
55
|
+
apps: true,
|
|
56
|
+
roots: { listChanged: true },
|
|
57
|
+
sampling: { tools: true, context: false },
|
|
58
|
+
media: true,
|
|
59
|
+
taskNotifications: true,
|
|
60
|
+
skills: true,
|
|
61
|
+
events: { profile: MCP_EVENTS_PROFILE },
|
|
62
|
+
},
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Each optional field requires a real installed Client handler. Supply `offer` as
|
|
68
|
+
v1 `clientCapabilities._meta` or v2 `capabilities._meta`. Verify the Agent's
|
|
69
|
+
acknowledgment before using the helper. The acknowledgment includes `version: 1`,
|
|
70
|
+
`read: true`, `call: true` and `control: 'installed-services'`. No acknowledgment
|
|
71
|
+
means access is unavailable, even if the Client sends a custom method anyway.
|
|
72
|
+
The stock CLI does not opt into remote Host control; an embedding must authorize it.
|
|
73
|
+
Import `MCP_EVENTS_PROFILE` from `@sorbetai/mcp`; its pinned experimental version is
|
|
74
|
+
independent of stable MCP support.
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { createAcpMcpHostClient } from '@sorbetai/acp/mcp-host';
|
|
78
|
+
|
|
79
|
+
const host = createAcpMcpHostClient({
|
|
80
|
+
peer: client.agent,
|
|
81
|
+
acknowledgment: initializeResult.capabilities._meta, // v2
|
|
82
|
+
});
|
|
83
|
+
const inventory = await host.query(sessionId);
|
|
84
|
+
const selected = inventory.servers.find((server) => server.name === approvedServer);
|
|
85
|
+
if (!selected) throw new Error('Approved MCP server is unavailable');
|
|
86
|
+
const binding = host.bind(selected.address);
|
|
87
|
+
const result = await binding.callTool({ name: 'approved_tool', arguments: {} });
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`query` returns live Agent-owned connections, negotiated protocol/server/client
|
|
91
|
+
capabilities and installed service flags. A service flag describes an installed
|
|
92
|
+
adapter, not a promise that every remote server supports every operation. Bindings
|
|
93
|
+
capture `{ sessionId, serverId, connectionId }`; they cannot choose another ACP
|
|
94
|
+
connection's attachment or follow a same-name replacement. Close a binding when
|
|
95
|
+
its consumer ends, and close the helper during ACP teardown.
|
|
96
|
+
Explicit server trust identities must be unique within a composition. Reusing a
|
|
97
|
+
`serverId` for two attached servers is rejected before opening the second connection.
|
|
98
|
+
|
|
99
|
+
The helper's `appClient` implements the four official SDK read method signatures
|
|
100
|
+
accepted by `McpAppSession`; its `appActions` sends admitted native tool actions.
|
|
101
|
+
See [Apps composition](../mcp/APPS.md#external-acp-host). Native resource and tool
|
|
102
|
+
results retain content, structured values, annotations and private metadata for
|
|
103
|
+
the authorized Host. `tools/list` returns the complete captured inventory rather
|
|
104
|
+
than replaying original MCP discovery pages. Remote read options currently accept
|
|
105
|
+
only `signal`; unsupported SDK request policies fail explicitly.
|
|
106
|
+
|
|
107
|
+
Register `_sorbet/mcp/progress` notifications with `host.handleProgress` to receive
|
|
108
|
+
App tool progress. Routing checks the generated request token and exact binding
|
|
109
|
+
address. Late or foreign updates cannot target a new view. `binding.close()` aborts
|
|
110
|
+
its pending requests and revokes local callbacks; closing does not undo remote
|
|
111
|
+
effects.
|
|
112
|
+
|
|
113
|
+
## Reverse requests and external services
|
|
114
|
+
|
|
115
|
+
Register `_sorbet/mcp/host/request` before opening Sessions when offering roots,
|
|
116
|
+
sampling or media. Its `kind` is `roots`, `sampling` or `media`; `address` identifies
|
|
117
|
+
the actual attached Session and MCP connection. Roots returns a native
|
|
118
|
+
`ListRootsResult`; sampling receives original native parameters and returns a
|
|
119
|
+
native `CreateMessageResultWithTools`; media receives original content and returns
|
|
120
|
+
model-compatible text/image blocks. Apply client-side consent, filesystem scope,
|
|
121
|
+
model permissions and cancellation. A sampling callback must not accidentally
|
|
122
|
+
reuse another Session's model context or credentials. Explicit SDK Host overrides
|
|
123
|
+
remain deployment-owned. `binding.rootsChanged()` sends the negotiated notification
|
|
124
|
+
to the captured connection for legacy protocol versions. Modern MCP has removed
|
|
125
|
+
that notification and its `listChanged` capability; the legacy-only operation
|
|
126
|
+
rejects explicitly on a modern connection. Reverse roots/sampling requests also
|
|
127
|
+
retain native request metadata and request/task identity in `context`; an optional
|
|
128
|
+
top-level `requestId` correlates bootstrap interactions to the actual ACP request.
|
|
129
|
+
This authorized Host profile is distinct from standard elicitation's metadata
|
|
130
|
+
privacy policy.
|
|
131
|
+
|
|
132
|
+
`binding.control(request)` accepts only the exported finite `McpHostRequest` union:
|
|
133
|
+
native resource/prompt/completion operations, external Task controls and installed
|
|
134
|
+
Skills/Events services. It is not an arbitrary MCP JSON-RPC proxy. Each dispatched
|
|
135
|
+
control runs as a normal Sorbet Tool operation. Experimental Events additionally
|
|
136
|
+
requires the pinned `MCP_EVENTS_PROFILE` on each request. Its checkpoint, durable
|
|
137
|
+
delivery and event-route policy remain explicit Agent-side dependencies. Receipt
|
|
138
|
+
of an Event never automatically starts model work.
|
|
139
|
+
|
|
140
|
+
An admitted operation that fails, is denied or is cancelled returns ACP error
|
|
141
|
+
`-32011` with `{ version: 1, operationId, status }`. Its Journal outcome remains
|
|
142
|
+
authoritative. Arbitrary remote error messages are not copied onto this wire
|
|
143
|
+
error; full native Tool `isError` results retain their normal result envelope.
|
|
144
|
+
A Host progress/UI delivery error may reject local consumption after the remote
|
|
145
|
+
operation succeeded; it does not rewrite that successful Effect or permit replay.
|
|
146
|
+
|
|
147
|
+
With `skills: true`, handle `skill-approve` with `{ approved: boolean }`, and
|
|
148
|
+
`skill-publish` / `skill-retract` with `{ accepted: true }` on the same reverse
|
|
149
|
+
request method. Keep origin, activation identity and `untrusted-mcp` tags when
|
|
150
|
+
storing published context. Consent grants neither code execution nor Tool
|
|
151
|
+
permissions. A deployment's existing consent and context Host remain in force.
|
|
152
|
+
Optional remote Skills do not remove ordinary servers that lack Skills support.
|
|
153
|
+
Lease release and connection cleanup await withdrawal; disconnected cleanup uses
|
|
154
|
+
a finite five-second attempt and reports failure. Previous model requests cannot
|
|
155
|
+
be retracted, and process crashes cannot guarantee UI/context withdrawal.
|
|
156
|
+
|
|
157
|
+
`createAcpMcpSkillsView` and `acpMcpSkillsRequestSchema` from the same public
|
|
158
|
+
`mcp-host` entry provide a reference current-content consumer. Register the schema
|
|
159
|
+
on the Host request method and delegate to `view.handle(params, signal)`; connect
|
|
160
|
+
`view.subscribe` or `view.snapshot` to the Client UI/context store. Its explicit
|
|
161
|
+
approval callback receives the original scoped manifest. Keep one view for the
|
|
162
|
+
connection lifetime: per-activation tombstones reject delayed publication after
|
|
163
|
+
withdrawal, even if an earlier handler ignored cancellation. `close()` revokes
|
|
164
|
+
the view. The default limit is 4,096 activations, then new activations fail closed;
|
|
165
|
+
this bounded live projection is not durable historical provenance or execution consent.
|
|
166
|
+
|
|
167
|
+
With a pinned `events` offer and an installed Agent Events service, handle `event`
|
|
168
|
+
and `event-control` with `{ accepted: true }`. Remote acceptance precedes local
|
|
169
|
+
routing and checkpointing. A crash between acceptance and checkpoint may repeat
|
|
170
|
+
delivery: persist scoped event IDs and apply the Host's own idempotency policy.
|
|
171
|
+
The Agent's store, reconnect and webhook policy are retained. A Client offer alone
|
|
172
|
+
does not install an Events service or authorize automatic model work.
|
|
173
|
+
For explicit reopen after reconnect, supply a stable `params.subscriptionId` to
|
|
174
|
+
`events/subscribe`; the returned local handle is still fresh and cannot select
|
|
175
|
+
the old connection. Reopening the same Session/server/logical subscription uses
|
|
176
|
+
the installed Host checkpoint store. Omitting the stable ID creates a new logical
|
|
177
|
+
subscription. Persisting a cursor alone does not guarantee replay support from the
|
|
178
|
+
server or exactly-once routing.
|
|
179
|
+
|
|
180
|
+
## External Task handoff and recovery
|
|
181
|
+
|
|
182
|
+
Offer `taskNotifications: true` only after registering
|
|
183
|
+
`_sorbet/mcp/task/created`. Persist the scoped `event.reference` and originating
|
|
184
|
+
operation identity before returning `{ accepted: true }`. The Agent awaits this
|
|
185
|
+
acknowledgment before an explicit `binding.startTask(params)` detaches its local
|
|
186
|
+
driver and returns the reference envelope. Starting uses the original MCP Tool's
|
|
187
|
+
schema, permission and Effect path; it is not a hidden control that can bypass
|
|
188
|
+
that Tool's policy. The Sorbet operation then terminates, while the external Task
|
|
189
|
+
continues independently of any Sorbet Run.
|
|
190
|
+
|
|
191
|
+
Use explicit start for a Host-selected tool known to return Tasks. A server may
|
|
192
|
+
execute a tool and return an immediate result even when a Task was requested; the
|
|
193
|
+
start API then fails without a reference. That failure does not prove the external
|
|
194
|
+
effect was absent and must not trigger automatic retry. Ordinary `callTool` accepts
|
|
195
|
+
both normal and Task-backed tool results. Both public methods support progress.
|
|
196
|
+
|
|
197
|
+
Use `tasks/snapshot`, `tasks/input`, `tasks/result` and explicit `tasks/cancel` via
|
|
198
|
+
`control`. `tasks/resume` binds a persisted reference to a new local continuation;
|
|
199
|
+
`tasks/release` detaches it without cancelling remote work. Handles are local to
|
|
200
|
+
one connection. Raw Task IDs must first have been observed at creation, listed by
|
|
201
|
+
the remote server or explicitly imported through a scoped recovery reference.
|
|
202
|
+
A reference describes scope; it is not an unforgeable capability token. Modern known-handle inventory is identified as such, rather than
|
|
203
|
+
pretending it is a complete remote task listing. Default ACP task endpoint identity
|
|
204
|
+
includes the Session; a deployment overriding it must include its stable principal
|
|
205
|
+
and authorization partition. A reconnect requires a fresh connection binding and
|
|
206
|
+
an explicitly validated reference, not reuse of an old local handle.
|
|
207
|
+
|
|
208
|
+
Remote creation may succeed before its reply or Host acknowledgment is durable.
|
|
209
|
+
Neither checkpointing nor ACK closes that crash gap. A failed handoff is not
|
|
210
|
+
permission to replay the original Tool. Persist observed references and reconcile
|
|
211
|
+
through explicit controls; uncertain external effects remain uncertain. Cancel,
|
|
212
|
+
disconnect, cleanup and OAuth retries do not establish rollback or exactly-once
|
|
213
|
+
execution. UI and service stores are not transported or silently reconstructed.
|
|
214
|
+
|
|
215
|
+
## Credential ownership
|
|
216
|
+
|
|
217
|
+
For the v2 relay, `AcpV2McpRelayHost.open` resolves an approved server ID to the
|
|
218
|
+
Client's local credential store, browser flow and network/process policy. Complete
|
|
219
|
+
authorization before opening the protected Transport; preserve the store and
|
|
220
|
+
recreate its public provider as needed after callback. Browser acceptance is not
|
|
221
|
+
OAuth success: the authorization provider validates callback state, issuer and
|
|
222
|
+
PKCE before storing credentials. Tokens, authorization codes and PKCE verifier
|
|
223
|
+
must not enter ACP, Journal, model context or session configuration.
|
|
224
|
+
|
|
225
|
+
Agent-owned HTTP connections use the embedding's local `mcp.prepareServer`
|
|
226
|
+
credentials. Standard ACP authentication authenticates the Agent; it does not
|
|
227
|
+
delegate arbitrary per-MCP-server OAuth credentials. See
|
|
228
|
+
[MCP authorization](../mcp/AUTHORIZATION.md) and [relay ownership](./README.md#acp-v2-relay-host).
|
|
229
|
+
|
|
230
|
+
## Behavioral evidence
|
|
231
|
+
|
|
232
|
+
- [Pure ACP elicitation](./tests/mcp-elicitation-client.test.ts): v1/v2 wire-only
|
|
233
|
+
consumers, form/URL, schema negotiation, bootstrap identity, completion and cancel.
|
|
234
|
+
- [External Apps](./tests/mcp-apps-host.test.ts): official App and real MCP HTTP
|
|
235
|
+
Server, permission denial, write-ahead Effects, cancellation and stale generations.
|
|
236
|
+
- [Remote Host controls](./tests/mcp-host-control.test.ts): both ACP versions,
|
|
237
|
+
roots/sampling/media, native reads and cross-Session/connection isolation.
|
|
238
|
+
- [External Tasks](./tests/mcp-host-tasks.test.ts): admitted startup, reference ACK,
|
|
239
|
+
input/result/cancel, reconnection and failure reconciliation without replay.
|
|
240
|
+
- [Remote Skills/Events](./tests/mcp-host-services.test.ts): client consent and
|
|
241
|
+
acknowledged publication/withdrawal, event ACK ordering and scoped cleanup.
|
|
242
|
+
- [Client-owned OAuth](./tests/mcp-authorization-host.test.ts): real discovery,
|
|
243
|
+
PKCE callback, refresh and reattachment, with wire-level secret checks.
|
|
244
|
+
|
|
245
|
+
Run `pnpm --filter @sorbetai/acp test` after building MCP dependencies. Generated
|
|
246
|
+
compatibility records describe verified native features and Sorbet integrations
|
|
247
|
+
separately; their rows are not counts of independent product features.
|