@automatalabs/acp-agents 0.8.0 → 0.9.0

package/dist/interactive.js

@@ -0,0 +1,139 @@
+import { appendPromptImages, mergeTurnMeta, validatePromptImages, } from "./prompt.js";
+/** A held-open multi-turn ACP session backed by a dedicated agent process. Only one prompt may
+ *  be in flight at a time; hosts that want queued turns should serialize calls themselves so
+ *  cancellation, permissions, and turn text stay attributable to a single active turn. If the
+ *  dedicated process dies, the runner observes that per session by auto-releasing this wrapper:
+ *  session-scoped listeners are removed, later prompt() calls fail with the released-session
+ *  error, and `session_close` is emitted on this session's event stream. The connection-scoped
+ *  `backend_error` event is emitted on the runner bus only; it is not delivered through
+ *  session.on(). */
+export class InteractiveSession {
+    sessionId;
+    backendId;
+    session;
+    connection;
+    backend;
+    subscribe;
+    onReleaseCallback;
+    signal;
+    label;
+    subscriptions = new Set();
+    removeAbort;
+    promptInFlight = false;
+    releasePromise;
+    /** Construct the public wrapper around an already-open ACP session. Hosts normally receive
+     *  instances from AcpAgentRunner.openSession(), which supplies the internal session/connection
+     *  dependencies and owns lifecycle tracking. */
+    constructor(deps) {
+        this.session = deps.session;
+        this.connection = deps.connection;
+        this.backend = deps.backend;
+        this.subscribe = deps.subscribe;
+        this.onReleaseCallback = deps.onRelease;
+        this.signal = deps.signal;
+        this.label = deps.label;
+        this.sessionId = deps.session.sessionId;
+        this.backendId = deps.connection.backendId;
+        if (deps.signal) {
+            const signal = deps.signal;
+            const onAbort = () => {
+                void this.release();
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            this.removeAbort = () => signal.removeEventListener("abort", onAbort);
+            if (signal.aborted)
+                void this.release();
+        }
+    }
+    /** Negotiated initialize capabilities for this session's dedicated connection. */
+    get capabilities() {
+        return this.connection.capabilities;
+    }
+    /** Send one prompt turn. A concurrent prompt on the same InteractiveSession is rejected with a
+     *  clear host-side error; queueing is deliberately left to the host so turn boundaries remain
+     *  explicit. Per-turn images are appended only to this prompt, and SessionHandle.prompt()
+     *  performs capability adaptation before sending. */
+    async prompt(content, opts = {}) {
+        if (this.releasePromise)
+            throw new Error("InteractiveSession has been released");
+        this.signal?.throwIfAborted();
+        if (this.promptInFlight) {
+            throw new Error("InteractiveSession.prompt() already has a prompt in flight; await it before sending another turn");
+        }
+        validatePromptImages(opts.images, this.label);
+        this.promptInFlight = true;
+        try {
+            const turnContent = appendPromptImages(content, opts.images);
+            const promptMeta = mergeTurnMeta(opts.promptMeta, this.backend.promptMeta(undefined));
+            const response = await this.session.prompt(turnContent, promptMeta);
+            return {
+                stopReason: response.stopReason,
+                text: this.session.currentTurnText(),
+            };
+        }
+        finally {
+            this.promptInFlight = false;
+        }
+    }
+    /** Best-effort ACP session/cancel for the active turn. Pending permission resolvers are
+     *  settled as cancelled by the SessionHandle/PooledConnection cancel path. */
+    async cancel() {
+        if (this.releasePromise)
+            return;
+        await this.session.cancel();
+    }
+    /** Subscribe to runner events for THIS ACP session only. Events from other one-shot or
+     *  interactive sessions on the same runner are filtered out by sessionId. The returned
+     *  unsubscribe thunk and every still-live subscription are removed automatically on release. */
+    on(name, listener) {
+        if (this.releasePromise)
+            return () => { };
+        const wrapped = (event) => {
+            if (event.sessionId === this.sessionId)
+                listener(event);
+        };
+        const removeRunnerListener = this.subscribe(name, wrapped);
+        let active = true;
+        const off = () => {
+            if (!active)
+                return;
+            active = false;
+            removeRunnerListener();
+            this.subscriptions.delete(off);
+        };
+        this.subscriptions.add(off);
+        return off;
+    }
+    /** Release the ACP session and close the dedicated process. Idempotent. Session close is
+     *  best-effort and bounded by SessionHandle; process disposal mirrors pool teardown. */
+    release() {
+        this.releasePromise ??= this.doRelease();
+        return this.releasePromise;
+    }
+    async doRelease() {
+        this.removeAbort?.();
+        this.removeAbort = undefined;
+        try {
+            await this.session.release();
+        }
+        catch {
+            // best-effort: release must still dispose the dedicated process and unregister.
+        }
+        try {
+            await this.connection.dispose();
+        }
+        catch {
+            // best-effort: mirrors pool disposal semantics.
+        }
+        finally {
+            this.removeSubscriptions();
+            this.onReleaseCallback(this);
+        }
+    }
+    removeSubscriptions() {
+        const subscriptions = [...this.subscriptions];
+        for (const off of subscriptions)
+            off();
+        this.subscriptions.clear();
+    }
+}

package/dist/permissions.d.ts

@@ -1,4 +1,13 @@
 import type { RequestPermissionRequest, RequestPermissionResponse } from "@agentclientprotocol/sdk";
+import type { AcpEventContext } from "./events.js";
+/** Async human-in-the-loop decider for ACP permission requests. When present, it REPLACES the
+ *  synchronous ToolPolicy path for the sessions it applies to: the agent turn parks until this
+ *  resolver selects an ACP permission outcome. It may resolve arbitrarily later (seconds or
+ *  minutes); the library guarantees every parked request is settled with the ACP
+ *  `{ outcome: { outcome: "cancelled" } }` response when its session is released, its turn is
+ *  cancelled via session/cancel, or its connection dies, so teardown can never leave an agent
+ *  turn hung behind an unanswered permission prompt. */
+export type PermissionResolver = (params: RequestPermissionRequest, ctx: AcpEventContext) => Promise<RequestPermissionResponse> | RequestPermissionResponse;
 export interface ToolPolicy {
     /** Allow-list (agentType `tools`). When non-empty, a tool that matches NOTHING is denied. */
     allow?: string[];

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAqC3B"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;wDAMwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,wBAAwB,EAChC,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,yBAAyB,CAAC,GAAG,yBAAyB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAKD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,UAAU,GACjB,yBAAyB,CAqC3B"}

package/dist/pool.d.ts

@@ -2,6 +2,7 @@ import type { Backend } from "./backend.js";
 import { SessionHandle, type AcpSessionOptions } from "./acp-client.js";
 import { type ClientHandlers } from "./client-handlers.js";
 import type { AcpEventSink } from "./events.js";
+import type { PermissionResolver } from "./permissions.js";
 export interface AcpPoolOptions {
     /** Long-lived processes to keep PER backend. Default 1; falls back to AGENTPRISM_ACP_POOL_SIZE. */
     size?: number;
@@ -9,9 +10,10 @@ export interface AcpPoolOptions {
     clientHandlers?: ClientHandlers;
 }
 /** Internal wiring the runner injects (NOT part of the public AcpPoolOptions surface): the typed
- *  event sink forwarded to every PooledConnection so ACP events bubble up to `runner.on(...)`. */
+ *  event sink and runner-default permission resolver forwarded to every PooledConnection. */
 export interface AcpPoolDeps {
     onEvent?: AcpEventSink;
+    permissionResolver?: PermissionResolver;
 }
 /** Resolve the per-backend pool size: explicit option wins, else env, else 1. Clamped to >= 1. */
 export declare function resolvePoolSize(option?: number): number;

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAoB,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;kGACkG;AAClG,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAOzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAyBxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAoB,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4FAA4F;IAC5F,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;6FAC6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IAUrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IATvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAOzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}

package/dist/pool.js

@@ -55,6 +55,7 @@ export class AcpAgentPool {
             const connection = PooledConnection.create(backend, {
                 onDead: (dead) => this.drop(key, dead),
                 onEvent: this.deps.onEvent,
+                permissionResolver: this.deps.permissionResolver,
                 clientHandlers: this.clientHandlers,
             });
             connections.push(connection);

package/dist/prompt.d.ts

@@ -0,0 +1,21 @@
+import type { ContentBlock } from "@agentclientprotocol/sdk";
+import { type PromptImage } from "@automatalabs/shared-types";
+import type { TSchema } from "typebox";
+import type { Backend } from "./backend.js";
+/** Build the exact one-shot run() prompt text: optional engine instructions, a diagnostic label,
+ *  the user prompt, and (for schema runs) the backend-appropriate final-output contract. */
+export declare function buildRunPrompt(prompt: string, opts: {
+    instructions?: string;
+    label?: string;
+}, schema: TSchema | undefined, backend: Backend): string;
+/** Validate prompt images before spawning/sending. Invalid images are deterministic script
+ *  errors, never provider failures, and the bad index is part of the contract for callers. */
+export declare function validatePromptImages(images: readonly PromptImage[] | undefined, label?: string): void;
+/** One-shot run() image shape: the text prompt first, then each image attachment. */
+export declare function promptWithImages(text: string, images: readonly PromptImage[]): ContentBlock[];
+/** Interactive prompt image shape: string prompts match run(); ContentBlock prompts keep the
+ *  caller's blocks and append this turn's image attachments. */
+export declare function appendPromptImages(content: string | ContentBlock[], images: readonly PromptImage[] | undefined): string | ContentBlock[];
+/** Merge generic turn-scoped `_meta` UNDER the backend-computed turn meta. */
+export declare function mergeTurnMeta(user: Record<string, unknown> | undefined, backend: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C;4FAC4F;AAC5F,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/C,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,OAAO,EAAE,OAAO,GACf,MAAM,CAoBR;AAED;8FAC8F;AAC9F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0BrG;AAgBD,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,YAAY,EAAE,CAE7F;AAED;gEACgE;AAChE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,EAChC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,GACzC,MAAM,GAAG,YAAY,EAAE,CAIzB;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGrC"}

package/dist/prompt.js

@@ -0,0 +1,75 @@
+import { WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
+import { toJsonSchema } from "./schema-strict.js";
+/** Build the exact one-shot run() prompt text: optional engine instructions, a diagnostic label,
+ *  the user prompt, and (for schema runs) the backend-appropriate final-output contract. */
+export function buildRunPrompt(prompt, opts, schema, backend) {
+    const parts = [];
+    if (opts.instructions)
+        parts.push(opts.instructions);
+    if (opts.label)
+        parts.push(`Task label: ${opts.label}`);
+    parts.push(prompt);
+    if (schema) {
+        const contract = [
+            "Final output contract:",
+            "- Your FINAL message MUST be a single JSON object that conforms to the required output schema.",
+            "- Output ONLY that JSON object — no prose, no explanation, and no markdown code fences.",
+            "- If you need to inspect files or run commands first, do so, then emit the JSON object as your final message.",
+        ];
+        if (backend.embedSchemaInPrompt) {
+            // Custom ACP agents may ignore `_meta.outputSchema`; state the schema in-band so the
+            // repair ladder is correcting against a visible contract, not an unseen extension key.
+            contract.push(`- The required output schema (JSON Schema):\n${JSON.stringify(toJsonSchema(schema))}`);
+        }
+        parts.push(contract.join("\n"));
+    }
+    return parts.join("\n\n");
+}
+/** Validate prompt images before spawning/sending. Invalid images are deterministic script
+ *  errors, never provider failures, and the bad index is part of the contract for callers. */
+export function validatePromptImages(images, label) {
+    if (!images || images.length === 0)
+        return;
+    for (let i = 0; i < images.length; i += 1) {
+        const image = images[i];
+        if (typeof image?.data !== "string" || image.data.trim() === "") {
+            throw new WorkflowError(`images[${i}].data must be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+        if (typeof image.mimeType !== "string" || image.mimeType.trim() === "") {
+            throw new WorkflowError(`images[${i}].mimeType must be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+        if (image.uri !== undefined && (typeof image.uri !== "string" || image.uri.trim() === "")) {
+            throw new WorkflowError(`images[${i}].uri must be a non-empty string when present`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+    }
+}
+/** Convert base64 image attachments to ACP image ContentBlocks without capability adaptation.
+ *  SessionHandle.prompt() performs the advertised-capability downgrade at send time. */
+function imageContentBlocks(images) {
+    const blocks = [];
+    for (const image of images) {
+        blocks.push(image.uri === undefined
+            ? { type: "image", data: image.data, mimeType: image.mimeType }
+            : { type: "image", data: image.data, mimeType: image.mimeType, uri: image.uri });
+    }
+    return blocks;
+}
+/** One-shot run() image shape: the text prompt first, then each image attachment. */
+export function promptWithImages(text, images) {
+    return [{ type: "text", text }, ...imageContentBlocks(images)];
+}
+/** Interactive prompt image shape: string prompts match run(); ContentBlock prompts keep the
+ *  caller's blocks and append this turn's image attachments. */
+export function appendPromptImages(content, images) {
+    if (!images || images.length === 0)
+        return content;
+    if (typeof content === "string")
+        return promptWithImages(content, images);
+    return [...content, ...imageContentBlocks(images)];
+}
+/** Merge generic turn-scoped `_meta` UNDER the backend-computed turn meta. */
+export function mergeTurnMeta(user, backend) {
+    if (!user)
+        return backend;
+    return { ...user, ...(backend ?? {}) };
+}

package/dist/runner.d.ts

@@ -3,31 +3,48 @@ import type { TSchema } from "typebox";
 import { type AcpPoolOptions } from "./pool.js";
 import { type AcpEventListener, type AcpEventName } from "./events.js";
 import type { Backend } from "./backend.js";
+import { InteractiveSession, type InteractiveSessionOptions } from "./interactive.js";
 import { type BackendRegistry, type CustomBackendConfig } from "./registry.js";
+import type { PermissionResolver } from "./permissions.js";
 /** Constructor options for the runner: pool sizing, client-side handlers, and the custom-backend
  *  registry. `backends` merges over (and wins against) env-declared AGENTPRISM_BACKENDS entries. */
 export interface AcpRunnerOptions extends AcpPoolOptions {
     /** Custom ACP backends, keyed by registered name (see registry.ts for the config shape
      *  and the routing rules). Names are case-insensitive; "claude"/"codex" are reserved. */
     backends?: Record<string, CustomBackendConfig>;
+    /** Runner-wide human-in-the-loop permission resolver. When set, it replaces ToolPolicy
+     *  auto-decisions for every session that does not provide its own resolver. */
+    onPermissionRequest?: PermissionResolver;
 }
 export declare class AcpAgentRunner implements AgentRunner {
     private readonly pool;
     /** The resolved custom-backend registry (env + option, validated at construction). */
     private readonly backends;
-    /** Typed bus carrying every ACP event from every pooled session. Beyond the AgentRunner seam
-     *  (additive observability) — subscribing never affects a run and never enters the resume hash. */
+    /** Typed bus carrying every ACP event from every pooled or interactive session. Beyond the
+     *  AgentRunner seam (additive observability) — subscribing never affects a run and never enters
+     *  the resume hash. */
     private readonly events;
     private readonly emitEvent;
+    /** Client-side handlers and the runner-wide permission resolver are initialize/session wiring,
+     *  so dedicated interactive connections must receive the SAME deps the pool receives. */
+    private readonly clientHandlers;
+    private readonly permissionResolver;
+    /** 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(). */
+    private readonly interactiveSessions;
+    private readonly onProcessExit;
+    private exitHookInstalled;
+    private disposed;
     constructor(options?: AcpRunnerOptions);
     /**
      * 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_request", "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 best-effort observers:
-     * a throwing listener is isolated and never affects the run.
+     * ("session_update" catch-all, "permission_pending", "permission_request", "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
+     * best-effort observers: a throwing listener is isolated and never affects the run.
      */
     on<K extends AcpEventName>(name: K, listener: AcpEventListener<K>): () => void;
     /** Subscribe once; the listener auto-unsubscribes after its first delivery. */
@@ -35,10 +52,25 @@ export declare class AcpAgentRunner implements AgentRunner {
     off<K extends AcpEventName>(name: K, listener: AcpEventListener<K>): void;
     removeAllListeners(name?: AcpEventName): void;
     listenerCount(name: AcpEventName): number;
+    /**
+     * Open a held ACP session for multi-turn callers. Unlike run(), this does NOT acquire a pool
+     * slot: it spawns one dedicated backend process, opens one ACP session on it, and hands the
+     * caller an InteractiveSession that must be released. The dedicated process means a long-lived
+     * chat/debug loop never starves one-shot run() calls on the same backend (the default pool size
+     * is one).
+     */
+    openSession(opts: InteractiveSessionOptions): Promise<InteractiveSession>;
     run<S extends TSchema | undefined = undefined>(prompt: string, options?: RunOptions<S>): Promise<AgentResult<S>>;
     /** Tear down the whole pool (close every long-lived process). Call when the run ends / the
      *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */
     dispose(): Promise<void>;
+    /** 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. */
+    private prepareSession;
+    private installExitHook;
+    private removeExitHook;
+    /** Synchronous best-effort child kill for the process-exit hook (no async work is possible). */
+    private killAllSync;
 }
 /** Factory the mcp-server composition root calls to inject the runner into the engine. The pool
  *  size and the custom-backend registry are runner-level options — NOT RunOptions fields, so they

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAQvB;oGACoG;AACpG,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;6FACyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAChD;AAED,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C;uGACmG;IACnG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;gBAE9E,OAAO,GAAE,gBAAqB;IAK1C;;;;;;;;OAQG;IACH,EAAE,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI9E,+EAA+E;IAC/E,IAAI,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIhF,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIzE,kBAAkB,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAI7C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAInC,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA8G1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;;qDAGqD;AACrD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAE1E;AA2HD;;;;oCAIoC;AACpC,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAM1G"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}