@agen-ai/provider-acp 0.4.1 → 0.4.3

package/README.md

@@ -1,15 +1,15 @@
 # @agen-ai/provider-acp
 
 An optional provider for the AgenAI coding-agent runtime. It translates the stable
-Agent Client Protocol wire version 1 into the existing Agent Protocol V11 session
-API. The coordinated source SDK version is `0.4.1` and remains unpublished;
-the published release is `0.4.0`.
+Agent Client Protocol wire version 1 into the existing Agent Protocol V12 session
+API. The coordinated release is `0.4.3`; published `0.4.1` qualification remains
+historical evidence for its exact V11 artifacts.
 The package is ESM, MIT licensed, side-effect-free on import and requires Node.js
 22 or newer. It depends only on the public transport, runtime and protocol packages;
 the core packages remain independent of ACP.
 
 The provider pins the transport's `schema-v1.23.0` stable profile. It translates
-ACP into current V11 capabilities and rejects unsupported semantics explicitly.
+ACP into current V12 capabilities and rejects unsupported semantics explicitly.
 Connection negotiation, configured host facilities, and mapping policy fix one
 capability envelope per instance; every later connection must match it.
 
@@ -55,7 +55,7 @@ under a different policy.
 | 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. |
 | 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. |
 | 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. |
-| 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. |
+| Forms | Canonical boolean/single-select/multi-select forms that fit V12 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. |
 | 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. |
 | Plans | Complete replacements of observed turn plans. A mode called “plan” does not establish enforced planning behavior or approval authority. |
 | 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. |
@@ -69,7 +69,7 @@ Through-turn branching, same-turn steering, enforced plan mode, persistent
 SDK-owned tool-approval grants, context usage/compaction, account quota, effective skill/rule
 inventory, collaboration, generated resources and artifact publication remain
 unsupported. ACP usage counters can decrease without confirmed compaction and
-cannot satisfy V11's context continuity contract. Unsupported media output fails
+cannot satisfy V12's context continuity contract. Unsupported media output fails
 explicitly rather than disappearing from an otherwise successful transcript.
 Embedded terminal references also fail explicitly: a mutable, possibly truncated
 terminal snapshot does not provide an ordered append-only transcript. Agents can
@@ -82,7 +82,7 @@ over other conversations or account state.
 
 ## Operational failures and uncertainty
 
-The provider maps supported standard `schema-v1.23.0` prompt errors into V11 `AgentError` values.
+The provider maps supported standard `schema-v1.23.0` prompt errors into V12 `AgentError` values.
 Standard `-32000` reports `authentication` with an `authenticate` user-action hint; `-32602` reports
 `invalid_request`; `-32603` reports `provider`; standard parse/request/method errors report `protocol`.
 Other remote codes remain `unknown` with unknown recovery. Mapping uses the standard error code,
@@ -403,7 +403,7 @@ It does not publish packages, integrate a consumer application or enable private
 
 ## Session-lifetime folder decisions
 
-The unpublished `0.4.1` source includes the opt-in mapping on
+The `0.4.1` release includes the opt-in mapping on
 `createNodeAcpProviderDriver`:
 `sessionInteractions: { mapping: 'grok-folder-trust-v1' }`. Supply an explicit
 `executionBoundary` at construction and the generic `interactions.onRequest`
@@ -412,8 +412,9 @@ remains noninteractive. The mapping is absent by default, and ordinary standard
 unknown-extension handling never enables it implicitly.
 
 The selected launch arguments are exactly `['agent', '--no-leader', 'stdio']`.
-The adapter exposes create-only `sessionInteractions` support with an exclusive
-producer and decision requests. The handler receives a neutral workspace
+The adapter exposes the exact `sessionInteractions.mappings` tuple
+`{ openingOperation: 'create', requestKind: 'decision' }`, exclusive producer
+ownership and, in current 0.4.3 source, `humanWait: ['bounded', 'until_withdrawn_or_closed']`. The handler receives a neutral workspace
 decision and can keep its response capability after opening returns, before
 any model turn. Use the generic
 [runtime lifecycle](../agent-runtime/README.md#session-lifetime-interactions)
@@ -478,9 +479,168 @@ other builds/platforms, browser login, native durable recovery, SDK-managed
 remembered permissions or private execution support. The earlier failed native
 ownership attempt remains unqualified.
 
+The current V12 decision descriptor omits `expiresAt` because this native mapping reports no
+provider-owned expiry. The bounded host timer remains a separate policy boundary;
+`humanWait: { kind: 'until_withdrawn_or_closed' }` omits that human timer and
+rejects an explicitly supplied `limits.requestTimeoutMs`. Initialization,
+response observation, authentication and cleanup keep their finite bounds.
+Responses require `{ kind: 'decision', choiceId }`. Generalized runtime terminal/deadline and
+exact support declarations apply to this mapping: an answered terminal records
+`{ kind: 'answered', response: { kind: 'decision', choiceId } }`, and host timeout records
+`{ kind: 'expired', source: 'host_policy' }`. A validated consumer handle exposes the effective
+`deadline` separately from the provider descriptor. Raw driver instances return candidate adapters
+whose interaction callback receives `kind: 'direct'`; registry materialization installs the
+validated consumer facade. Session forms, plan reviews and native continuations
+remain unsupported by `grok-folder-trust-v1`. The retained SDK02 native evidence
+above remains specific to its original finite waiting configuration.
+
+## Restored plan requests in current 0.4.3 source
+
+The Node constructor accepts a separate explicit selection:
+`sessionInteractions: { mapping: 'grok-build-1.0.60-session-requests-v1' }`.
+It requires an exclusive descendant-owning `executionBoundary`, exact direct
+arguments `['agent', '--no-leader', 'stdio']`, modern stable ACP
+`schema-v1.23.0`, and initialized native `_meta.agentVersion: '1.0.60'`.
+The version observation is checked on every connection; it does not authenticate
+an executable or its publisher. The host owns executable selection and byte verification.
+
+This source mapping declares exactly `resume / plan_review` and
+`resume / plan_review / after_open_return` continuation timing. It uses
+`session/load` for the selected restoration. Install `interactions.onRequest`
+and `nativeContinuations.onExecution` before resuming. The continuation handler
+must begin pulling its sole `execution.outputs` iterator before an approval or
+revision response can enter native work. A caller turn and a native continuation
+share the same execution slot and continuous output validation.
+
+The exact `_x.ai/exit_plan_mode` callback supplies a bounded complete plan
+snapshot and three offered choices. Approval maps to `{ outcome: 'approved' }`;
+revision maps to `{ outcome: 'cancelled', feedback }`; abandonment maps to
+`{ outcome: 'abandoned' }` and needs no execution reservation. A revised response
+must identify the offered plan revision and carry its bounded feedback. Missing
+or null plan content cannot become a fabricated review snapshot.
+
+Approval and revision continue the native request without sending
+`session/prompt`. The existing session turn/queue owner accepts a fresh
+`_x.ai/queue/changed.runningPromptId` beginning `plan-resume-`, correlates live
+output to that exact prompt, and completes only on its matching
+`_x.ai/session_notification` `turn_completed` update. Normal completion requires
+`stop_reason: 'end_turn'` and observed live output. Exact `stop_reason: 'cancelled'`
+uses the existing admitted cancellation reason to report `canceled`, or `expired`
+for a timeout, including cancellation after promotion before any assistant output.
+An unsolicited native `cancelled` terminal also reports `canceled`, without
+asserting that a caller requested interruption.
+The original execution reader retains that terminal and cleanup. The pinned
+[Grok cancellation source](https://github.com/xai-org/grok-build/blob/2bdd1d6a6369de0e8c68132ea4539e9abd9e14a8/crates/codegen/xai-grok-shell/src/session/acp_session_impl/cancel.rs#L842)
+emits this exact cancellation terminal; historical `interrupted` is not an active
+cancellation alias. Errors and foreign prompt/session identities remain failures.
+
+Historical replay, a generic interaction-resolved notification and the local
+response receipt establish no continuation completion. Prompt identities observed
+in historical or replayed queue, output and terminal channels remain retained
+under the existing shared queue/state budget, preventing later reuse as a fresh
+promotion. Repeated notifications for the already owned current prompt remain
+valid and do not reserve the same identity twice. Wrong, reused or competing
+identities fail the owned session. Ordinary caller turns remain available after
+that execution and its reader settle.
+
+The selected 1.0.60 mapping also isolates direct native child-session observations.
+Only a root-channel `_x.ai/session_notification` `subagent_spawned` announcement
+with exact parent, child and subagent identities records that relationship.
+Announced child queue notifications, stable session updates and native terminal
+observations are validated and discarded before parent metadata, output,
+continuation prompt tracking or completion. Unknown extensions, tool text and
+permission metadata cannot announce a child. Arbitrary foreign sessions,
+conflicting identity reuse and nested child announcements fail the owned session.
+
+Each retained relationship shares the existing session queue's count and byte
+budget; each identity is bounded to 256 UTF-8 bytes. Exact repeated announcements
+reserve no extra state. Relationships remain reserved until session stop because
+a child's prompt terminal does not establish child-session retirement. Historical
+relationships are replay-only and cannot become live; discarded load-time child
+observations still consume the opening replay budget. This observation scope adds
+no public collaboration capability or child permission, filesystem, terminal or
+form authority. Parent-addressed permission requests retain their existing root
+session routing, and child-addressed requests remain rejected.
+
+For an announced live child with an exact attempt identity, this mapping recognizes
+one ordered native permission cancellation sequence. The child's
+`pending_interaction` must first identify a permission tool. Its exact root-routed
+`session/request_permission` callback must then identify that child through
+`toolCall._meta['x.ai/requestingSessionId']` and the same tool ID. A subsequent
+child `interaction_resolved` followed by a root `subagent_finished` with the exact
+child/subagent/attempt identities and `status: 'cancelled'` withdraws only that
+original callback. The existing request owner queues `request.unavailable` for a
+displayed request before rejecting its reverse callback with `-32800`; an unseen
+queued callback is removed without publishing its ID. A child `turn_completed`
+notification supplies no permission cancellation authority.
+
+An `interaction_resolved` notification alone cannot establish withdrawal because
+it also covers answered and failed interactions. If its exact callback has not
+already accepted an answer, new answer entry waits for corroboration under the
+existing finite `cancellationTimeoutMs`; duplicate observations do not refresh
+that deadline. Missing or contradictory corroboration fails and quiesces the
+owned session without manufacturing withdrawal. An already entered answer keeps
+its original receipt. Native callback reservations remain retained until actual
+transport settlement and entered host work finish. Child/tool census entries,
+including retired identities and their possible answer-wait state, share the
+session count and byte budgets until stop. Pre-admission, prior-turn and replayed
+facts cannot attach to or withdraw a future callback. This mapping consumes
+observed native facts; it adds no child cancellation command or child-addressed
+request authority.
+
+The selected lifecycle request queue retains at most
+`min(maxPendingRequests, 16)` native turn callbacks and 1 MiB of request material,
+within the existing shared session budget. Lower configured limits still win.
+Queued, displayed, response-entered and canceled callbacks remain counted until
+their actual transport settlement and any entered host callback finish. Generic
+ACP compositions retain the existing configurable request ceiling of 1–256
+and default 16; the selected request-material ceiling does not replace the
+8 MiB default output budget.
+
+Exact standard `$/cancel_request` disables only its correlated reverse callback.
+A displayed turn request emits one `request.unavailable` with reason `withdrawn`
+on its original execution before the next surviving FIFO request opens. A queued
+canceled callback stays unseen. The protocol cancellation response is separate
+from a human denial, and an already entered local delivery receipt keeps its
+truth even if cancellation or a later write failure occurs. Output continues
+through the original reader.
+
+Both finite and `until_withdrawn_or_closed` human waiting are accepted for these
+selected session requests. Actual provider expiry remains independent. This
+mapping adds no create/branch session review, outside-turn form, remembered
+approval, durable native recovery or private Hostd authority. Folder-trust
+selection and its create-only restriction remain independent.
+
+Controlled public-constructor and pipe-boundary proof establishes generic FIFO,
+queued withdrawal, exact continuation admission and resource bounds. Final MS009
+installed-native proof separately qualifies Grok Build 1.0.60 on Linux x86_64 /
+Node 24.18.0 with modern stable `schema-v1.23.0`: exact active A withdrawal with
+zero A answers, later B once-only delivery/effect, the original output terminal,
+fresh retained approve/revise continuations with no caller prompt, and no-work
+abandonment during its bounded observation. Each selected case independently
+observes the original workload empty after first SDK close while the consumer
+remains alive, before disposal.
+
+That current Grok composition explicitly sets `GROK_AUTO_WAKE=0`,
+`GROK_WORKER_THREADS=1`, `GROK_SUBAGENT_WORKER_THREADS=1` and
+`GROK_GIX_STATUS_THREADS=1`. Automatic parent wake remains unqualified. Native
+permission forwarding is observed to serialize; simultaneous live Grok callbacks
+into the SDK FIFO queue remain unqualified under the user-accepted MS009 amendment.
+Generic ACP FIFO and the separate Claude diagnostic's native FIFO proof do not
+extend that Grok claim. The selected human-wait observation is 250 ms, which proves
+that mapping's bounded observation rather than arbitrary native waiting duration.
+
+The campaign uses isolated scripted model responses and a constant fake credential;
+it qualifies no real backend authentication, inference or billing. The separate
+Grok 1.0.50 remembered-edit regression retains its historical launch environment
+and recorded task-limit warnings; it makes no capacity-headroom claim. Existing
+Grok 1.0.50 qualification and the legacy `v0.11.4` transport profile retain their
+original scope. The [0.4.2 migration guide](../../MIGRATING-TO-0.4.2.md) identifies
+the executable examples, supported tuples and unsupported native paths.
+
 ## Reserved execution ownership
 
-This surface is included in the unpublished `0.4.1` source candidate.
+This surface is included in the `0.4.1` release.
 
 The Node constructor also accepts an explicit `executionBoundary`. This host-owned
 port is useful when native descendants can create their own sessions or process
@@ -761,8 +921,8 @@ close ends that handle's ownership. The host retains control over its process po
 Canonical forms preflight the whole schema before presenting a request. They
 support at most 16 ordinary fields and 100 choices per selection. Free-text fields,
 nested objects, numeric fields, defaults, patterns/formats, and constraints without
-a V11 representation are rejected. Native free text permits blank/whitespace values
-and measures length in Unicode code points; V11 text answers use nonblank/UTF-16
+a V12 representation are rejected. Native free text permits blank/whitespace values
+and measures length in Unicode code points; V12 text answers use nonblank/UTF-16
 bounds. The provider does not narrow those native semantics silently. Enumerated
 string values can map through opaque canonical selection IDs.
 A required multi-select must require exactly one minimum selection; an optional
@@ -783,7 +943,7 @@ binding grants no interaction authority. Their host callbacks receive a turn
 lifetime signal that ends on cancellation, settlement or close.
 
 Image input allows at most 16 images, 375,000 decoded bytes per image and 750,000
-decoded bytes total, subject to the stricter 1 MiB V11 turn-content bound. Declared
+decoded bytes total, subject to the stricter 1 MiB V12 turn-content bound. Declared
 media type, dimensions, base64 encoding and byte counts are validated. The provider
 does not decode pixels or publish generated bytes; hosts needing image-content
 inspection must perform it before submitting input.

package/dist/capabilities.js

@@ -9,9 +9,9 @@ function freezeCapabilities(value) {
 }
 function acpProviderCapabilities(providerKey, negotiated, configuration = "managed", authenticationFlows = [], sessionInteractions, permissionMapping = { mapping: "once-only-v1" }) {
   return freezeCapabilities(parseAgentCapabilities({
-    protocolVersion: 11,
+    protocolVersion: 12,
     providerKey,
-    sessions: { create: true, resume: sessionInteractions === void 0 && (negotiated.agentCapabilities.loadSession === true || negotiated.agentCapabilities.sessionCapabilities?.resume != null), branch: { kind: "unsupported" } },
+    sessions: { create: true, resume: sessionInteractions?.mapping !== "grok-folder-trust-v1" && (negotiated.agentCapabilities.loadSession === true || negotiated.agentCapabilities.sessionCapabilities?.resume != null), branch: { kind: "unsupported" } },
     turns: { interactionModes: ["default"], interrupt: true, steer: { kind: "unsupported" } },
     requests: {
       approval: acpPermissionCapability(permissionMapping),

package/dist/connection/contracts.d.ts

@@ -30,6 +30,8 @@ export interface AcpNegotiatedAgent {
     readonly authMethods: readonly AcpJsonValue[];
 }
 export interface AcpSessionIngress {
+    readonly joinCallbacks: () => Promise<void>;
+    readonly onExtensionNotification?: (input: AcpNotificationContext) => void | Promise<void>;
     readonly onNotification: (input: AcpNotificationContext) => void | Promise<void>;
     readonly onPermissionRequest: (input: AcpReverseRequestContext) => Promise<AcpJsonValue>;
     readonly onElicitationRequest: (input: AcpReverseRequestContext) => Promise<AcpJsonValue>;
@@ -43,7 +45,7 @@ export interface AcpInitializedConnection {
     readonly attachSession: (ingress: AcpSessionIngress) => () => void;
     readonly bindSession: (binding: AcpBoundSession) => void;
     readonly requestWithScope: (method: string, params: AcpJsonValue, scope: AcpHostInteractionScope, options?: AcpRequestOptions) => Promise<AcpJsonValue>;
-    readonly hostElicitation?: (context: AcpReverseRequestContext) => Promise<AcpJsonValue>;
+    readonly hostElicitation?: (context: AcpReverseRequestContext, observeCallback?: (work: Promise<void>) => void) => Promise<AcpJsonValue>;
     readonly close: () => Promise<void>;
 }
 //# sourceMappingURL=contracts.d.ts.map

package/dist/connection/initialize.js

@@ -12,6 +12,7 @@ import { SessionInteractionBroker } from "../sessionInteractions/broker.js";
 import { createSessionInteractionExtensionRegistry } from "../sessionInteractions/extensions.js";
 import { GROK_FOLDER_TRUST_CAPABILITY_META, GROK_FOLDER_TRUST_METHOD } from "../sessionInteractions/grokFolderTrust.js";
 import { awaitHost } from "../host/lifecycle.js";
+import { GROK_PLAN_REVIEW_METHOD, GROK_QUEUE_METHOD, GROK_SESSION_NOTIFICATION_METHOD } from "../sessionInteractions/grokPlanReview.js";
 async function initializeAcpConnection(input) {
   throwIfAgentOperationAborted(input.context.signal);
   const initialization = new AbortController();
@@ -52,6 +53,7 @@ async function initializeAcpConnection(input) {
   const stopped = new AbortController();
   let client;
   let ingress;
+  let joinSessionCallbacks;
   let attached = false;
   let closePromise;
   let releasePromise;
@@ -63,7 +65,8 @@ async function initializeAcpConnection(input) {
     host,
     limits: input.limits,
     stopped: stopped.signal,
-    ingress: () => ingress
+    ingress: () => ingress,
+    ...input.sessionInteractions ? { humanTimeoutMs: () => sessionInteractions?.humanTimeoutMs() } : {}
   });
   const release = () => {
     if (released) return Promise.resolve();
@@ -83,7 +86,11 @@ async function initializeAcpConnection(input) {
       closePromise = Promise.resolve().then(async () => {
         try {
           const stopping = [router.close(), ...client ? [client.dispose()] : [], release()];
-          const cleanup = await Promise.allSettled([...stopping, ...sessionInteractions ? [sessionInteractions.join()] : []]);
+          const cleanup = await Promise.allSettled([
+            ...stopping,
+            ...joinSessionCallbacks ? [joinSessionCallbacks()] : [],
+            ...sessionInteractions ? [sessionInteractions.join()] : []
+          ]);
           const failures = cleanup.filter((result) => result.status === "rejected");
           if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP connection cleanup failed.");
         } finally {
@@ -113,7 +120,8 @@ async function initializeAcpConnection(input) {
   if (input.sessionInteractions) sessionInteractions = new SessionInteractionBroker({
     stopped: stopped.signal,
     limits: input.limits,
-    onFailure: fail
+    onFailure: fail,
+    selection: input.sessionInteractions
   });
   const onPeerEnd = () => {
     fail(new AcpProviderConnectionError("acp_provider_peer_closed", "The ACP peer closed its stream."));
@@ -140,7 +148,7 @@ async function initializeAcpConnection(input) {
       schemaChannel: "stable",
       unknownExtensionPolicy: input.unknownExtensionPolicy,
       outboundRequestIdPrefix: "agenai-acp-",
-      ...sessionInteractions ? { extensions: createSessionInteractionExtensionRegistry() } : {},
+      ...input.sessionInteractions ? { extensions: createSessionInteractionExtensionRegistry(input.sessionInteractions) } : {},
       limits: {
         maxInboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 1024 * 1024),
         maxOutboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 8 * 1024 * 1024),
@@ -152,6 +160,13 @@ async function initializeAcpConnection(input) {
         shutdownDrainMs: 0
       },
       notificationHandlers: {
+        ...input.sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1" ? Object.fromEntries([GROK_QUEUE_METHOD, GROK_SESSION_NOTIFICATION_METHOD].map((method) => [
+          method,
+          (notification) => {
+            if (!ingress?.onExtensionNotification) throw new AcpProviderConnectionError("acp_provider_session_not_attached", "Native continuation output has no bound owner.");
+            return ingress.onExtensionNotification(notification);
+          }
+        ])) : {},
         "session/update": (notification) => {
           if (!ingress) throw new AcpProviderConnectionError("acp_provider_session_not_attached", "ACP output has no bound session.");
           return ingress.onNotification(notification);
@@ -159,7 +174,7 @@ async function initializeAcpConnection(input) {
         "elicitation/complete": (notification) => router.complete(notification.params ?? null)
       },
       reverseRequestHandlers: {
-        ...sessionInteractions ? { [GROK_FOLDER_TRUST_METHOD]: sessionInteractions.handleRequest } : {},
+        ...sessionInteractions ? { [input.sessionInteractions?.mapping === "grok-folder-trust-v1" ? GROK_FOLDER_TRUST_METHOD : GROK_PLAN_REVIEW_METHOD]: sessionInteractions.handleRequest } : {},
         ...Object.fromEntries([
           "session/request_permission",
           "elicitation/create",
@@ -180,20 +195,20 @@ async function initializeAcpConnection(input) {
     const response = await createAcpStandardSessionOperations(client).initialize({
       protocolVersion: 1,
       clientCapabilities: {
-        ...sessionInteractions ? { _meta: GROK_FOLDER_TRUST_CAPABILITY_META } : {},
+        ...input.sessionInteractions?.mapping === "grok-folder-trust-v1" ? { _meta: GROK_FOLDER_TRUST_CAPABILITY_META } : {},
         fs: { readTextFile: !!host.readTextFile, writeTextFile: !!host.writeTextFile },
         terminal: !!host.createTerminal,
         auth: { terminal: !!host.authenticateInTerminal && !!input.authentication?.terminal },
         elicitation: { form: {}, ...host.url ? { url: {} } : {} },
         ...input.configuration === "selectable" ? { session: { configOptions: { boolean: {} } } } : {}
       },
-      clientInfo: { name: "@agen-ai/provider-acp", version: "0.4.1" }
+      clientInfo: { name: "@agen-ai/provider-acp", version: "0.4.2" }
     }, {
       timeoutMs: input.limits.initializationTimeoutMs,
       signal: initialization.signal
     });
     if (stopped.signal.aborted) throw stopped.signal.reason;
-    const negotiated = readNegotiatedAgent(response, input.permissionMapping);
+    const negotiated = readNegotiatedAgent(response, input.permissionMapping, input.sessionInteractions);
     initialization.signal.removeEventListener("abort", onAbort);
     return Object.freeze({
       client,
@@ -202,7 +217,7 @@ async function initializeAcpConnection(input) {
       ...execution ? { execution } : {},
       ...sessionInteractions ? { sessionInteractions } : {},
       bindSession: (binding) => router.bindSession(binding),
-      ...host.form || host.url ? { hostElicitation: (context) => router.sessionElicitation(context) } : {},
+      ...host.form || host.url ? { hostElicitation: (context, observeCallback) => router.sessionElicitation(context, observeCallback) } : {},
       async requestWithScope(method, params, scope, options = {}) {
         if (!["authenticate", "session/new", "session/load", "session/resume", "session/set_config_option", "session/set_mode"].includes(method)) {
           throw new TypeError("This ACP method does not grant request-scoped host interaction authority.");
@@ -219,6 +234,7 @@ async function initializeAcpConnection(input) {
         if (attached) throw new AcpProviderConnectionError("acp_provider_connection_already_attached", "ACP connections accept exactly one session.");
         attached = true;
         ingress = next;
+        joinSessionCallbacks = next.joinCallbacks;
         return () => {
           ingress = void 0;
         };

package/dist/connection/negotiation.d.ts

@@ -1,7 +1,8 @@
 import type { AcpJsonValue } from '@agen-ai/acp-transport';
 import type { AcpNegotiatedAgent } from './contracts.js';
 import type { AcpPermissionMappingSelection } from '../permissions/contracts.js';
+import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
 /** The transport has already validated the complete pinned initialize response. */
-export declare function readNegotiatedAgent(response: AcpJsonValue, permissionMapping?: AcpPermissionMappingSelection): AcpNegotiatedAgent;
+export declare function readNegotiatedAgent(response: AcpJsonValue, permissionMapping?: AcpPermissionMappingSelection, sessionInteractions?: AcpSessionInteractionSelection): AcpNegotiatedAgent;
 export declare function negotiatedEnvelope(negotiated: AcpNegotiatedAgent): string;
 //# sourceMappingURL=negotiation.d.ts.map

package/dist/connection/negotiation.js

@@ -11,7 +11,7 @@ function immutableProtocolData(value) {
   }
   return value;
 }
-function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only-v1" }) {
+function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only-v1" }, sessionInteractions) {
   const value = response;
   if (value.protocolVersion !== 1) {
     throw new AcpProviderConnectionError("acp_provider_version_unsupported", "ACP wire version 1 is required.");
@@ -28,6 +28,13 @@ function readNegotiatedAgent(response, permissionMapping = { mapping: "once-only
     agentInfo = Object.freeze({ name: info.name, version: info.version });
   }
   let agentVersion;
+  if (sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1") {
+    const meta = value._meta;
+    if (meta === null || typeof meta !== "object" || Array.isArray(meta) || meta.agentVersion !== "1.0.60") {
+      throw new AcpProviderConnectionError("acp_session_profile_mismatch", "The selected session mapping requires exact initialized agentVersion 1.0.60.");
+    }
+    agentVersion = "1.0.60";
+  }
   if (permissionMapping.mapping === "declared-complete-consequences-v1") {
     if (agentInfo?.name !== permissionMapping.agentInfo.name || agentInfo.version !== permissionMapping.agentInfo.version) {
       throw new AcpProviderConnectionError("acp_permission_profile_mismatch", "The initialized ACP identity does not match the selected permission profile.");

package/dist/host/interactions.d.ts

@@ -7,15 +7,20 @@ export declare class AcpHostInteractions {
     private readonly urls;
     private readonly pendingUrls;
     private readonly leases;
+    private readonly forms;
     constructor(input: {
         readonly instanceId: AgentInstanceId;
         readonly host: AcpHostFacilities;
         readonly limits: AcpProviderLimits;
         readonly stopped: AbortSignal;
+        readonly humanTimeoutMs?: () => number | undefined;
     });
-    request(context: AcpReverseRequestContext, scope: AcpHostInteractionScope, scopeSignal: AbortSignal): Promise<AcpJsonValue>;
+    request(context: AcpReverseRequestContext, scope: AcpHostInteractionScope, scopeSignal: AbortSignal, observeCallback?: (work: Promise<void>) => void): Promise<AcpJsonValue>;
+    joinRequest(settled: Promise<void>): Promise<void>;
     complete(id: string): Promise<void>;
     private releaseUrl;
+    private closeForms;
+    private closeOwned;
     close(): Promise<void>;
     closeScope(signal: AbortSignal): Promise<void>;
 }

package/dist/host/interactions.js

@@ -1,3 +1,4 @@
+import { DEFAULT_AGENT_SESSION_INTERACTION_LIMITS } from "@agen-ai/agent-runtime";
 import { validateAcpFormContent, validateAcpFormSchema } from "../session/requests/forms.js";
 import { awaitHost, hostDeadline } from "./lifecycle.js";
 import { AcpHostLeases } from "./leases.js";
@@ -10,7 +11,8 @@ class AcpHostInteractions {
   urls = /* @__PURE__ */ new Map();
   pendingUrls = /* @__PURE__ */ new Map();
   leases;
-  async request(context, scope, scopeSignal) {
+  forms = /* @__PURE__ */ new Map();
+  async request(context, scope, scopeSignal, observeCallback) {
     const params = hostObject(context.params);
     const message = hostText(params.message, 4e3);
     const signal = AbortSignal.any([context.signal, scopeSignal, this.input.stopped]);
@@ -18,15 +20,23 @@ class AcpHostInteractions {
       if (!this.input.host.form) throw unsupportedHostRequest();
       const schema = freezeHostData(structuredClone(hostObject(params.requestedSchema)));
       validateAcpFormSchema(schema);
-      const deadline2 = hostDeadline(signal, this.input.limits.authenticationTimeoutMs);
+      const timeoutMs = scope.kind === "authentication" ? this.input.limits.authenticationTimeoutMs : this.input.humanTimeoutMs ? this.input.humanTimeoutMs() : DEFAULT_AGENT_SESSION_INTERACTION_LIMITS.requestTimeoutMs;
+      const lifetime = new AbortController();
+      const formSignal = AbortSignal.any([signal, lifetime.signal]);
+      const deadline2 = timeoutMs === void 0 ? { signal: formSignal, close() {
+      } } : hostDeadline(formSignal, timeoutMs);
+      const callback = Promise.resolve().then(() => {
+        if (deadline2.signal.aborted) throw deadline2.signal.reason;
+        return this.input.host.form({ instanceId: this.input.instanceId, scope, signal: deadline2.signal, message, requestedSchema: schema });
+      });
+      const actualCallback = callback.then(() => void 0, () => void 0);
+      observeCallback?.(actualCallback);
+      const completion = Promise.all([actualCallback, context.settled]).then(() => {
+        this.forms.delete(context.settled);
+      });
+      this.forms.set(context.settled, { scopeSignal, lifetime, completion });
       try {
-        const result = await awaitHost(this.input.host.form({
-          instanceId: this.input.instanceId,
-          scope,
-          signal: deadline2.signal,
-          message,
-          requestedSchema: schema
-        }), deadline2.signal);
+        const result = await awaitHost(callback, deadline2.signal);
         if (result.action === "accept") {
           const content = hostObject(result.content);
           validateAcpFormContent(schema, content);
@@ -101,6 +111,9 @@ class AcpHostInteractions {
       if (!this.urls.has(id)) deadline.close();
     }
   }
+  joinRequest(settled) {
+    return this.forms.get(settled)?.completion ?? Promise.resolve();
+  }
   async complete(id) {
     const interaction = this.urls.get(id);
     if (!interaction) {
@@ -127,18 +140,31 @@ class AcpHostInteractions {
     interaction.detach();
     this.urls.delete(id);
   }
-  async close() {
-    await this.leases.close();
-    for (const interaction of this.urls.values()) interaction.detach();
-    this.urls.clear();
+  async closeForms(scope) {
+    const entries = [...this.forms.values()].filter((entry) => scope === void 0 || entry.scopeSignal === scope);
+    for (const entry of entries) entry.lifetime.abort(new DOMException("Host form closed.", "AbortError"));
+    const deadline = hostDeadline(new AbortController().signal, this.input.limits.hostOperationTimeoutMs);
+    try {
+      await awaitHost(Promise.all(entries.map((entry) => entry.completion)), deadline.signal);
+    } finally {
+      deadline.close();
+    }
   }
-  async closeScope(signal) {
-    await this.leases.close(signal);
-    for (const [id, interaction] of this.urls) if (interaction.scopeSignal === signal) {
+  async closeOwned(scope) {
+    const results = await Promise.allSettled([this.leases.close(scope), this.closeForms(scope)]);
+    const failures = results.filter((result) => result.status === "rejected");
+    if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP host interaction cleanup failed.");
+    for (const [id, interaction] of this.urls) if (scope === void 0 || interaction.scopeSignal === scope) {
       interaction.detach();
       this.urls.delete(id);
     }
   }
+  close() {
+    return this.closeOwned();
+  }
+  closeScope(signal) {
+    return this.closeOwned(signal);
+  }
 }
 export {
   AcpHostInteractions

package/dist/host/router.d.ts

@@ -14,13 +14,14 @@ export declare class AcpHostRouter {
     private readonly terminals;
     private readonly requests;
     private binding;
-    private pending;
+    private readonly pending;
     private bytes;
     constructor(input: {
         readonly instanceId: AgentInstanceId;
         readonly host: AcpHostFacilities;
         readonly limits: AcpProviderLimits;
         readonly stopped: AbortSignal;
+        readonly humanTimeoutMs?: () => number | undefined;
         readonly ingress: () => AcpSessionIngress | undefined;
     });
     bindSession(binding: AcpBoundSession): void;
@@ -41,7 +42,7 @@ export declare class AcpHostRouter {
     private requireSession;
     private hostRequest;
     complete(value: AcpJsonValue): Promise<void>;
-    sessionElicitation(context: AcpReverseRequestContext): Promise<AcpJsonValue>;
+    sessionElicitation(context: AcpReverseRequestContext, observeCallback?: (work: Promise<void>) => void): Promise<AcpJsonValue>;
     close(): Promise<void>;
 }
 //# sourceMappingURL=router.d.ts.map