@automatalabs/acp-agents 0.7.0 → 0.9.0

package/dist/runner.js

@@ -16,36 +16,56 @@
 //
 // Timeout and abort are the ENGINE's job: we honor opts.signal (wired to ACP session/cancel)
 // and re-throw on abort, but never implement our own timeout.
+import { isAbsolute } from "node:path";
 import { WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
+import { PooledConnection } from "./acp-client.js";
 import { AcpAgentPool } from "./pool.js";
 import { TypedEventEmitter, } from "./events.js";
+import { InteractiveSession } from "./interactive.js";
 import { ClaudeBackend } from "./backends/claude.js";
 import { CodexBackend } from "./backends/codex.js";
 import { CustomAcpBackend } from "./backends/custom.js";
 import { registryWithRunBackends, resolveBackendRegistry, } from "./registry.js";
 import { mapThrownError } from "./errors-map.js";
-import { toJsonSchema } from "./schema-strict.js";
 import { resolveStructuredOutput } from "./structured-output.js";
+import { buildRunPrompt, mergeTurnMeta, promptWithImages, validatePromptImages, } from "./prompt.js";
 export class AcpAgentRunner {
     pool;
     /** The resolved custom-backend registry (env + option, validated at construction). */
     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. */
     events = new TypedEventEmitter();
     emitEvent = (name, event) => this.events.emit(name, event);
+    /** 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. */
+    clientHandlers;
+    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(). */
+    interactiveSessions = new Map();
+    onProcessExit = () => this.killAllSync();
+    exitHookInstalled = false;
+    disposed = false;
     constructor(options = {}) {
-        this.pool = new AcpAgentPool(options, { onEvent: this.emitEvent });
+        this.clientHandlers = options.clientHandlers;
+        this.permissionResolver = options.onPermissionRequest;
+        this.pool = new AcpAgentPool(options, {
+            onEvent: this.emitEvent,
+            permissionResolver: options.onPermissionRequest,
+        });
         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_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(name, listener) {
         return this.events.on(name, listener);
@@ -63,6 +83,75 @@ export class AcpAgentRunner {
     listenerCount(name) {
         return this.events.listenerCount(name);
     }
+    /**
+     * 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).
+     */
+    async openSession(opts) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        validateInteractiveCwd(opts.cwd, opts.label);
+        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;
+        try {
+            session = await connection.openSession(prepared.sessionOptions);
+            opts.signal?.throwIfAborted();
+            await applyModelSelection(session, prepared.modelSpec, opts);
+            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;
+        }
+    }
     async run(prompt, options = {}) {
         const opts = options;
         const schema = opts.schema;
@@ -79,38 +168,27 @@ export class AcpAgentRunner {
                 agentLabel: opts.label,
             });
         }
-        const backend = selectBackend(opts, registry);
-        const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
         const cwd = opts.cwd ?? process.cwd();
-        const session = await this.pool.acquire(backend, {
+        validatePromptImages(opts.images, opts.label);
+        const prepared = this.prepareSession(opts, {
             cwd,
             schema,
-            policy,
+            registry,
             signal: opts.signal,
-            mcpServers: opts.mcpServers,
-            // Generic session-scoped _meta passthrough (RunOptions.meta) — merged UNDER the
-            // backend-computed keys and the runId stamp in openSession. Additive; never hashed.
-            meta: opts.meta,
-            // Engine correlation id -> session/new _meta (META_KEYS.runId). Additive; never hashed.
-            runId: opts.runId,
-            // Stamped onto emitted ACP events as context (never sent on the wire).
-            label: opts.label,
-            // CODEX-ONLY session instruction overrides -> session/new _meta bare keys. Additive; never
-            // hashed. The Claude backend ignores them.
-            baseInstructions: opts.baseInstructions,
-            developerInstructions: opts.developerInstructions,
         });
+        const session = await this.pool.acquire(prepared.backend, prepared.sessionOptions);
         try {
             opts.signal?.throwIfAborted();
             // For a CUSTOM backend chosen by its registered name, the name itself is routing, not a
             // model id: "browser" selects nothing; "browser/foo" selects "foo". Built-ins get the
             // full spec unchanged (their catalogs match provider-prefixed and bare ids).
-            await applyModelSelection(session, innerModelSpec(opts.model ?? opts.tier, backend), opts);
-            const text = buildPrompt(prompt, opts, schema, backend);
+            await applyModelSelection(session, prepared.modelSpec, opts);
+            const text = buildRunPrompt(prompt, opts, schema, prepared.backend);
+            const initialPrompt = opts.images && opts.images.length > 0 ? promptWithImages(text, opts.images) : text;
             // Generic turn-scoped _meta passthrough merged UNDER the backend-computed keys (e.g. the
             // outputSchema forward when a schema is set) — user meta never clobbers the schema channel.
-            const promptMeta = mergeTurnMeta(opts.promptMeta, backend.promptMeta(schema));
-            const response = await session.prompt(text, promptMeta);
+            const promptMeta = mergeTurnMeta(opts.promptMeta, prepared.backend.promptMeta(schema));
+            const response = await session.prompt(initialPrompt, promptMeta);
             opts.signal?.throwIfAborted();
             // Inspect the turn's stop reason BEFORE the text/schema path: a refusal or truncation
             // must surface distinctly here, never be misread as empty output or burned through the
@@ -125,7 +203,7 @@ export class AcpAgentRunner {
                         assertNormalStopReason(repromptResponse.stopReason, opts.label);
                     },
                     lastText: () => session.currentTurnText(),
-                    tryNative: () => backend.nativeStructured(session),
+                    tryNative: () => prepared.backend.nativeStructured(session),
                 };
                 const result = await resolveStructuredOutput(structuredSession, schema, {
                     maxSchemaRetries: opts.maxSchemaRetries,
@@ -175,9 +253,60 @@ export class AcpAgentRunner {
     /** 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. */
     async dispose() {
+        this.disposed = true;
+        this.removeExitHook();
+        const sessions = [...this.interactiveSessions.keys()];
+        await Promise.all(sessions.map((session) => session.release()));
         await this.pool.dispose();
         this.events.removeAllListeners();
     }
+    /** 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) {
+        const backend = selectBackend(opts, config.registry);
+        const policy = { allow: opts.toolNames, deny: opts.disallowedToolNames };
+        return {
+            backend,
+            modelSpec: innerModelSpec(opts.model ?? opts.tier, backend),
+            sessionOptions: {
+                cwd: config.cwd,
+                schema: config.schema,
+                policy,
+                permissionResolver: config.permissionResolver,
+                signal: config.signal,
+                mcpServers: opts.mcpServers,
+                // Generic session-scoped _meta passthrough (RunOptions.meta) — merged UNDER the
+                // backend-computed keys and the runId stamp in openSession. Additive; never hashed.
+                meta: opts.meta,
+                // Engine correlation id -> session/new _meta (META_KEYS.runId). Additive; never hashed.
+                runId: opts.runId,
+                // Stamped onto emitted ACP events as context (never sent on the wire).
+                label: opts.label,
+                // CODEX-ONLY session instruction overrides -> session/new _meta bare keys. Additive;
+                // never hashed. The Claude backend ignores them.
+                baseInstructions: opts.baseInstructions,
+                developerInstructions: opts.developerInstructions,
+                retainSessionLog: config.retainSessionLog,
+            },
+        };
+    }
+    installExitHook() {
+        if (this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = true;
+        process.once("exit", this.onProcessExit);
+    }
+    removeExitHook() {
+        if (!this.exitHookInstalled)
+            return;
+        this.exitHookInstalled = false;
+        process.removeListener("exit", this.onProcessExit);
+    }
+    /** Synchronous best-effort child kill for the process-exit hook (no async work is possible). */
+    killAllSync() {
+        for (const connection of this.interactiveSessions.values())
+            connection.killNow();
+    }
 }
 /** 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
@@ -232,31 +361,6 @@ async function applyModelSelection(session, spec, opts) {
     for (const fallback of modifierFallbacks ?? [])
         opts.onModelFallback?.(fallback);
 }
-function buildPrompt(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) {
-            // The agent behind a custom backend may ignore the `_meta.outputSchema` forward, so the
-            // schema must be STATED, not just wired — otherwise the model invents its own keys and
-            // the repair ladder can never converge. Built-ins skip this: their native constraint
-            // channel is authoritative.
-            contract.push(`- The required output schema (JSON Schema):\n${JSON.stringify(toJsonSchema(schema))}`);
-        }
-        parts.push(contract.join("\n"));
-    }
-    return parts.join("\n\n");
-}
 /** Pick the backend by model/tier. Cross-provider routing = which ACP server to spawn.
  *  Registered CUSTOM names resolve FIRST (exact name, or `name/<inner-model>` prefix) so a
  *  registry entry is never shadowed by the built-in heuristics; then the claude/codex
@@ -295,11 +399,12 @@ function innerModelSpec(spec, backend) {
         return spec.slice(backend.id.length + 1) || undefined;
     return spec;
 }
-/** Merge the generic turn-scoped meta passthrough UNDER the backend-computed turn meta. */
-function mergeTurnMeta(user, backend) {
-    if (!user)
-        return backend;
-    return { ...user, ...(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) {
+    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 });
+    }
 }
 function backendIdForSpec(spec) {
     if (!spec)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@agentclientprotocol/claude-agent-acp": "0.55.0",
     "@automatalabs/codex-acp": "1.3.0",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.6.0"
+    "@automatalabs/shared-types": "0.7.0"
   },
   "scripts": {
     "build": "tsc -b",