@agen-ai/provider-acp 0.4.0 → 0.4.2

package/dist/host/router.js

@@ -11,12 +11,11 @@ class AcpHostRouter {
     this.interactions = new AcpHostInteractions(input);
     this.terminals = new AcpHostTerminals(input.host, input.limits);
   }
-  input;
   interactions;
   terminals;
   requests = /* @__PURE__ */ new Map();
   binding;
-  pending = 0;
+  pending = /* @__PURE__ */ new Map();
   bytes = 0;
   bindSession(binding) {
     if (this.binding && (binding.nativeSessionId !== this.binding.nativeSessionId || binding.sessionId !== this.binding.sessionId || binding.workingDirectory !== this.binding.workingDirectory)) {
@@ -55,32 +54,27 @@ class AcpHostRouter {
     };
   }
   admit(context) {
+    const params = hostObject(context.params);
+    if (context.method === "session/request_permission" || context.method === "elicitation/create" && Object.hasOwn(params, "sessionId")) return this.route(context, params);
     const bytes = Buffer.byteLength(JSON.stringify(context.params), "utf8");
-    if (this.pending >= this.input.limits.maxPendingRequests || this.bytes + bytes > this.input.limits.maxQueuedBytes) {
+    if (this.pending.size >= this.input.limits.maxPendingRequests || this.bytes + bytes > this.input.limits.maxQueuedBytes) {
       throw new AcpRpcHandlerError(-32603, "The host request capacity was exceeded.");
     }
-    this.pending += 1;
     this.bytes += bytes;
-    let result;
-    try {
-      result = this.route(context);
-    } catch (error) {
-      this.pending -= 1;
+    const retirement = context.settled.then(() => this.interactions.joinRequest(context.settled)).then(() => {
+      this.pending.delete(context.settled);
       this.bytes -= bytes;
-      throw error;
-    }
+    });
+    this.pending.set(context.settled, retirement);
+    const result = this.route(context, params);
     return result.then((value) => {
       if (Buffer.byteLength(JSON.stringify(value), "utf8") > Math.min(this.input.limits.maxQueuedBytes, 8 * 1024 * 1024) - 512) {
         throw invalidHostRequest();
       }
       return value;
-    }).finally(() => {
-      this.pending -= 1;
-      this.bytes -= bytes;
     });
   }
-  route(context) {
-    const params = hostObject(context.params);
+  route(context, params) {
     if (context.method === "elicitation/create") {
       const session2 = Object.hasOwn(params, "sessionId");
       const request = Object.hasOwn(params, "requestId");
@@ -144,20 +138,28 @@ class AcpHostRouter {
     const id = hostText(hostObject(value).elicitationId, 256);
     return this.interactions.complete(id);
   }
-  sessionElicitation(context) {
+  sessionElicitation(context, observeCallback) {
     const bound = this.requireSession(hostObject(context.params), context.signal);
     return this.interactions.request(context, {
       kind: "session",
       sessionId: bound.sessionId,
       workingDirectory: bound.workingDirectory
-    }, context.signal);
+    }, context.signal, observeCallback);
   }
   async close() {
     for (const request of this.requests.values()) request.abort();
     this.requests.clear();
-    const results = await Promise.allSettled([this.interactions.close(), this.terminals.close()]);
-    const failures = results.filter((result) => result.status === "rejected");
-    if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP host facility cleanup failed.");
+    const deadline = hostDeadline(new AbortController().signal, this.input.limits.hostOperationTimeoutMs);
+    const join = async () => {
+      while (this.pending.size > 0) await Promise.all(this.pending.values());
+    };
+    try {
+      const results = await Promise.allSettled([this.interactions.close(), this.terminals.close(), awaitHost(join(), deadline.signal)]);
+      const failures = results.filter((result) => result.status === "rejected");
+      if (failures.length) throw new AggregateError(failures.map((result) => result.reason), "ACP host facility cleanup failed.");
+    } finally {
+      deadline.close();
+    }
   }
 }
 export {

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

package/dist/instance.js

@@ -6,7 +6,9 @@ import {
   createAgentProviderReadiness,
   createAgentProviderSessionCleanupError,
   isAgentProviderSessionCleanupErrorFor,
-  throwIfAgentOperationAborted
+  throwIfAgentOperationAborted,
+  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 +19,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 +53,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 +71,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 +80,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 +91,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 +133,16 @@ async function createAcpProviderInstance(input) {
   const open = async (context, resume) => {
     throwIfAgentOperationAborted(context.signal);
     throwIfAgentOperationAborted(lifetime.signal);
+    if (input.sessionInteractions?.mapping === "grok-folder-trust-v1" && resume) throw new AgentProviderContractError(
+      input.providerKey,
+      "session_interactions_unsupported",
+      "The selected ACP session interaction mapping supports creation only."
+    );
+    if (input.sessionInteractions && (input.sessionInteractions.mapping === "grok-folder-trust-v1" || resume) && 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 +168,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,32 +195,39 @@ 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: {
             binding: parsed.binding,
-            method: sessionCapabilities?.resume != null ? "session/resume" : "session/load"
+            method: input.sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1" ? "session/load" : sessionCapabilities?.resume != null ? "session/resume" : "session/load"
           } } : {},
           mcpServers,
           connection,
           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;
+        if (context.interactions) 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 +250,34 @@ async function createAcpProviderInstance(input) {
       creatingIds.delete(parsed.sessionId);
     }
   };
+  const adapter = Object.freeze({
+    ...input.sessionInteractions ? { sessionInteractions: Object.freeze({
+      kind: "supported",
+      mappings: input.sessionInteractions.mapping === "grok-folder-trust-v1" ? Object.freeze([Object.freeze({ openingOperation: "create", requestKind: "decision" })]) : Object.freeze([Object.freeze({ openingOperation: "resume", requestKind: "plan_review" })]),
+      producerOwnership: "exclusive",
+      humanWait: Object.freeze(["bounded", "until_withdrawn_or_closed"])
+    }) } : {},
+    ...input.sessionInteractions?.mapping === "grok-build-1.0.60-session-requests-v1" ? {
+      nativeContinuations: Object.freeze({
+        kind: "supported",
+        producerOwnership: "exclusive",
+        mappings: Object.freeze([Object.freeze({
+          openingOperation: "resume",
+          requestKind: "plan_review",
+          timing: "after_open_return"
+        })])
+      })
+    } : {},
+    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,
     accountQuota: { kind: "unsupported" },
     environment: { kind: "unsupported" },
     checkReadiness(check = {}) {
@@ -217,18 +292,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 +320,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 direct native executable, exact no-leader arguments and a handler for each selected opening tuple. */
+    readonly sessionInteractions?: Readonly<{
+        readonly mapping: 'grok-folder-trust-v1' | 'grok-build-1.0.60-session-requests-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
+};