@agen-ai/provider-acp 0.4.0 → 0.4.1

package/dist/instance.js

@@ -6,7 +6,10 @@ import {
   createAgentProviderReadiness,
   createAgentProviderSessionCleanupError,
   isAgentProviderSessionCleanupErrorFor,
-  throwIfAgentOperationAborted
+  throwIfAgentOperationAborted,
+  validateAgentProviderAdapter,
+  AgentProviderContractError,
+  DEFAULT_AGENT_SESSION_INTERACTION_LIMITS
 } from "@agen-ai/agent-runtime";
 import { createAcpAuthentication } from "./auth/controller.js";
 import { selectedAuthenticationMethods } from "./auth/methods.js";
@@ -17,18 +20,33 @@ import { negotiatedEnvelope } from "./connection/negotiation.js";
 import { assertAcpMcpSupport, supportsAcpSessionMcpBinding } from "./mcp.js";
 import { createAcpProviderSession } from "./session/create.js";
 import { AcpSessionResources } from "./session/resources.js";
+import { awaitHost, hostDeadline } from "./host/lifecycle.js";
+import { isNodeAcpExecutionCleanupError, NodeAcpExecutionCleanupError } from "./node/execution/errors.js";
 async function createAcpProviderInstance(input) {
   const lifetime = new AbortController();
-  const connect = (signal) => initializeAcpConnection({
-    createConnection: input.createConnection,
-    unknownExtensionPolicy: input.unknownExtensionPolicy,
-    context: { instanceId: input.instanceId, signal },
-    limits: input.limits,
-    usedStreams: input.usedStreams,
-    configuration: input.configuration,
-    authentication: input.authentication,
-    host: input.host
-  });
+  const executions = /* @__PURE__ */ new Set();
+  const connect = (signal) => {
+    throwIfAgentOperationAborted(signal);
+    const source = input.connectionSource.kind === "factory" ? input.connectionSource : { kind: "reserved", owner: input.connectionSource.reserve() };
+    if (source.kind === "reserved") {
+      executions.add(source.owner);
+      source.owner.whenDrained(() => {
+        executions.delete(source.owner);
+      });
+    }
+    return initializeAcpConnection({
+      source,
+      unknownExtensionPolicy: input.unknownExtensionPolicy,
+      context: { instanceId: input.instanceId, signal },
+      limits: input.limits,
+      usedStreams: input.usedStreams,
+      configuration: input.configuration,
+      authentication: input.authentication,
+      host: input.host,
+      permissionMapping: input.permissionMapping,
+      ...input.sessionInteractions ? { sessionInteractions: input.sessionInteractions } : {}
+    });
+  };
   let eager = await connect(lifetime.signal);
   const negotiated = eager.negotiated;
   let methods;
@@ -36,11 +54,13 @@ async function createAcpProviderInstance(input) {
   try {
     assertAcpMcpSupport(input.mcpServers, negotiated);
     methods = selectedAuthenticationMethods(negotiated, input.authentication, input.host);
-    capabilities = acpProviderCapabilities(input.providerKey, negotiated, input.configuration, [...methods.keys()]);
+    capabilities = acpProviderCapabilities(input.providerKey, negotiated, input.configuration, [...methods.keys()], input.sessionInteractions, input.permissionMapping);
   } catch (cause) {
+    if (eager.execution?.cleanupFailure) throw eager.execution.retainedError(cause, eager.execution.cleanupFailure.error);
     try {
       await eager.close();
     } catch (cleanupError) {
+      if (eager.execution) throw eager.execution.retainedError(cause, cleanupError);
       throw new AggregateError([cause, cleanupError], "ACP materialization and cleanup failed.");
     }
     throw cause;
@@ -52,7 +72,8 @@ async function createAcpProviderInstance(input) {
   const creatingIds = /* @__PURE__ */ new Set();
   const pending = /* @__PURE__ */ new Set();
   let disposePromise;
-  const cleanupPending = () => [...resources].some((resource) => resource.cleanupPending);
+  let disposeDeadline = 0;
+  const cleanupPending = () => [...resources].some((resource) => resource.cleanupPending) || [...executions].some((execution) => execution.cleanupPending);
   const bindingSupported = supportsAcpSessionMcpBinding(input.sessionMcpBinding, negotiated);
   const now = () => (/* @__PURE__ */ new Date()).toISOString();
   const retire = async (connection) => {
@@ -60,6 +81,10 @@ async function createAcpProviderInstance(input) {
     await connection.close();
     connections.delete(connection);
   };
+  const closeConnection = async (connection) => {
+    await connection.close();
+    if (input.sessionInteractions) connections.delete(connection);
+  };
   const acquire = async (signal) => {
     const reserved = eager;
     eager = void 0;
@@ -67,14 +92,22 @@ async function createAcpProviderInstance(input) {
     connections.add(connection);
     try {
       throwIfAgentOperationAborted(signal);
+      if (input.sessionInteractions && connection.stopped.aborted) throw connection.stopped.reason;
       if (negotiatedEnvelope(connection.negotiated) !== envelope) {
         throw new AcpProviderConnectionError("acp_provider_negotiation_changed", "The ACP peer changed its initialized behavior envelope.");
       }
       return connection;
     } catch (cause) {
+      const retained = (cleanupError) => new NodeAcpExecutionCleanupError({
+        cause,
+        cleanupError,
+        retryCleanup: () => retire(connection)
+      });
+      if (connection.execution?.cleanupFailure) throw retained(connection.execution.cleanupFailure.error);
       try {
         await retire(connection);
       } catch (cleanupError) {
+        if (connection.execution) throw retained(cleanupError);
         throw new AggregateError([cause, cleanupError], "ACP negotiation and cleanup failed.");
       }
       throw cause;
@@ -101,6 +134,16 @@ async function createAcpProviderInstance(input) {
   const open = async (context, resume) => {
     throwIfAgentOperationAborted(context.signal);
     throwIfAgentOperationAborted(lifetime.signal);
+    if (input.sessionInteractions && resume) throw new AgentProviderContractError(
+      input.providerKey,
+      "session_interactions_unsupported",
+      "The selected ACP session interaction mapping supports creation only."
+    );
+    if (input.sessionInteractions && context.interactions === void 0) throw new AgentProviderContractError(
+      input.providerKey,
+      "invalid_session_interaction",
+      "The selected ACP session interaction mapping requires a handler before opening."
+    );
     if (authentication.active) throw new AcpProviderConnectionError("acp_authentication_active", "Authentication owns the ACP instance.");
     if (authentication.cleanupPending) throw new AcpProviderConnectionError("acp_authentication_cleanup_pending", "Authentication terminal cleanup must complete before session mutation.");
     if (cleanupPending()) throw new AcpProviderConnectionError("acp_session_cleanup_pending", "Session resource cleanup must complete before session mutation.");
@@ -126,6 +169,14 @@ async function createAcpProviderInstance(input) {
       let opened;
       try {
         connection = await acquire(signal);
+        if (context.interactions) {
+          connection.sessionInteractions?.prepareOpening({
+            sessionId: parsed.sessionId,
+            workingDirectory: context.workingDirectory,
+            interactions: context.interactions,
+            signal
+          });
+        }
         const ownedConnection = connection;
         resource = new AcpSessionResources({
           instanceId: input.instanceId,
@@ -145,7 +196,7 @@ async function createAcpProviderInstance(input) {
         throwIfAgentOperationAborted(signal);
         const closeResources = () => resource.close();
         const sessionCapabilities = negotiated.agentCapabilities.sessionCapabilities;
-        const session = await createAcpProviderSession({
+        opened = await createAcpProviderSession({
           context: { ...context, sessionId: parsed.sessionId, configuration: parsed.configuration, signal },
           openingInput: context,
           ...parsed.operation === "resume" ? { resume: {
@@ -157,20 +208,27 @@ async function createAcpProviderInstance(input) {
           capabilities,
           limits: input.limits,
           now,
+          permissionMapping: input.permissionMapping,
           onClosed: () => {
             sessions.delete(parsed.sessionId);
             connections.delete(ownedConnection);
           },
           closeResources
         });
-        opened = session;
         throwIfAgentOperationAborted(signal);
-        sessions.set(parsed.sessionId, session);
-        return session;
+        connection.sessionInteractions?.adopt();
+        sessions.set(parsed.sessionId, opened.session);
+        return opened.session;
       } catch (cause) {
         if (isAgentProviderSessionCleanupErrorFor(cause, context) && cause.providerKey === input.providerKey) throw cause;
+        if (isNodeAcpExecutionCleanupError(cause)) throw createAgentProviderSessionCleanupError({
+          providerKey: input.providerKey,
+          openingInput: context,
+          errors: [cause],
+          retryCleanup: cause.retryCleanup
+        });
         if (resource || connection) {
-          const cleanup = () => opened ? opened.close({ reason: "contract_rejected" }) : resource ? resource.close() : retire(connection);
+          const cleanup = () => opened ? opened.cleanup() : resource ? resource.close() : retire(connection);
           try {
             await cleanup();
           } catch (cleanupError) {
@@ -193,16 +251,23 @@ async function createAcpProviderInstance(input) {
       creatingIds.delete(parsed.sessionId);
     }
   };
+  const adapter = Object.freeze({
+    ...input.sessionInteractions ? { sessionInteractions: Object.freeze({
+      kind: "supported",
+      openingOperations: Object.freeze(["create"]),
+      requestKinds: Object.freeze(["decision"]),
+      producerOwnership: "exclusive"
+    }) } : {},
+    hostBinding: bindingSupported ? Object.freeze({ kind: "supported", toolTransport: "mcp", instructionPlacements: Object.freeze(["tool_context"]) }) : Object.freeze({ kind: "unsupported" }),
+    createSession: (context) => open(context, false),
+    resumption: capabilities.sessions.resume ? Object.freeze({ kind: "supported", resumeSession: (context) => open(context, true) }) : Object.freeze({ kind: "unsupported" }),
+    branching: { kind: "unsupported" },
+    authentication: authentication.port
+  });
   return Object.freeze({
     instanceId: input.instanceId,
     capabilities,
-    adapter: Object.freeze({
-      hostBinding: bindingSupported ? Object.freeze({ kind: "supported", toolTransport: "mcp", instructionPlacements: Object.freeze(["tool_context"]) }) : Object.freeze({ kind: "unsupported" }),
-      createSession: (context) => open(context, false),
-      resumption: capabilities.sessions.resume ? Object.freeze({ kind: "supported", resumeSession: (context) => open(context, true) }) : Object.freeze({ kind: "unsupported" }),
-      branching: { kind: "unsupported" },
-      authentication: authentication.port
-    }),
+    adapter: input.sessionInteractions ? validateAgentProviderAdapter(capabilities, adapter) : adapter,
     accountQuota: { kind: "unsupported" },
     environment: { kind: "unsupported" },
     checkReadiness(check = {}) {
@@ -217,18 +282,24 @@ async function createAcpProviderInstance(input) {
     },
     dispose() {
       if (!disposePromise) {
+        disposeDeadline = Date.now() + Math.min(input.limits.hostOperationTimeoutMs, DEFAULT_AGENT_SESSION_INTERACTION_LIMITS.cleanupTimeoutMs);
         disposePromise = Promise.resolve().then(async () => {
           const failures = /* @__PURE__ */ new Set();
           const closingConnections = new Set(connections);
+          if (input.sessionInteractions) for (const connection of closingConnections) {
+            const reason = connection.stopped.reason;
+            if (connection.stopped.aborted && reason instanceof Error && !(reason instanceof AcpProviderConnectionError && reason.reasonCode === "acp_provider_connection_closed")) failures.add(reason);
+          }
           const closing = await Promise.allSettled([
             authentication.close(),
             ...[...sessions.values()].map((session) => session.close({ reason: "shutdown" })),
             ...[...resources].map((resource) => resource.close()),
-            ...[...closingConnections].map((connection) => connection.close())
+            ...[...closingConnections].map(closeConnection),
+            ...[...executions].map((execution) => execution.cleanup())
           ]);
           for (const result of closing) if (result.status === "rejected") failures.add(result.reason);
           await Promise.allSettled([...pending]);
-          const remaining = await Promise.allSettled([...connections].filter((connection) => !closingConnections.has(connection)).map((connection) => connection.close()));
+          const remaining = await Promise.allSettled([...connections].filter((connection) => !closingConnections.has(connection)).map(closeConnection));
           for (const result of remaining) if (result.status === "rejected") failures.add(result.reason);
           if (failures.size) throw new AggregateError(failures, "ACP instance cleanup failed.");
           connections.clear();
@@ -239,6 +310,10 @@ async function createAcpProviderInstance(input) {
         });
         lifetime.abort(new AcpProviderConnectionError("acp_provider_instance_disposed", "The ACP instance was disposed."));
       }
+      if (input.sessionInteractions || input.connectionSource.kind === "reserved") {
+        const deadline = hostDeadline(new AbortController().signal, Math.max(0, disposeDeadline - Date.now()));
+        return awaitHost(disposePromise, deadline.signal).finally(() => deadline.close());
+      }
       return disposePromise;
     }
   });

package/dist/node/contracts.d.ts

@@ -1,5 +1,6 @@
 import type { AcpProviderLimits } from '../limits.js';
 import type { CreateAcpProviderDriverOptions } from '../contracts.js';
+import type { NodeAcpExecutionBoundary } from './execution/types.js';
 export interface NodeAcpLaunchOptions {
     readonly executable: string;
     readonly args?: readonly string[];
@@ -10,6 +11,11 @@ export interface NodeAcpLaunchOptions {
 }
 export interface CreateNodeAcpProviderDriverOptions extends Omit<CreateAcpProviderDriverOptions, 'createConnection' | 'limits'> {
     readonly launch: NodeAcpLaunchOptions;
+    readonly executionBoundary?: NodeAcpExecutionBoundary;
+    /** Requires a genuine direct native executable, exact no-leader arguments and a handler for every created session. */
+    readonly sessionInteractions?: Readonly<{
+        readonly mapping: 'grok-folder-trust-v1';
+    }>;
     readonly limits?: Partial<AcpProviderLimits>;
 }
 //# sourceMappingURL=contracts.d.ts.map

package/dist/node/execution/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class NodeAcpExecutionCleanupError extends Error {
+    readonly cleanupError: unknown;
+    readonly retryCleanup: () => Promise<void>;
+    constructor(input: Readonly<{
+        cause: unknown;
+        cleanupError: unknown;
+        retryCleanup: () => Promise<void>;
+    }>);
+}
+export declare function isNodeAcpExecutionCleanupError(error: unknown): error is NodeAcpExecutionCleanupError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/node/execution/errors.js

@@ -0,0 +1,17 @@
+class NodeAcpExecutionCleanupError extends Error {
+  cleanupError;
+  retryCleanup;
+  constructor(input) {
+    super("The owned Node ACP execution cleanup remains incomplete.", { cause: input.cause });
+    this.name = "NodeAcpExecutionCleanupError";
+    this.cleanupError = input.cleanupError;
+    this.retryCleanup = input.retryCleanup;
+  }
+}
+function isNodeAcpExecutionCleanupError(error) {
+  return error instanceof NodeAcpExecutionCleanupError;
+}
+export {
+  NodeAcpExecutionCleanupError,
+  isNodeAcpExecutionCleanupError
+};

package/dist/node/execution/owner.d.ts

@@ -0,0 +1,34 @@
+import type { AcpConnectionFactoryContext, AcpConnectionLease } from '../../contracts.js';
+import { NodeAcpExecutionCleanupError } from './errors.js';
+import type { NodeAcpExecutionBoundary, NodeAcpExecutionInput, NodeAcpExecutionReservation } from './types.js';
+export declare class NodeAcpExecutionOwner {
+    private readonly cleanupTimeoutMs;
+    private state;
+    private startup;
+    private releaseState;
+    private readonly releaseComplete;
+    private failureNotice;
+    private cleanupAttempt;
+    private observation;
+    private cleanupWork;
+    private onDrained;
+    private failure;
+    private readonly startReservation;
+    private readonly releaseReservation;
+    constructor(reservation: NodeAcpExecutionReservation, cleanupTimeoutMs: number);
+    get cleanupPending(): boolean;
+    get cleanupFailure(): Readonly<{
+        error: unknown;
+    }> | undefined;
+    retainCleanup(work: () => Promise<void>): void;
+    whenDrained(callback: () => void): void;
+    start(context: AcpConnectionFactoryContext): Promise<AcpConnectionLease>;
+    /** Actual release is unbounded here; one outer observation owns the full connection deadline. */
+    release(): Promise<void>;
+    private beginRelease;
+    cleanup(): Promise<void>;
+    retainedError(cause: unknown, cleanupError: unknown): NodeAcpExecutionCleanupError;
+    joinCleanup(): Promise<void>;
+}
+export declare function executionReservationSource(boundary: NodeAcpExecutionBoundary, input: NodeAcpExecutionInput): () => NodeAcpExecutionOwner;
+//# sourceMappingURL=owner.d.ts.map

package/dist/node/execution/owner.js

@@ -0,0 +1,162 @@
+import { AcpProviderConnectionError } from "../../connection/errors.js";
+import { NodeAcpExecutionCleanupError } from "./errors.js";
+class NodeAcpExecutionOwner {
+  constructor(reservation, cleanupTimeoutMs) {
+    this.cleanupTimeoutMs = cleanupTimeoutMs;
+    const release = reservation.release;
+    const start = reservation.start;
+    if (typeof release !== "function" || typeof start !== "function") {
+      throw new TypeError("An execution reservation must provide callable start and release methods.");
+    }
+    this.startReservation = (context) => Reflect.apply(start, reservation, [context]);
+    this.releaseReservation = () => Reflect.apply(release, reservation, []);
+  }
+  state = "reserved";
+  startup;
+  releaseState = { kind: "idle" };
+  releaseComplete = Promise.withResolvers();
+  failureNotice = Promise.withResolvers();
+  cleanupAttempt;
+  observation;
+  cleanupWork = () => this.release();
+  onDrained = () => {
+  };
+  failure;
+  startReservation;
+  releaseReservation;
+  get cleanupPending() {
+    return this.state === "stopping";
+  }
+  get cleanupFailure() {
+    return this.failure;
+  }
+  retainCleanup(work) {
+    this.cleanupWork = work;
+  }
+  whenDrained(callback) {
+    this.onDrained = callback;
+  }
+  start(context) {
+    if (this.state !== "reserved") return Promise.reject(new TypeError("Execution startup is once-only and cannot follow release."));
+    this.state = "active";
+    this.startup = Promise.resolve().then(() => {
+      if (this.state !== "active") throw new DOMException("Execution startup was stopped.", "AbortError");
+      context.signal?.throwIfAborted();
+      return this.startReservation(Object.freeze({ ...context }));
+    });
+    void this.startup.catch(() => {
+    });
+    return this.startup.then((streams) => {
+      const stdout = streams.stdout;
+      const stdin = streams.stdin;
+      const stderr = streams.stderr;
+      return { ownership: "owned", stdout, stdin, ...stderr === void 0 ? {} : { stderr }, release: () => this.release() };
+    });
+  }
+  /** Actual release is unbounded here; one outer observation owns the full connection deadline. */
+  release() {
+    if (this.state === "released") return Promise.resolve();
+    this.state = "stopping";
+    if (this.releaseState.kind === "idle") this.beginRelease();
+    return this.releaseComplete.promise;
+  }
+  beginRelease() {
+    if (this.releaseState.kind === "running" || this.releaseState.kind === "complete") return;
+    const operation = Promise.withResolvers();
+    const actual = operation.promise.then(async () => {
+      await this.startup?.catch(() => void 0);
+      this.releaseState = { kind: "complete" };
+      this.releaseComplete.resolve();
+    }).catch((error) => {
+      this.releaseState = { kind: "failed", error };
+      this.failure = { error };
+      this.failureNotice.resolve(error);
+    });
+    this.releaseState = { kind: "running", actual };
+    try {
+      Promise.resolve(this.releaseReservation()).then(operation.resolve, operation.reject);
+    } catch (error) {
+      operation.reject(error);
+    }
+  }
+  cleanup() {
+    if (this.state === "released") return Promise.resolve();
+    this.state = "stopping";
+    if (this.observation) return this.observation;
+    const deadline = performance.now() + this.cleanupTimeoutMs;
+    this.failureNotice = Promise.withResolvers();
+    let initiate;
+    let actual = this.cleanupAttempt;
+    if (!actual) {
+      const operation = Promise.withResolvers();
+      actual = operation.promise.then(() => {
+        this.state = "released";
+        this.failure = void 0;
+        this.onDrained();
+      }).catch((error) => {
+        this.failure = { error };
+        this.cleanupAttempt = void 0;
+        throw error;
+      });
+      this.cleanupAttempt = actual;
+      initiate = () => {
+        try {
+          Promise.resolve(this.cleanupWork()).then(operation.resolve, operation.reject);
+        } catch (error) {
+          operation.reject(error);
+        }
+      };
+    }
+    const cleanup = actual;
+    this.observation = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new AcpProviderConnectionError(
+        "acp_node_execution_cleanup_timeout",
+        "The owned Node ACP execution cleanup exceeded its observation deadline."
+      )), Math.max(0, deadline - performance.now()));
+      cleanup.then(() => {
+        clearTimeout(timeout);
+        resolve();
+      }, (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+      this.failureNotice.promise.then((error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    }).catch((error) => {
+      this.failure ??= { error };
+      throw error;
+    }).finally(() => {
+      this.observation = void 0;
+    });
+    if (this.releaseState.kind === "failed") this.beginRelease();
+    initiate?.();
+    return this.observation;
+  }
+  retainedError(cause, cleanupError) {
+    return new NodeAcpExecutionCleanupError({ cause, cleanupError, retryCleanup: () => this.cleanup() });
+  }
+  joinCleanup() {
+    if (this.cleanupAttempt) return this.cleanupAttempt;
+    if (this.state === "released") return Promise.resolve();
+    return Promise.reject(this.failure?.error ?? new Error("Execution cleanup has not started."));
+  }
+}
+function executionReservationSource(boundary, input) {
+  const reserve = boundary?.reserve;
+  if (typeof reserve !== "function") throw new TypeError("A Node ACP execution boundary must provide a synchronous reserve method.");
+  const used = /* @__PURE__ */ new WeakSet();
+  return () => {
+    const reservation = Reflect.apply(reserve, boundary, [input]);
+    if (!reservation || typeof reservation !== "object" || "then" in reservation || used.has(reservation)) {
+      throw new TypeError("Execution reserve must return a fresh synchronous inert reservation.");
+    }
+    used.add(reservation);
+    return new NodeAcpExecutionOwner(reservation, 2 * input.shutdownTimeoutMs);
+  };
+}
+export {
+  NodeAcpExecutionOwner,
+  executionReservationSource
+};

package/dist/node/execution/types.d.ts

@@ -0,0 +1,20 @@
+import type { MaybePromise } from '@agen-ai/agent-runtime';
+import type { AcpConnectionFactoryContext, AcpConnectionStreams } from '../../contracts.js';
+export interface NodeAcpExecutionInput {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly shutdownTimeoutMs: number;
+}
+/** Reserve fresh inert state; resource acquisition and execution belong to start. */
+export interface NodeAcpExecutionBoundary {
+    readonly reserve: (input: NodeAcpExecutionInput) => NodeAcpExecutionReservation;
+}
+/** Own the workload before execution, including descendants in other groups or sessions. */
+export interface NodeAcpExecutionReservation {
+    readonly start: (context: AcpConnectionFactoryContext) => MaybePromise<AcpConnectionStreams>;
+    /** Fence startup, terminate and join the workload and streams; failed release remains retryable. */
+    readonly release: () => MaybePromise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/node/index.d.ts

@@ -1,6 +1,8 @@
 import type { AgentProviderDriver } from '@agen-ai/agent-runtime';
 import type { CreateNodeAcpProviderDriverOptions } from './contracts.js';
 export type { NodeAcpLaunchOptions, CreateNodeAcpProviderDriverOptions } from './contracts.js';
-/** Launches an owned POSIX process group. Windows hosts must supply an owned connection factory. */
+export type { NodeAcpExecutionInput, NodeAcpExecutionBoundary, NodeAcpExecutionReservation } from './execution/types.js';
+export { NodeAcpExecutionCleanupError, isNodeAcpExecutionCleanupError } from './execution/errors.js';
+/** Uses the supplied inert execution owner, or the default owned POSIX process-group launcher. */
 export declare function createNodeAcpProviderDriver(options: CreateNodeAcpProviderDriverOptions): AgentProviderDriver;
 //# sourceMappingURL=index.d.ts.map

package/dist/node/index.js

@@ -1,20 +1,30 @@
-import { createAcpProviderDriver } from "../driver.js";
-import { resolveNodeAcpLaunch } from "./launch.js";
+import { createAcpProviderDriverInternal } from "../driverFactory.js";
+import { resolveNodeAcpLaunch, resolveNodeAcpSessionInteractions } from "./launch.js";
 import { spawnAcpProcess } from "./process.js";
+import { executionReservationSource } from "./execution/owner.js";
+import { NodeAcpExecutionCleanupError, isNodeAcpExecutionCleanupError } from "./execution/errors.js";
 function createNodeAcpProviderDriver(options) {
   const launch = resolveNodeAcpLaunch(options.launch);
-  return createAcpProviderDriver({
+  const boundary = options.executionBoundary;
+  if (boundary === void 0 && Object.hasOwn(options, "executionBoundary")) throw new TypeError("An explicitly supplied execution boundary must be valid.");
+  const reserve = boundary === void 0 ? void 0 : executionReservationSource(boundary, launch);
+  const sessionInteractions = resolveNodeAcpSessionInteractions(options, launch);
+  if (sessionInteractions && !reserve) throw new TypeError("The Grok folder-trust mapping requires an exclusive descendant-owning execution boundary.");
+  return createAcpProviderDriverInternal({
     providerKey: options.providerKey,
-    createConnection: (context) => spawnAcpProcess(launch, context),
+    connectionSource: reserve ? { kind: "reserved", reserve } : { kind: "factory", create: (context) => spawnAcpProcess(launch, context) },
     ...options.unknownExtensionPolicy !== void 0 ? { unknownExtensionPolicy: options.unknownExtensionPolicy } : {},
+    ...options.permissionMapping !== void 0 ? { permissionMapping: options.permissionMapping } : {},
     ...options.limits ? { limits: options.limits } : {},
     ...options.configuration ? { configuration: options.configuration } : {},
     ...options.authentication ? { authentication: options.authentication } : {},
     ...options.host ? { host: options.host } : {},
     ...options.mcpServers ? { mcpServers: options.mcpServers } : {},
     ...options.sessionMcpBinding ? { sessionMcpBinding: options.sessionMcpBinding } : {}
-  });
+  }, sessionInteractions);
 }
 export {
-  createNodeAcpProviderDriver
+  NodeAcpExecutionCleanupError,
+  createNodeAcpProviderDriver,
+  isNodeAcpExecutionCleanupError
 };

package/dist/node/launch.d.ts

@@ -1,10 +1,7 @@
-import type { NodeAcpLaunchOptions } from './contracts.js';
-export interface ResolvedNodeAcpLaunch {
-    readonly executable: string;
-    readonly args: readonly string[];
-    readonly cwd: string;
-    readonly env: Readonly<Record<string, string>>;
-    readonly shutdownTimeoutMs: number;
-}
+import type { CreateNodeAcpProviderDriverOptions, NodeAcpLaunchOptions } from './contracts.js';
+import type { AcpSessionInteractionSelection } from '../sessionInteractions/contracts.js';
+import type { NodeAcpExecutionInput } from './execution/types.js';
+export type ResolvedNodeAcpLaunch = NodeAcpExecutionInput;
 export declare function resolveNodeAcpLaunch(launch: NodeAcpLaunchOptions): ResolvedNodeAcpLaunch;
+export declare function resolveNodeAcpSessionInteractions(options: CreateNodeAcpProviderDriverOptions, launch: ResolvedNodeAcpLaunch): AcpSessionInteractionSelection | undefined;
 //# sourceMappingURL=launch.d.ts.map

package/dist/node/launch.js

@@ -31,6 +31,18 @@ function resolveNodeAcpLaunch(launch) {
     shutdownTimeoutMs
   });
 }
+function resolveNodeAcpSessionInteractions(options, launch) {
+  const selection = options.sessionInteractions;
+  if (selection === void 0 && !Object.hasOwn(options, "sessionInteractions")) return void 0;
+  if (!selection || typeof selection !== "object" || Array.isArray(selection) || Reflect.ownKeys(selection).length !== 1 || !Object.hasOwn(selection, "mapping") || selection.mapping !== "grok-folder-trust-v1") {
+    throw new TypeError("ACP session interaction selection must name the supported mapping without additional fields.");
+  }
+  if (launch.args.length !== 3 || launch.args[0] !== "agent" || launch.args[1] !== "--no-leader" || launch.args[2] !== "stdio") {
+    throw new TypeError("The Grok folder-trust mapping requires exact direct arguments: agent --no-leader stdio.");
+  }
+  return Object.freeze({ mapping: "grok-folder-trust-v1" });
+}
 export {
-  resolveNodeAcpLaunch
+  resolveNodeAcpLaunch,
+  resolveNodeAcpSessionInteractions
 };

package/dist/permissions/contracts.d.ts

@@ -0,0 +1,22 @@
+export interface AcpPermissionOptionSignature {
+    readonly optionId: string;
+    readonly kind: 'allow_once' | 'reject_once' | 'allow_always' | 'reject_always';
+}
+export interface AcpPermissionMenuSignature {
+    readonly toolKind: 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+    readonly options: readonly [AcpPermissionOptionSignature, ...AcpPermissionOptionSignature[]];
+}
+/** Complete declarations attest that these exact menus add no unrepresented choice effects. */
+export type AcpPermissionMappingSelection = Readonly<{
+    mapping: 'once-only-v1';
+}> | Readonly<{
+    mapping: 'grok-build-1.0.50-edit-remembrance-v1';
+}> | Readonly<{
+    mapping: 'declared-complete-consequences-v1';
+    agentInfo: Readonly<{
+        name: string;
+        version: string;
+    }>;
+    menus: readonly [AcpPermissionMenuSignature, ...AcpPermissionMenuSignature[]];
+}>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/permissions/mapping.d.ts

@@ -0,0 +1,13 @@
+import type { AcpJsonObject } from '@agen-ai/acp-transport';
+import { type AgentApprovalOption } from '@agen-ai/agent-protocol';
+import type { AcpPermissionMappingSelection } from './contracts.js';
+export interface MappedPermissionOptions {
+    readonly options: readonly AgentApprovalOption[];
+    readonly nativeOptions: ReadonlyMap<string, string>;
+    readonly warning?: Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
+export declare function mapAcpPermissionOptions(selection: AcpPermissionMappingSelection, params: AcpJsonObject): MappedPermissionOptions;
+//# sourceMappingURL=mapping.d.ts.map