@automatalabs/acp-agents 0.13.0 → 0.15.0

package/dist/runner.js

@@ -42,6 +42,7 @@ export class AcpAgentRunner {
      *  so dedicated interactive connections must receive the SAME deps the pool receives. */
     clientHandlers;
     permissionResolver;
+    elicitationResolver;
     /** Held-open interactive sessions own dedicated ACP processes outside the pool. The runner
      *  tracks their connections so dispose() can release them and the process-exit hook can
      *  synchronously kill any dedicated children if the host exits without release(). */
@@ -52,16 +53,20 @@ export class AcpAgentRunner {
     constructor(options = {}) {
         this.clientHandlers = options.clientHandlers;
         this.permissionResolver = options.onPermissionRequest;
+        this.elicitationResolver = options.onElicitation;
         this.pool = new AcpAgentPool(options, {
             onEvent: this.emitEvent,
             permissionResolver: options.onPermissionRequest,
+            elicitationResolver: options.onElicitation,
+            advertiseElicitation: Boolean(options.onElicitation),
         });
         this.backends = resolveBackendRegistry(options.backends);
     }
     /**
      * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
      * ("agent_message_chunk", "tool_call", "usage_update", …) or one of the cross-cutting events
-     * ("session_update" catch-all, "permission_pending", "permission_request", "raw_message",
+     * ("session_update" catch-all, "permission_pending", "permission_request",
+     * "elicitation_pending", "elicitation_request", "elicitation_complete", "raw_message",
      * "session_open", "session_close", "backend_error"). The listener is typed to the event.
      * Returns an unsubscribe thunk. A pooled runner multiplexes many concurrent runs, so each
      * event carries `{ sessionId, backendId, label?, runId? }` for filtering. Listeners are
@@ -91,70 +96,66 @@ export class AcpAgentRunner {
      * is one).
      */
     async openSession(opts) {
+        return this.createInteractiveSession(opts, "openSession", (connection, prepared) => connection.openSession(prepared.sessionOptions));
+    }
+    /** List persisted ACP sessions from the selected backend. */
+    async listSessions(opts = {}) {
         if (this.disposed)
             throw new Error("ACP agent runner is disposed");
-        validateInteractiveCwd(opts.cwd, opts.label);
+        validateOptionalLifecycleCwd(opts.cwd, opts.label, "listSessions");
         opts.signal?.throwIfAborted();
-        const prepared = this.prepareSession(opts, {
-            cwd: opts.cwd,
-            schema: undefined,
-            registry: this.backends,
-            permissionResolver: opts.onPermissionRequest,
-            retainSessionLog: false,
-        });
-        this.installExitHook();
-        let interactive;
-        const connection = PooledConnection.create(prepared.backend, {
-            onDead: () => {
-                // Dedicated connections are not stored in pool arrays, so there is nothing to evict.
-                // Once the public wrapper exists, process death releases it through the normal path:
-                // subscriptions are removed, session_close is emitted, and future prompt() calls fail
-                // with the clean released-session error. Before then, openSession's catch tears down.
-                void interactive?.release();
-            },
-            onEvent: this.emitEvent,
-            permissionResolver: this.permissionResolver,
-            clientHandlers: this.clientHandlers,
-        });
-        let session;
+        const backend = selectBackend(opts, this.backends);
+        const connection = this.createDedicatedConnection(backend, () => undefined);
         try {
-            session = await connection.openSession(prepared.sessionOptions);
+            const request = {
+                ...(opts.cwd ? { cwd: opts.cwd } : {}),
+                ...(opts.cursor ? { cursor: opts.cursor } : {}),
+                ...(opts.meta ? { _meta: opts.meta } : {}),
+            };
+            const response = await connection.listSessions(request, opts.label);
             opts.signal?.throwIfAborted();
-            await applyModelSelection(session, prepared.modelSpec, opts);
-            opts.signal?.throwIfAborted();
-            if (opts.mode)
-                await session.setMode(opts.mode);
+            if (this.disposed)
+                throw new Error("ACP agent runner is disposed");
+            return response;
+        }
+        finally {
+            await disposeBestEffort(connection);
+        }
+    }
+    /** Delete a persisted ACP session from the selected backend. */
+    async deleteSession(opts) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        if (typeof opts.sessionId !== "string" || opts.sessionId.trim() === "") {
+            throw new WorkflowError("deleteSession requires sessionId to be a non-empty string", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
+        }
+        opts.signal?.throwIfAborted();
+        const backend = selectBackend(opts, this.backends);
+        const connection = this.createDedicatedConnection(backend, () => undefined);
+        try {
+            const request = {
+                sessionId: opts.sessionId,
+                ...(opts.meta ? { _meta: opts.meta } : {}),
+            };
+            await connection.deleteSession(request, opts.label);
             opts.signal?.throwIfAborted();
             if (this.disposed)
                 throw new Error("ACP agent runner is disposed");
-            interactive = new InteractiveSession({
-                session,
-                connection,
-                backend: prepared.backend,
-                subscribe: (name, listener) => this.events.on(name, listener),
-                onRelease: (self) => this.interactiveSessions.delete(self),
-                signal: opts.signal,
-                label: opts.label,
-            });
-            this.interactiveSessions.set(interactive, connection);
-            return interactive;
         }
-        catch (error) {
-            try {
-                await session?.release();
-            }
-            catch {
-                // best-effort: openSession failed, so teardown must never mask the real error.
-            }
-            try {
-                await connection.dispose();
-            }
-            catch {
-                // best-effort: same as pool teardown.
-            }
-            throw error;
+        finally {
+            await disposeBestEffort(connection);
         }
     }
+    /** Load an existing ACP session and return a live, routed InteractiveSession. */
+    async loadSession(opts) {
+        validateLifecycleSessionId(opts.sessionId, opts.label, "loadSession");
+        return this.createInteractiveSession(opts, "loadSession", (connection, prepared) => connection.loadSession(opts.sessionId, prepared.sessionOptions));
+    }
+    /** Resume an existing ACP session without replay and return a live, routed InteractiveSession. */
+    async resumeSession(opts) {
+        validateLifecycleSessionId(opts.sessionId, opts.label, "resumeSession");
+        return this.createInteractiveSession(opts, "resumeSession", (connection, prepared) => connection.resumeSession(opts.sessionId, prepared.sessionOptions));
+    }
     async run(prompt, options = {}) {
         const opts = options;
         const schema = opts.schema;
@@ -266,6 +267,72 @@ export class AcpAgentRunner {
         await this.pool.dispose();
         this.events.removeAllListeners();
     }
+    async createInteractiveSession(opts, methodName, open) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        validateInteractiveCwd(opts.cwd, opts.label, methodName);
+        opts.signal?.throwIfAborted();
+        const prepared = this.prepareSession(opts, {
+            cwd: opts.cwd,
+            schema: undefined,
+            registry: this.backends,
+            permissionResolver: opts.permissionResolver ?? opts.onPermissionRequest,
+            elicitationResolver: opts.onElicitation,
+            retainSessionLog: opts.retainSessionLog ?? false,
+        });
+        this.installExitHook();
+        let interactive;
+        const connection = this.createDedicatedConnection(prepared.backend, () => {
+            // Dedicated connections are not stored in pool arrays, so there is nothing to evict.
+            // Once the public wrapper exists, process death releases it through the normal path:
+            // subscriptions are removed, session_close is emitted, and future prompt() calls fail
+            // with the clean released-session error. Before then, this method's catch tears down.
+            void interactive?.release();
+        });
+        let session;
+        try {
+            session = await open(connection, prepared);
+            opts.signal?.throwIfAborted();
+            await applyModelSelection(session, prepared.modelSpec, opts);
+            opts.signal?.throwIfAborted();
+            if (opts.mode)
+                await session.setMode(opts.mode);
+            opts.signal?.throwIfAborted();
+            if (this.disposed)
+                throw new Error("ACP agent runner is disposed");
+            interactive = new InteractiveSession({
+                session,
+                connection,
+                backend: prepared.backend,
+                subscribe: (name, listener) => this.events.on(name, listener),
+                onRelease: (self) => this.interactiveSessions.delete(self),
+                signal: opts.signal,
+                label: opts.label,
+            });
+            this.interactiveSessions.set(interactive, connection);
+            return interactive;
+        }
+        catch (error) {
+            try {
+                await session?.release();
+            }
+            catch {
+                // best-effort: lifecycle setup failed, so teardown must never mask the real error.
+            }
+            await disposeBestEffort(connection);
+            throw error;
+        }
+    }
+    createDedicatedConnection(backend, onDead) {
+        return PooledConnection.create(backend, {
+            onDead,
+            onEvent: this.emitEvent,
+            permissionResolver: this.permissionResolver,
+            elicitationResolver: this.elicitationResolver,
+            advertiseElicitation: Boolean(this.elicitationResolver),
+            clientHandlers: this.clientHandlers,
+        });
+    }
     /** Build the backend choice, model-selection spec, tool policy, and session/new options in one
      *  place for run() and openSession() so new AcpSessionOptions fields cannot drift by path. */
     prepareSession(opts, config) {
@@ -284,6 +351,7 @@ export class AcpAgentRunner {
                 schema: config.schema,
                 policy,
                 permissionResolver: config.permissionResolver,
+                elicitationResolver: config.elicitationResolver,
                 signal: config.signal,
                 mcpServers: opts.mcpServers,
                 // Generic session-scoped _meta passthrough (RunOptions.meta) — merged UNDER the
@@ -412,9 +480,27 @@ function innerModelSpec(spec, backend) {
 }
 /** Interactive sessions are public and long-lived, so fail before spawning a dedicated process
  *  when the required worktree root is absent or not absolute. */
-function validateInteractiveCwd(cwd, label) {
+function validateInteractiveCwd(cwd, label, methodName) {
     if (typeof cwd !== "string" || cwd.trim() === "" || !isAbsolute(cwd)) {
-        throw new WorkflowError("openSession requires cwd to be a non-empty absolute path", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        throw new WorkflowError(`${methodName} requires cwd to be a non-empty absolute path`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+    }
+}
+function validateOptionalLifecycleCwd(cwd, label, methodName) {
+    if (cwd === undefined || cwd === null)
+        return;
+    validateInteractiveCwd(cwd, label, methodName);
+}
+function validateLifecycleSessionId(sessionId, label, methodName) {
+    if (typeof sessionId !== "string" || sessionId.trim() === "") {
+        throw new WorkflowError(`${methodName} requires sessionId to be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+    }
+}
+async function disposeBestEffort(connection) {
+    try {
+        await connection.dispose();
+    }
+    catch {
+        // Dedicated lifecycle processes are already no longer useful; never mask the request result.
     }
 }
 function backendIdForSpec(spec) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"