@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.
Files changed (80) hide show
  1. package/COMPATIBILITY.md +235 -0
  2. package/MCP_HOST.md +247 -0
  3. package/README.md +514 -2
  4. package/agent.json +15 -0
  5. package/dist/LICENSE.pi +21 -0
  6. package/dist/LICENSE.worker.acorn +21 -0
  7. package/dist/LICENSE.worker.acorn-walk +21 -0
  8. package/dist/LICENSE.worker.effect +21 -0
  9. package/dist/LICENSE.worker.ensure-error +9 -0
  10. package/dist/LICENSE.worker.es-toolkit +21 -0
  11. package/dist/LICENSE.worker.typebox +23 -0
  12. package/dist/agent-B7tO52_4.d.ts +50 -0
  13. package/dist/agent-DY9tWj9z.js +1718 -0
  14. package/dist/agent-DY9tWj9z.js.map +1 -0
  15. package/dist/authentication-pNA443FX.js +132 -0
  16. package/dist/authentication-pNA443FX.js.map +1 -0
  17. package/dist/compatibility-1QpPxK_p.js +744 -0
  18. package/dist/compatibility-1QpPxK_p.js.map +1 -0
  19. package/dist/compatibility-BD_TbVPM.d.ts +622 -0
  20. package/dist/compatibility.d.ts +2 -0
  21. package/dist/compatibility.js +3 -0
  22. package/dist/environment-D9j7BLR7.js +945 -0
  23. package/dist/environment-D9j7BLR7.js.map +1 -0
  24. package/dist/esm-BtdR1t_L.js +1762 -0
  25. package/dist/esm-BtdR1t_L.js.map +1 -0
  26. package/dist/execAsync-B4-X9Hoy.js +14 -0
  27. package/dist/execAsync-B4-X9Hoy.js.map +1 -0
  28. package/dist/experimental-v2-BCAb8mKD.js +1551 -0
  29. package/dist/experimental-v2-BCAb8mKD.js.map +1 -0
  30. package/dist/experimental-v2-BkVh4DI5.d.ts +71 -0
  31. package/dist/experimental-v2.d.ts +4 -0
  32. package/dist/experimental-v2.js +8 -0
  33. package/dist/extensions-Da4-kIik.js +14 -0
  34. package/dist/extensions-Da4-kIik.js.map +1 -0
  35. package/dist/extensions.d.ts +33 -0
  36. package/dist/extensions.js +3 -0
  37. package/dist/filesystem-worker.js +11706 -0
  38. package/dist/filesystem-worker.js.map +1 -0
  39. package/dist/getMachineId-bsd-IHzOcFWI.js +30 -0
  40. package/dist/getMachineId-bsd-IHzOcFWI.js.map +1 -0
  41. package/dist/getMachineId-darwin-BecBWon1.js +27 -0
  42. package/dist/getMachineId-darwin-BecBWon1.js.map +1 -0
  43. package/dist/getMachineId-linux-Ce7oJ7Ie.js +23 -0
  44. package/dist/getMachineId-linux-Ce7oJ7Ie.js.map +1 -0
  45. package/dist/getMachineId-unsupported-BkvLks-h.js +18 -0
  46. package/dist/getMachineId-unsupported-BkvLks-h.js.map +1 -0
  47. package/dist/getMachineId-win-DjQUtLb-.js +29 -0
  48. package/dist/getMachineId-win-DjQUtLb-.js.map +1 -0
  49. package/dist/index-fSbkxdkc.d.ts +1932 -0
  50. package/dist/index-zP3wkYvN.d.ts +9329 -0
  51. package/dist/index.d.ts +10 -0
  52. package/dist/index.js +10 -0
  53. package/dist/isolate-worker.mjs +150612 -0
  54. package/dist/managed-worker.js +116 -0
  55. package/dist/managed-worker.js.map +1 -0
  56. package/dist/mcp-host-profile-DHnfdZNU.js +9331 -0
  57. package/dist/mcp-host-profile-DHnfdZNU.js.map +1 -0
  58. package/dist/mcp-host.d.ts +322 -0
  59. package/dist/mcp-host.js +388 -0
  60. package/dist/mcp-host.js.map +1 -0
  61. package/dist/metrics-BUyfNRF_-BmvM6Q32.js +694 -0
  62. package/dist/metrics-BUyfNRF_-BmvM6Q32.js.map +1 -0
  63. package/dist/otlp-BHSWLZNu.js +16144 -0
  64. package/dist/otlp-BHSWLZNu.js.map +1 -0
  65. package/dist/process-worker.js +47 -0
  66. package/dist/process-worker.js.map +1 -0
  67. package/dist/prompt-work-CiuX5Z_7.js +33337 -0
  68. package/dist/prompt-work-CiuX5Z_7.js.map +1 -0
  69. package/dist/stdio-SpFgt4YA.js +38 -0
  70. package/dist/stdio-SpFgt4YA.js.map +1 -0
  71. package/dist/stdio-cli-main-DBUMMwJi.js +7217 -0
  72. package/dist/stdio-cli-main-DBUMMwJi.js.map +1 -0
  73. package/dist/stdio-cli.d.ts +1 -0
  74. package/dist/stdio-cli.js +10 -0
  75. package/dist/stdio-cli.js.map +1 -0
  76. package/dist/stdio.d.ts +21 -0
  77. package/dist/stdio.js +10 -0
  78. package/dist/supervised-command-bugWwh_y-CN8RpnOM.js +123 -0
  79. package/dist/supervised-command-bugWwh_y-CN8RpnOM.js.map +1 -0
  80. package/package.json +111 -3
@@ -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.