@yemi33/minions 0.1.2372 → 0.1.2374

package/engine/acp-transport.js

@@ -0,0 +1,594 @@
+/**
+ * engine/acp-transport.js — Shared ACP (Agent Client Protocol) transport layer
+ * (P-4c6e8a72, extracted from engine/cc-worker-pool.js).
+ *
+ * `copilot --acp` is a long-lived JSON-RPC server over stdin/stdout. This
+ * module owns the protocol-level plumbing that is identical regardless of
+ * WHO is pooling the worker (a CC/doc-chat tab vs. a fleet agent dispatch):
+ *
+ *   - process spawn (`spawnAcp`) — resolves the `copilot` binary via the
+ *     runtime adapter and launches it with `--acp`.
+ *   - newline-delimited JSON-RPC framing, request/response correlation, and
+ *     `session/update` notification dispatch (the `Worker` class).
+ *   - typed error envelope (`ERROR_CODES` / `typedError`).
+ *   - ACP `session/update` content helpers (`extractChunkText`,
+ *     `mapAcpToolCallToToolUse`) and the `session/new` params builder
+ *     (`buildSessionNewParams`).
+ *
+ * Consumers (engine/cc-worker-pool.js — one persistent worker per CC/doc-chat
+ * tab, permanent ownership; engine/agent-worker-pool.js — a fixed-size pool of
+ * workers leased/released per fleet agent dispatch) own their OWN pooling
+ * policy (eviction rules, idle reaping, FIFO acquire queues, mcpServersHash
+ * matching strategy) on top of this shared transport. Neither consumer
+ * duplicates the JSON-RPC framing code — both `require('./acp-transport')`.
+ *
+ * `Worker` takes its OS-process side effects (`spawnAcp`, `killImmediate`,
+ * `now`) via constructor-injected `internals` rather than a module-level
+ * singleton, so two independent pools (CC's tab pool and the fleet's agent
+ * pool) can each stub their own `_internals` for tests without stepping on
+ * each other's module state.
+ *
+ * See `notes/archive/2026-05-13-ripley-W-mp3h2wq2000e64f7-2026-05-13-0301.md`
+ * for the original ACP protocol probe (line framing, request/response
+ * correlation, cold-vs-warm timings, cancel semantics, configOptions surface)
+ * and `notes/archive/2026-07-10-ripley-P-7a1c2e4f-2026-07-10-0141.md` for the
+ * follow-up spike confirming: cancel is safe to reuse (no eviction needed
+ * purely for a cancel), `stopReason` is `end_turn` even after a cancel on
+ * copilot CLI 1.0.70 (NOT `cancelled`), and `session/new`'s `mcpServers`
+ * param only accepts remote http/sse servers — local/stdio MCP servers are
+ * resolved from `$COPILOT_HOME/mcp-config.json` at process boot, so a
+ * changed local-server set requires a full respawn (not just a fresh
+ * `session/new`).
+ *
+ * No new npm deps — Node built-ins only (child_process, crypto).
+ */
+
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+
+// W-mpmwxni2000c25c7-c — typed error codes the transport emits through every
+// failure exit so a consumer (CC streaming handler / doc-chat pool wrapper /
+// fleet agent-worker-pool / SSE writer) can render a structured error
+// envelope instead of parsing the stderr string.
+const ERROR_CODES = Object.freeze({
+  // spawn() threw synchronously OR the child process emitted an 'error'
+  // event (binary missing on PATH, exec failed, EPERM, etc.). Retriable
+  // because a transient PATH / fs glitch may recover.
+  WORKER_SPAWN_FAILED: 'worker-spawn-failed',
+  // The worker process exited DURING the ACP handshake (initialize or
+  // session/new) — usually `copilot login` is incomplete or the CLI
+  // version is too old. Also fires when session/new returns no
+  // sessionId. Retriable: the caller swaps to a fallback model / a re-auth
+  // may unblock the next attempt.
+  ACP_HANDSHAKE_FAILED: 'acp-handshake-failed',
+  // The worker process exited AFTER a successful handshake (the daemon
+  // died mid-turn). Retriable — the next call cold-spawns a fresh worker.
+  WORKER_DIED: 'worker-died',
+  // The consumer's per-turn timeout fired before the ACP session/prompt
+  // resolved. Owned by the consumer (the transport itself has no turn
+  // timeout) but exported here so all callers stringify the same constant.
+  // Retriable — most timeouts are transient.
+  CC_TURN_TIMEOUT: 'cc-turn-timeout',
+});
+
+// Build a typed Error carrying the `{ message, code, retriable }` envelope
+// fields the consumer expects. Plain Errors flow through unchanged; the
+// helper only stamps the extra metadata. Keep retriable defaulting to
+// `true` so a caller that forgets to set it still gets the safe default.
+function typedError(message, code, retriable = true) {
+  const err = new Error(message);
+  err.code = code;
+  err.retriable = retriable;
+  return err;
+}
+
+// Cap concurrent warm spawns triggered by a burst of acquisitions. Without a
+// cap, a burst of callers would fan out N parallel cold spawns; with one,
+// the excess waits in FIFO order while the first few warm. Exported so
+// consumers that pre-warm (like cc-worker-pool.js's warmTab) can share the
+// same knob instead of hardcoding their own copy.
+const WARM_MAX_CONCURRENT = 3;
+
+// Real spawn implementation — resolves `copilot` through the runtime adapter
+// so every ACP transport consumer gets the SAME native/leadingArgs contract
+// as the only other spawn site (engine/spawn-agent.js ~line 595). A bare
+// `spawn('copilot', {shell:false})` cannot exec a `.cmd`/`.ps1`/extensionless
+// npm shim on Windows — it ENOENTs instantly (copilot issue #2370 /
+// W-mqid8uev). resolveBinary() resolves the real JS entry
+// (node_modules/@github/copilot/index.js) and reports whether to spawn it
+// directly (native) or under the current Node process (shim).
+function spawnAcp({ cwd } = {}) {
+  const copilot = require('./runtimes/copilot');
+  const resolved = copilot.resolveBinary({ env: process.env });
+  if (!resolved || !resolved.bin) {
+    throw new Error(
+      `copilot binary not resolvable -- ${copilot.installHint || 'install the GitHub Copilot CLI'}`
+    );
+  }
+  const { bin, native, leadingArgs = [] } = resolved;
+  const acpArgs = [...leadingArgs, '--acp', '--allow-all', '--max-autopilot-continues', '1'];
+  // Mirror engine/spawn-agent.js: native binaries run directly; a non-native
+  // (JS entry / npm shim) runs under process.execPath as `node <bin> ...`.
+  const execBin = native ? bin : process.execPath;
+  const execArgs = native ? acpArgs : [bin, ...acpArgs];
+  return spawn(execBin, execArgs, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    cwd: cwd || process.cwd(),
+    windowsHide: true,
+    // Don't pass shell:true — the native/leadingArgs handling above already
+    // produces a directly-spawnable argv, and a shell wrapper would swallow
+    // the stdin/stdout JSON-RPC framing.
+  });
+}
+
+// Real kill implementation — lazy require so a caller that stubs its own
+// _internals for tests doesn't need engine/shared loaded.
+function killImmediate(proc) {
+  try {
+    const shared = require('./shared');
+    shared.killImmediate(proc);
+  } catch {
+    try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+  }
+}
+
+function hashMcpServers(mcpServers) {
+  // Stable hash via JSON.stringify; mcpServers is an array of plain objects
+  // in practice (name/command/env) so the natural key order is fine.
+  const json = mcpServers == null ? '[]' : JSON.stringify(mcpServers);
+  return crypto.createHash('sha256').update(json).digest('hex');
+}
+
+// Bug B (issue #2479): `model` and `effort` were stored on the Worker but
+// never forwarded to ACP `session/new`, so any model override was silently
+// dropped. Build the params object here and only include fields that are
+// defined — sending `model: undefined` would force the daemon onto its
+// built-in default instead of letting it pick whatever the user has
+// configured globally.
+function buildSessionNewParams({ cwd, mcpServers, model, effort }) {
+  const params = { cwd, mcpServers: mcpServers || [] };
+  if (model !== undefined && model !== null && model !== '') params.model = model;
+  if (effort !== undefined && effort !== null && effort !== '') params.effort = effort;
+  return params;
+}
+
+function extractChunkText(content) {
+  if (content == null) return '';
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    let out = '';
+    for (const block of content) {
+      if (block && typeof block.text === 'string') out += block.text;
+    }
+    return out;
+  }
+  if (typeof content === 'object' && typeof content.text === 'string') return content.text;
+  return '';
+}
+
+// Map an ACP `tool_call` session/update notification to the {name, input}
+// shape the dashboard's formatToolSummary already understands. ACP's `kind`
+// is a coarse category (execute|read|edit|search|fetch|think|other); we
+// translate to the closest Claude tool name so the existing chip formatters
+// keep working (Bash → "$ <cmd>", Read → "Reading <path>", etc.). Unknown
+// kinds fall back to ACP's human-readable `title` with the raw input
+// attached, which renders through the default `<title>(<key>: <val>)`
+// formatter.
+//
+// Kind-based routing is intentionally NOT used — ACP overloads `kind:read`
+// for both file-view and grep, and `kind:execute` sometimes arrives without
+// a `command`. Field-detection on rawInput is more reliable.
+function mapAcpToolCallToToolUse(update) {
+  if (!update || update.sessionUpdate !== 'tool_call') return null;
+  const rawInput = (update.rawInput && typeof update.rawInput === 'object') ? update.rawInput : {};
+  const title = update.title || update.kind || 'Tool';
+
+  if (typeof rawInput.command === 'string' && rawInput.command) {
+    return { name: 'Bash', input: { command: rawInput.command } };
+  }
+  if (typeof rawInput.pattern === 'string' && rawInput.pattern) {
+    return { name: 'Grep', input: { pattern: rawInput.pattern, path: rawInput.paths || rawInput.path || '.' } };
+  }
+  if (typeof rawInput.path === 'string' && rawInput.path) {
+    const isEdit = String(update.kind || '').toLowerCase() === 'edit';
+    return { name: isEdit ? 'Edit' : 'Read', input: { file_path: rawInput.path } };
+  }
+  if (typeof rawInput.url === 'string' && rawInput.url) {
+    return { name: 'WebFetch', input: { url: rawInput.url } };
+  }
+  return { name: title, input: {} };
+}
+
+/**
+ * Worker — one `copilot --acp` process, one ACP session, newline-delimited
+ * JSON-RPC framing over stdin/stdout.
+ *
+ * Construction does NOT spawn the process — call `_spawnAndInit()` (spawn +
+ * `initialize` + `session/new` handshake) to bring the worker up. Consumers
+ * own the higher-level lifecycle policy (permanent per-tab ownership for
+ * cc-worker-pool.js; lease/release for agent-worker-pool.js).
+ *
+ * `internals` is `{ spawnAcp({cwd}), killImmediate(proc), now() }` —
+ * constructor-injected so each consumer module can stub its OWN copy for
+ * tests (see cc-worker-pool.js's and agent-worker-pool.js's respective
+ * `_internals` objects) without the two pools' test stubs colliding on a
+ * shared module-level singleton. `trace(...parts)` is an optional structured
+ * logger (default no-op); consumers wire their own env-gated trace prefix.
+ */
+class Worker {
+  constructor({ id, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd, internals, trace }) {
+    this.id = id;
+    this.model = model;
+    this.effort = effort;
+    this.mcpServers = mcpServers || [];
+    this.mcpServersHash = mcpServersHash;
+    this.systemPromptHash = systemPromptHash;
+    this.cwd = cwd || process.cwd();
+    this._internals = internals;
+    this._trace = typeof trace === 'function' ? trace : () => {};
+
+    this.proc = null;
+    this.sessionId = null;
+    this.pending = new Map();      // id → { resolve, reject }
+    this.inflight = null;          // current { id, sessionId, onChunk, onDone, onError, signal, signalHandler, settled }
+    this.readBuf = '';
+    this.nextReqId = 1;
+    this.lastUsedAt = this._internals.now();
+    this.killed = false;
+    this.spawnError = null;
+    this.firstSystemPromptSent = false;
+    // In-flight spawn+initialize+session/new promise. Set by the consumer
+    // before the worker is registered in its own pool bookkeeping, cleared
+    // after the handshake settles. Racing callers await this to avoid the
+    // "warm-reuse path returns sessionId=null while init is still pending"
+    // hang on first message of a freshly-warmed worker (W-mpd45blx00072f04).
+    this.initPromise = null;
+  }
+
+  // ── Spawn + initialize handshake ────────────────────────────────────────
+  async _spawnAndInit() {
+    let proc;
+    try {
+      proc = this._internals.spawnAcp({ cwd: this.cwd });
+    } catch (err) {
+      // spawn() threw synchronously — typically ENOENT (copilot binary not
+      // on PATH) or EACCES. Surface as worker-spawn-failed so the consumer
+      // can show "install the CLI / fix PATH" guidance.
+      throw typedError(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        ERROR_CODES.WORKER_SPAWN_FAILED,
+        true
+      );
+    }
+    this.proc = proc;
+
+    proc.stdout.on('data', (chunk) => this._onStdout(chunk));
+    // stderr is captured for diagnostics but we don't act on it.
+    if (proc.stderr) proc.stderr.on('data', () => { /* ignore */ });
+
+    // Race the init handshake against an early process exit so an auth
+    // failure (which kills the daemon before initialize completes) surfaces
+    // a clear error instead of hanging forever.
+    let earlyExitReject;
+    const earlyExitPromise = new Promise((_, reject) => {
+      earlyExitReject = (code) => {
+        this.killed = true;
+        // Early exit DURING the handshake = acp-handshake-failed (almost
+        // always missing `copilot login`, stale CLI, or daemon crash on
+        // boot). Retriable so re-auth or a CLI upgrade can recover.
+        const err = typedError(
+          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`,
+          ERROR_CODES.ACP_HANDSHAKE_FAILED,
+          true
+        );
+        this.spawnError = err;
+        this._failAllPending(err);
+        reject(err);
+      };
+    });
+    const earlyExitHandler = (code) => earlyExitReject(code);
+    proc.once('exit', earlyExitHandler);
+
+    const errorHandler = (err) => {
+      // proc 'error' event fires when the OS can't actually start the child
+      // (ENOENT after a successful spawn() call, etc.). Treat as a spawn
+      // failure even though we made it past the synchronous spawn() above.
+      const wrapped = typedError(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`,
+        ERROR_CODES.WORKER_SPAWN_FAILED,
+        true
+      );
+      this.spawnError = wrapped;
+      this.killed = true;
+      this._failAllPending(wrapped);
+    };
+    proc.on('error', errorHandler);
+
+    try {
+      await Promise.race([
+        this._call('initialize', { protocolVersion: 1, clientCapabilities: {} }),
+        earlyExitPromise,
+      ]);
+      const result = await Promise.race([
+        this._call('session/new', buildSessionNewParams({
+          cwd: this.cwd, mcpServers: this.mcpServers, model: this.model, effort: this.effort,
+        })),
+        earlyExitPromise,
+      ]);
+      this.sessionId = result && result.sessionId;
+      if (!this.sessionId) {
+        // Handshake completed without an error but the daemon didn't hand
+        // back a sessionId — protocol violation or partial init failure.
+        throw typedError(
+          'copilot --acp failed -- session/new returned no sessionId',
+          ERROR_CODES.ACP_HANDSHAKE_FAILED,
+          true
+        );
+      }
+    } finally {
+      // Either the handshake finished (swap to a persistent exit handler that
+      // just marks killed) or it failed (proc is dying anyway).
+      proc.removeListener('exit', earlyExitHandler);
+    }
+    proc.on('exit', () => {
+      this.killed = true;
+      // Post-handshake exit = the daemon died mid-conversation. Retriable
+      // because the next call will cold-spawn a fresh worker.
+      const err = typedError(
+        'copilot --acp process exited',
+        ERROR_CODES.WORKER_DIED,
+        true
+      );
+      this._failAllPending(err);
+      // Settle inflight too if it's still hanging
+      if (this.inflight && !this.inflight.settled) {
+        const cb = this.inflight.onError;
+        this.inflight.settled = true;
+        this.inflight = null;
+        if (cb) try { cb(err); } catch { /* swallow */ }
+      }
+    });
+  }
+
+  _failAllPending(err) {
+    for (const { reject } of this.pending.values()) {
+      try { reject(err); } catch { /* swallow */ }
+    }
+    this.pending.clear();
+  }
+
+  // ── Newline-delimited JSON-RPC line framing ────────────────────────────
+  _onStdout(chunk) {
+    this.readBuf += chunk.toString('utf8');
+    let i;
+    while ((i = this.readBuf.indexOf('\n')) >= 0) {
+      const line = this.readBuf.slice(0, i).trim();
+      this.readBuf = this.readBuf.slice(i + 1);
+      if (!line) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch { continue; }
+      this._handleMessage(obj);
+    }
+  }
+
+  _handleMessage(obj) {
+    // Response (matches an outbound id)
+    if (obj.id != null && this.pending.has(obj.id)) {
+      const { resolve, reject } = this.pending.get(obj.id);
+      this.pending.delete(obj.id);
+      if (obj.error) reject(new Error(obj.error.message || 'ACP error'));
+      else resolve(obj.result);
+      return;
+    }
+    // Notification (no id) — only `session/update` matters for streaming.
+    if (obj.method === 'session/update' && obj.params) {
+      const notifSid = obj.params.sessionId;
+      const inflightSid = this.inflight ? this.inflight.sessionId : null;
+      const updKind = obj.params.update && obj.params.update.sessionUpdate;
+      if (!this.inflight) {
+        this._trace(`id=${this.id} session/update dropped: no inflight (notifSid=${notifSid} kind=${updKind})`);
+        return;
+      }
+      if (notifSid !== inflightSid) {
+        this._trace(`id=${this.id} session/update dropped: sid mismatch (notifSid=${notifSid} inflightSid=${inflightSid} kind=${updKind})`);
+        return;
+      }
+      this._trace(`id=${this.id} session/update delivered: sid=${notifSid} kind=${updKind}`);
+      const update = obj.params.update;
+      if (!update) return;
+      if (update.sessionUpdate === 'agent_message_chunk') {
+        const text = extractChunkText(update.content);
+        if (text && this.inflight.onChunk) {
+          try { this.inflight.onChunk(text); } catch { /* swallow */ }
+        }
+      } else if (update.sessionUpdate === 'tool_call' && this.inflight.onToolUse) {
+        // ACP `tool_call` (pending) → chip label via mapAcpToolCallToToolUse.
+        const mapped = mapAcpToolCallToToolUse(update);
+        if (mapped) {
+          try { this.inflight.onToolUse(mapped.name, mapped.input, update.toolCallId); }
+          catch { /* swallow */ }
+        }
+      } else if (update.sessionUpdate === 'tool_call_update' && this.inflight.onToolUpdate) {
+        // Terminal-state updates only (completed/failed). In-progress updates
+        // exist in the ACP spec but add chip churn without actionable info.
+        if (update.status === 'completed' || update.status === 'failed') {
+          try { this.inflight.onToolUpdate(update.toolCallId, update.status); }
+          catch { /* swallow */ }
+        }
+      }
+    }
+  }
+
+  _writeFrame(obj) {
+    if (this.killed) return;
+    if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) return;
+    try { this.proc.stdin.write(JSON.stringify(obj) + '\n'); }
+    catch { /* pipe may be broken; exit handler will fire */ }
+  }
+
+  _call(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = this.nextReqId++;
+      this.pending.set(id, { resolve, reject });
+      this._writeFrame({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  _notify(method, params) {
+    this._writeFrame({ jsonrpc: '2.0', method, params });
+  }
+
+  // ── Stream a single turn ───────────────────────────────────────────────
+  stream(promptText, opts = {}) {
+    const { onChunk, onToolUse, onToolUpdate, onDone, onError, signal, systemPromptText } = opts;
+    if (this.killed) {
+      const err = new Error('acp-transport: worker is closed');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    if (this.inflight) {
+      const err = new Error('acp-transport: a prompt is already in flight on this worker');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    this.lastUsedAt = this._internals.now();
+
+    // Inject the <system> block on the first prompt of a session — Copilot
+    // ACP has no in-protocol "set system prompt" method, so the per-session
+    // adapter pattern of <system>...</system> prepended to the first user
+    // message remains correct.
+    let prompt = promptText;
+    if (!this.firstSystemPromptSent && systemPromptText) {
+      prompt = `<system>\n${systemPromptText}\n</system>\n\n${promptText}`;
+    }
+    this.firstSystemPromptSent = true;
+
+    const id = this.nextReqId++;
+    const inflight = {
+      id,
+      sessionId: this.sessionId,
+      onChunk,
+      onToolUse,
+      onToolUpdate,
+      onDone,
+      onError,
+      signal,
+      signalHandler: null,
+      settled: false,
+    };
+    this.inflight = inflight;
+    this._trace(`id=${this.id} stream begin: worker.sessionId=${this.sessionId} inflight.sessionId=${inflight.sessionId} reqId=${id}`);
+
+    if (signal && typeof signal.addEventListener === 'function') {
+      inflight.signalHandler = () => this.cancel();
+      try { signal.addEventListener('abort', inflight.signalHandler); } catch { /* swallow */ }
+    }
+
+    return new Promise((resolve) => {
+      const finalize = (err, result) => {
+        if (inflight.settled) return;
+        inflight.settled = true;
+        if (this.inflight === inflight) this.inflight = null;
+        this.lastUsedAt = this._internals.now();
+        if (signal && inflight.signalHandler) {
+          try { signal.removeEventListener('abort', inflight.signalHandler); }
+          catch { /* swallow */ }
+        }
+        if (err) {
+          if (onError) try { onError(err); } catch { /* swallow */ }
+        } else {
+          if (onDone) try { onDone(result); } catch { /* swallow */ }
+        }
+        resolve();
+      };
+
+      this.pending.set(id, {
+        resolve: (result) => finalize(null, result),
+        reject: (err) => finalize(err, null),
+      });
+      this._writeFrame({
+        jsonrpc: '2.0',
+        id,
+        method: 'session/prompt',
+        params: { sessionId: this.sessionId, prompt: [{ type: 'text', text: prompt }] },
+      });
+    });
+  }
+
+  cancel() {
+    if (!this.inflight || this.killed) return;
+    // session/cancel is a JSON-RPC notification (no id). Per the P-7a1c2e4f
+    // spike, the in-flight session/prompt response arrives with
+    // stopReason:"end_turn" (NOT "cancelled" on copilot CLI 1.0.70) — we
+    // don't branch on that field, only on the promise settling.
+    this._notify('session/cancel', { sessionId: this.inflight.sessionId });
+  }
+
+  async newSession({ mcpServers, systemPromptHash, model, effort, cwd }) {
+    // Cancel any inflight before swapping the underlying session.
+    if (this.inflight) {
+      this.cancel();
+      // Wait briefly for the cancelled response to settle so we don't leak
+      // a stale inflight reference into the new session.
+      const inflight = this.inflight;
+      await new Promise((resolve) => {
+        const start = this._internals.now();
+        const wait = () => {
+          if (!inflight || inflight.settled || this._internals.now() - start > 1000) resolve();
+          else setTimeout(wait, 5);
+        };
+        wait();
+      });
+    }
+    // Bug B (issue #2479): if the caller is rotating the session because the
+    // system prompt changed, they may also be passing a fresh model/effort —
+    // update bookkeeping BEFORE session/new so the new fields land on the
+    // daemon. Falls through to whatever we already had when callers omit them.
+    if (model !== undefined) this.model = model;
+    if (effort !== undefined) this.effort = effort;
+    // agent-worker-pool.js reuses a warm worker across dispatches with
+    // different cwds (unlike cc-worker-pool.js, whose tabs never change
+    // cwd) — allow the caller to rotate it in on a session swap.
+    if (cwd !== undefined && cwd !== null && cwd !== '') this.cwd = cwd;
+    const result = await this._call('session/new', buildSessionNewParams({
+      cwd: this.cwd, mcpServers: mcpServers || [], model: this.model, effort: this.effort,
+    }));
+    this.sessionId = result && result.sessionId;
+    this.systemPromptHash = systemPromptHash;
+    this.firstSystemPromptSent = false;
+  }
+
+  close() {
+    if (this.killed) return;
+    this.killed = true;
+    // Best-effort cancel of an inflight prompt so the daemon doesn't keep
+    // generating into a torn-down session before we kill the proc.
+    if (this.inflight) {
+      try { this._notify('session/cancel', { sessionId: this.inflight.sessionId }); }
+      catch { /* swallow */ }
+    }
+    if (this.proc) {
+      try { this._internals.killImmediate(this.proc); } catch { /* already dead */ }
+    }
+    this._failAllPending(new Error('acp-transport: worker closed'));
+    if (this.inflight && !this.inflight.settled) {
+      const cb = this.inflight.onError;
+      this.inflight.settled = true;
+      this.inflight = null;
+      if (cb) try { cb(new Error('acp-transport: worker closed')); } catch { /* swallow */ }
+    }
+  }
+}
+
+module.exports = {
+  ERROR_CODES,
+  typedError,
+  spawnAcp,
+  killImmediate,
+  hashMcpServers,
+  buildSessionNewParams,
+  extractChunkText,
+  mapAcpToolCallToToolUse,
+  Worker,
+  WARM_MAX_CONCURRENT,
+};