@wrongstack/acp 0.274.0 → 0.275.0

package/dist/client.js

@@ -2,6 +2,7 @@ import { expectDefined, writeErr } from '@wrongstack/core';
 import * as fsp from 'fs/promises';
 import * as path from 'path';
 import { spawn } from 'child_process';
+import '@wrongstack/core/coordination';
 
 // src/agent/stdio-transport.ts
 var ClientTransport = class {
@@ -20,9 +21,10 @@ var ClientTransport = class {
   }
   async start() {
     if (this.child) return;
-    const [{ spawn: spawn2 }, { buildChildEnv }] = await Promise.all([
+    const [{ spawn: spawn2 }, { buildChildEnv }, os] = await Promise.all([
       import('child_process'),
-      import('@wrongstack/core')
+      import('@wrongstack/core'),
+      import('os')
     ]);
     return new Promise((resolve3, reject) => {
       const timeout = setTimeout(() => {
@@ -30,10 +32,12 @@ var ClientTransport = class {
           new Error(`ACP child process failed to start within ${this.opts.handshakeTimeoutMs}ms`)
         );
       }, this.opts.handshakeTimeoutMs);
+      const isPkgLauncher = this.opts.command === "npx" || this.opts.command === "uvx";
+      const spawnCwd = isPkgLauncher ? os.homedir() : this.opts.cwd;
       try {
         this.child = spawn2(this.opts.command, this.opts.args ?? [], {
           env: { ...buildChildEnv(), ...this.opts.env },
-          cwd: this.opts.cwd,
+          cwd: spawnCwd,
           stdio: ["pipe", "pipe", "pipe"],
           windowsHide: true,
           // On Windows, most ACP-supporting tools (claude, gemini, codex,
@@ -52,17 +56,39 @@ var ClientTransport = class {
       }
       const child = this.child;
       child.stdout.setEncoding("utf8");
+      let settled = false;
+      const onSpawnFailure = (err) => {
+        if (settled) {
+          this.closed = true;
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(err);
+      };
+      child.on("error", onSpawnFailure);
+      child.stdout.on("error", onSpawnFailure);
+      if (this.opts.skipHandshakeMarker) {
+        child.stdout.on("data", (c) => this.onChildData(c));
+        child.stderr.on("data", (c) => this.onChildError(c));
+        child.on("close", (code) => this.onChildClose(code));
+        child.once("spawn", () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          resolve3();
+        });
+        return;
+      }
       const onReady = () => {
+        if (settled) return;
+        settled = true;
         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");
@@ -73,14 +99,6 @@ var ClientTransport = class {
         }
       };
       child.stdout.on("data", waitForMarker);
-      child.stdout.on("error", (err) => {
-        clearTimeout(timeout);
-        reject(err);
-      });
-      child.on("error", (err) => {
-        clearTimeout(timeout);
-        reject(err);
-      });
     });
   }
   send(msg) {
@@ -153,6 +171,115 @@ var ClientTransport = class {
     }
   }
 };
+
+// src/client/websocket-transport.ts
+var WebSocketClientTransport = class {
+  ws = null;
+  handlers = /* @__PURE__ */ new Set();
+  closed = false;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  start() {
+    const WS = globalThis.WebSocket;
+    if (!WS) {
+      return Promise.reject(
+        new Error(
+          "global WebSocket is not available \u2014 Node \u2265 22 is required for the remote ACP transport"
+        )
+      );
+    }
+    const timeoutMs = this.opts.handshakeTimeoutMs ?? 3e4;
+    return new Promise((resolve3, reject) => {
+      let settled = false;
+      const ws = new WS(this.opts.url, this.opts.protocols);
+      this.ws = ws;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        try {
+          ws.close();
+        } catch {
+        }
+        reject(new Error(`WebSocket failed to open within ${timeoutMs}ms`));
+      }, timeoutMs);
+      ws.addEventListener("open", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve3();
+      });
+      ws.addEventListener("error", (ev) => {
+        if (settled) {
+          this.closed = true;
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "WebSocket error";
+        reject(new Error(message));
+      });
+      ws.addEventListener("close", () => {
+        this.closed = true;
+      });
+      ws.addEventListener("message", (ev) => {
+        this.onData(ev.data);
+      });
+    });
+  }
+  send(msg) {
+    if (this.closed || !this.ws) {
+      return Promise.reject(new Error("WebSocket transport is not open"));
+    }
+    try {
+      this.ws.send(JSON.stringify(msg));
+      return Promise.resolve();
+    } catch (err) {
+      return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+  onMessage(handler) {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+  stop() {
+    this.closed = true;
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+      }
+      this.ws = null;
+    }
+  }
+  onData(data) {
+    const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? Buffer.from(data).toString("utf8") : Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+    if (!text.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        try {
+          this.dispatch(JSON.parse(line));
+        } catch {
+        }
+      }
+      return;
+    }
+    this.dispatch(msg);
+  }
+  dispatch(msg) {
+    for (const handler of [...this.handlers]) {
+      try {
+        handler(msg);
+      } catch {
+      }
+    }
+  }
+};
 var DEFAULT_OPTIONS = {
   asyncTools: true,
   pollIntervalMs: 500,
@@ -195,6 +322,7 @@ var ToolTranslator = class {
    */
   async callTool(transport, name, args, callId = crypto.randomUUID()) {
     await transport.send({
+      jsonrpc: "2.0",
       method: "tools/call",
       id: callId,
       params: { name, arguments: args }
@@ -318,12 +446,11 @@ function randomHex(bytes) {
 }
 
 // src/client/permission.ts
-var defaultPermissionPolicy = async (req) => {
-  if (req.signal.aborted) return { outcome: "cancelled" };
-  const ranked = [...req.options].sort((a, b) => {
+function pickAllow(options) {
+  const ranked = [...options].sort((a, b) => {
     const score = (k) => {
-      if (k === "allow_always") return 0;
-      if (k === "allow_once") return 1;
+      if (k === "allow_once") return 0;
+      if (k === "allow_always") return 1;
       if (k === "reject_once") return 2;
       return 3;
     };
@@ -334,7 +461,33 @@ var defaultPermissionPolicy = async (req) => {
     return { outcome: "cancelled" };
   }
   return { outcome: "selected", optionId: chosen.optionId };
+}
+function pickReject(options) {
+  const reject = options.find(
+    (o) => o.kind === "reject_once" || o.kind === "reject_always"
+  );
+  return reject ? { outcome: "selected", optionId: reject.optionId } : { outcome: "cancelled" };
+}
+var READ_ONLY_KINDS = /* @__PURE__ */ new Set(["read", "search", "fetch", "think"]);
+var defaultPermissionPolicy = async (req) => {
+  if (req.signal.aborted) return { outcome: "cancelled" };
+  return pickAllow(req.options);
 };
+var readOnlyPermissionPolicy = async (req) => {
+  if (req.signal.aborted) return { outcome: "cancelled" };
+  const kind = req.toolCall.kind;
+  if (kind && READ_ONLY_KINDS.has(kind)) {
+    return pickAllow(req.options);
+  }
+  return pickReject(req.options);
+};
+function makePermissionPolicy(decide) {
+  return async (req) => {
+    if (req.signal.aborted) return { outcome: "cancelled" };
+    const allow = await decide(req);
+    return allow ? pickAllow(req.options) : pickReject(req.options);
+  };
+}
 var TerminalServer = class {
   terminals = /* @__PURE__ */ new Map();
   projectRoot;
@@ -530,6 +683,12 @@ var ACPSession = class _ACPSession {
   nextId = 1;
   /** True after close() has been called. */
   closed = false;
+  // Agent-provided info from the initialize handshake
+  agentCapabilities = {};
+  agentInfo = null;
+  authMethods = [];
+  /** Protocol version negotiated with the agent during initialize. */
+  negotiatedVersion = ACP_PROTOCOL_VERSION;
   constructor(opts, transport) {
     this.opts = opts;
     this.transport = transport;
@@ -551,6 +710,36 @@ var ACPSession = class _ACPSession {
     this.terminalServer = new TerminalServer(termOpts);
     this.permissionPolicy = opts.permissionPolicy ?? defaultPermissionPolicy;
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Public accessors
+  // ──────────────────────────────────────────────────────────────────────
+  /** Agent capabilities advertised during initialize. */
+  getCapabilities() {
+    return { ...this.agentCapabilities };
+  }
+  /** Authentication methods advertised by the agent. */
+  getAuthMethods() {
+    return [...this.authMethods];
+  }
+  /** Agent info (name, title, version) from initialize. */
+  getAgentInfo() {
+    return this.agentInfo;
+  }
+  /** Whether the agent requires authentication (has auth methods). */
+  requiresAuth() {
+    return this.authMethods.length > 0;
+  }
+  /** Current session id, if one exists. */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /** Protocol version negotiated during initialize. */
+  getNegotiatedVersion() {
+    return this.negotiatedVersion;
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // Lifecycle — start
+  // ──────────────────────────────────────────────────────────────────────
   /**
    * Spawn the child, run the initialize handshake, install the
    * message dispatch, and return a ready session.
@@ -560,20 +749,37 @@ var ACPSession = class _ACPSession {
       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);
+    return _ACPSession.attach(opts, transport, `failed to spawn ${opts.command}`);
+  }
+  /**
+   * Connect to a REMOTE ACP agent over a WebSocket instead of spawning a
+   * local subprocess. `opts.command` is ignored for the wire (a label is
+   * still useful for `role`); everything else (projectRoot sandbox for
+   * fs/terminal, timeouts, permission policy, MCP servers) applies the same.
+   */
+  static async connectWebSocket(wsOpts, opts) {
+    const transport = new WebSocketClientTransport(wsOpts);
+    return _ACPSession.attach(opts, transport, `failed to connect to ${wsOpts.url}`);
+  }
+  /**
+   * Connect using a caller-supplied transport. Lets advanced callers plug
+   * in their own wire (SDK streams, in-process pipes, test doubles).
+   */
+  static async connect(transport, opts) {
+    return _ACPSession.attach(opts, transport, "failed to connect transport");
+  }
+  /** Shared connect path: start the transport, install dispatch, handshake. */
+  static async attach(opts, transport, spawnErrLabel) {
     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);
+      throw new ACPSessionError("spawn_failed", `${spawnErrLabel}: ${msg}`, err);
     }
     const session = new _ACPSession(opts, transport);
     transport.onMessage((msg) => session.handleMessage(msg));
@@ -588,14 +794,16 @@ var ACPSession = class _ACPSession {
     }
     return session;
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Initialization
+  // ──────────────────────────────────────────────────────────────────────
   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 }
+        terminal: true
       },
       clientInfo: { name: "wrongstack", title: "WrongStack", version: "0.263.0" }
     });
@@ -606,53 +814,344 @@ var ACPSession = class _ACPSession {
       throw new ACPSessionError("protocol_error", "initialize returned no protocolVersion");
     }
     const r = result;
-    if (r.protocolVersion !== ACP_PROTOCOL_VERSION) {
+    if (r.protocolVersion > ACP_PROTOCOL_VERSION) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        `agent requires protocolVersion=${r.protocolVersion}, client supports up to ${ACP_PROTOCOL_VERSION}`
+      );
+    }
+    this.negotiatedVersion = r.protocolVersion;
+    this.agentCapabilities = r.agentCapabilities ?? {};
+    this.agentInfo = r.agentInfo ?? null;
+    this.authMethods = r.authMethods ?? [];
+    this.state = "ready";
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // Authentication
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Authenticate with the agent using one of the advertised auth methods.
+   * Call this AFTER start() and BEFORE any session/new call.
+   *
+   * Throws ACPSessionError('auth_failed') if the agent rejects the
+   * authentication or if the methodId is not in the advertised list.
+   */
+  async authenticate(methodId) {
+    if (this.state === "closed") {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (this.state !== "ready") {
+      throw new ACPSessionError(
+        "protocol_error",
+        `authenticate called in state=${this.state} (expected 'ready')`
+      );
+    }
+    if (!this.authMethods.some((m) => m.id === methodId)) {
+      throw new ACPSessionError(
+        "auth_failed",
+        `auth method "${methodId}" not in advertised methods: ${this.authMethods.map((m) => m.id).join(", ")}`
+      );
+    }
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "authenticate", { methodId });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("auth_failed", `authenticate failed: ${result.message}`, result);
+    }
+    this.state = "authenticated";
+  }
+  /**
+   * Log out from the current authenticated session.
+   * Only callable if the agent advertises `auth.logout` capability.
+   */
+  async logout() {
+    if (this.state === "closed") {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (!this.agentCapabilities.auth?.logout) {
       throw new ACPSessionError(
         "unsupported_capability",
-        `agent speaks protocolVersion=${r.protocolVersion}, client speaks ${ACP_PROTOCOL_VERSION}`
+        "agent does not support logout (auth.logout capability not advertised)"
       );
     }
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "logout", {});
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("logout_failed", `logout failed: ${result.message}`, result);
+    }
     this.state = "ready";
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Session management
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Load an existing session. The agent replays the conversation history
+   * via session/update notifications before responding.
+   *
+   * Only works if the agent advertises `loadSession` capability.
+   *
+   * @param sessionId - The session to load
+   * @param mcpServers - Optional MCP servers (defaults to options.mcpServers)
+   * @param cwd - Optional working directory (defaults to options.cwd or projectRoot)
+   */
+  async loadSession(sessionId, mcpServers, cwd) {
+    if (this.closed) {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (!this.agentCapabilities.loadSession) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        "agent does not support session/load (loadSession capability not advertised)"
+      );
+    }
+    if (this.sessionId) {
+      await this.closeSession();
+    }
+    this.resetScratch();
+    const servers = this.filterMcpServers(mcpServers ?? this.opts.mcpServers);
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/load", {
+      sessionId,
+      cwd: cwd ?? this.opts.cwd ?? this.opts.projectRoot,
+      mcpServers: servers
+    });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/load failed: ${result.message}`, result);
+    }
+    this.sessionId = sessionId;
+  }
+  /**
+   * Resume an existing session without replaying history.
+   *
+   * Only works if the agent advertises `sessionCapabilities.resume`.
+   *
+   * @param sessionId - The session to resume
+   * @param mcpServers - Optional MCP servers (defaults to options.mcpServers)
+   * @param cwd - Optional working directory (defaults to options.cwd or projectRoot)
+   */
+  async resumeSession(sessionId, mcpServers, cwd) {
+    if (this.closed) {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (!this.agentCapabilities.sessionCapabilities?.resume) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        "agent does not support session/resume (sessionCapabilities.resume not advertised)"
+      );
+    }
+    if (this.sessionId) {
+      await this.closeSession();
+    }
+    const servers = this.filterMcpServers(mcpServers ?? this.opts.mcpServers);
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/resume", {
+      sessionId,
+      cwd: cwd ?? this.opts.cwd ?? this.opts.projectRoot,
+      mcpServers: servers
+    });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/resume failed: ${result.message}`, result);
+    }
+    this.sessionId = sessionId;
+  }
+  /**
+   * List existing sessions known to the agent.
+   *
+   * Only works if the agent advertises `sessionCapabilities.list`.
+   */
+  async listSessions(cursor, cwd) {
+    if (this.closed) {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (!this.agentCapabilities.sessionCapabilities?.list) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        "agent does not support session/list (sessionCapabilities.list not advertised)"
+      );
+    }
+    const id = this.allocId();
+    const params = {};
+    if (cursor !== void 0) params.cursor = cursor;
+    if (cwd !== void 0) params.cwd = cwd;
+    const result = await this.sendRequest(id, "session/list", params);
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/list failed: ${result.message}`, result);
+    }
+    const r = result;
+    return {
+      sessions: r.sessions ?? [],
+      nextCursor: r.nextCursor
+    };
+  }
+  /**
+   * Delete a session from the agent's session list.
+   *
+   * Only works if the agent advertises `sessionCapabilities.delete`.
+   */
+  async deleteSession(sessionId) {
+    if (this.closed) {
+      throw new ACPSessionError("closed", "session is closed");
+    }
+    if (!this.agentCapabilities.sessionCapabilities?.delete) {
+      throw new ACPSessionError(
+        "unsupported_capability",
+        "agent does not support session/delete (sessionCapabilities.delete not advertised)"
+      );
+    }
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/delete", { sessionId });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/delete failed: ${result.message}`, result);
+    }
+    if (this.sessionId === sessionId) {
+      this.sessionId = null;
+    }
+  }
+  /**
+   * Fork a session — create a new session from an existing one.
+   */
+  async forkSession(sourceSessionId, cwd, mcpServers) {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const servers = this.filterMcpServers(mcpServers ?? this.opts.mcpServers);
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/fork", {
+      sessionId: sourceSessionId,
+      cwd: cwd ?? this.opts.cwd ?? this.opts.projectRoot,
+      ...servers.length > 0 ? { mcpServers: servers } : {}
+    });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/fork failed: ${result.message}`, result);
+    }
+    const newId = result.sessionId;
+    if (typeof newId !== "string" || !newId) {
+      throw new ACPSessionError("protocol_error", "session/fork returned no sessionId", result);
+    }
+    return newId;
+  }
+  /**
+   * Set the active mode for a session.
+   */
+  async setMode(sessionId, modeId) {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/set_mode", { sessionId, modeId });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/set_mode failed: ${result.message}`, result);
+    }
+  }
+  /**
+   * Set a configuration option for a session.
+   */
+  async setConfigOption(sessionId, configId, value) {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "session/set_config_option", {
+      sessionId,
+      configId,
+      value
+    });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `session/set_config_option failed: ${result.message}`, result);
+    }
+  }
+  /**
+   * List available providers and the current provider.
+   */
+  async listProviders() {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "providers/list", {});
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `providers/list failed: ${result.message}`, result);
+    }
+    const r = result;
+    return { providers: r.providers ?? [], currentProviderId: r.currentProviderId ?? null };
+  }
+  /**
+   * Send an MCP message to the agent for routing.
+   */
+  async mcpMessage(connectionId, message) {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "mcp/message", { connectionId, message });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `mcp/message failed: ${result.message}`, result);
+    }
+    return result;
+  }
+  /**
+   * Set the active provider for the agent.
+   */
+  async setProvider(providerId, config) {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "providers/set", { providerId, ...config ?? {} });
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `providers/set failed: ${result.message}`, result);
+    }
+  }
+  /**
+   * Disable the current provider.
+   */
+  async disableProvider() {
+    if (this.closed) throw new ACPSessionError("closed", "session is closed");
+    const id = this.allocId();
+    const result = await this.sendRequest(id, "providers/disable", {});
+    if (isJsonRpcError(result)) {
+      throw new ACPSessionError("prompt_failed", `providers/disable failed: ${result.message}`, result);
+    }
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // Prompt
+  // ──────────────────────────────────────────────────────────────────────
   /**
    * Run one prompt turn. Creates a session if needed, sends the
    * prompt, streams session/update notifications, and resolves with
    * the agent's response.
    *
+   * @param blocks - Content blocks to send. Use `textContent()` for plain
+   *   text, or include ImageContent/AudioContent if the agent's
+   *   `promptCapabilities` allow it.
+   * @param signal - AbortSignal for cancellation.
+   *
    * 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) {
+  async prompt(blocks, signal, onProgress) {
     if (this.closed) {
       throw new ACPSessionError("closed", "session is closed");
     }
-    if (this.state !== "ready" && this.state !== "done") {
+    if (this.state !== "ready" && this.state !== "authenticated" && this.state !== "done") {
       throw new ACPSessionError("protocol_error", `prompt called in state=${this.state}`);
     }
     if (signal.aborted) {
-      return { text: "", stopReason: "cancelled", hasText: false };
+      return emptyRunResult("cancelled");
     }
     if (!this.sessionId) {
       await this.createSession();
     }
     this.resetScratch();
+    this.progressHandler = onProgress ?? null;
     const promptId = this.allocId();
     const turnPromise = this.sendRequest(
       promptId,
       "session/prompt",
       {
         sessionId: this.sessionId,
-        prompt: [textContent(text)]
+        prompt: blocks
       },
       this.timeoutMs
     );
     let cancelled = false;
     const onAbort = () => {
       cancelled = true;
-      this.transport.send({ method: "session/cancel", params: { sessionId: this.sessionId } }).catch(() => {
+      this.transport.send({
+        jsonrpc: "2.0",
+        method: "session/cancel",
+        params: { sessionId: this.sessionId }
+      }).catch(() => {
       });
     };
     signal.addEventListener("abort", onAbort, { once: true });
@@ -670,6 +1169,7 @@ var ACPSession = class _ACPSession {
       throw new ACPSessionError("prompt_failed", `session/prompt failed: ${msg}`, err);
     } finally {
       signal.removeEventListener("abort", onAbort);
+      this.progressHandler = null;
     }
     this.state = "done";
     if (isJsonRpcError(response)) {
@@ -682,14 +1182,18 @@ var ACPSession = class _ACPSession {
       stopReason,
       hasText: finalText.length > 0,
       usage: this.scratch.usage,
-      plan: this.scratch.plan
+      plan: this.scratch.plan,
+      toolCalls: [...this.scratch.toolCalls.values()],
+      diffs: this.scratch.diffs,
+      thoughts: this.scratch.thoughts
     };
   }
   async createSession() {
+    const servers = this.filterMcpServers(this.opts.mcpServers);
     const id = this.allocId();
     const result = await this.sendRequest(id, "session/new", {
       cwd: this.opts.cwd ?? this.opts.projectRoot,
-      mcpServers: []
+      mcpServers: servers
     });
     if (isJsonRpcError(result)) {
       throw new ACPSessionError(
@@ -708,12 +1212,40 @@ var ACPSession = class _ACPSession {
     }
     this.sessionId = sessionId;
   }
+  /**
+   * Close the current session gracefully (if the agent supports it).
+   *
+   * Sends `session/close` JSON-RPC request, then clears the local
+   * session id. Best-effort — errors are swallowed so the caller can
+   * always proceed to transport teardown.
+   */
+  async closeSession() {
+    if (!this.sessionId) return;
+    const sid = this.sessionId;
+    this.sessionId = null;
+    if (this.agentCapabilities.sessionCapabilities?.close) {
+      const id = this.allocId();
+      try {
+        await this.sendRequest(id, "session/close", { sessionId: sid }, 1e4);
+      } catch {
+      }
+    }
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // Lifecycle — close
+  // ──────────────────────────────────────────────────────────────────────
   /** Tear down the session and kill the child process. */
   async close() {
     if (this.closed) return;
     this.closed = true;
     this.state = "closed";
     this.terminalServer.releaseAll();
+    if (this.sessionId && this.agentCapabilities.sessionCapabilities?.close) {
+      try {
+        await this.closeSession();
+      } catch {
+      }
+    }
     for (const [, p] of this.pending) {
       clearTimeout(p.timeoutHandle);
       p.reject(new ACPSessionError("closed", "session was closed"));
@@ -724,6 +1256,24 @@ var ACPSession = class _ACPSession {
     } catch {
     }
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Helpers
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Filter MCP servers according to agent capabilities.
+   * - Stdio servers are always included.
+   * - HTTP servers are only included if agent supports mcpCapabilities.http.
+   * - SSE servers are only included if agent supports mcpCapabilities.sse.
+   */
+  filterMcpServers(servers) {
+    if (!servers || servers.length === 0) return [];
+    const mcpCaps = this.agentCapabilities.mcpCapabilities ?? {};
+    return servers.filter((s) => {
+      if ("type" in s && s.type === "http") return mcpCaps.http === true;
+      if ("type" in s && s.type === "sse") return mcpCaps.sse === true;
+      return true;
+    });
+  }
   // ────────────────────────────────────────────────────────────────────
   // Wire layer
   // ────────────────────────────────────────────────────────────────────
@@ -757,6 +1307,28 @@ var ACPSession = class _ACPSession {
       });
     });
   }
+  /**
+   * Send a JSON-RPC 2.0 success response to an agent-initiated request.
+   *
+   * Per JSON-RPC 2.0 (and the official ACP SDK's message router) a Response
+   * object MUST carry `jsonrpc: "2.0"` and MUST NOT carry a `method` field —
+   * the SDK classifies any object with a `method` key as a Request and drops
+   * it as a response, so an agent's `fs/*`, `terminal/*`, or
+   * `session/request_permission` callback would hang forever. The legacy
+   * `ACPMessage` type predates v1 (requires `method`, lacks `jsonrpc`), so we
+   * build the correct wire object and cast at the boundary.
+   */
+  sendResult(id, result) {
+    return this.transport.send({ jsonrpc: "2.0", id, result });
+  }
+  /** Send a JSON-RPC 2.0 error response (no `method` field, per spec). */
+  sendErrorResponse(id, code, message) {
+    return this.transport.send({
+      jsonrpc: "2.0",
+      id,
+      error: { code, message }
+    });
+  }
   handleMessage(msg) {
     if (msg.id !== void 0 && (msg.result !== void 0 || msg.error !== void 0)) {
       const pending = this.pending.get(msg.id);
@@ -786,6 +1358,23 @@ var ACPSession = class _ACPSession {
       void this.handleTerminalRequest(msg);
       return;
     }
+    if (msg.method === "mcp/connect" || msg.method === "mcp/message" || msg.method === "mcp/disconnect") {
+      if (msg.id !== void 0) {
+        this.sendResult(msg.id, {}).catch(() => {
+        });
+      }
+      return;
+    }
+    if (msg.method === "elicitation/create" || msg.method === "elicitation/complete") {
+      if (msg.id !== void 0) {
+        this.sendResult(msg.id, {}).catch(() => {
+        });
+      }
+      return;
+    }
+    if (msg.method === "$/cancel_request") {
+      return;
+    }
     if (msg.method) {
       console.warn(`[acp-session] unhandled method: ${msg.method}`);
     }
@@ -794,31 +1383,44 @@ var ACPSession = class _ACPSession {
     const update = msg.params?.update;
     if (typeof update !== "object" || update === null) return;
     const u = update;
+    this.emitProgress({ type: "raw", update: u });
     switch (u.sessionUpdate) {
       case "agent_message_chunk": {
         const text = extractText(u.content);
-        if (text) this.accumulatedText(text);
+        if (text) {
+          this.scratch.text += text;
+          this.emitProgress({ type: "message", text });
+        }
         return;
       }
-      case "thought_chunk":
+      case "thought_chunk": {
+        const text = extractText(u.content);
+        if (text) {
+          this.scratch.thoughts += text;
+          this.emitProgress({ type: "thought", text });
+        }
         return;
+      }
       case "tool_call":
-      case "tool_call_update":
+      case "tool_call_update": {
+        this.captureToolCall(u, u.sessionUpdate === "tool_call");
         return;
+      }
       case "plan":
         if (Array.isArray(u.entries)) {
-          this.accumulatedPlan(u.entries);
+          this.scratch.plan = u.entries;
+          this.emitProgress({ type: "plan", entries: u.entries });
         }
         return;
       case "usage_update":
         if (typeof u.used === "number" && typeof u.size === "number") {
-          this.accumulatedUsage({
+          const usage = {
             used: u.used,
             size: u.size,
-            ...typeof u.cost === "object" && u.cost !== null ? {
-              cost: u.cost
-            } : {}
-          });
+            ...typeof u.cost === "object" && u.cost !== null ? { cost: u.cost } : {}
+          };
+          this.scratch.usage = usage;
+          this.emitProgress({ type: "usage", usage });
         }
         return;
       case "available_commands_update":
@@ -826,27 +1428,62 @@ var ACPSession = class _ACPSession {
       case "config_option_update":
       case "session_info_update":
       case "user_message_chunk":
+      case "next_edit_suggestions":
+      case "elicitation":
         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;
+  /**
+   * Fold a `tool_call` / `tool_call_update` notification into the scratch
+   * tool-call map (deduped by toolCallId), extract any `diff` content into
+   * the diffs list, and emit live progress.
+   */
+  captureToolCall(u, isNew) {
+    const toolCallId = typeof u.toolCallId === "string" ? u.toolCallId : "";
+    if (!toolCallId) return;
+    const prev = this.scratch.toolCalls.get(toolCallId);
+    const record = {
+      toolCallId,
+      title: typeof u.title === "string" ? u.title : prev?.title ?? toolCallId,
+      kind: typeof u.kind === "string" ? u.kind : prev?.kind,
+      status: typeof u.status === "string" ? u.status : prev?.status ?? (isNew ? "pending" : "in_progress"),
+      rawInput: isRecord(u.rawInput) ? u.rawInput : prev?.rawInput,
+      rawOutput: isRecord(u.rawOutput) ? u.rawOutput : prev?.rawOutput
+    };
+    this.scratch.toolCalls.set(toolCallId, record);
+    if (Array.isArray(u.content)) {
+      for (const c of u.content) {
+        if (c && typeof c === "object" && c.type === "diff") {
+          const diff = {
+            path: c.path,
+            oldText: c.oldText,
+            newText: c.newText
+          };
+          this.scratch.diffs.push(diff);
+          this.emitProgress({ type: "diff", diff });
+        }
+      }
+    }
+    this.emitProgress({
+      type: isNew ? "tool_call" : "tool_call_update",
+      toolCall: record
+    });
   }
-  accumulatedUsage(u) {
-    this.scratch.usage = u;
+  emitProgress(event) {
+    if (!this.progressHandler) return;
+    try {
+      this.progressHandler(event);
+    } catch {
+    }
   }
+  /** Live progress handler installed for the duration of a `prompt()` turn. */
+  progressHandler = null;
+  // Per-prompt scratch state
+  scratch = { text: "", thoughts: "", toolCalls: /* @__PURE__ */ new Map(), diffs: [] };
   resetScratch() {
-    this.scratch = { text: "" };
+    this.scratch = { text: "", thoughts: "", toolCalls: /* @__PURE__ */ new Map(), diffs: [] };
   }
   async handlePermissionRequest(msg) {
     const id = msg.id;
@@ -855,11 +1492,7 @@ var ACPSession = class _ACPSession {
     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" }
-      });
+      await this.sendErrorResponse(id, -32602, "toolCall is required");
       return;
     }
     const policyAbort = new AbortController();
@@ -868,22 +1501,14 @@ var ACPSession = class _ACPSession {
       options,
       signal: policyAbort.signal
     });
-    await this.transport.send({
-      id,
-      method: "session/request_permission",
-      result: { outcome }
-    });
+    await this.sendResult(id, { 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" }
-      });
+      await this.sendErrorResponse(id, -32602, "path is required");
       return;
     }
     try {
@@ -892,19 +1517,19 @@ var ACPSession = class _ACPSession {
           sessionId: params.sessionId ?? "",
           path: params.path
         });
-        await this.transport.send({ id, method: msg.method, result });
+        await this.sendResult(id, result);
       } else {
         await this.fileServer.writeTextFile({
           sessionId: params.sessionId ?? "",
           path: params.path,
           content: params.content ?? ""
         });
-        await this.transport.send({ id, method: msg.method, result: {} });
+        await this.sendResult(id, {});
       }
     } 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 } });
+      await this.sendErrorResponse(id, code, message);
     }
   }
   async handleTerminalRequest(msg) {
@@ -929,61 +1554,73 @@ var ACPSession = class _ACPSession {
             createOpts.outputByteLimit = params.outputByteLimit;
           }
           const result = this.terminalServer.create(createOpts);
-          await this.transport.send({ id, method: msg.method, result });
+          await this.sendResult(id, 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 });
+          await this.sendResult(id, 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 });
+          await this.sendResult(id, exit);
           return;
         }
         case "terminal/kill": {
           const terminalId = String(params.terminalId ?? "");
           this.terminalServer.kill(terminalId);
-          await this.transport.send({ id, method: msg.method, result: {} });
+          await this.sendResult(id, {});
           return;
         }
         case "terminal/release": {
           const terminalId = String(params.terminalId ?? "");
           this.terminalServer.release(terminalId);
-          await this.transport.send({ id, method: msg.method, result: {} });
+          await this.sendResult(id, {});
           return;
         }
         default:
-          await this.transport.send({
-            id,
-            method: msg.method,
-            error: { code: -32601, message: `unknown method: ${msg.method}` }
-          });
+          await this.sendErrorResponse(id, -32601, `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 }
-      });
+      await this.sendErrorResponse(id, -32603, message);
     }
   }
 };
 function textContent(text) {
   return { type: "text", text };
 }
+function imageContent(mimeType, data) {
+  return { type: "image", mimeType, data };
+}
+function audioContent(mimeType, data) {
+  return { type: "audio", mimeType, data };
+}
 function extractText(block) {
   if (typeof block !== "object" || block === null) return "";
   const b = block;
   if (b.type === "text" && typeof b.text === "string") return b.text;
+  if (b.type === "resource" && b.resource && typeof b.resource === "object" && typeof b.resource.text === "string") {
+    return b.resource.text;
+  }
   return "";
 }
-
-// src/integration/acp-subagent-runner.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function emptyRunResult(stopReason) {
+  return {
+    text: "",
+    stopReason,
+    hasText: false,
+    toolCalls: [],
+    diffs: [],
+    thoughts: ""
+  };
+}
 async function makeACPSubagentRunner(options) {
   const { runner, stop } = await makeACPSubagentRunnerWithStop(options);
   const wrappedRunner = async (task, ctx) => {
@@ -998,42 +1635,69 @@ async function makeACPSubagentRunner(options) {
 async function makeACPSubagentRunnerWithStop(options) {
   const projectRoot = options.projectRoot ?? options.cwd ?? process.cwd();
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
+  const persistent = options.persistent === true;
+  let shared = null;
+  const startSession = async () => {
+    return 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,
+      ...options.permissionPolicy !== void 0 ? { permissionPolicy: options.permissionPolicy } : {},
+      ...options.mcpServers !== void 0 ? { mcpServers: options.mcpServers } : {}
+    });
+  };
   const runner = async (task, ctx) => {
-    let session = null;
+    let session;
+    const reuse = persistent && shared !== 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
-      });
+      session = reuse ? shared : await startSession();
+      if (persistent) shared = session;
     } catch (err) {
       throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
     }
+    const onProgress = (event) => {
+      try {
+        ctx.budget.markActivity();
+      } catch {
+      }
+      options.onProgress?.(event);
+    };
     try {
-      const result = await session.prompt(task.description, ctx.signal);
+      const result = await session.prompt(
+        [textContent(task.description)],
+        ctx.signal,
+        onProgress
+      );
       return {
         result: result.text,
         iterations: 1,
-        toolCalls: 0
+        toolCalls: result.toolCalls.length
       };
     } catch (err) {
-      if (err instanceof ACPSessionError && err.kind === "aborted") {
-        throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
-      }
       throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
     } finally {
+      if (!persistent) {
+        try {
+          await session.close();
+        } catch {
+        }
+      }
+    }
+  };
+  const stop = async () => {
+    if (shared) {
+      const s = shared;
+      shared = null;
       try {
-        await session.close();
+        await s.close();
       } catch {
       }
     }
   };
-  const stop = () => {
-  };
   return { runner, stop };
 }
 function acpErrorToSubagentError(err, subagentId) {
@@ -1072,6 +1736,9 @@ function mapACPKind(acpKind) {
       return "bridge_failed";
     case "prompt_failed":
       return "tool_failed";
+    case "auth_failed":
+    case "logout_failed":
+      return "bridge_failed";
     case "aborted":
       return "aborted_by_parent";
     case "closed":
@@ -1092,6 +1759,6 @@ function isRetryable(kind) {
   }
 }
 
-export { ClientTransport, ToolTranslator, makeACPSubagentRunner };
+export { ACPSession, ACPSessionError, ClientTransport, ToolTranslator, WebSocketClientTransport, audioContent, defaultPermissionPolicy, imageContent, makeACPSubagentRunner, makePermissionPolicy, readOnlyPermissionPolicy, textContent };
 //# sourceMappingURL=client.js.map
 //# sourceMappingURL=client.js.map