@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.
- package/LICENSE +21 -0
- package/README.md +823 -2
- package/dist/auth/controller.d.ts +23 -0
- package/dist/auth/controller.js +170 -0
- package/dist/auth/methods.d.ts +12 -0
- package/dist/auth/methods.js +51 -0
- package/dist/capabilities.d.ts +6 -0
- package/dist/capabilities.js +47 -0
- package/dist/configuration/catalog.d.ts +35 -0
- package/dist/configuration/catalog.js +220 -0
- package/dist/configuration/control.d.ts +19 -0
- package/dist/configuration/control.js +109 -0
- package/dist/configuration/errors.d.ts +6 -0
- package/dist/configuration/errors.js +14 -0
- package/dist/configuration.d.ts +3 -0
- package/dist/configuration.js +9 -0
- package/dist/connection/acquire.d.ts +6 -0
- package/dist/connection/acquire.js +30 -0
- package/dist/connection/contracts.d.ts +49 -0
- package/dist/connection/contracts.js +0 -0
- package/dist/connection/errors.d.ts +5 -0
- package/dist/connection/errors.js +10 -0
- package/dist/connection/initialize.d.ts +20 -0
- package/dist/connection/initialize.js +254 -0
- package/dist/connection/negotiation.d.ts +7 -0
- package/dist/connection/negotiation.js +57 -0
- package/dist/contracts.d.ts +65 -0
- package/dist/contracts.js +0 -0
- package/dist/driver.d.ts +4 -0
- package/dist/driver.js +11 -0
- package/dist/driverFactory.d.ts +8 -0
- package/dist/driverFactory.js +48 -0
- package/dist/environment/commands.d.ts +17 -0
- package/dist/environment/commands.js +104 -0
- package/dist/host/contracts.d.ts +108 -0
- package/dist/host/contracts.js +0 -0
- package/dist/host/interactions.d.ts +22 -0
- package/dist/host/interactions.js +145 -0
- package/dist/host/leases.d.ts +18 -0
- package/dist/host/leases.js +68 -0
- package/dist/host/lifecycle.d.ts +9 -0
- package/dist/host/lifecycle.js +56 -0
- package/dist/host/router.d.ts +47 -0
- package/dist/host/router.js +164 -0
- package/dist/host/terminals.d.ts +15 -0
- package/dist/host/terminals.js +92 -0
- package/dist/host/validation.d.ts +13 -0
- package/dist/host/validation.js +69 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +10 -0
- package/dist/instance.d.ts +25 -0
- package/dist/instance.js +323 -0
- package/dist/limits.d.ts +14 -0
- package/dist/limits.js +42 -0
- package/dist/mcp.d.ts +9 -0
- package/dist/mcp.js +62 -0
- package/dist/node/contracts.d.ts +21 -0
- package/dist/node/contracts.js +0 -0
- package/dist/node/execution/errors.d.ts +11 -0
- package/dist/node/execution/errors.js +17 -0
- package/dist/node/execution/owner.d.ts +34 -0
- package/dist/node/execution/owner.js +162 -0
- package/dist/node/execution/types.d.ts +20 -0
- package/dist/node/execution/types.js +0 -0
- package/dist/node/index.d.ts +8 -0
- package/dist/node/index.js +30 -0
- package/dist/node/launch.d.ts +7 -0
- package/dist/node/launch.js +48 -0
- package/dist/node/process.d.ts +4 -0
- package/dist/node/process.js +98 -0
- package/dist/permissions/contracts.d.ts +22 -0
- package/dist/permissions/contracts.js +0 -0
- package/dist/permissions/mapping.d.ts +13 -0
- package/dist/permissions/mapping.js +99 -0
- package/dist/permissions/selection.d.ts +5 -0
- package/dist/permissions/selection.js +96 -0
- package/dist/session/completion.d.ts +4 -0
- package/dist/session/completion.js +59 -0
- package/dist/session/create.d.ts +27 -0
- package/dist/session/create.js +29 -0
- package/dist/session/errors.d.ts +6 -0
- package/dist/session/errors.js +14 -0
- package/dist/session/files.d.ts +8 -0
- package/dist/session/files.js +35 -0
- package/dist/session/mapping.d.ts +42 -0
- package/dist/session/mapping.js +210 -0
- package/dist/session/media.d.ts +5 -0
- package/dist/session/media.js +22 -0
- package/dist/session/native.d.ts +7 -0
- package/dist/session/native.js +34 -0
- package/dist/session/opening.d.ts +23 -0
- package/dist/session/opening.js +69 -0
- package/dist/session/plans.d.ts +5 -0
- package/dist/session/plans.js +20 -0
- package/dist/session/queue.d.ts +32 -0
- package/dist/session/queue.js +104 -0
- package/dist/session/requests/elicitation.d.ts +14 -0
- package/dist/session/requests/elicitation.js +24 -0
- package/dist/session/requests/forms.d.ts +31 -0
- package/dist/session/requests/forms.js +239 -0
- package/dist/session/requests/pending.d.ts +46 -0
- package/dist/session/requests/pending.js +78 -0
- package/dist/session/requests/resolution.d.ts +5 -0
- package/dist/session/requests/resolution.js +32 -0
- package/dist/session/resources.d.ts +30 -0
- package/dist/session/resources.js +101 -0
- package/dist/session/session.d.ts +46 -0
- package/dist/session/session.js +521 -0
- package/dist/session/turn.d.ts +33 -0
- package/dist/session/turn.js +0 -0
- package/dist/sessionInteractions/broker.d.ts +42 -0
- package/dist/sessionInteractions/broker.js +171 -0
- package/dist/sessionInteractions/contracts.d.ts +3 -0
- package/dist/sessionInteractions/contracts.js +0 -0
- package/dist/sessionInteractions/extensions.d.ts +3 -0
- package/dist/sessionInteractions/extensions.js +17 -0
- package/dist/sessionInteractions/grokFolderTrust.d.ts +43 -0
- package/dist/sessionInteractions/grokFolderTrust.js +107 -0
- package/dist/sessionInteractions/request.d.ts +38 -0
- package/dist/sessionInteractions/request.js +145 -0
- package/package.json +58 -3
package/README.md
CHANGED
|
@@ -1,3 +1,824 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @agen-ai/provider-acp
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
```
|