@agen-ai/provider-acp 0.4.0 → 0.4.1

package/dist/connection/initialize.js

@@ -8,6 +8,10 @@ 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";
 async function initializeAcpConnection(input) {
   throwIfAgentOperationAborted(input.context.signal);
   const initialization = new AbortController();
@@ -18,11 +22,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,6 +40,13 @@ 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();
@@ -42,6 +56,7 @@ async function initializeAcpConnection(input) {
   let closePromise;
   let releasePromise;
   let released = false;
+  let sessionInteractions;
   const host = input.host ?? {};
   const router = new AcpHostRouter({
     instanceId: input.context.instanceId,
@@ -63,11 +78,12 @@ 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, ...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 +98,31 @@ 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
+  });
+  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 +140,7 @@ async function initializeAcpConnection(input) {
       schemaChannel: "stable",
       unknownExtensionPolicy: input.unknownExtensionPolicy,
       outboundRequestIdPrefix: "agenai-acp-",
+      ...sessionInteractions ? { extensions: createSessionInteractionExtensionRegistry() } : {},
       limits: {
         maxInboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 1024 * 1024),
         maxOutboundFrameBytes: Math.min(input.limits.maxQueuedBytes, 8 * 1024 * 1024),
@@ -132,6 +159,7 @@ async function initializeAcpConnection(input) {
         "elicitation/complete": (notification) => router.complete(notification.params ?? null)
       },
       reverseRequestHandlers: {
+        ...sessionInteractions ? { [GROK_FOLDER_TRUST_METHOD]: sessionInteractions.handleRequest } : {},
         ...Object.fromEntries([
           "session/request_permission",
           "elicitation/create",
@@ -144,36 +172,35 @@ 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: {
+        ...sessionInteractions ? { _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.1" }
     }, {
       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);
     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) } : {},
       async requestWithScope(method, params, scope, options = {}) {
@@ -199,9 +226,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,7 @@
 import type { AcpJsonValue } from '@agen-ai/acp-transport';
 import type { AcpNegotiatedAgent } from './contracts.js';
+import type { AcpPermissionMappingSelection } from '../permissions/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): 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" }) {
   const value = response;
   if (value.protocolVersion !== 1) {
     throw new AcpProviderConnectionError("acp_provider_version_unsupported", "ACP wire version 1 is required.");
@@ -27,9 +27,23 @@ function readNegotiatedAgent(response) {
     }
     agentInfo = Object.freeze({ name: info.name, version: info.version });
   }
+  let agentVersion;
+  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.js

@@ -7,7 +7,6 @@ class AcpHostInteractions {
     this.input = input;
     this.leases = new AcpHostLeases(input.limits.hostOperationTimeoutMs);
   }
-  input;
   urls = /* @__PURE__ */ new Map();
   pendingUrls = /* @__PURE__ */ new Map();
   leases;

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.js

@@ -11,7 +11,6 @@ class AcpHostRouter {
     this.interactions = new AcpHostInteractions(input);
     this.terminals = new AcpHostTerminals(input.host, input.limits);
   }
-  input;
   interactions;
   terminals;
   requests = /* @__PURE__ */ new Map();

package/dist/host/terminals.js

@@ -8,8 +8,6 @@ class AcpHostTerminals {
     this.limits = limits;
     this.leases = new AcpHostLeases(limits.hostOperationTimeoutMs);
   }
-  host;
-  limits;
   terminals = /* @__PURE__ */ new Map();
   leases;
   async request(method, params, session) {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { createAcpProviderDriver } from './driver.js';
 export { DEFAULT_ACP_PROVIDER_LIMITS, type AcpProviderLimits } from './limits.js';
 export { AcpProviderConnectionError } from './connection/errors.js';
 export { AcpProviderSessionError } from './session/errors.js';
+export type { AcpPermissionOptionSignature, AcpPermissionMenuSignature, AcpPermissionMappingSelection, } from './permissions/contracts.js';
 export type { AcpConnectionStreams, AcpConnectionLease, AcpConnectionFactoryContext, AcpConnectionFactory, AcpSessionMcpBindingContext, AcpSessionMcpBindingLease, AcpSessionMcpBindingFactory, AcpSessionMcpBindingOptions, CreateAcpProviderDriverOptions, } from './contracts.js';
 export type { AcpAuthenticationMethods, AcpHostFacilities, AcpHostInteractionScope, AcpHostInteractionInput, AcpHostFormInput, AcpHostFormResponse, AcpHostUrlInput, AcpHostUrlDecision, AcpHostUrlInteractionLease, AcpHostSessionInput, AcpHostFileReadInput, AcpHostFileWriteInput, AcpHostTerminalCreateInput, AcpHostTerminalLease, AcpHostTerminalOutput, AcpHostTerminalExitStatus, AcpHostAuthenticationTerminalInput, AcpHostAuthenticationTerminalLease, } from './host/contracts.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/instance.d.ts

@@ -1,13 +1,16 @@
 import { type AgentInstanceId, type AgentProviderKey } from '@agen-ai/agent-protocol';
 import type { AcpStandardMcpServer, AcpUnknownExtensionPolicy } from '@agen-ai/acp-transport';
 import { type MaterializedAgentProviderInstance } from '@agen-ai/agent-runtime';
-import type { AcpConnectionFactory, AcpSessionMcpBindingOptions } from './contracts.js';
+import type { AcpSessionMcpBindingOptions } from './contracts.js';
 import type { AcpAuthenticationMethods, AcpHostFacilities } from './host/contracts.js';
 import type { AcpProviderLimits } from './limits.js';
+import type { AcpConnectionSource } from './connection/contracts.js';
+import type { AcpSessionInteractionSelection } from './sessionInteractions/contracts.js';
+import type { AcpPermissionMappingSelection } from './permissions/contracts.js';
 export declare function createAcpProviderInstance(input: {
     readonly providerKey: AgentProviderKey;
     readonly instanceId: AgentInstanceId;
-    readonly createConnection: AcpConnectionFactory;
+    readonly connectionSource: AcpConnectionSource;
     readonly unknownExtensionPolicy: AcpUnknownExtensionPolicy;
     readonly limits: AcpProviderLimits;
     readonly usedStreams: WeakSet<object>;
@@ -15,6 +18,8 @@ export declare function createAcpProviderInstance(input: {
     readonly authentication: AcpAuthenticationMethods;
     readonly host: AcpHostFacilities;
     readonly mcpServers: readonly AcpStandardMcpServer[];
+    readonly permissionMapping: AcpPermissionMappingSelection;
     readonly sessionMcpBinding?: AcpSessionMcpBindingOptions;
+    readonly sessionInteractions?: AcpSessionInteractionSelection;
 }): Promise<MaterializedAgentProviderInstance>;
 //# sourceMappingURL=instance.d.ts.map