@wrongstack/acp 0.260.0 → 0.264.0

package/dist/client.js

@@ -1,4 +1,7 @@
 import { expectDefined, writeErr } from '@wrongstack/core';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+import { spawn } from 'child_process';
 
 // src/agent/stdio-transport.ts
 var ClientTransport = class {
@@ -17,22 +20,30 @@ var ClientTransport = class {
   }
   async start() {
     if (this.child) return;
-    const [{ spawn }, { buildChildEnv }] = await Promise.all([
+    const [{ spawn: spawn2 }, { buildChildEnv }] = await Promise.all([
       import('child_process'),
       import('@wrongstack/core')
     ]);
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const timeout = setTimeout(() => {
         reject(
           new Error(`ACP child process failed to start within ${this.opts.handshakeTimeoutMs}ms`)
         );
       }, this.opts.handshakeTimeoutMs);
       try {
-        this.child = spawn(this.opts.command, this.opts.args ?? [], {
+        this.child = spawn2(this.opts.command, this.opts.args ?? [], {
           env: { ...buildChildEnv(), ...this.opts.env },
           cwd: this.opts.cwd,
           stdio: ["pipe", "pipe", "pipe"],
-          windowsHide: true
+          windowsHide: true,
+          // On Windows, most ACP-supporting tools (claude, gemini, codex,
+          // qwen, copilot) are installed as `.cmd` shims under
+          // AppData\Roaming\npm\. Node's spawn won't find them via
+          // `shell: false` because the .cmd extension is not in the
+          // default PATHEXT lookup. The argv here is always from our
+          // own static catalog or from a hardcoded spec, never from
+          // user input, so shell-expansion is bounded.
+          shell: process.platform === "win32"
         });
       } catch (err) {
         clearTimeout(timeout);
@@ -41,17 +52,24 @@ var ClientTransport = class {
       }
       const child = this.child;
       child.stdout.setEncoding("utf8");
+      const onReady = () => {
+        child.stdout.on("data", (c) => this.onChildData(c));
+        child.stderr.on("data", (c) => this.onChildError(c));
+        child.on("close", (code) => this.onChildClose(code));
+        clearTimeout(timeout);
+        resolve3();
+      };
+      if (this.opts.skipHandshakeMarker) {
+        onReady();
+        return;
+      }
       const waitForMarker = (chunk) => {
         this.buffer += chunk;
         const idx = this.buffer.indexOf("[wstack-acp]\n");
         if (idx !== -1) {
           this.buffer = this.buffer.slice(idx + "[wstack-acp]\n".length);
           child.stdout.removeListener("data", waitForMarker);
-          child.stdout.on("data", (c) => this.onChildData(c));
-          child.stderr.on("data", (c) => this.onChildError(c));
-          child.on("close", (code) => this.onChildClose(code));
-          clearTimeout(timeout);
-          resolve();
+          onReady();
         }
       };
       child.stdout.on("data", waitForMarker);
@@ -67,19 +85,19 @@ var ClientTransport = class {
   }
   send(msg) {
     if (!this.child) return Promise.reject(new Error("ClientTransport not started"));
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const line = JSON.stringify(msg) + "\n";
       this.child?.stdin.write(line, "utf8", (err) => {
         if (err) reject(err);
-        else resolve();
+        else resolve3();
       });
     });
   }
   read() {
     if (this.messageQueue.length > 0) return Promise.resolve(expectDefined(this.messageQueue.shift()));
     if (this.closed) return Promise.resolve(null);
-    return new Promise((resolve) => {
-      this.resolveRead = resolve;
+    return new Promise((resolve3) => {
+      this.resolveRead = resolve3;
     });
   }
   onMessage(handler) {
@@ -121,9 +139,9 @@ var ClientTransport = class {
   }
   dispatch(msg) {
     if (this.resolveRead) {
-      const resolve = this.resolveRead;
+      const resolve3 = this.resolveRead;
       this.resolveRead = null;
-      resolve(msg);
+      resolve3(msg);
     } else {
       this.messageQueue.push(msg);
     }
@@ -140,32 +158,6 @@ var DEFAULT_OPTIONS = {
   pollIntervalMs: 500,
   totalTimeoutMs: 12e4
 };
-function extractTextFromContent(blocks) {
-  const parts = [];
-  for (const b of blocks) {
-    if (b.type === "text") parts.push(b.text);
-    else if (b.type === "resource") parts.push(`[resource: ${b.resource.uri}]`);
-    else if (b.type === "image") parts.push(`[image: ${b.data.slice(0, 20)}...]`);
-    else if (b.type === "progress") {
-      if (b.messages?.length) parts.push(b.messages.join("\n"));
-    }
-  }
-  return parts.join("\n");
-}
-function parseToolResponse(taskId, subagentId, response) {
-  const blocks = response.result.content;
-  const text = extractTextFromContent(blocks);
-  const isError = response.result.isError || text.toLowerCase().includes("error") || text.toLowerCase().includes("failed");
-  return {
-    taskId,
-    subagentId,
-    status: isError ? "failed" : "success",
-    result: text,
-    iterations: 1,
-    toolCalls: 1,
-    durationMs: 0
-  };
-}
 var ToolTranslator = class {
   opts;
   pending = /* @__PURE__ */ new Map();
@@ -207,12 +199,12 @@ var ToolTranslator = class {
       id: callId,
       params: { name, arguments: args }
     });
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve3, reject) => {
       const timeout = setTimeout(() => {
         this.pending.delete(callId);
         reject(new Error(`Tool call ${name} timed out after ${this.opts.totalTimeoutMs}ms`));
       }, this.opts.totalTimeoutMs);
-      this.pending.set(callId, { resolve, reject, timeout });
+      this.pending.set(callId, { resolve: resolve3, reject, timeout });
     });
   }
   cancelAll() {
@@ -223,97 +215,881 @@ var ToolTranslator = class {
   }
 };
 
-// src/integration/acp-subagent-runner.ts
-async function makeACPSubagentRunner(options) {
-  const transport = new ClientTransport(clientTransportOptions(options));
-  const translator = new ToolTranslator(options.toolTranslatorOpts);
-  const activeAbort = new AbortController();
-  let sessionStarted = false;
-  const startSession = async () => {
-    if (sessionStarted) return;
-    await transport.start();
-    await transport.send({
-      method: "initialize",
-      id: "1",
-      params: {
-        capabilities: ["code-generation", "async-tools", "streaming", "progress"],
-        protocolVersion: "2024-11",
-        sessionId: options.role ?? "wrongstack-subagent"
+// src/types/acp-v1.ts
+var ACP_PROTOCOL_VERSION = 1;
+var FsError = class extends Error {
+  code;
+  path;
+  constructor(code, path3, message) {
+    super(message);
+    this.name = "FsError";
+    this.code = code;
+    this.path = path3;
+  }
+};
+var FileServer = class {
+  root;
+  timeoutMs;
+  constructor(opts) {
+    this.root = path.resolve(opts.projectRoot);
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  /** Read a text file. Returns the content as a string. */
+  async readTextFile(params) {
+    const safe = this.resolveInside(params.path);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const content = await fsp.readFile(safe, {
+        encoding: "utf8",
+        signal: controller.signal
+      });
+      return { content };
+    } catch (err) {
+      if (controller.signal.aborted) {
+        throw new FsError("TIMEOUT", safe, `readTextFile timed out after ${this.timeoutMs}ms`);
+      }
+      throw mapFsError(err, safe);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** Write a text file. Atomic via write-then-rename. */
+  async writeTextFile(params) {
+    const safe = this.resolveInside(params.path);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const tmp = `${safe}.${randomHex(4)}.tmp`;
+    try {
+      await fsp.writeFile(tmp, params.content, {
+        encoding: "utf8",
+        signal: controller.signal
+      });
+      await fsp.rename(tmp, safe);
+    } catch (err) {
+      try {
+        await fsp.unlink(tmp);
+      } catch {
+      }
+      if (controller.signal.aborted) {
+        throw new FsError("TIMEOUT", safe, `writeTextFile timed out after ${this.timeoutMs}ms`);
       }
+      throw mapFsError(err, safe);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Resolve a path; throw `FsError('OUTSIDE_ROOT')` if the result is
+   * not under the project root. Symlinks are not followed here — we
+   * operate on the textual path. A future hardening pass can
+   * `fs.realpath` each access to catch symlink escapes.
+   */
+  resolveInside(p) {
+    if (typeof p !== "string" || p.length === 0) {
+      throw new FsError("INVALID_PATH", p, "path is empty or not a string");
+    }
+    if (!path.isAbsolute(p)) {
+      throw new FsError("INVALID_PATH", p, "path must be absolute (ACP requirement)");
+    }
+    const resolved = path.resolve(p);
+    const rootWithSep = this.root.endsWith(path.sep) ? this.root : this.root + path.sep;
+    if (resolved !== this.root && !resolved.startsWith(rootWithSep)) {
+      throw new FsError("OUTSIDE_ROOT", resolved, "path is outside the project root");
+    }
+    return resolved;
+  }
+};
+function mapFsError(err, p) {
+  const code = err?.code;
+  if (code === "ENOENT") return new FsError("ENOENT", p, `no such file: ${p}`);
+  if (code === "EACCES" || code === "EPERM") {
+    return new FsError("EACCES", p, `permission denied: ${p}`);
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  return new FsError("INVALID_PATH", p, msg);
+}
+function randomHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes * 2; i++) {
+    out += Math.floor(Math.random() * 16).toString(16);
+  }
+  return out;
+}
+
+// src/client/permission.ts
+var defaultPermissionPolicy = async (req) => {
+  if (req.signal.aborted) return { outcome: "cancelled" };
+  const ranked = [...req.options].sort((a, b) => {
+    const score = (k) => {
+      if (k === "allow_always") return 0;
+      if (k === "allow_once") return 1;
+      if (k === "reject_once") return 2;
+      return 3;
+    };
+    return score(a.kind) - score(b.kind);
+  });
+  const chosen = ranked[0];
+  if (!chosen || chosen.kind === "reject_once" || chosen.kind === "reject_always") {
+    return { outcome: "cancelled" };
+  }
+  return { outcome: "selected", optionId: chosen.optionId };
+};
+var TerminalServer = class {
+  terminals = /* @__PURE__ */ new Map();
+  projectRoot;
+  commandTimeoutMs;
+  outputByteLimit;
+  nextId = 1;
+  constructor(opts) {
+    this.projectRoot = path.resolve(opts.projectRoot);
+    this.commandTimeoutMs = opts.commandTimeoutMs ?? 5 * 6e4;
+    this.outputByteLimit = opts.outputByteLimit ?? 1024 * 1024;
+    if (opts.signal) {
+      opts.signal.addEventListener("abort", () => this.releaseAll());
+    }
+  }
+  /** Spawn a new terminal. Returns the agent-facing id. */
+  create(params) {
+    const id = `term_${this.nextId++}`;
+    const cwd = this.resolveCwd(params.cwd);
+    const proc = spawn(params.command, params.args ?? [], {
+      cwd,
+      env: this.buildEnv(params.env),
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+      // shell: false on purpose. The terminal server is invoked with
+      // the agent's explicit argv; turning on shell-mode would make
+      // the command a single shell-parsed string, which breaks
+      // Windows cmd quoting for the common case of running node with
+      // `-e "<script>"`. If a future feature needs shell features
+      // (pipes, redirects), it should be opt-in per-call, not the
+      // default.
     });
-    const initResp = await transport.read();
-    if (!initResp || initResp.error) {
-      throw new Error(`ACP initialize failed: ${initResp?.error?.message ?? "no response"}`);
+    const state = {
+      proc,
+      cwd,
+      command: params.command,
+      args: params.args ?? [],
+      output: "",
+      retainedBytes: 0,
+      truncated: false,
+      exitStatus: void 0,
+      timeoutHandle: null,
+      exitPromise: new Promise((resolve3) => {
+        proc.on("close", (code, signalName) => {
+          if (state.timeoutHandle) {
+            clearTimeout(state.timeoutHandle);
+            state.timeoutHandle = null;
+          }
+          const exitStatus = {
+            exitCode: typeof code === "number" ? code : null,
+            signal: typeof signalName === "string" ? signalName : null
+          };
+          state.exitStatus = exitStatus;
+          resolve3(exitStatus);
+        });
+        proc.on("error", (err) => {
+          if (state.timeoutHandle) {
+            clearTimeout(state.timeoutHandle);
+            state.timeoutHandle = null;
+          }
+          const exitStatus = { exitCode: 127, signal: null };
+          state.exitStatus = exitStatus;
+          state.output += `[spawn error] ${err.message}
+`;
+          state.retainedBytes += Buffer.byteLength(state.output, "utf8");
+          resolve3(exitStatus);
+        });
+      })
+    };
+    const perCallByteLimit = params.outputByteLimit ?? this.outputByteLimit;
+    proc.stdout?.setEncoding("utf8");
+    proc.stderr?.setEncoding("utf8");
+    const onData = (chunk) => {
+      state.output += chunk;
+      state.retainedBytes = Buffer.byteLength(state.output, "utf8");
+      while (state.retainedBytes > perCallByteLimit) {
+        const trimmed = state.output.slice(1);
+        state.output = trimmed;
+        const newBytes = Buffer.byteLength(state.output, "utf8");
+        if (newBytes >= state.retainedBytes) {
+          break;
+        }
+        state.retainedBytes = newBytes;
+        state.truncated = true;
+      }
+    };
+    proc.stdout?.on("data", onData);
+    proc.stderr?.on("data", onData);
+    state.timeoutHandle = setTimeout(() => {
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+      }
+    }, this.commandTimeoutMs);
+    this.terminals.set(id, state);
+    return { terminalId: id };
+  }
+  /** Return captured output and (if available) the exit status. */
+  output(terminalId) {
+    const state = this.terminals.get(terminalId);
+    if (!state) throw new Error(`unknown terminal: ${terminalId}`);
+    return {
+      output: state.output,
+      truncated: state.truncated,
+      ...state.exitStatus ? { exitStatus: state.exitStatus } : {}
+    };
+  }
+  /** Block until the process exits. Resolves with the exit status. */
+  async waitForExit(terminalId) {
+    const state = this.terminals.get(terminalId);
+    if (!state) throw new Error(`unknown terminal: ${terminalId}`);
+    return state.exitPromise;
+  }
+  /** Kill the process but keep the terminal record (agent can still read output). */
+  kill(terminalId) {
+    const state = this.terminals.get(terminalId);
+    if (!state) throw new Error(`unknown terminal: ${terminalId}`);
+    try {
+      state.proc.kill("SIGTERM");
+    } catch {
     }
-    translator.attachToTransport({
-      onMessage: (h) => transport.onMessage(h),
-      send: (m) => transport.send(m)
+  }
+  /** Kill the process if alive and remove the record. */
+  release(terminalId) {
+    const state = this.terminals.get(terminalId);
+    if (!state) return;
+    if (state.timeoutHandle) {
+      clearTimeout(state.timeoutHandle);
+      state.timeoutHandle = null;
+    }
+    try {
+      state.proc.kill("SIGKILL");
+    } catch {
+    }
+    this.terminals.delete(terminalId);
+  }
+  /** Kill all active terminals. Used on session close. */
+  releaseAll() {
+    for (const id of [...this.terminals.keys()]) {
+      this.release(id);
+    }
+  }
+  resolveCwd(cwd) {
+    if (!cwd) return this.projectRoot;
+    const resolved = path.resolve(cwd);
+    const rootWithSep = this.projectRoot.endsWith(path.sep) ? this.projectRoot : this.projectRoot + path.sep;
+    if (resolved !== this.projectRoot && !resolved.startsWith(rootWithSep)) {
+      return this.projectRoot;
+    }
+    return resolved;
+  }
+  buildEnv(agentEnv) {
+    const env = { ...process.env };
+    if (process.platform === "win32") {
+      if (env.Path !== void 0 && env.PATH === void 0) env.PATH = env.Path;
+      if (env.PATHEXT !== void 0 && env.PATHEXT_CASE === void 0) {
+        env.PATHEXT_CASE = env.PATHEXT;
+      }
+    }
+    if (agentEnv) {
+      for (const { name, value } of agentEnv) {
+        env[name] = value;
+      }
+    }
+    return env;
+  }
+};
+
+// src/client/acp-session.ts
+var ACPSessionError = class extends Error {
+  kind;
+  cause;
+  constructor(kind, message, cause) {
+    super(message);
+    this.name = "ACPSessionError";
+    this.kind = kind;
+    this.cause = cause;
+  }
+};
+function isJsonRpcError(v) {
+  return typeof v === "object" && v !== null && typeof v.code === "number" && typeof v.message === "string";
+}
+var ACPSession = class _ACPSession {
+  transport;
+  fileServer;
+  terminalServer;
+  permissionPolicy;
+  timeoutMs;
+  opts;
+  state = "init";
+  sessionId = null;
+  /** Pending outbound requests (initialize, session/new, session/prompt, etc). */
+  pending = /* @__PURE__ */ new Map();
+  nextId = 1;
+  /** True after close() has been called. */
+  closed = false;
+  constructor(opts, transport) {
+    this.opts = opts;
+    this.transport = transport;
+    this.timeoutMs = opts.timeoutMs ?? 5 * 6e4;
+    const fsOpts = {
+      projectRoot: opts.projectRoot
+    };
+    if (opts.fsTimeoutMs !== void 0) fsOpts.timeoutMs = opts.fsTimeoutMs;
+    this.fileServer = new FileServer(fsOpts);
+    const termOpts = {
+      projectRoot: opts.projectRoot
+    };
+    if (opts.terminalTimeoutMs !== void 0) {
+      termOpts.commandTimeoutMs = opts.terminalTimeoutMs;
+    }
+    if (opts.terminalOutputByteLimit !== void 0) {
+      termOpts.outputByteLimit = opts.terminalOutputByteLimit;
+    }
+    this.terminalServer = new TerminalServer(termOpts);
+    this.permissionPolicy = opts.permissionPolicy ?? defaultPermissionPolicy;
+  }
+  /**
+   * Spawn the child, run the initialize handshake, install the
+   * message dispatch, and return a ready session.
+   */
+  static async start(opts) {
+    const transportOpts = {
+      command: opts.command,
+      args: opts.args ? [...opts.args] : [],
+      handshakeTimeoutMs: 3e4,
+      // ACPSession is the v1 CLIENT side: it speaks to external agents
+      // (Claude Code, Gemini CLI, …) that do NOT emit a `[wstack-acp]\n`
+      // startup marker. The transport should treat the child as ready
+      // as soon as the process is spawned and stdout is flowing.
+      skipHandshakeMarker: true
+    };
+    if (opts.env !== void 0) transportOpts.env = opts.env;
+    if (opts.cwd !== void 0) transportOpts.cwd = opts.cwd;
+    const transport = new ClientTransport(transportOpts);
+    try {
+      await transport.start();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new ACPSessionError("spawn_failed", `failed to spawn ${opts.command}: ${msg}`, err);
+    }
+    const session = new _ACPSession(opts, transport);
+    transport.onMessage((msg) => session.handleMessage(msg));
+    try {
+      await session.initialize();
+    } catch (err) {
+      try {
+        transport.stop();
+      } catch {
+      }
+      throw err;
+    }
+    return session;
+  }
+  async initialize() {
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "initialize", {
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: { readTextFile: true, writeTextFile: true },
+        terminal: true,
+        promptCapabilities: { image: false, audio: false, embeddedContext: true }
+      },
+      clientInfo: { name: "wrongstack", title: "WrongStack", version: "0.263.0" }
     });
-    sessionStarted = true;
-  };
-  const runner = async (task, ctx) => {
-    ctx.signal.addEventListener("abort", () => {
-      activeAbort.abort();
-      transport.stop();
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("init_failed", `initialize failed: ${result.message}`, result);
+    }
+    if (typeof result !== "object" || result === null || typeof result.protocolVersion !== "number") {
+      throw new ACPSessionError("protocol_error", "initialize returned no protocolVersion");
+    }
+    const r = result;
+    if (r.protocolVersion !== ACP_PROTOCOL_VERSION) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        `agent speaks protocolVersion=${r.protocolVersion}, client speaks ${ACP_PROTOCOL_VERSION}`
+      );
+    }
+    this.state = "ready";
+  }
+  /**
+   * Run one prompt turn. Creates a session if needed, sends the
+   * prompt, streams session/update notifications, and resolves with
+   * the agent's response.
+   *
+   * Cancellation: if `signal` aborts mid-prompt, we send
+   * `session/cancel` (a notification per spec) and keep accepting
+   * updates until the agent returns with `stopReason: 'cancelled'`.
+   * The result is the same shape as a normal turn, with
+   * `stopReason === 'cancelled'`.
+   */
+  async prompt(text, signal) {
+    if (this.closed) {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (this.state !== "ready" && this.state !== "done") {
+      throw new ACPSessionError("protocol_error", `prompt called in state=${this.state}`);
+    }
+    if (signal.aborted) {
+      return { text: "", stopReason: "cancelled", hasText: false };
+    }
+    if (!this.sessionId) {
+      await this.createSession();
+    }
+    this.resetScratch();
+    const promptId = this.allocId();
+    const turnPromise = this.sendRequest(
+      promptId,
+      "session/prompt",
+      {
+        sessionId: this.sessionId,
+        prompt: [textContent(text)]
+      },
+      this.timeoutMs
+    );
+    let cancelled = false;
+    const onAbort = () => {
+      cancelled = true;
+      this.transport.send({ method: "session/cancel", params: { sessionId: this.sessionId } }).catch(() => {
+      });
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    this.state = "prompting";
+    let response;
+    try {
+      response = await turnPromise;
+    } catch (err) {
+      this.state = "done";
+      signal.removeEventListener("abort", onAbort);
+      if (cancelled || signal.aborted) {
+        throw new ACPSessionError("aborted", "prompt was aborted by the parent");
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new ACPSessionError("prompt_failed", `session/prompt failed: ${msg}`, err);
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+    }
+    this.state = "done";
+    if (isJsonRpcError(response)) {
+      throw new ACPSessionError("prompt_failed", `agent error: ${response.message}`, response);
+    }
+    const stopReason = response.stopReason ?? "end_turn";
+    const finalText = this.scratch.text;
+    return {
+      text: finalText,
+      stopReason,
+      hasText: finalText.length > 0,
+      usage: this.scratch.usage,
+      plan: this.scratch.plan
+    };
+  }
+  async createSession() {
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/new", {
+      cwd: this.opts.cwd ?? this.opts.projectRoot,
+      mcpServers: []
     });
-    await startSession();
-    const callId = crypto.randomUUID();
-    let toolResult = null;
-    const resultPromise = new Promise((resolve, reject) => {
-      const budgetMs = ctx.budget.limits.timeoutMs ?? 3e5;
-      const timeout = setTimeout(() => {
-        reject(new Error(`ACP task timed out for subagent ${ctx.subagentId} (${budgetMs}ms budget)`));
-      }, budgetMs);
-      transport.onMessage((msg) => {
-        if (msg.method === "tools/call" && msg.id !== void 0) {
-          clearTimeout(timeout);
-          resolve(msg);
-        }
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError(
+        "session_create_failed",
+        `session/new failed: ${result.message}`,
+        result
+      );
+    }
+    const sessionId = result.sessionId;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      throw new ACPSessionError(
+        "protocol_error",
+        "session/new returned no sessionId",
+        result
+      );
+    }
+    this.sessionId = sessionId;
+  }
+  /** Tear down the session and kill the child process. */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.state = "closed";
+    this.terminalServer.releaseAll();
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timeoutHandle);
+      p.reject(new ACPSessionError("closed", "session was closed"));
+    }
+    this.pending.clear();
+    try {
+      this.transport.stop();
+    } catch {
+    }
+  }
+  // ────────────────────────────────────────────────────────────────────
+  // Wire layer
+  // ────────────────────────────────────────────────────────────────────
+  allocId() {
+    return this.nextId++;
+  }
+  async sendRequest(id, method, params, timeoutMs) {
+    return new Promise((resolve3, reject) => {
+      const effectiveTimeout = timeoutMs ?? this.timeoutMs;
+      const handle = setTimeout(() => {
+        this.pending.delete(id);
+        reject(
+          new ACPSessionError(
+            "protocol_error",
+            `${method} timed out after ${effectiveTimeout}ms`
+          )
+        );
+      }, effectiveTimeout);
+      this.pending.set(id, {
+        method,
+        resolve: resolve3,
+        reject,
+        timeoutMs: effectiveTimeout,
+        timeoutHandle: handle
       });
-      ctx.signal.addEventListener("abort", () => {
-        clearTimeout(timeout);
-        reject(new Error("Task aborted by parent"));
+      this.transport.send({ jsonrpc: "2.0", id, method, params }).catch((err) => {
+        clearTimeout(handle);
+        this.pending.delete(id);
+        const msg = err instanceof Error ? err.message : String(err);
+        reject(new ACPSessionError("protocol_error", `send ${method} failed: ${msg}`, err));
+      });
+    });
+  }
+  handleMessage(msg) {
+    if (msg.id !== void 0 && (msg.result !== void 0 || msg.error !== void 0)) {
+      const pending = this.pending.get(msg.id);
+      if (!pending) return;
+      clearTimeout(pending.timeoutHandle);
+      this.pending.delete(msg.id);
+      if (msg.error !== void 0) {
+        pending.reject(new Error(msg.error.message ?? "unknown JSON-RPC error"));
+      } else {
+        pending.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "session/update") {
+      this.handleUpdate(msg);
+      return;
+    }
+    if (msg.method === "session/request_permission") {
+      void this.handlePermissionRequest(msg);
+      return;
+    }
+    if (msg.method === "fs/read_text_file" || msg.method === "fs/write_text_file") {
+      void this.handleFsRequest(msg);
+      return;
+    }
+    if (msg.method && msg.method.startsWith("terminal/")) {
+      void this.handleTerminalRequest(msg);
+      return;
+    }
+    if (msg.method) {
+      console.warn(`[acp-session] unhandled method: ${msg.method}`);
+    }
+  }
+  handleUpdate(msg) {
+    const update = msg.params?.update;
+    if (typeof update !== "object" || update === null) return;
+    const u = update;
+    switch (u.sessionUpdate) {
+      case "agent_message_chunk": {
+        const text = extractText(u.content);
+        if (text) this.accumulatedText(text);
+        return;
+      }
+      case "thought_chunk":
+        return;
+      case "tool_call":
+      case "tool_call_update":
+        return;
+      case "plan":
+        if (Array.isArray(u.entries)) {
+          this.accumulatedPlan(u.entries);
+        }
+        return;
+      case "usage_update":
+        if (typeof u.used === "number" && typeof u.size === "number") {
+          this.accumulatedUsage({
+            used: u.used,
+            size: u.size,
+            ...typeof u.cost === "object" && u.cost !== null ? {
+              cost: u.cost
+            } : {}
+          });
+        }
+        return;
+      case "available_commands_update":
+      case "current_mode_update":
+      case "config_option_update":
+      case "session_info_update":
+      case "user_message_chunk":
+        return;
+      default:
+        console.warn(`[acp-session] unhandled sessionUpdate: ${u.sessionUpdate}`);
+        return;
+    }
+  }
+  // Per-prompt scratch state. Reset at the start of each prompt() and
+  // read at the end to assemble the ACPSessionRunResult. The stream
+  // pump writes to it via the three `accumulated*` helpers below.
+  scratch = { text: "" };
+  accumulatedText(chunk) {
+    this.scratch.text += chunk;
+  }
+  accumulatedPlan(entries) {
+    this.scratch.plan = entries;
+  }
+  accumulatedUsage(u) {
+    this.scratch.usage = u;
+  }
+  resetScratch() {
+    this.scratch = { text: "" };
+  }
+  async handlePermissionRequest(msg) {
+    const id = msg.id;
+    if (id === void 0) return;
+    const params = msg.params;
+    const toolCall = params?.toolCall;
+    const options = Array.isArray(params?.options) ? params.options : [];
+    if (!toolCall) {
+      await this.transport.send({
+        id,
+        method: "session/request_permission",
+        error: { code: -32602, message: "toolCall is required" }
       });
+      return;
+    }
+    const policyAbort = new AbortController();
+    const outcome = await this.permissionPolicy({
+      toolCall,
+      options,
+      signal: policyAbort.signal
     });
+    await this.transport.send({
+      id,
+      method: "session/request_permission",
+      result: { outcome }
+    });
+  }
+  async handleFsRequest(msg) {
+    const id = msg.id;
+    if (id === void 0) return;
+    const params = msg.params;
+    if (!params?.path) {
+      await this.transport.send({
+        id,
+        method: msg.method,
+        error: { code: -32602, message: "path is required" }
+      });
+      return;
+    }
+    try {
+      if (msg.method === "fs/read_text_file") {
+        const result = await this.fileServer.readTextFile({
+          sessionId: params.sessionId ?? "",
+          path: params.path
+        });
+        await this.transport.send({ id, method: msg.method, result });
+      } else {
+        await this.fileServer.writeTextFile({
+          sessionId: params.sessionId ?? "",
+          path: params.path,
+          content: params.content ?? ""
+        });
+        await this.transport.send({ id, method: msg.method, result: {} });
+      }
+    } catch (err) {
+      const code = err instanceof FsError ? -32602 : -32603;
+      const message = err instanceof Error ? err.message : String(err);
+      await this.transport.send({ id, method: msg.method, error: { code, message } });
+    }
+  }
+  async handleTerminalRequest(msg) {
+    const id = msg.id;
+    if (id === void 0) return;
+    const params = msg.params ?? {};
     try {
-      await transport.send({
-        method: "agent/run",
-        id: callId,
-        params: {
-          task: task.description,
-          sessionId: ctx.subagentId
+      switch (msg.method) {
+        case "terminal/create": {
+          const createOpts = {
+            sessionId: String(params.sessionId ?? ""),
+            command: String(params.command ?? ""),
+            args: Array.isArray(params.args) ? params.args : []
+          };
+          if (Array.isArray(params.env)) {
+            createOpts.env = params.env;
+          }
+          if (typeof params.cwd === "string") {
+            createOpts.cwd = params.cwd;
+          }
+          if (typeof params.outputByteLimit === "number") {
+            createOpts.outputByteLimit = params.outputByteLimit;
+          }
+          const result = this.terminalServer.create(createOpts);
+          await this.transport.send({ id, method: msg.method, result });
+          return;
         }
+        case "terminal/output": {
+          const terminalId = String(params.terminalId ?? "");
+          const out = this.terminalServer.output(terminalId);
+          await this.transport.send({ id, method: msg.method, result: out });
+          return;
+        }
+        case "terminal/wait_for_exit": {
+          const terminalId = String(params.terminalId ?? "");
+          const exit = await this.terminalServer.waitForExit(terminalId);
+          await this.transport.send({ id, method: msg.method, result: exit });
+          return;
+        }
+        case "terminal/kill": {
+          const terminalId = String(params.terminalId ?? "");
+          this.terminalServer.kill(terminalId);
+          await this.transport.send({ id, method: msg.method, result: {} });
+          return;
+        }
+        case "terminal/release": {
+          const terminalId = String(params.terminalId ?? "");
+          this.terminalServer.release(terminalId);
+          await this.transport.send({ id, method: msg.method, result: {} });
+          return;
+        }
+        default:
+          await this.transport.send({
+            id,
+            method: msg.method,
+            error: { code: -32601, message: `unknown method: ${msg.method}` }
+          });
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      await this.transport.send({
+        id,
+        method: msg.method,
+        error: { code: -32603, message }
+      });
+    }
+  }
+};
+function textContent(text) {
+  return { type: "text", text };
+}
+function extractText(block) {
+  if (typeof block !== "object" || block === null) return "";
+  const b = block;
+  if (b.type === "text" && typeof b.text === "string") return b.text;
+  return "";
+}
+
+// src/integration/acp-subagent-runner.ts
+async function makeACPSubagentRunner(options) {
+  const { runner, stop } = await makeACPSubagentRunnerWithStop(options);
+  const wrappedRunner = async (task, ctx) => {
+    try {
+      return await runner(task, ctx);
+    } finally {
+      stop();
+    }
+  };
+  return wrappedRunner;
+}
+async function makeACPSubagentRunnerWithStop(options) {
+  const projectRoot = options.projectRoot ?? options.cwd ?? process.cwd();
+  const timeoutMs = options.timeoutMs ?? 5 * 6e4;
+  const runner = async (task, ctx) => {
+    let session = null;
+    try {
+      session = await ACPSession.start({
+        command: options.command,
+        ...options.args !== void 0 ? { args: options.args } : {},
+        ...options.env !== void 0 ? { env: options.env } : {},
+        ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+        projectRoot,
+        timeoutMs,
+        role: options.role
       });
-      toolResult = await resultPromise;
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
+    }
+    try {
+      const result = await session.prompt(task.description, ctx.signal);
       return {
-        result: `ACP subagent error: ${msg}`,
-        iterations: 0,
+        result: result.text,
+        iterations: 1,
         toolCalls: 0
       };
+    } catch (err) {
+      if (err instanceof ACPSessionError && err.kind === "aborted") {
+        throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
+      }
+      throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
+    } finally {
+      try {
+        await session.close();
+      } catch {
+      }
     }
-    if (!toolResult) {
-      return { result: "ACP subagent returned no result", iterations: 1, toolCalls: 1 };
-    }
-    const parsed = parseToolResponse(task.id, ctx.subagentId, toolResult);
+  };
+  const stop = () => {
+  };
+  return { runner, stop };
+}
+function acpErrorToSubagentError(err, subagentId) {
+  if (err instanceof ACPSessionError) {
+    const kind = mapACPKind(err.kind);
     return {
-      result: parsed.result ?? parsed.error,
-      iterations: parsed.iterations,
-      toolCalls: parsed.toolCalls
+      kind,
+      message: `${subagentId}: ${err.message}`,
+      retryable: isRetryable(kind),
+      cause: {
+        name: err.name,
+        message: err.message,
+        ...err.stack !== void 0 ? { stack: err.stack } : {}
+      }
     };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    kind: "bridge_failed",
+    message: `${subagentId}: ${message}`,
+    retryable: false,
+    cause: {
+      name: err instanceof Error ? err.name : "Error",
+      message,
+      ...err instanceof Error && err.stack !== void 0 ? { stack: err.stack } : {}
+    }
   };
-  return runner;
 }
-function clientTransportOptions(options) {
-  const out = {
-    command: options.command,
-    handshakeTimeoutMs: 3e4
-  };
-  if (options.args !== void 0) out.args = options.args;
-  if (options.env !== void 0) out.env = options.env;
-  if (options.cwd !== void 0) out.cwd = options.cwd;
-  return out;
+function mapACPKind(acpKind) {
+  switch (acpKind) {
+    case "spawn_failed":
+    case "init_failed":
+    case "session_create_failed":
+    case "agent_died":
+    case "protocol_error":
+      return "bridge_failed";
+    case "prompt_failed":
+      return "tool_failed";
+    case "aborted":
+      return "aborted_by_parent";
+    case "closed":
+    case "unsupported_capability":
+      return "unknown";
+  }
+}
+function isRetryable(kind) {
+  switch (kind) {
+    case "provider_5xx":
+    case "provider_rate_limit":
+    case "provider_timeout":
+    case "tool_threw":
+    case "budget_timeout":
+      return true;
+    default:
+      return false;
+  }
 }
 
 export { ClientTransport, ToolTranslator, makeACPSubagentRunner };