@agen-ai/provider-acp 0.4.0 → 0.4.2

package/dist/connection/contracts.d.ts

@@ -1,16 +1,37 @@
 import type { AcpClient, AcpJsonObject, AcpJsonValue, AcpNotificationContext, AcpReverseRequestContext, AcpRequestOptions } from '@agen-ai/acp-transport';
 import type { AcpHostInteractionScope } from '../host/contracts.js';
 import type { AcpBoundSession } from '../host/router.js';
+import type { SessionInteractionBroker } from '../sessionInteractions/broker.js';
+import type { AcpConnectionFactory } from '../contracts.js';
+import type { NodeAcpExecutionOwner } from '../node/execution/owner.js';
+export type AcpConnectionSource = Readonly<{
+    kind: 'factory';
+    create: AcpConnectionFactory;
+}> | Readonly<{
+    kind: 'reserved';
+    reserve: () => NodeAcpExecutionOwner;
+}>;
+export type AcpConnectionAcquisition = Readonly<{
+    kind: 'factory';
+    create: AcpConnectionFactory;
+}> | Readonly<{
+    kind: 'reserved';
+    owner: NodeAcpExecutionOwner;
+}>;
 export interface AcpNegotiatedAgent {
     readonly protocolVersion: 1;
     readonly agentInfo?: Readonly<{
         name: string;
         version: string;
     }>;
+    /** Bounded compatibility observation retained only by the selected Grok permission profile. */
+    readonly agentVersion?: string;
     readonly agentCapabilities: AcpJsonObject;
     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>;
@@ -19,10 +40,12 @@ export interface AcpInitializedConnection {
     readonly client: AcpClient;
     readonly negotiated: AcpNegotiatedAgent;
     readonly stopped: AbortSignal;
+    readonly execution?: NodeAcpExecutionOwner;
+    readonly sessionInteractions?: SessionInteractionBroker;
     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/errors.js

@@ -4,7 +4,6 @@ class AcpProviderConnectionError extends Error {
     this.reasonCode = reasonCode;
     this.name = "AcpProviderConnectionError";
   }
-  reasonCode;
 }
 export {
   AcpProviderConnectionError

package/dist/connection/initialize.d.ts

@@ -1,10 +1,12 @@
 import { type AcpUnknownExtensionPolicy } from '@agen-ai/acp-transport';
-import type { AcpConnectionFactory, AcpConnectionFactoryContext } from '../contracts.js';
+import type { AcpConnectionFactoryContext } from '../contracts.js';
 import type { AcpProviderLimits } from '../limits.js';
-import type { AcpInitializedConnection } from './contracts.js';
+import type { AcpConnectionAcquisition, AcpInitializedConnection } from './contracts.js';
 import type { AcpAuthenticationMethods, AcpHostFacilities } from '../host/contracts.js';
+import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
+import type { AcpPermissionMappingSelection } from '../permissions/contracts.js';
 export declare function initializeAcpConnection(input: {
-    readonly createConnection: AcpConnectionFactory;
+    readonly source: AcpConnectionAcquisition;
     readonly unknownExtensionPolicy: AcpUnknownExtensionPolicy;
     readonly context: AcpConnectionFactoryContext;
     readonly limits: AcpProviderLimits;
@@ -12,5 +14,7 @@ export declare function initializeAcpConnection(input: {
     readonly host?: AcpHostFacilities;
     readonly authentication?: AcpAuthenticationMethods;
     readonly configuration?: 'managed' | 'selectable';
+    readonly sessionInteractions?: AcpSessionInteractionSelection;
+    readonly permissionMapping?: AcpPermissionMappingSelection;
 }): Promise<AcpInitializedConnection>;
 //# sourceMappingURL=initialize.d.ts.map

package/dist/connection/initialize.js

@@ -8,6 +8,11 @@ import { AcpProviderConnectionError } from "./errors.js";
 import { acquireAcpLease, releaseOwnedLease } from "./acquire.js";
 import { readNegotiatedAgent } from "./negotiation.js";
 import { AcpHostRouter } from "../host/router.js";
+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();
@@ -18,11 +23,14 @@ async function initializeAcpConnection(input) {
     "ACP connection acquisition or initialization exceeded its deadline."
   )), input.limits.initializationTimeoutMs);
   let lease;
+  const execution = input.source.kind === "reserved" ? input.source.owner : void 0;
   try {
-    lease = await acquireAcpLease(input.createConnection, { ...input.context, signal: initialization.signal });
+    const context = { ...input.context, signal: initialization.signal };
+    lease = input.source.kind === "factory" ? await acquireAcpLease(input.source.create, context) : await awaitHost(input.source.owner.start(context), initialization.signal);
     try {
       validateLease(lease, input.usedStreams);
     } catch (cause) {
+      if (execution) throw cause;
       try {
         await releaseOwnedLease(lease);
       } catch (cleanupError) {
@@ -33,22 +41,32 @@ async function initializeAcpConnection(input) {
   } catch (cause) {
     clearTimeout(timeout);
     input.context.signal?.removeEventListener("abort", onInitializationAbort);
+    if (execution) {
+      try {
+        await execution.cleanup();
+      } catch (cleanupError) {
+        throw execution.retainedError(cause, cleanupError);
+      }
+    }
     throw cause;
   }
   const stopped = new AbortController();
   let client;
   let ingress;
+  let joinSessionCallbacks;
   let attached = false;
   let closePromise;
   let releasePromise;
   let released = false;
+  let sessionInteractions;
   const host = input.host ?? {};
   const router = new AcpHostRouter({
     instanceId: input.context.instanceId,
     host,
     limits: input.limits,
     stopped: stopped.signal,
-    ingress: () => ingress
+    ingress: () => ingress,
+    ...input.sessionInteractions ? { humanTimeoutMs: () => sessionInteractions?.humanTimeoutMs() } : {}
   });
   const release = () => {
     if (released) return Promise.resolve();
@@ -63,11 +81,16 @@ async function initializeAcpConnection(input) {
   const stop = (reason) => {
     if (!stopped.signal.aborted) stopped.abort(reason);
   };
-  const close = () => {
+  const closeActual = () => {
     if (!closePromise) {
       closePromise = Promise.resolve().then(async () => {
         try {
-          const cleanup = await Promise.allSettled([router.close(), ...client ? [client.dispose()] : [], release()]);
+          const stopping = [router.close(), ...client ? [client.dispose()] : [], release()];
+          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 {
@@ -82,21 +105,32 @@ async function initializeAcpConnection(input) {
         closePromise = void 0;
         throw error;
       });
+      sessionInteractions?.stop({ kind: "session_closed" });
       stop(new AcpProviderConnectionError("acp_provider_connection_closed", "The ACP connection was closed."));
     }
     return closePromise;
   };
-  const onPeerEnd = () => {
-    stop(new AcpProviderConnectionError("acp_provider_peer_closed", "The ACP peer closed its stream."));
+  execution?.retainCleanup(closeActual);
+  const close = () => execution ? execution.cleanup() : closeActual();
+  const fail = (error) => {
+    if (stopped.signal.aborted) return;
+    stop(error);
     void close().catch(() => void 0);
   };
+  if (input.sessionInteractions) sessionInteractions = new SessionInteractionBroker({
+    stopped: stopped.signal,
+    limits: input.limits,
+    onFailure: fail,
+    selection: input.sessionInteractions
+  });
+  const onPeerEnd = () => {
+    fail(new AcpProviderConnectionError("acp_provider_peer_closed", "The ACP peer closed its stream."));
+  };
   const onPeerError = (error) => {
-    stop(error);
-    void close().catch(() => void 0);
+    fail(error);
   };
   const onAbort = () => {
-    stop(initialization.signal.reason instanceof Error ? initialization.signal.reason : new DOMException("ACP initialization was aborted.", "AbortError"));
-    void close().catch(() => void 0);
+    fail(initialization.signal.reason instanceof Error ? initialization.signal.reason : new DOMException("ACP initialization was aborted.", "AbortError"));
   };
   lease.stdout.once("end", onPeerEnd);
   lease.stdout.once("close", onPeerEnd);
@@ -114,6 +148,7 @@ async function initializeAcpConnection(input) {
       schemaChannel: "stable",
       unknownExtensionPolicy: input.unknownExtensionPolicy,
       outboundRequestIdPrefix: "agenai-acp-",
+      ...input.sessionInteractions ? { extensions: createSessionInteractionExtensionRegistry(input.sessionInteractions) } : {},
       limits: {
         maxInboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 1024 * 1024),
         maxOutboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 8 * 1024 * 1024),
@@ -125,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);
@@ -132,6 +174,7 @@ async function initializeAcpConnection(input) {
         "elicitation/complete": (notification) => router.complete(notification.params ?? null)
       },
       reverseRequestHandlers: {
+        ...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",
@@ -144,38 +187,37 @@ async function initializeAcpConnection(input) {
           "terminal/release"
         ].map((method) => [method, (request) => router.admit(request)]))
       },
-      onFatalError: (error) => {
-        stop(error);
-        void close().catch(() => void 0);
-      }
+      onFatalError: fail
     });
     void client.closed.then((result) => {
-      stop(result.error ?? new AcpProviderConnectionError("acp_provider_connection_closed", "The ACP connection stopped."));
-      void close().catch(() => void 0);
+      fail(result.error ?? new AcpProviderConnectionError("acp_provider_connection_closed", "The ACP connection stopped."));
     });
     const response = await createAcpStandardSessionOperations(client).initialize({
       protocolVersion: 1,
       clientCapabilities: {
+        ...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.0" }
+      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);
+    const negotiated = readNegotiatedAgent(response, input.permissionMapping, input.sessionInteractions);
     initialization.signal.removeEventListener("abort", onAbort);
     return Object.freeze({
       client,
       negotiated,
       stopped: stopped.signal,
+      ...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.");
@@ -192,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;
         };
@@ -199,9 +242,11 @@ async function initializeAcpConnection(input) {
       close
     });
   } catch (cause) {
+    if (execution?.cleanupFailure) throw execution.retainedError(cause, execution.cleanupFailure.error);
     try {
       await close();
     } catch (cleanupError) {
+      if (execution) throw execution.retainedError(cause, cleanupError);
       throw new AggregateError([cause, cleanupError], "ACP initialization and cleanup failed.");
     }
     throw cause;

package/dist/connection/negotiation.d.ts

@@ -1,6 +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): 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) {
+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.");
@@ -27,9 +27,30 @@ function readNegotiatedAgent(response) {
     }
     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.");
+    }
+  } else if (permissionMapping.mapping === "grok-build-1.0.50-edit-remembrance-v1") {
+    const meta = value._meta;
+    const version = meta !== null && typeof meta === "object" && !Array.isArray(meta) ? meta.agentVersion : void 0;
+    if (typeof version !== "string" || version.length > 160 || version !== version.trim() || /[\p{Cc}\p{Cf}]/u.test(version) || version !== "1.0.50") {
+      throw new AcpProviderConnectionError("acp_permission_profile_mismatch", "The selected Grok permission profile requires the exact initialized agentVersion 1.0.50.");
+    }
+    agentVersion = version;
+  }
   return Object.freeze({
     protocolVersion: 1,
     ...agentInfo ? { agentInfo } : {},
+    ...agentVersion ? { agentVersion } : {},
     agentCapabilities: immutableProtocolData(value.agentCapabilities ?? {}),
     authMethods: immutableProtocolData(value.authMethods ?? [])
   });

package/dist/contracts.d.ts

@@ -4,6 +4,7 @@ import type { AgentSessionHostBinding, MaybePromise } from '@agen-ai/agent-runti
 import type { AcpProviderLimits } from './limits.js';
 import type { AcpStandardMcpServer, AcpUnknownExtensionPolicy } from '@agen-ai/acp-transport';
 import type { AcpAuthenticationMethods, AcpHostFacilities } from './host/contracts.js';
+import type { AcpPermissionMappingSelection } from './permissions/contracts.js';
 export type { AcpProviderLimits } from './limits.js';
 export interface AcpConnectionStreams {
     readonly stdout: Readable;
@@ -51,6 +52,8 @@ export interface CreateAcpProviderDriverOptions {
     readonly createConnection: AcpConnectionFactory;
     /** Defaults to standard handling of unknown optional vendor extensions. */
     readonly unknownExtensionPolicy?: AcpUnknownExtensionPolicy;
+    /** Defaults to once-only choices; complete profiles require independently qualified native semantics. */
+    readonly permissionMapping?: AcpPermissionMappingSelection;
     readonly limits?: Partial<AcpProviderLimits>;
     readonly configuration?: 'managed' | 'selectable';
     readonly authentication?: AcpAuthenticationMethods;

package/dist/driver.d.ts

@@ -1,4 +1,4 @@
-import { type AgentProviderDriver } from '@agen-ai/agent-runtime';
+import type { AgentProviderDriver } from '@agen-ai/agent-runtime';
 import type { CreateAcpProviderDriverOptions } from './contracts.js';
 export declare function createAcpProviderDriver(options: CreateAcpProviderDriverOptions): AgentProviderDriver;
 //# sourceMappingURL=driver.d.ts.map

package/dist/driver.js

@@ -1,43 +1,10 @@
-import { parseAgentProviderKey } from "@agen-ai/agent-protocol";
-import { defineAgentProviderDriver } from "@agen-ai/agent-runtime";
-import { parseAcpProviderConfiguration } from "./configuration.js";
-import { createAcpProviderInstance } from "./instance.js";
-import { resolveAcpProviderLimits } from "./limits.js";
-import { resolveAuthenticationMapping } from "./auth/methods.js";
-import { resolveHostFacilities } from "./host/validation.js";
-import { resolveAcpMcpServers, resolveAcpSessionMcpBinding } from "./mcp.js";
+import { createAcpProviderDriverInternal } from "./driverFactory.js";
 function createAcpProviderDriver(options) {
-  const providerKey = parseAgentProviderKey(options.providerKey);
-  const createConnection = options.createConnection;
-  if (typeof createConnection !== "function") throw new TypeError("An ACP connection factory is required.");
-  const unknownExtensionPolicy = options.unknownExtensionPolicy === void 0 ? "standard" : options.unknownExtensionPolicy;
-  if (unknownExtensionPolicy !== "reject" && unknownExtensionPolicy !== "standard") throw new TypeError("ACP unknown extension policy is invalid.");
-  const limits = resolveAcpProviderLimits(options.limits);
-  const configuration = options.configuration ?? "managed";
-  if (configuration !== "managed" && configuration !== "selectable") throw new TypeError("ACP configuration mode is invalid.");
-  const authentication = resolveAuthenticationMapping(options.authentication);
-  const host = resolveHostFacilities(options.host);
-  const mcpServers = resolveAcpMcpServers(options.mcpServers);
-  const sessionMcpBinding = resolveAcpSessionMcpBinding(options.sessionMcpBinding);
-  const usedStreams = /* @__PURE__ */ new WeakSet();
-  return defineAgentProviderDriver({
-    providerKey,
-    supportsMultipleInstances: true,
-    parseConfiguration: parseAcpProviderConfiguration,
-    createInstance: ({ instanceId }) => createAcpProviderInstance({
-      providerKey,
-      instanceId,
-      createConnection,
-      unknownExtensionPolicy,
-      limits,
-      usedStreams,
-      configuration,
-      authentication,
-      host,
-      mcpServers,
-      ...sessionMcpBinding ? { sessionMcpBinding } : {}
-    })
-  });
+  if (Object.hasOwn(options, "sessionInteractions")) {
+    throw new TypeError("ACP session interaction mappings require the Node provider constructor and its exclusive process ownership.");
+  }
+  if (Object.hasOwn(options, "executionBoundary")) throw new TypeError("Execution boundaries require the Node provider constructor.");
+  return createAcpProviderDriverInternal({ ...options, connectionSource: { kind: "factory", create: options.createConnection } });
 }
 export {
   createAcpProviderDriver

package/dist/driverFactory.d.ts

@@ -0,0 +1,8 @@
+import { type AgentProviderDriver } from '@agen-ai/agent-runtime';
+import type { CreateAcpProviderDriverOptions } from './contracts.js';
+import type { AcpSessionInteractionSelection } from './sessionInteractions/contracts.js';
+import type { AcpConnectionSource } from './connection/contracts.js';
+export declare function createAcpProviderDriverInternal(options: Omit<CreateAcpProviderDriverOptions, 'createConnection'> & Readonly<{
+    connectionSource: AcpConnectionSource;
+}>, sessionInteractions?: AcpSessionInteractionSelection): AgentProviderDriver;
+//# sourceMappingURL=driverFactory.d.ts.map

package/dist/driverFactory.js

@@ -0,0 +1,48 @@
+import { parseAgentProviderKey } from "@agen-ai/agent-protocol";
+import { defineAgentProviderDriver } from "@agen-ai/agent-runtime";
+import { parseAcpProviderConfiguration } from "./configuration.js";
+import { createAcpProviderInstance } from "./instance.js";
+import { resolveAcpProviderLimits } from "./limits.js";
+import { resolveAuthenticationMapping } from "./auth/methods.js";
+import { resolveHostFacilities } from "./host/validation.js";
+import { resolveAcpMcpServers, resolveAcpSessionMcpBinding } from "./mcp.js";
+import { resolveAcpPermissionMapping } from "./permissions/selection.js";
+function createAcpProviderDriverInternal(options, sessionInteractions) {
+  const providerKey = parseAgentProviderKey(options.providerKey);
+  const connectionSource = options.connectionSource;
+  if (connectionSource.kind === "factory" && typeof connectionSource.create !== "function") throw new TypeError("An ACP connection factory is required.");
+  const unknownExtensionPolicy = options.unknownExtensionPolicy === void 0 ? "standard" : options.unknownExtensionPolicy;
+  if (unknownExtensionPolicy !== "reject" && unknownExtensionPolicy !== "standard") throw new TypeError("ACP unknown extension policy is invalid.");
+  const limits = resolveAcpProviderLimits(options.limits);
+  const configuration = options.configuration ?? "managed";
+  if (configuration !== "managed" && configuration !== "selectable") throw new TypeError("ACP configuration mode is invalid.");
+  const authentication = resolveAuthenticationMapping(options.authentication);
+  const host = resolveHostFacilities(options.host);
+  const mcpServers = resolveAcpMcpServers(options.mcpServers);
+  const sessionMcpBinding = resolveAcpSessionMcpBinding(options.sessionMcpBinding);
+  const permissionMapping = resolveAcpPermissionMapping(options.permissionMapping);
+  const usedStreams = /* @__PURE__ */ new WeakSet();
+  return defineAgentProviderDriver({
+    providerKey,
+    supportsMultipleInstances: true,
+    parseConfiguration: parseAcpProviderConfiguration,
+    createInstance: ({ instanceId }) => createAcpProviderInstance({
+      providerKey,
+      instanceId,
+      connectionSource,
+      unknownExtensionPolicy,
+      limits,
+      usedStreams,
+      configuration,
+      authentication,
+      host,
+      mcpServers,
+      permissionMapping,
+      ...sessionMcpBinding ? { sessionMcpBinding } : {},
+      ...sessionInteractions ? { sessionInteractions } : {}
+    })
+  });
+}
+export {
+  createAcpProviderDriverInternal
+};

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";
@@ -7,11 +8,11 @@ class AcpHostInteractions {
     this.input = input;
     this.leases = new AcpHostLeases(input.limits.hostOperationTimeoutMs);
   }
-  input;
   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]);
@@ -19,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);
@@ -102,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) {
@@ -128,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/leases.js

@@ -4,7 +4,6 @@ class AcpHostLeases {
   constructor(timeoutMs) {
     this.timeoutMs = timeoutMs;
   }
-  timeoutMs;
   entries = /* @__PURE__ */ new Set();
   used = /* @__PURE__ */ new WeakSet();
   closed = false;

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