@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.
Files changed (38) hide show
  1. package/COMPATIBILITY.md +231 -0
  2. package/README.md +270 -2
  3. package/agent.json +15 -0
  4. package/dist/LICENSE.pi +21 -0
  5. package/dist/agent-B7PnGaB0.js +1600 -0
  6. package/dist/agent-B7PnGaB0.js.map +1 -0
  7. package/dist/agent-DfScvNX2.d.ts +43 -0
  8. package/dist/authentication-CraYYCai.js +132 -0
  9. package/dist/authentication-CraYYCai.js.map +1 -0
  10. package/dist/compatibility-B1ZA8Wvn.d.ts +606 -0
  11. package/dist/compatibility-Cmomxq8E.js +728 -0
  12. package/dist/compatibility-Cmomxq8E.js.map +1 -0
  13. package/dist/compatibility.d.ts +2 -0
  14. package/dist/compatibility.js +3 -0
  15. package/dist/experimental-v2-CB_5NMax.d.ts +35 -0
  16. package/dist/experimental-v2-DH1LLn_I.js +1088 -0
  17. package/dist/experimental-v2-DH1LLn_I.js.map +1 -0
  18. package/dist/experimental-v2.d.ts +3 -0
  19. package/dist/experimental-v2.js +4 -0
  20. package/dist/extensions-czICN7yK.js +10 -0
  21. package/dist/extensions-czICN7yK.js.map +1 -0
  22. package/dist/extensions.d.ts +29 -0
  23. package/dist/extensions.js +3 -0
  24. package/dist/filesystem-worker.js +10445 -0
  25. package/dist/filesystem-worker.js.map +1 -0
  26. package/dist/index-BzGG36Gz.d.ts +8248 -0
  27. package/dist/index.d.ts +9 -0
  28. package/dist/index.js +7 -0
  29. package/dist/session-attachments-DXvfzXfV.js +23124 -0
  30. package/dist/session-attachments-DXvfzXfV.js.map +1 -0
  31. package/dist/stdio-Bwi2cEOV.js +38 -0
  32. package/dist/stdio-Bwi2cEOV.js.map +1 -0
  33. package/dist/stdio-cli.d.ts +1 -0
  34. package/dist/stdio-cli.js +91 -0
  35. package/dist/stdio-cli.js.map +1 -0
  36. package/dist/stdio.d.ts +20 -0
  37. package/dist/stdio.js +7 -0
  38. package/package.json +85 -3
@@ -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
- # Temporary Holding Version
1
+ # `@sorbetai/acp`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ }
@@ -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.