@yemi33/minions 0.1.1910 → 0.1.1911

package/engine/cc-worker-pool.js

@@ -0,0 +1,512 @@
+/**
+ * engine/cc-worker-pool.js — Persistent per-tab Copilot worker pool (W-mp3ioyh300056f36).
+ *
+ * Sub-task B of W-mp2w003600196c51 ("CC perf: persistent per-tab Copilot
+ * worker"). Wraps `copilot --acp` (Agent Client Protocol — long-lived JSON-RPC
+ * server over stdin/stdout) so that a Command Center / doc-chat tab keeps a
+ * single warm Copilot process across N turns instead of paying the
+ * spawn + initialize + session/new (~14 s) cost on every turn.
+ *
+ * Public API:
+ *
+ *   pool.getSession({ tabId, model, effort, mcpServers, systemPromptHash, cwd })
+ *     → SessionHandle: {
+ *         sessionId,
+ *         stream(promptText, { onChunk, onDone, onError, signal, systemPromptText }) → Promise,
+ *         cancel(),                  // session/cancel notification
+ *         close(),                   // tear down this tab
+ *       }
+ *   pool.closeTab(tabId)             // cancel inflight, kill proc, drop entry
+ *   pool.shutdown()                  // close every tab and stop the idle reaper
+ *
+ * Internal model (one process per tab):
+ *
+ *   tabs: Map<tabId, Worker> where Worker = {
+ *     proc, sessionId, model, effort, mcpServers, mcpServersHash,
+ *     systemPromptHash, cwd, lastUsedAt,
+ *     pending: Map<id, { resolve, reject }>, inflight, readBuf, nextReqId
+ *   }
+ *
+ *   TODO (sub-task C/D follow-up): multiplex N tabs onto one ACP process
+ *   (`session/new` per tab, single `proc`). ACP supports it; left as a
+ *   follow-up perf win once one-process-per-tab is proven in the dashboard.
+ *
+ * Eviction rules:
+ *   - mcpServers changes      → kill proc entirely + respawn
+ *   - systemPromptHash change → keep proc, send a fresh `session/new`
+ *   - model / effort change   → no eviction (state updated in place)
+ *   - closeTab                → `session/cancel` if inflight, then kill proc
+ *   - Idle > 10 min           → kill proc (reaper sweep every 60 s)
+ *
+ * Auth precheck: when `copilot --acp` exits before the initialize handshake
+ * completes, surface
+ *   "copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login
+ *    is complete (...)"
+ * so the dashboard can surface a precise reason instead of a generic timeout.
+ *
+ * No new npm deps — Node built-ins only (child_process, events, timers, crypto).
+ *
+ * See `notes/archive/2026-05-13-ripley-W-mp3h2wq2000e64f7-2026-05-13-0301.md`
+ * for the ACP protocol probe (line framing, request/response correlation,
+ * cold-vs-warm timings, cancel semantics, configOptions surface).
+ */
+
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+
+// 10 minutes — matches the work-item spec.
+const IDLE_REAPER_MS = 10 * 60 * 1000;
+// Reaper sweep cadence. Not exposed as ENGINE_DEFAULTS to keep the pool
+// dependency-free; sub-task C/D can plumb a config knob if needed.
+const REAPER_INTERVAL_MS = 60 * 1000;
+
+// Test seam — every external side effect goes through `_internals` so
+// test/unit/cc-worker-pool.test.js can stub spawn/now/killImmediate.
+const _internals = {
+  spawnAcp({ cwd } = {}) {
+    return spawn(
+      'copilot',
+      ['--acp', '--allow-all', '--max-autopilot-continues', '1'],
+      {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: cwd || process.cwd(),
+        windowsHide: true,
+        // Don't pass shell:true — Copilot is a binary on PATH and a shell
+        // wrapper would swallow stdin/stdout framing.
+      }
+    );
+  },
+  killImmediate(proc) {
+    // Lazy require so unit tests that don't load engine/shared still work.
+    try {
+      const shared = require('./shared');
+      shared.killImmediate(proc);
+    } catch {
+      try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+    }
+  },
+  now() { return Date.now(); },
+};
+
+const _tabs = new Map();
+let _reaperTimer = null;
+
+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');
+}
+
+class Worker {
+  constructor({ tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd }) {
+    this.tabId = tabId;
+    this.model = model;
+    this.effort = effort;
+    this.mcpServers = mcpServers || [];
+    this.mcpServersHash = mcpServersHash;
+    this.systemPromptHash = systemPromptHash;
+    this.cwd = cwd || process.cwd();
+
+    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 = _internals.now();
+    this.killed = false;
+    this.spawnError = null;
+    this.firstSystemPromptSent = false;
+  }
+
+  // ── Spawn + initialize handshake ────────────────────────────────────────
+  async _spawnAndInit() {
+    let proc;
+    try {
+      proc = _internals.spawnAcp({ cwd: this.cwd });
+    } catch (err) {
+      throw new Error(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      );
+    }
+    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;
+        const err = new Error(
+          `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (exit ${code})`
+        );
+        this.spawnError = err;
+        this._failAllPending(err);
+        reject(err);
+      };
+    });
+    const earlyExitHandler = (code) => earlyExitReject(code);
+    proc.once('exit', earlyExitHandler);
+
+    const errorHandler = (err) => {
+      const wrapped = new Error(
+        `copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete (${err.message})`
+      );
+      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', { cwd: this.cwd, mcpServers: this.mcpServers }),
+        earlyExitPromise,
+      ]);
+      this.sessionId = result && result.sessionId;
+      if (!this.sessionId) {
+        throw new Error('copilot --acp failed -- session/new returned no sessionId');
+      }
+    } 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;
+      const err = new Error('copilot --acp process exited');
+      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 && this.inflight) {
+      if (obj.params.sessionId !== this.inflight.sessionId) return;
+      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 */ }
+        }
+      }
+      // Other update kinds (available_commands_update, tool_call, ...) are
+      // ignored in sub-task B. Sub-task C/D will surface tool_call to the
+      // dashboard's onToolUse callback.
+    }
+  }
+
+  _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, onDone, onError, signal, systemPromptText } = opts;
+    if (this.killed) {
+      const err = new Error('cc-worker-pool: tab is closed');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    if (this.inflight) {
+      const err = new Error('cc-worker-pool: a prompt is already in flight on this tab');
+      if (onError) try { onError(err); } catch { /* swallow */ }
+      return Promise.resolve();
+    }
+    this.lastUsedAt = _internals.now();
+
+    // Inject the <system> block on the first prompt of a session — Copilot
+    // ACP has no in-protocol "set system prompt" method (per Ripley's note),
+    // 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,
+      onDone,
+      onError,
+      signal,
+      signalHandler: null,
+      settled: false,
+    };
+    this.inflight = inflight;
+
+    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 = _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). The in-flight
+    // session/prompt response will arrive with stopReason=cancelled per the
+    // ACP spec — we don't synthesize a fake response client-side.
+    this._notify('session/cancel', { sessionId: this.inflight.sessionId });
+  }
+
+  async newSession({ mcpServers, systemPromptHash }) {
+    // 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 = _internals.now();
+        const wait = () => {
+          if (!inflight || inflight.settled || _internals.now() - start > 1000) resolve();
+          else setTimeout(wait, 5);
+        };
+        wait();
+      });
+    }
+    const result = await this._call('session/new', {
+      cwd: this.cwd,
+      mcpServers: mcpServers || [],
+    });
+    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 { _internals.killImmediate(this.proc); } catch { /* already dead */ }
+    }
+    this._failAllPending(new Error('cc-worker-pool: 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('cc-worker-pool: worker closed')); } catch { /* swallow */ }
+    }
+  }
+}
+
+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 '';
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+async function getSession({ tabId, model, effort, mcpServers, systemPromptHash, cwd } = {}) {
+  if (!tabId) throw new Error('cc-worker-pool.getSession: tabId is required');
+  const mcpServersHash = _hashMcpServers(mcpServers);
+  let worker = _tabs.get(tabId);
+
+  if (worker) {
+    if (worker.killed) {
+      _tabs.delete(tabId);
+      worker = null;
+    } else if (worker.mcpServersHash !== mcpServersHash) {
+      // mcpServers shape changed → must respawn the proc; the daemon
+      // resolves MCP server config at process boot, not per session.
+      _tabs.delete(tabId);
+      worker.close();
+      worker = null;
+    } else if (worker.systemPromptHash !== systemPromptHash) {
+      // System prompt changed → keep the warm process, drop the session
+      // and create a fresh one. Saves the ~2.1 s initialize handshake.
+      await worker.newSession({ mcpServers, systemPromptHash });
+      worker.model = model;
+      worker.effort = effort;
+      worker.lastUsedAt = _internals.now();
+    } else {
+      // Warm reuse — only update bookkeeping. model/effort changes on a
+      // warm session are tracked here but not pushed via configOptions in
+      // sub-task B; sub-task C/D will wire that to ACP `session/configure`
+      // (or equivalent) once the dashboard exposes the toggle live.
+      worker.model = model;
+      worker.effort = effort;
+      worker.lastUsedAt = _internals.now();
+    }
+  }
+
+  if (!worker) {
+    worker = new Worker({
+      tabId, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd,
+    });
+    _tabs.set(tabId, worker);
+    try {
+      await worker._spawnAndInit();
+    } catch (err) {
+      _tabs.delete(tabId);
+      try { worker.close(); } catch { /* already torn down */ }
+      throw err;
+    }
+  }
+
+  _ensureReaper();
+
+  return {
+    sessionId: worker.sessionId,
+    stream: (promptText, opts) => worker.stream(promptText, opts),
+    cancel: () => worker.cancel(),
+    close: () => closeTab(tabId),
+  };
+}
+
+function closeTab(tabId) {
+  const worker = _tabs.get(tabId);
+  if (!worker) return;
+  _tabs.delete(tabId);
+  worker.close();
+}
+
+function shutdown() {
+  for (const worker of _tabs.values()) {
+    try { worker.close(); } catch { /* swallow */ }
+  }
+  _tabs.clear();
+  if (_reaperTimer) {
+    clearInterval(_reaperTimer);
+    _reaperTimer = null;
+  }
+}
+
+function _ensureReaper() {
+  if (_reaperTimer) return;
+  _reaperTimer = setInterval(_reapIdleTabs, REAPER_INTERVAL_MS);
+  if (typeof _reaperTimer.unref === 'function') _reaperTimer.unref();
+}
+
+function _reapIdleTabs() {
+  const now = _internals.now();
+  for (const [tabId, worker] of [..._tabs]) {
+    if (worker.inflight) continue;
+    if (now - worker.lastUsedAt > IDLE_REAPER_MS) {
+      _tabs.delete(tabId);
+      try { worker.close(); } catch { /* already torn down */ }
+    }
+  }
+}
+
+module.exports = {
+  getSession,
+  closeTab,
+  shutdown,
+  // Exposed for unit tests; engine code MUST go through the public API.
+  _internals,
+  _tabs,
+  _reapIdleTabs,
+  IDLE_REAPER_MS,
+  REAPER_INTERVAL_MS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1910",
+  "version": "0.1.1911",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"