@agen-ai/provider-acp 0.0.0-stage → 0.4.1

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 (121) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +823 -2
  3. package/dist/auth/controller.d.ts +23 -0
  4. package/dist/auth/controller.js +170 -0
  5. package/dist/auth/methods.d.ts +12 -0
  6. package/dist/auth/methods.js +51 -0
  7. package/dist/capabilities.d.ts +6 -0
  8. package/dist/capabilities.js +47 -0
  9. package/dist/configuration/catalog.d.ts +35 -0
  10. package/dist/configuration/catalog.js +220 -0
  11. package/dist/configuration/control.d.ts +19 -0
  12. package/dist/configuration/control.js +109 -0
  13. package/dist/configuration/errors.d.ts +6 -0
  14. package/dist/configuration/errors.js +14 -0
  15. package/dist/configuration.d.ts +3 -0
  16. package/dist/configuration.js +9 -0
  17. package/dist/connection/acquire.d.ts +6 -0
  18. package/dist/connection/acquire.js +30 -0
  19. package/dist/connection/contracts.d.ts +49 -0
  20. package/dist/connection/contracts.js +0 -0
  21. package/dist/connection/errors.d.ts +5 -0
  22. package/dist/connection/errors.js +10 -0
  23. package/dist/connection/initialize.d.ts +20 -0
  24. package/dist/connection/initialize.js +254 -0
  25. package/dist/connection/negotiation.d.ts +7 -0
  26. package/dist/connection/negotiation.js +57 -0
  27. package/dist/contracts.d.ts +65 -0
  28. package/dist/contracts.js +0 -0
  29. package/dist/driver.d.ts +4 -0
  30. package/dist/driver.js +11 -0
  31. package/dist/driverFactory.d.ts +8 -0
  32. package/dist/driverFactory.js +48 -0
  33. package/dist/environment/commands.d.ts +17 -0
  34. package/dist/environment/commands.js +104 -0
  35. package/dist/host/contracts.d.ts +108 -0
  36. package/dist/host/contracts.js +0 -0
  37. package/dist/host/interactions.d.ts +22 -0
  38. package/dist/host/interactions.js +145 -0
  39. package/dist/host/leases.d.ts +18 -0
  40. package/dist/host/leases.js +68 -0
  41. package/dist/host/lifecycle.d.ts +9 -0
  42. package/dist/host/lifecycle.js +56 -0
  43. package/dist/host/router.d.ts +47 -0
  44. package/dist/host/router.js +164 -0
  45. package/dist/host/terminals.d.ts +15 -0
  46. package/dist/host/terminals.js +92 -0
  47. package/dist/host/validation.d.ts +13 -0
  48. package/dist/host/validation.js +69 -0
  49. package/dist/index.d.ts +8 -0
  50. package/dist/index.js +10 -0
  51. package/dist/instance.d.ts +25 -0
  52. package/dist/instance.js +323 -0
  53. package/dist/limits.d.ts +14 -0
  54. package/dist/limits.js +42 -0
  55. package/dist/mcp.d.ts +9 -0
  56. package/dist/mcp.js +62 -0
  57. package/dist/node/contracts.d.ts +21 -0
  58. package/dist/node/contracts.js +0 -0
  59. package/dist/node/execution/errors.d.ts +11 -0
  60. package/dist/node/execution/errors.js +17 -0
  61. package/dist/node/execution/owner.d.ts +34 -0
  62. package/dist/node/execution/owner.js +162 -0
  63. package/dist/node/execution/types.d.ts +20 -0
  64. package/dist/node/execution/types.js +0 -0
  65. package/dist/node/index.d.ts +8 -0
  66. package/dist/node/index.js +30 -0
  67. package/dist/node/launch.d.ts +7 -0
  68. package/dist/node/launch.js +48 -0
  69. package/dist/node/process.d.ts +4 -0
  70. package/dist/node/process.js +98 -0
  71. package/dist/permissions/contracts.d.ts +22 -0
  72. package/dist/permissions/contracts.js +0 -0
  73. package/dist/permissions/mapping.d.ts +13 -0
  74. package/dist/permissions/mapping.js +99 -0
  75. package/dist/permissions/selection.d.ts +5 -0
  76. package/dist/permissions/selection.js +96 -0
  77. package/dist/session/completion.d.ts +4 -0
  78. package/dist/session/completion.js +59 -0
  79. package/dist/session/create.d.ts +27 -0
  80. package/dist/session/create.js +29 -0
  81. package/dist/session/errors.d.ts +6 -0
  82. package/dist/session/errors.js +14 -0
  83. package/dist/session/files.d.ts +8 -0
  84. package/dist/session/files.js +35 -0
  85. package/dist/session/mapping.d.ts +42 -0
  86. package/dist/session/mapping.js +210 -0
  87. package/dist/session/media.d.ts +5 -0
  88. package/dist/session/media.js +22 -0
  89. package/dist/session/native.d.ts +7 -0
  90. package/dist/session/native.js +34 -0
  91. package/dist/session/opening.d.ts +23 -0
  92. package/dist/session/opening.js +69 -0
  93. package/dist/session/plans.d.ts +5 -0
  94. package/dist/session/plans.js +20 -0
  95. package/dist/session/queue.d.ts +32 -0
  96. package/dist/session/queue.js +104 -0
  97. package/dist/session/requests/elicitation.d.ts +14 -0
  98. package/dist/session/requests/elicitation.js +24 -0
  99. package/dist/session/requests/forms.d.ts +31 -0
  100. package/dist/session/requests/forms.js +239 -0
  101. package/dist/session/requests/pending.d.ts +46 -0
  102. package/dist/session/requests/pending.js +78 -0
  103. package/dist/session/requests/resolution.d.ts +5 -0
  104. package/dist/session/requests/resolution.js +32 -0
  105. package/dist/session/resources.d.ts +30 -0
  106. package/dist/session/resources.js +101 -0
  107. package/dist/session/session.d.ts +46 -0
  108. package/dist/session/session.js +521 -0
  109. package/dist/session/turn.d.ts +33 -0
  110. package/dist/session/turn.js +0 -0
  111. package/dist/sessionInteractions/broker.d.ts +42 -0
  112. package/dist/sessionInteractions/broker.js +171 -0
  113. package/dist/sessionInteractions/contracts.d.ts +3 -0
  114. package/dist/sessionInteractions/contracts.js +0 -0
  115. package/dist/sessionInteractions/extensions.d.ts +3 -0
  116. package/dist/sessionInteractions/extensions.js +17 -0
  117. package/dist/sessionInteractions/grokFolderTrust.d.ts +43 -0
  118. package/dist/sessionInteractions/grokFolderTrust.js +107 -0
  119. package/dist/sessionInteractions/request.d.ts +38 -0
  120. package/dist/sessionInteractions/request.js +145 -0
  121. package/package.json +58 -3
package/README.md CHANGED
@@ -1,3 +1,824 @@
1
- # Temporary Holding Version
1
+ # @agen-ai/provider-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
+ An optional provider for the AgenAI coding-agent runtime. It translates the stable
4
+ Agent Client Protocol wire version 1 into the existing Agent Protocol V11 session
5
+ API. The coordinated source SDK version is `0.4.1` and remains unpublished;
6
+ the published release is `0.4.0`.
7
+ The package is ESM, MIT licensed, side-effect-free on import and requires Node.js
8
+ 22 or newer. It depends only on the public transport, runtime and protocol packages;
9
+ the core packages remain independent of ACP.
10
+
11
+ The provider pins the transport's `schema-v1.23.0` stable profile. It translates
12
+ ACP into current V11 capabilities and rejects unsupported semantics explicitly.
13
+ Connection negotiation, configured host facilities, and mapping policy fix one
14
+ capability envelope per instance; every later connection must match it.
15
+
16
+ Tool approvals default to once-only scoped consequences. Both constructors accept an explicit
17
+ `permissionMapping` selection for completely described provider-managed remembered choices.
18
+ Native option labels or kinds alone never establish their consequences. See
19
+ [Remembered tool approvals](#remembered-tool-approvals) for mapping admission and qualification limits.
20
+
21
+ ## Unknown extensions
22
+
23
+ Both `createAcpProviderDriver` and `createNodeAcpProviderDriver` default to
24
+ `unknownExtensionPolicy: 'standard'`. This deliberately changes the public
25
+ provider default in `0.4.0`. Direct transport clients
26
+ continue to default to `'reject'`. AgenAI's controlled private Hostd composition
27
+ explicitly selects `'reject'`; public interoperability does not change that policy.
28
+
29
+ Standard handling discards otherwise unregistered underscore notifications after
30
+ the transport's envelope, size and notification-rate checks. An unsupported
31
+ underscore request receives a correlated `-32601` response without invoking a
32
+ host callback. Core methods, exact registered extensions and protocol controls
33
+ keep their existing validation; malformed registered payloads and unknown `$/`
34
+ controls still fail the connection. Ignoring an optional message such as
35
+ `_x.ai/mcp/servers_updated` establishes no MCP tool exposure or feature support.
36
+ Discarded notifications produce no neutral event or effect authority. Request
37
+ errors remain within the existing outbound byte/backpressure budget and retain
38
+ their IDs until writing finishes; all other transport/provider bounds remain
39
+ unchanged. Required vendor features still need an explicit supported mapping.
40
+
41
+ Set `unknownExtensionPolicy: 'reject'` on either provider constructor to retain
42
+ strict handling on every connection, including authentication reconnects and
43
+ native resume. Only `undefined` selects the default; other values outside
44
+ `'standard'` and `'reject'` throw `TypeError` before connection acquisition or
45
+ process launch. The constructor captures the resolved policy, so later mutation
46
+ of its options cannot change it. The policy is host composition and is absent
47
+ from the closed, empty serialized `driverConfiguration`. Changing policy needs
48
+ a fresh driver and materialization; uncertain native work must not be retried
49
+ under a different policy.
50
+
51
+ ## Capability matrix
52
+
53
+ | Surface | Supported behavior and requirements |
54
+ | --- | --- |
55
+ | Turns and requests | Default text turns, streamed assistant/reasoning text, tool progress, cancellation and once-only exact-action permissions by default, with opt-in complete remembered-choice mappings. One execution retains the original native prompt across request waits and answers. |
56
+ | Resume | Exact persisted binding using advertised `session/resume`, otherwise advertised `session/load`. Load history is bounded and suppressed from new-turn output. No automatic recreation after failure. |
57
+ | Configuration | Managed by default. Explicit `configuration: 'selectable'` maps observed boolean/select catalogs, with a session-mode fallback when config options are absent. Unknown metadata differs from observed empty metadata. |
58
+ | Forms | Canonical boolean/single-select/multi-select forms that fit V11 constraints. An intent stage preserves decline separately from cancel, followed by answers on the same native waiter. Explicit host form facilities can handle broader native forms. |
59
+ | Images | Inline base64 PNG/JPEG/WebP only when the peer advertises image input, within image and total turn budgets. No implicit local-file read or URL fetch. |
60
+ | Plans | Complete replacements of observed turn plans. A mode called “plan” does not establish enforced planning behavior or approval authority. |
61
+ | File changes | Partial structured observations from native tool diffs. Canonical paths contained by the working directory become sorted relative display paths without filesystem reads. Unfinished tools remain unknown at ordinary turn completion. No final workspace diff or Review artifact is inferred. |
62
+ | Commands | Session catalogs and invalidations from `available_commands_update`. Missing metadata remains uninitialized; an observed empty list is available and empty. |
63
+ | Authentication | Explicit method-to-flow selection and host interaction facilities. Agent methods retain the authenticated connection; terminal methods require a host facility and fresh verified initialization afterward. |
64
+ | Files and terminals | Explicit host callbacks, correlated to the bound native session. Terminal support requires the complete output/wait/kill/release lifecycle; embedded terminal transcript references remain unsupported. |
65
+ | MCP setup | Static host-approved `mcpServers` and optional owned `sessionMcpBinding` factory for creation/resume. HTTP/SSE require advertised peer support. Configuration is not observed tool exposure. |
66
+ | Session decisions | Opt-in `grok-folder-trust-v1` on the Node constructor, with a required host execution boundary and handler registered before create. This outside-turn mapping has its own exact support and qualification scope below. |
67
+
68
+ Through-turn branching, same-turn steering, enforced plan mode, persistent
69
+ SDK-owned tool-approval grants, context usage/compaction, account quota, effective skill/rule
70
+ inventory, collaboration, generated resources and artifact publication remain
71
+ unsupported. ACP usage counters can decrease without confirmed compaction and
72
+ cannot satisfy V11's context continuity contract. Unsupported media output fails
73
+ explicitly rather than disappearing from an otherwise successful transcript.
74
+ Embedded terminal references also fail explicitly: a mutable, possibly truncated
75
+ terminal snapshot does not provide an ordered append-only transcript. Agents can
76
+ use terminal RPCs and emit their observed output as ordinary text/tool content.
77
+
78
+ ACP administration (list/delete/logout/import) has no portable provider API in
79
+ this release. Host-owned integrations may use the transport directly with their
80
+ own authorization and native lifecycle policy. No capability grants authority
81
+ over other conversations or account state.
82
+
83
+ ## Operational failures and uncertainty
84
+
85
+ The provider maps supported standard `schema-v1.23.0` prompt errors into V11 `AgentError` values.
86
+ Standard `-32000` reports `authentication` with an `authenticate` user-action hint; `-32602` reports
87
+ `invalid_request`; `-32603` reports `provider`; standard parse/request/method errors report `protocol`.
88
+ Other remote codes remain `unknown` with unknown recovery. Mapping uses the standard error code,
89
+ without copying remote messages, arbitrary data or xAI-specific meanings into a canonical failure.
90
+ Generic ACP does not infer rate limits or exhausted allowance from vendor code `-32003`, and its
91
+ account-quota capability remains unsupported.
92
+
93
+ A validated prompt error response establishes a failed terminal result. A lost response, process loss,
94
+ or unconfirmed cancellation after dispatch does not establish that result; preserve uncertainty and
95
+ close the unusable session without replaying its prompt. Operational classification cannot override
96
+ native settlement or cleanup ownership. The provider does not infer `runtime.retrying` from an RPC
97
+ failure, add a retry loop or enable a vendor retry extension. A future faithful mapping still needs
98
+ explicit native evidence and turn correlation.
99
+
100
+ ## Explicit Node process launch
101
+
102
+ Import process construction through the exact `/node` entrypoint. Supply an
103
+ absolute executable and working directory. Arguments are literal strings and
104
+ spawning always uses `shell: false`. Only the supplied environment is passed to
105
+ the child; the current process environment is never inherited.
106
+
107
+ ```ts
108
+ import {
109
+ parseAgentConfigurationRevisionId,
110
+ parseAgentInstanceId,
111
+ parseAgentProviderKey,
112
+ parseAgentSessionId,
113
+ parseAgentTurnId,
114
+ } from '@agen-ai/agent-protocol';
115
+ import {
116
+ createAgentProviderRegistry,
117
+ isAgentProviderSessionCleanupErrorFor,
118
+ type AgentProviderCreateSessionInput,
119
+ type AgentProviderSession,
120
+ } from '@agen-ai/agent-runtime';
121
+ import { createNodeAcpProviderDriver } from '@agen-ai/provider-acp/node';
122
+
123
+ const providerKey = parseAgentProviderKey('my-acp-agent');
124
+ const instanceId = parseAgentInstanceId('my-agent:primary');
125
+ const driver = createNodeAcpProviderDriver({
126
+ providerKey,
127
+ launch: {
128
+ executable: '/opt/my-agent/bin/agent',
129
+ args: ['--acp'],
130
+ cwd: '/work/project',
131
+ env: { HOME: '/work/agent-home', PATH: '/usr/bin:/bin' },
132
+ },
133
+ });
134
+ const registry = await createAgentProviderRegistry({
135
+ drivers: [driver],
136
+ definitions: [{ providerKey, instanceId, driverConfiguration: {} }],
137
+ });
138
+ const instance = registry.requireInstance(instanceId);
139
+ const openingInput: AgentProviderCreateSessionInput = {
140
+ sessionId: parseAgentSessionId('session:example'),
141
+ workingDirectory: '/work/project',
142
+ configuration: {
143
+ kind: 'managed',
144
+ revision: parseAgentConfigurationRevisionId('configuration:1'),
145
+ },
146
+ onBindingCreated(binding) {
147
+ // Persist this exact opaque binding before proceeding with application work.
148
+ console.log(binding);
149
+ },
150
+ };
151
+ let session: AgentProviderSession | undefined;
152
+ let retainedOpeningCleanup = false;
153
+ try {
154
+ try {
155
+ session = await instance.adapter.createSession(openingInput);
156
+ } catch (error) {
157
+ retainedOpeningCleanup = isAgentProviderSessionCleanupErrorFor(error, openingInput);
158
+ throw error;
159
+ }
160
+ const execution = session.startTurn({
161
+ turnId: parseAgentTurnId('turn:example'),
162
+ interactionMode: 'default',
163
+ parts: [{ type: 'text', text: 'Explain this project.' }],
164
+ });
165
+ for await (const output of execution.outputs) {
166
+ console.log(output);
167
+ }
168
+ } finally {
169
+ if (!retainedOpeningCleanup) {
170
+ await session?.close({ reason: 'shutdown' });
171
+ await registry.dispose();
172
+ }
173
+ }
174
+ ```
175
+
176
+ An exact failed-opening cleanup receipt keeps the registry owned. Retain the receipt and call its
177
+ `retryCleanup()` before disposing the registry. A failed session close likewise skips registry
178
+ disposal; retain that session and retry its cleanup before releasing dependent owners.
179
+
180
+ The registry validates instance, adapter, capability, and canonical output
181
+ contracts. `startTurn` reserves one execution; its native prompt starts lazily
182
+ when `execution.outputs` is first consumed. Keep one output consumer through
183
+ actual terminal settlement. Requests are installed before `request.opened`, so
184
+ an answer can be sent immediately from that event with
185
+ `await execution.resolveRequest({ resolution })`, independently of the next
186
+ output pull. One canonical request is offered at a time; additional bounded
187
+ native callbacks retain FIFO order while unrelated output continues.
188
+ The immediate `await` above is appropriate once the answer is already available. If a person must
189
+ choose it, enqueue the exact request to a separately owned, signal-aware handler and keep pulling
190
+ outputs; join that handler after initiating cancellation and close. The public
191
+ [live-output example](../../examples/live-request-output.ts) demonstrates the ownership without
192
+ native launch or credentials, and the [migration guide](../../MIGRATING-TO-0.4.md) shows before/after code.
193
+
194
+ The response Promise reports `delivered`, `rejected` with `requestState` of
195
+ `pending` or `unavailable`, or `delivery_uncertain`. For ACP, `delivered` means the
196
+ exact still-live local callback accepted the answer, or the canonical form flow
197
+ accepted its intent step. An intent receipt does not await the fields answer.
198
+ The later JSON-RPC write has no peer acknowledgment; delivery does not establish
199
+ wire receipt or model consumption. A later transport failure belongs to the
200
+ original execution's output and cannot revoke an accepted response or authorize
201
+ its replay. Local input/correlation and pre-abort failures reject with their
202
+ precise errors. Do not retry an uncertain response or prompt.
203
+ Only `rejected/pending` preserves the exact response's eligibility for a fresh valid answer.
204
+ `rejected/unavailable` removes it without completing the original execution. Request expiry,
205
+ accepted interruption and observed terminality fence later answers; an older waiting observation
206
+ never restores that eligibility. Close starts native cancellation before joining response work.
207
+ If cleanup fails, retain the session or exact opening-cleanup receipt and its dependent registry/MCP
208
+ resources until the owned retry succeeds.
209
+
210
+ The `startTurn` signal and deadline govern the entire native prompt, including
211
+ time spent waiting for permission or a form answer. Keep them valid through
212
+ terminal settlement. `execution.resolveRequest` has its own operation signal,
213
+ which does not replace the original prompt lifetime. Await each output
214
+ destination's acknowledgement before advancing the iterator. Persist the exact
215
+ opaque binding before application work; a display log is not durable session
216
+ storage.
217
+
218
+ To launch a registry installation, first acquire an exact installation reference
219
+ and resolve its verified recipe through `@agen-ai/acp-registry/node`. Pass the
220
+ absolute executable, literal arguments and approved environment to this same
221
+ constructor. Retain that reference until every session and owned process has
222
+ successfully closed. Startup or disposal failure does not authorize releasing it;
223
+ the host must retain ownership and establish native-process quiescence.
224
+
225
+ ## Injected connections and ownership
226
+
227
+ The root entrypoint exports `createAcpProviderDriver`. Its constructor accepts
228
+ `providerKey`, `createConnection`, and optional `limits`, `configuration`,
229
+ `authentication`, `host`, `mcpServers`, `sessionMcpBinding`, and `permissionMapping`. The connection factory receives the public
230
+ `instanceId` and an initialization `signal`. Return fresh, exclusive Node
231
+ `stdout`, `stdin`, and optional `stderr` streams for every invocation, with one of:
232
+
233
+ - `{ ownership: 'owned', stdout, stdin, stderr?, release }`: the provider invokes
234
+ the lease's idempotent release callback when it closes the connection.
235
+ Concurrent cleanup is coalesced, successful release is retained, and failed
236
+ cleanup can be explicitly retried through session or registry disposal.
237
+ - `{ ownership: 'borrowed', stdout, stdin, stderr? }`: the provider removes its
238
+ stream listeners on close and leaves stream destruction to the caller.
239
+
240
+ The factory owns acquisition work until it returns a lease and must honor its
241
+ abort signal. Initialization has one deadline covering acquisition and the
242
+ initialize request. If an uncooperative factory delivers an owned lease after
243
+ that deadline, the provider invokes its release callback asynchronously; callers
244
+ remain responsible for factory work that never returns a lease. A release
245
+ callback owns only the resources of its own lease.
246
+
247
+ Materialization eagerly initializes one connection and reserves it for the
248
+ first session. Later sessions acquire fresh connections, verify the same frozen
249
+ initialization envelope, then create their own native session. Driver
250
+ configuration is strictly `{}`; launch and connection authority belong to the
251
+ driver constructor. The built-in `/node` launcher supports POSIX systems and creates
252
+ a separate process group for each connection. Closing a session or instance sends
253
+ `SIGTERM` to that group, then escalates to `SIGKILL` if necessary. Each phase waits
254
+ up to `shutdownTimeoutMs`; successful cleanup requires both group disappearance and
255
+ closed child streams, including when the leader exited first or descendants closed
256
+ their streams. Failed cleanup remains available for explicit retry.
257
+
258
+ This process-group ownership is not a sandbox: descendants that deliberately leave
259
+ the group require host-provided OS containment. The host must reap exited children.
260
+ The built-in launcher rejects Windows before spawning with
261
+ `acp_provider_process_platform_unsupported`. Windows hosts can use
262
+ `createAcpProviderDriver` with an owned connection factory backed by their own process
263
+ supervisor, such as a Windows Job Object; the SDK does not supply a native Windows
264
+ process-tree launcher in `0.4.0`.
265
+
266
+ ## Remembered tool approvals
267
+
268
+ `permissionMapping` is constructor configuration on both `createAcpProviderDriver` and
269
+ `createNodeAcpProviderDriver`. It is captured when the driver is created and is absent from the
270
+ empty serialized `driverConfiguration`. Omission or `{ mapping: 'once-only-v1' }` retains the
271
+ conservative once-only subset of each menu and advertises `providerManagedRemembrance: false`.
272
+ A remembered-only native menu is unsupported under that default.
273
+
274
+ For a peer whose complete permission behavior you have inspected and qualified, declare its exact
275
+ initialized identity and complete ordered menus:
276
+
277
+ ```ts
278
+ import type { AcpPermissionMappingSelection } from '@agen-ai/provider-acp';
279
+
280
+ const permissionMapping = {
281
+ mapping: 'declared-complete-consequences-v1',
282
+ agentInfo: { name: 'example-agent', version: '1.2.3' },
283
+ menus: [{
284
+ toolKind: 'edit',
285
+ options: [
286
+ { optionId: 'allow-once', kind: 'allow_once' },
287
+ { optionId: 'remember-allow', kind: 'allow_always' },
288
+ { optionId: 'deny-once', kind: 'reject_once' },
289
+ { optionId: 'remember-deny', kind: 'reject_always' },
290
+ ],
291
+ }],
292
+ } as const satisfies AcpPermissionMappingSelection;
293
+ ```
294
+
295
+ Pass that value with your ordinary connection or Node launch options. The example identities are
296
+ illustrative. Selecting this mapping is your attestation that every listed option has only its
297
+ current allow/deny decision and once-only or provider-managed remembered consequence. A choice
298
+ that also changes mode, clears context or grants another authority needs a different complete
299
+ mapping; this API cannot discover hidden effects or authenticate the implementation from its name.
300
+
301
+ Declarations contain 1–16 menus, each with 1–16 options. Native IDs must be canonical strings of
302
+ 1–256 characters and unique within each menu. Menu signatures must be unique. Peer names are
303
+ bounded to 256 characters and versions to 160; edge whitespace and control/format characters are
304
+ rejected. Tool kinds use the pinned ACP standard vocabulary. Selection uses exact identity, tool
305
+ kind and the complete ordered ID/kind list; native labels are display data. There are no predicates,
306
+ regular expressions, native payload bags or custom mapping callbacks.
307
+
308
+ The capability reflects the selected declarations. Remembered-only menus advertise no precise
309
+ modes and `providerManagedRemembrance: true`; combined menus advertise once/exact-action as well.
310
+ A remembered option has the neutral label “Allow and remember” or “Deny and remember” and an
311
+ explanation that duration and future matching are unspecified. Native wording is omitted from its
312
+ optional description. An offered choice never promises that a provider actually saved a rule.
313
+
314
+ The SDK keeps distinct offered IDs, including several options with the same immediate decision.
315
+ Resolve one exact public option ID on the original execution. The live callback returns its exact
316
+ original native ID once. Deny-once, deny-and-remember and cancellation remain distinct. Continue
317
+ reading the original execution outputs through terminal settlement; a delivery receipt establishes
318
+ local callback acceptance, not native persistence, later matching or successful tool execution.
319
+
320
+ Malformed constructor selection throws `TypeError` before acquisition. A selected peer identity
321
+ mismatch fails initialization with `acp_permission_profile_mismatch`; retain any failed cleanup
322
+ owner as usual. Declared menu mismatches or unqualified option/request metadata fail with
323
+ `acp_permission_consequence_unsupported`. Duplicate IDs are rejected across the entire native menu
324
+ before any filtering. Invalid menu size fails with `acp_permission_options_invalid`. The default's
325
+ remembered-only refusal remains `acp_permission_persistence_unsupported`.
326
+
327
+ The built-in `{ mapping: 'grok-build-1.0.50-edit-remembrance-v1' }` selects the narrowly inspected
328
+ Grok Build 1.0.50 edit behavior. Its peer must report `_meta.agentVersion: '1.0.50'`. It recognizes
329
+ only the inspected `SearchReplace` edit input with `replace_all: false` and the ordered native menu
330
+ `allow-edits-session`/`allow_always`, `allow-once`/`allow_once`, `reject-once`/`reject_once`.
331
+ Other action categories retain the once-only subset with an explicit warning on the original
332
+ output stream; unsupported remembered-only menus fail. Native terminal remembrance and remembered
333
+ denial are not qualified by this edit profile. Duration and applicability remain unknown despite
334
+ native wording or observed same-session behavior.
335
+
336
+ The selected constructor and your host-owned installation/launch attest to the exact inspected
337
+ native executable; the reported version does not authenticate its bytes. The inspected candidate
338
+ is Linux x86_64 Grok Build 1.0.50 (`c58f321264ba`), SHA-256
339
+ `c80de0155706ff2d995623887b102f2d0abd2c62b2643dea3a0cebaf7dd724d5`, launched with
340
+ `agent --no-leader stdio`. Controlled mapping tests prove exact reply behavior; the installed
341
+ native fixture proof below separately establishes the selected edits' actual effects and cleanup.
342
+
343
+ This turn-level selection is independent of session-lifetime folder trust, host filesystem/terminal
344
+ facilities and unknown-extension policy. It creates no SDK permission database, automatic answer
345
+ cache, revoke operation or private Workspaces execution authority.
346
+
347
+ ### Qualified remembered-edit scope (SDK03)
348
+
349
+ Two final native fixture attempts used the genuine executable above, the selected
350
+ `grok-build-1.0.50-edit-remembrance-v1` mapping, modern stable `schema-v1.23.0` and a matching
351
+ installed seven-package `0.4.1`/Agent Protocol V11 set. The recorded tuple is Linux x86_64 kernel
352
+ `7.0.0-38-generic`, Node `24.18.0`, pnpm `11.7.0`, systemd `259.5`, Bubblewrap `0.11.1` and owned
353
+ tmpfs state. An isolated loopback model fixture drove actual native tool calls without real account
354
+ credentials or paid/backend inference. The SDK owned the only ACP reader and responder; a passive
355
+ observer independently checked exact native choices and actual fixture effects.
356
+
357
+ The first attempt used one public/native session and six turns:
358
+
359
+ | Turn | Observed request and effect |
360
+ | --- | --- |
361
+ | Once-only edit | One request; exact once-only native choice delivered once; edit performed. |
362
+ | Repeat after once-only | Asked again; exact once-only choice delivered once; edit performed. |
363
+ | Remembered edit | One request; exact remembered native choice delivered once; edit performed. |
364
+ | Exact repeat after remembrance | No new request; edit performed. |
365
+ | Neighboring owned file | No new request; edit performed. |
366
+ | Uncovered terminal action | Asked again; effect occurred after its exact once-only approval. |
367
+
368
+ The second attempt reopened the verified retained owned state with both a fresh native process
369
+ and a distinct native session. Its first edit asked again and performed the expected edit after
370
+ one exact once-only answer. This combined restart/new-session observation does not isolate the
371
+ effect of either change or define a general expiry or storage contract. Same-process second-session
372
+ behavior was observed only in separate native discovery, outside this installed Node composition.
373
+
374
+ For both attempts, successful public `session.close()` preceded an independent empty checkpoint
375
+ of the same physical workload cgroup while the controller remained alive, before registry or host
376
+ disposal. No earlier external cleanup intervention or OOM kill occurred. Native effects, answer
377
+ correlation and SDK cleanup were checked independently.
378
+
379
+ The exact retained report SHA-256 identities are
380
+ `4ea3ea5b9fac16761b32919ac476ec9b4621f2e99434c441d9eefadb469c5a6b` (six-turn attempt) and
381
+ `bd93b95c3fdba51b0f7f03eaea0393e796a4626298eaedb2a9ebf1ce9bb36730` (retained-state restart).
382
+ The native-used package archives have these SHA-256 identities:
383
+
384
+ | Package at `0.4.1` | Native-used archive SHA-256 |
385
+ | --- | --- |
386
+ | `@agen-ai/validation` | `84d97191d2175be1c7d83e86a007157b80c303088b94be0c05ec6961e2a41729` |
387
+ | `@agen-ai/agent-protocol` | `5a647b2fa504ec3175d58075f503f5e9e435186ec0e8c0758e74ea37741ad192` |
388
+ | `@agen-ai/agent-runtime` | `81dc5ed8940d96bc5f3ae3f0fdb2ad862af87a087e57032db41995a29dacf4b4` |
389
+ | `@agen-ai/agent-orchestration` | `914ad78cdac3ee6af1fe6a7d8522e5c216a3de670816462a082f5c0bde0988fa` |
390
+ | `@agen-ai/acp-transport` | `81314926f24fa428e910c0256671add61f525cac036d5b2841185a7c3e953894` |
391
+ | `@agen-ai/provider-acp` | `2a68df821134fc0af48ab850c1a48ad33be74b8e42e64a6d916bfe2eb84acf6a` |
392
+ | `@agen-ai/acp-registry` | `ab317cc347bf53dcd0045aff4a6d74cb429fc6781c336ea6ed128ced13bdaa07` |
393
+
394
+ Later documentation or packing can change archive bytes; the same version is not an identity
395
+ check. Reuse of this evidence requires comparison of the exact installed dependency closure,
396
+ runtime/declaration members, mapping and host composition. The earlier SDK02 folder-trust proof
397
+ below used different `0.4.1`/V10 artifacts and establishes a separate session-lifetime behavior.
398
+
399
+ Duration and applicability remain unknown. This fixture proof does not qualify arbitrary path
400
+ matching, separate projects/profiles, remembered denial, terminal remembrance, revocation,
401
+ worktree/account/distributed behavior, real-model inference or other native/runtime pairings.
402
+ It does not publish packages, integrate a consumer application or enable private execution.
403
+
404
+ ## Session-lifetime folder decisions
405
+
406
+ The unpublished `0.4.1` source includes the opt-in mapping on
407
+ `createNodeAcpProviderDriver`:
408
+ `sessionInteractions: { mapping: 'grok-folder-trust-v1' }`. Supply an explicit
409
+ `executionBoundary` at construction and the generic `interactions.onRequest`
410
+ handler on each `createSession` input before opening. Materialization itself
411
+ remains noninteractive. The mapping is absent by default, and ordinary standard
412
+ unknown-extension handling never enables it implicitly.
413
+
414
+ The selected launch arguments are exactly `['agent', '--no-leader', 'stdio']`.
415
+ The adapter exposes create-only `sessionInteractions` support with an exclusive
416
+ producer and decision requests. The handler receives a neutral workspace
417
+ decision and can keep its response capability after opening returns, before
418
+ any model turn. Use the generic
419
+ [runtime lifecycle](../agent-runtime/README.md#session-lifetime-interactions)
420
+ for presentation, exact offered choices, receipt handling and cleanup. The core
421
+ [runnable example](../../examples/lifecycle-interactions.ts) requires no ACP
422
+ dependency, native account or network.
423
+
424
+ | Phase or surface | Selected mapping support |
425
+ | --- | --- |
426
+ | Create a session with an early handler | Workspace decision may remain pending after opening returns. |
427
+ | Grant or decline the offered decision | One bound response, with a local delivery receipt separate from native effect. |
428
+ | Close while unanswered | Retires eligibility, joins the native producer and callback, and refuses a late response. |
429
+ | Interactive materialization | Unsupported; no materialization handler is added. |
430
+ | Resume or branch in this selected profile | Unsupported. Generic ACP resume remains a separate unselected capability. |
431
+ | Injected/shared root connections | Unsupported for this mapping; the Node-only execution boundary is required. |
432
+ | Session forms or authentication questions | Unsupported by this outside-turn decision mapping. Existing turn/form and adapter authentication APIs remain separate. |
433
+
434
+ The grant consequence covers current and future configuration for the workspace
435
+ and is provider-managed persistent trust that can affect other sessions using
436
+ that profile. Detected configuration categories do not narrow it. Decline leaves
437
+ configuration gated without revoking old grants or proving a persisted denial.
438
+ Do not expose native request IDs or use a parallel transport responder. Only
439
+ the offered neutral response capability may answer the request.
440
+
441
+ `delivered` establishes acceptance by the local provider handler. It does not
442
+ universally prove native receipt, loaded configuration or stored trust. An
443
+ entered delivery failure or timeout is uncertain and fences further mutation;
444
+ close without resending the choice. A request's terminal promise or aborted
445
+ presentation signal cannot replace full producer/callback cleanup. Retain the
446
+ session, opening cleanup receipt and dependent host/installation owners when
447
+ cleanup fails.
448
+
449
+ ### Qualified session-lifetime scope (SDK02)
450
+
451
+ The earlier SDK02 native qualification covers Grok Build `1.0.50` (`c58f321264ba`),
452
+ executable SHA-256 `c80de0155706ff2d995623887b102f2d0abd2c62b2643dea3a0cebaf7dd724d5`,
453
+ direct no-leader stdio, this selected mapping, modern stable `schema-v1.23.0`,
454
+ its retained installed public SDK `0.4.1`/Agent Protocol V10 artifacts, API-key authentication,
455
+ Linux x86_64 kernel
456
+ `7.0.0-38-generic`, Node `24.18.0`, and the exact retained reference,
457
+ toolchain, network and dependency inputs. It is local qualification, with no
458
+ package publication or consumer-repository integration implied. These exact earlier artifacts
459
+ are distinct from the SDK03 V11 remembered-edit artifacts above despite sharing version `0.4.1`.
460
+
461
+ Three separate native runs established grant, decline and pending close. Grant
462
+ additionally observed the vendor-written isolated workspace trust file. Decline
463
+ established local acceptance and absence of a grant; no further hidden native
464
+ acknowledgment was attested. Pending close sent no choice before close, joined
465
+ the handler and rejected the stale grant as unavailable. Each run independently
466
+ enrolled the genuine target and observed the same stable cgroup empty after SDK
467
+ close with the consumer alive, before registry or host disposal, without external
468
+ intervention. The trusted host was retired afterward.
469
+
470
+ Native wire reply correlation and prompt-frame counts remain unobserved. Zero
471
+ SDK turn invocations is a frozen-consumer-source claim. Separate installed
472
+ controlled peers prove exact wire correlation, no prompts and failure ownership;
473
+ the real Linux controlled lane proves descendant containment and negative
474
+ close-checkpoint behavior. Neither substitutes for native effect evidence.
475
+ The bounded native runs fit the reference's 64-task/512 MiB/180-second limits
476
+ for these setup scenarios only. They establish no general model-turn sizing,
477
+ other builds/platforms, browser login, native durable recovery, SDK-managed
478
+ remembered permissions or private execution support. The earlier failed native
479
+ ownership attempt remains unqualified.
480
+
481
+ ## Reserved execution ownership
482
+
483
+ This surface is included in the unpublished `0.4.1` source candidate.
484
+
485
+ The Node constructor also accepts an explicit `executionBoundary`. This host-owned
486
+ port is useful when native descendants can create their own sessions or process
487
+ groups. It is required when selecting
488
+ `sessionInteractions: { mapping: 'grok-folder-trust-v1' }`; omission fails at
489
+ constructor admission before materialization. The root injected constructor does
490
+ not accept this Node-only option. Ordinary unselected Node drivers keep the
491
+ process-group launcher described above.
492
+
493
+ Import the types from `@agen-ai/provider-acp/node`. A boundary synchronously
494
+ reserves one fresh, inert owner for each immutable launch recipe:
495
+
496
+ ```ts
497
+ interface NodeAcpExecutionBoundary {
498
+ reserve(input: NodeAcpExecutionInput): NodeAcpExecutionReservation;
499
+ }
500
+ ```
501
+
502
+ The recipe contains the exact absolute executable, literal arguments, working
503
+ directory, explicit environment and `shutdownTimeoutMs`. `reserve` must acquire
504
+ no resources and start no asynchronous work. The SDK retains its bound `start`
505
+ and `release` methods before entering startup. `start(context)` establishes the
506
+ operating-system boundary before executing native code and returns ACP streams;
507
+ it receives the current initialization signal. `release()` must synchronously
508
+ fence further startup, initiate termination, and join entered startup, streams
509
+ and the complete descendant workload. It must work before, during and after
510
+ startup. Late startup results remain owned by that same reservation.
511
+
512
+ A supplied object is an ownership contract, not containment proof. The host must
513
+ prevent the workload from leaving its boundary or controlling its supervisor.
514
+ A changing PID list or killing one process group cannot establish that guarantee.
515
+ The standalone [Linux reference](../../examples/execution/linux/README.md) uses
516
+ explicit cgroup delegation and isolated supervisor controls. Its platform and
517
+ host prerequisites are separate from the portable SDK API; there is no automatic
518
+ privilege escalation or fallback to weaker ownership for the selected mapping.
519
+
520
+ For the qualified Linux composition, retain the external host before starting
521
+ it, then give its boundary to the Node driver. The host supplies the physical
522
+ installation, workspace and each writable profile/runtime/temp mount plus an
523
+ explicit native environment:
524
+
525
+ ```ts
526
+ import { createNodeAcpProviderDriver } from '@agen-ai/provider-acp/node';
527
+ import { createLinuxExecutionHost } from '../../examples/execution/linux/boundary.mjs';
528
+
529
+ const host = createLinuxExecutionHost({
530
+ network: 'host',
531
+ networkInputs: {
532
+ resolver: '/etc/resolv.conf',
533
+ hosts: '/etc/hosts',
534
+ certificates: '/etc/ssl/certs',
535
+ },
536
+ mounts: [
537
+ { path: installationRoot, writable: false },
538
+ { path: workspaceRoot, writable: true },
539
+ ...ownedProfileMounts,
540
+ ],
541
+ });
542
+ await host.start();
543
+ const driver = createNodeAcpProviderDriver({
544
+ providerKey,
545
+ sessionInteractions: { mapping: 'grok-folder-trust-v1' },
546
+ executionBoundary: host.executionBoundary,
547
+ launch: { executable: approvedExecutable, args: ['agent', '--no-leader', 'stdio'],
548
+ cwd: workspaceRoot, env: explicitNativeEnvironment, shutdownTimeoutMs: 2_000 },
549
+ });
550
+ ```
551
+
552
+ Construct a registry with that driver and register the generic handler on
553
+ session opening. On success, close the session, dispose the registry, then
554
+ dispose the host. Retain the host if `start()` rejects. When qualifying cleanup,
555
+ keep the exact empty boundary for an independent checkpoint after SDK close
556
+ and before registry/host disposal. Networking and confinement remain explicit
557
+ host authority; the SDK does not create this Linux host automatically.
558
+
559
+ If initial materialization fails and cleanup remains incomplete, the `/node`
560
+ entrypoint exposes `NodeAcpExecutionCleanupError` and
561
+ `isNodeAcpExecutionCleanupError`. Through `createAgentProviderRegistry`, this
562
+ error remains the registry error's `cause`. Keep that original object and its
563
+ bound `retryCleanup()` callback until cleanup succeeds. Its `cause` preserves the
564
+ original startup failure and `cleanupError` records the failed cleanup attempt.
565
+ The callback retains the full acquired resource lifetime, including native work,
566
+ streams and entered provider callbacks. Serializing the error cannot preserve
567
+ this cleanup authority.
568
+
569
+ For example, a failed registry construction can be inspected without replacing
570
+ the callable owner:
571
+
572
+ ```ts
573
+ import { AgentProviderRegistryError } from '@agen-ai/agent-runtime';
574
+ import { isNodeAcpExecutionCleanupError } from '@agen-ai/provider-acp/node';
575
+
576
+ if (error instanceof AgentProviderRegistryError && isNodeAcpExecutionCleanupError(error.cause)) {
577
+ const retained = error.cause;
578
+ await retained.retryCleanup();
579
+ // Only now may the host release resources that depended on this native owner.
580
+ }
581
+ ```
582
+
583
+ If this retry rejects, keep `retained` and the external host owned for explicit
584
+ recovery. A late cleanup success cannot change the original opening failure or
585
+ authorize another native action. Host intervention during qualification keeps
586
+ the original verdict failed even if recovery eventually succeeds.
587
+
588
+ Each cleanup attempt has one observation window of `2 * shutdownTimeoutMs`
589
+ (default four seconds, maximum sixty seconds). A timeout preserves actual pending
590
+ work. A retry gets a fresh observation window and joins the same work; it never
591
+ starts a second process or overlaps an unfinished release. Only a release that
592
+ actually settled with failure may be called again. A shorter runtime deadline
593
+ can return first while the same cleanup remains owned.
594
+
595
+ Once an instance exists, an unsuccessful session opening uses the existing exact
596
+ `AgentProviderSessionCleanupError` receipt. A returned session keeps its normal
597
+ `close` retry path. Retain the corresponding instance, registry and host supervisor
598
+ until all dependent cleanup succeeds. A successful session close establishes
599
+ native quiescence under the supplied owner's contract; independent qualification
600
+ must verify that the concrete owner fulfills it.
601
+
602
+ ## Session-scoped MCP bindings
603
+
604
+ `sessionMcpBinding: { transport, create }` pairs a host-certified `http` or `sse` transport
605
+ with an owned factory. The provider declares runtime host-binding support only when that transport
606
+ was negotiated with the peer. The factory runs only when an opening carries a `hostBinding`, after
607
+ connection initialization and before native session creation or resume. Its trusted context carries
608
+ the instance/session IDs, working directory, opening operation, validated binding facade and an
609
+ acquisition signal. Parent identity never comes from a model tool argument.
610
+
611
+ An application using the optional orchestration package can compose its explicit bridge:
612
+
613
+ ```ts
614
+ import { startDelegationMcpBridge } from "@agen-ai/agent-orchestration/mcp";
615
+
616
+ const sessionMcpBinding = {
617
+ transport: "http" as const,
618
+ async create({ hostBinding, signal }: import("@agen-ai/provider-acp").AcpSessionMcpBindingContext) {
619
+ const bridge = await startDelegationMcpBridge({ binding: hostBinding, signal });
620
+ return {
621
+ mcpServers: [{ type: "http" as const, name: bridge.server.name, url: bridge.server.url,
622
+ headers: Object.entries(bridge.server.headers).map(([name, value]) => ({ name, value })) }],
623
+ release: bridge.release,
624
+ };
625
+ },
626
+ };
627
+ // Supply sessionMcpBinding to either ACP driver constructor.
628
+ ```
629
+
630
+ Each opening needs a fresh binding and lease, including native resume. Dynamic entries must use the
631
+ declared transport and merge with static entries under the existing combined 32-server/512-KiB
632
+ limits. Duplicate names are rejected. The factory installs the binding's actual tools and
633
+ `tool_context` instructions; ACP does not claim a trusted system/developer instruction channel.
634
+ Neither the factory nor its transport may call the facade's `release`: the validated runtime owns
635
+ the original binding.
636
+
637
+ Factory rejection must leave no factory-owned producers. A partially acquired resource must remain
638
+ represented by an owned lease, including a lease delivered after cancellation. Closing quiesces
639
+ the native connection before releasing the MCP lease, then runtime closes the original binding.
640
+ `hostOperationTimeoutMs` bounds acquisition and cleanup waits without discarding the actual pending
641
+ factory or release promise. Pending or failed opening cleanup blocks new openings and authentication
642
+ changes until its retained responsibility is settled.
643
+ Failed opening cleanup retains an explicit retry receipt; failed or pending cleanup cannot be
644
+ treated as successful disposal. Ending a parent turn does not close its session binding or cancel
645
+ independently admitted children.
646
+
647
+ Advertising a transport and accepting a server list are configuration evidence. Qualify each real
648
+ agent/version separately with MCP initialization, tool discovery and an actual invocation. A peer
649
+ that accepts but never exposes tools is not qualified by this adapter. Configuration labels likewise
650
+ do not certify model, reasoning or fast-mode semantics: hosts must map exact selectable session
651
+ configuration, verify it before the first child prompt, and reject shared/global-only changes.
652
+
653
+ From the public SDK repository root, `pnpm examples:delegation:acp` runs a credentialless peer that
654
+ actually discovers and invokes the managed tools. It applies synthetic Standard/Max configuration
655
+ before the child prompt, lets the parent turn finish while the child waits for approval, and later
656
+ delivers the completion through another authorized parent turn. See `examples/delegation/README.md`
657
+ for the shared direct and qualified durable workflows. These fixtures do not qualify a real native
658
+ agent/version. Required vendor features still need an exact supported mapping, and explicit reject
659
+ policy can prevent session opening after successful initialization when the peer emits an
660
+ unregistered vendor extension. AgenAI Workspaces preferences and Hostd production rollout remain
661
+ separate product work.
662
+
663
+ In the standalone repository, the separate opt-in
664
+ [native qualification example](../../examples/delegation/native/README.md) documents the exact
665
+ Grok Build `1.0.50` (`c58f321264ba`) Linux x86_64 pairing qualified on 2026-10-11 with explicit API-key
666
+ authentication, `grok-4.3`, `Low` reasoning and verified request-default standard mapping. Final MS003
667
+ r6 direct and retained-installation reports record actual managed callbacks and once-only approvals,
668
+ real child-result consumption in a later parent turn, cancellation after provider start and closed
669
+ cleanup. Retained mode observes installer exit before a fresh worker reopens the verified store.
670
+ Those immutable version-1 reports use the prior continuation API; the current version-2 execution
671
+ reports require fresh installed qualification. Current hermetic checks establish synthetic behavior.
672
+ The review-applicability record preserves those reports and separately qualifies later preflight,
673
+ deadline and diagnostic-cleanup repairs. The locally authored catalog and transformed binary prove
674
+ exact artifact/launch identity, without authenticating a publisher or certifying backend billing.
675
+ This scope does not qualify browser login, durable native recovery, private Hostd/fleet execution,
676
+ other native pairings, releases or platforms. The qualified SQLite reference remains separate.
677
+
678
+ The 2026-10-10 Grok Build `1.0.34` session-opening failure on `_x.ai/mcp/servers_updated` remains
679
+ historical evidence under the then-strict policy; it involved no model prompt or paid inference.
680
+ The public standard default does not retroactively qualify that binary.
681
+
682
+ ## Configuration and resume
683
+
684
+ Choose `configuration: 'selectable'` at driver construction to expose the existing
685
+ runtime configuration port. Preserve native defaults with this bootstrap input:
686
+
687
+ ```ts
688
+ const configuration = {
689
+ kind: 'selected' as const,
690
+ revision: parseAgentConfigurationRevisionId('configuration:1'),
691
+ catalogRevision: 1,
692
+ selections: [],
693
+ };
694
+ ```
695
+
696
+ This reserved input is not evidence of an empty catalog. Read `listConfiguration`, present its offered
697
+ fields/options, and submit its exact catalog and field revisions through
698
+ `applyConfigurationSelection`.
699
+
700
+ Native field/option IDs remain behind opaque public IDs. Group labels preserve
701
+ their context. Empty optional descriptions normalize to an omitted description;
702
+ identifiers, labels and metadata bounds remain validated. Changed mapped catalogs advance revisions;
703
+ duplicate observations do not. The provider checks the offered revision immediately before local
704
+ dispatch and requires an acknowledged result. ACP supplies no peer-side
705
+ compare-and-set, so this is not an atomic remote-state guarantee. A dispatched
706
+ selection with a failed, lost or unconfirmed result makes the session unusable;
707
+ close and rematerialize without automatically replaying the selection.
708
+
709
+ Persist the exact binding supplied by `onBindingCreated` and pass it to the
710
+ runtime's normal `resumeSession`. Resume restores that conversation, not a
711
+ requested history anchor or fabricated branch. Load replay has total byte/message
712
+ bounds and an opening deadline. Historical permission requests are rejected.
713
+
714
+ ## Host facilities and authentication
715
+
716
+ The typed `host` object supplies optional `form`, `url`, `readTextFile`,
717
+ `writeTextFile`, `createTerminal`, and `authenticateInTerminal` callbacks. There
718
+ are no ambient filesystem, terminal, browser, credential or environment fallbacks.
719
+ Callbacks receive the instance, authorized interaction/session scope and abort
720
+ signal. The application must enforce workspace, network, executable and user
721
+ policy before performing the requested operation. Paths and commands are requests,
722
+ not authorization; these callbacks do not create a sandbox.
723
+
724
+ A URL facility presents consent before opening a URL and never prefetches it. Its
725
+ lease supplies the user's accept/decline/cancel decision, optional completion,
726
+ and idempotent release. Publishing a URL does not count as acceptance. Out-of-turn
727
+ form/URL interactions must match an exact active session-control or authentication
728
+ RPC ID. Unknown/completed IDs are rejected; prompts do not acquire this authority.
729
+
730
+ Enable authentication with an exact selection such as
731
+ `authentication: { browser: { methodId: 'advertised-method-id' } }` and the host
732
+ interactions required by that agent. Browser/device-code flows require an
733
+ agent-managed method. Terminal flows require an advertised terminal method and
734
+ `host.authenticateInTerminal`, which reproduces the host-configured invocation
735
+ with the method's arguments/environment under host policy. Terminal login does
736
+ not send `authenticate` RPC. Native method labels are not used to guess flows.
737
+
738
+ The provider does not copy credentials between connections. A confirmed
739
+ agent-managed login retains that exact idle connection for the next session.
740
+ Authentication changes are rejected while sessions are active. An interrupted
741
+ attempt after dispatch may leave external account state uncertain; the provider
742
+ retires the connection and does not retry login automatically.
743
+
744
+ File callbacks are independently advertised. Terminal support requires a complete
745
+ facility. Handles are scoped to their connection/session; unknown or cross-session
746
+ handles never reach host callbacks. Leases own their resources even when ACP
747
+ streams are borrowed. Idempotent `release` must terminate a running owned process.
748
+ Hosts must honor abort signals; late-acquired leases are released after cancellation.
749
+ Pending terminal, URL and authentication lease acquisitions remain owned and count
750
+ against facility capacity. Disposal waits within the host-operation deadline and
751
+ fails if acquisition or release is still unresolved. Failed releases remain owned
752
+ for an explicit disposal retry; a successful disposal never hides pending cleanup.
753
+ File reads receive an explicit `maxBytes` bound so the host can reject oversized
754
+ content before allocating it; the provider never silently truncates a file response.
755
+ Terminal handles belong to the session and may span turns. Interrupting a prompt
756
+ does not prove that every terminal exited; native release or session/connection
757
+ close ends that handle's ownership. The host retains control over its process policy.
758
+
759
+ ## Form and media limits
760
+
761
+ Canonical forms preflight the whole schema before presenting a request. They
762
+ support at most 16 ordinary fields and 100 choices per selection. Free-text fields,
763
+ nested objects, numeric fields, defaults, patterns/formats, and constraints without
764
+ a V11 representation are rejected. Native free text permits blank/whitespace values
765
+ and measures length in Unicode code points; V11 text answers use nonblank/UTF-16
766
+ bounds. The provider does not narrow those native semantics silently. Enumerated
767
+ string values can map through opaque canonical selection IDs.
768
+ A required multi-select must require exactly one minimum selection; an optional
769
+ multi-select must allow zero. Unsupported shapes never produce a partial form.
770
+
771
+ The first stage offers “Provide answers” (or “Accept” for an empty form) and
772
+ “Decline”. Canceling either stage returns native cancel; decline returns native
773
+ decline. Submitting the answer stage returns native accept with validated content.
774
+ Both stages hold one native request, adding a user step without prompt replay.
775
+ Active session forms use canonical requests when they fit the supported subset.
776
+ An explicit `host.form` callback handles valid broader forms directly, including
777
+ blank text, Unicode code-point bounds, numeric bounds and defaults without
778
+ canonical conversion. Exactly correlated control/auth forms also use that host
779
+ facility. The provider validates the entire native schema and the host's returned
780
+ content; patterns/formats remain unsupported before any callback. Session forms
781
+ and URL interactions require an active prompt; historical replay or an idle
782
+ binding grants no interaction authority. Their host callbacks receive a turn
783
+ lifetime signal that ends on cancellation, settlement or close.
784
+
785
+ Image input allows at most 16 images, 375,000 decoded bytes per image and 750,000
786
+ decoded bytes total, subject to the stricter 1 MiB V11 turn-content bound. Declared
787
+ media type, dimensions, base64 encoding and byte counts are validated. The provider
788
+ does not decode pixels or publish generated bytes; hosts needing image-content
789
+ inspection must perform it before submitting input.
790
+
791
+ ## Bounds and evidence
792
+
793
+ `limits` can override `maxQueuedMessages`, `maxQueuedBytes`,
794
+ `maxPendingRequests`, `maxHostTerminals`, `hostOperationTimeoutMs`,
795
+ `authenticationTimeoutMs`, `initializationTimeoutMs`, `promptTimeoutMs`, and
796
+ `cancellationTimeoutMs`. Defaults share a 128-entry, 8 MiB budget across queued
797
+ sources and retained current-turn item state, with output/control headroom
798
+ reserved inside that budget. Large bursts and turns with many retained items
799
+ can exhaust the same budget. Defaults allow 16 pending requests, 16 host terminals,
800
+ 30 seconds for initialization or a host operation, 15 minutes for authentication,
801
+ 30 minutes for a prompt, and 5 seconds for cancellation. Admission
802
+ reserves finite source capacity synchronously. Response and cancellation
803
+ processing remain independent of slow output consumers. Overflow, malformed
804
+ messages, process loss, or unconfirmed cancellation fail closed and require
805
+ closing the unusable session before rematerialization.
806
+
807
+ Readiness reports completed initialization and the reported agent version when
808
+ available. It does not prove authentication or inference. The Node launcher
809
+ does not install agents, load credentials, apply a sandbox, or grant production
810
+ execution authority. Those responsibilities belong to the application. Tests
811
+ use synthetic processes and streams; they do not qualify a native agent,
812
+ authenticated account, paid inference, or a production host.
813
+
814
+ The selected schema is stable `schema-v1.23.0` at upstream commit
815
+ `6d08f412a7a1370d3cc9a124e3be3d6acf92641e`, using ACP wire version 1.
816
+ The package version, schema release and native agent version are separate identities.
817
+ Qualify the exact native release, target, credentials, toolchain and confinement
818
+ policy before relying on native behavior; initialization alone is a narrower claim.
819
+
820
+ ```sh
821
+ pnpm --filter @agen-ai/provider-acp build
822
+ pnpm --filter @agen-ai/provider-acp typecheck
823
+ pnpm --filter @agen-ai/provider-acp test
824
+ ```