ruvnet-brain 3.9.85-dev → 3.9.129-dev

package/plugin/mcp/managed-cli-interface.mjs

@@ -0,0 +1,236 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const MANAGED_EXECUTABLES = Object.freeze([
+  'ruflo',
+  'claude-flow',
+  'agentic-flow',
+  'agentic-qe',
+  'ruvector',
+  'agent-browser',
+  'ruv-swarm',
+]);
+
+const MANAGED = new Set(MANAGED_EXECUTABLES);
+const SUBCOMMAND = /^[a-z][a-z0-9-]*$/;
+const MAX_ARGS = 256;
+const MAX_ARG_BYTES = 8192;
+const DEFAULT_FRESH_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+
+const executableSchema = {
+  type: 'string',
+  enum: [...MANAGED_EXECUTABLES],
+  description: 'One of the finite RuvNet ecosystem executables managed by this boundary.',
+};
+
+export const MANAGED_CLI_TOOLS = Object.freeze([
+  {
+    name: 'ruvnet_cli_help',
+    description: 'Read a managed CLI interface from the executable itself. Runs only the supplied subcommand path plus --help and records a fresh stamp only after exit 0.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        executable: executableSchema,
+        argv: {
+          type: 'array',
+          description: 'Zero, one, or two literal lowercase subcommand tokens. --help is appended by the server.',
+          items: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+          maxItems: 2,
+          default: [],
+        },
+      },
+      required: ['executable', 'argv'],
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: 'ruvnet_cli_run',
+    description: 'Run a managed CLI with a literal argv array and no shell. Refuses unless the matching interface help was read successfully in the last 24 hours.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        executable: executableSchema,
+        argv: {
+          type: 'array',
+          description: 'Literal argv tokens. Shell metacharacters are ordinary argument bytes and are never evaluated.',
+          items: { type: 'string', maxLength: MAX_ARG_BYTES },
+          maxItems: MAX_ARGS,
+        },
+      },
+      required: ['executable', 'argv'],
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  },
+]);
+
+function assertExecutable(executable) {
+  if (typeof executable !== 'string' || !MANAGED.has(executable)) {
+    throw new Error(`unknown managed executable: ${String(executable || '')}`);
+  }
+  return executable;
+}
+
+function literalArgv(argv) {
+  if (!Array.isArray(argv) || argv.length > MAX_ARGS) throw new Error('argv must be an array of at most 256 strings');
+  return argv.map((arg) => {
+    if (typeof arg !== 'string' || arg.includes('\0') || Buffer.byteLength(arg) > MAX_ARG_BYTES) {
+      throw new Error('every argv entry must be a literal string of at most 8192 bytes without NUL');
+    }
+    return arg;
+  });
+}
+
+export function helpKey(executable, argv) {
+  const tool = assertExecutable(executable);
+  const args = literalArgv(argv);
+  const subcommands = [];
+  for (const arg of args) {
+    if (!SUBCOMMAND.test(arg)) break;
+    subcommands.push(arg);
+    if (subcommands.length === 2) break;
+  }
+  return [tool, ...subcommands].join('.');
+}
+
+export function stampKeysForHelp(executable, argv) {
+  const tool = assertExecutable(executable);
+  const args = literalArgv(argv);
+  if (args.length > 2 || args.some((arg) => !SUBCOMMAND.test(arg))) {
+    throw new Error('invalid subcommand path: help accepts zero, one, or two lowercase tokens');
+  }
+  const exact = [tool, ...args].join('.');
+  if (args.length < 2) return [exact];
+  return [exact, [tool, args[0]].join('.')];
+}
+
+function stateDir(env) {
+  const brainHome = env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
+  return env.RUVNET_BRAIN_HELP_READ_DIR || path.join(brainHome, 'help-read');
+}
+
+function freshStamp(executable, argv, env, now = Date.now()) {
+  const stamp = path.join(stateDir(env), helpKey(executable, argv));
+  let stat;
+  try {
+    stat = fs.statSync(stamp);
+  } catch {
+    return false;
+  }
+  const configured = Number(env.RUVNET_BRAIN_HELP_MAX_AGE_MS);
+  const maxAge = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_FRESH_MS;
+  return now - stat.mtimeMs < maxAge;
+}
+
+function writeStamps(executable, argv, env) {
+  const dir = stateDir(env);
+  fs.mkdirSync(dir, { recursive: true });
+  for (const key of stampKeysForHelp(executable, argv)) {
+    const stamp = path.join(dir, key);
+    const temporary = path.join(dir, `.${key}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+    try {
+      fs.writeFileSync(temporary, '', { flag: 'wx', mode: 0o600 });
+      fs.renameSync(temporary, stamp);
+    } finally {
+      try { fs.unlinkSync(temporary); } catch { /* renamed or never created */ }
+    }
+  }
+}
+
+function execute(executable, argv, env) {
+  return new Promise((resolve) => {
+    const child = spawn(executable, argv, {
+      env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let settled = false;
+    const append = (chunks, chunk, used) => {
+      const remaining = MAX_OUTPUT_BYTES - used;
+      if (remaining > 0) chunks.push(chunk.subarray(0, remaining));
+      return used + Math.min(chunk.length, Math.max(remaining, 0));
+    };
+    child.stdout.on('data', (chunk) => { stdoutBytes = append(stdout, chunk, stdoutBytes); });
+    child.stderr.on('data', (chunk) => { stderrBytes = append(stderr, chunk, stderrBytes); });
+    const configured = Number(env.RUVNET_BRAIN_MANAGED_CLI_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGTERM');
+      resolve({ code: null, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), error: `timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.once('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: null, stdout: '', stderr: '', error: error.message });
+    });
+    child.once('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), error: null });
+    });
+  });
+}
+
+function resultOf(executable, argv, result) {
+  const output = [result.stdout, result.stderr].filter(Boolean).join(result.stdout && result.stderr ? '\n' : '');
+  if (result.error || result.code !== 0) {
+    const reason = result.error || `exit ${result.code}`;
+    return {
+      content: [{ type: 'text', text: output || `${executable} ${argv.join(' ')} failed: ${reason}` }],
+      isError: true,
+    };
+  }
+  return {
+    content: [{ type: 'text', text: output || `${executable} ${argv.join(' ')} completed successfully` }],
+    isError: false,
+  };
+}
+
+export async function callManagedCli(toolName, args, env = process.env) {
+  try {
+    const executable = assertExecutable(args?.executable);
+    const argv = literalArgv(args?.argv);
+
+    if (toolName === 'ruvnet_cli_help') {
+      stampKeysForHelp(executable, argv);
+      const commandArgv = [...argv, '--help'];
+      const execution = await execute(executable, commandArgv, env);
+      if (execution.code === 0 && !execution.error) writeStamps(executable, argv, env);
+      return resultOf(executable, commandArgv, execution);
+    }
+
+    if (toolName === 'ruvnet_cli_run') {
+      if (!freshStamp(executable, argv, env)) {
+        const key = helpKey(executable, argv).replaceAll('.', ' ');
+        return {
+          content: [{ type: 'text', text: `Read the interface first with ruvnet_cli_help for: ${key}` }],
+          isError: true,
+        };
+      }
+      return resultOf(executable, argv, await execute(executable, argv, env));
+    }
+
+    return {
+      content: [{ type: 'text', text: `unknown managed CLI tool: ${String(toolName || '')}` }],
+      isError: true,
+    };
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+      isError: true,
+    };
+  }
+}

package/plugin/mcp/server.mjs

@@ -33,6 +33,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline';
+import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
 const KB = process.env.RUVNET_BRAIN_KB || path.join(BRAIN_HOME, 'kb');
@@ -43,9 +44,9 @@ const LEASE = path.join(LEASES, `mcp-${process.pid}.json`);
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'ruvnet-brain', version: '2.0.0' };
-// Static fallback tool declaration — same name + inputSchema the brain declares (the SCHEMA is the
-// frozen contract; the description is data and is refreshed from the live child when one is up).
-const FALLBACK_TOOLS = [{
+// Local frozen tool declarations. search_ruvnet is only a fallback: a live child's declaration wins
+// so its description can refresh. The two managed-CLI schemas are owned by this protocol shell.
+const SEARCH_TOOL = {
   name: 'search_ruvnet',
   description: 'Source-grounded knowledge base for the RuvNet ecosystem. (Brain bundle not installed on this machine — calls will return install guidance.)',
   inputSchema: {
@@ -56,7 +57,19 @@ const FALLBACK_TOOLS = [{
     },
     required: ['query'],
   },
-}];
+};
+const FALLBACK_TOOLS = [SEARCH_TOOL, ...MANAGED_CLI_TOOLS];
+
+function withLocalTools(tools) {
+  const merged = new Map();
+  for (const tool of Array.isArray(tools) ? tools : []) {
+    if (tool?.name) merged.set(tool.name, tool);
+  }
+  for (const tool of FALLBACK_TOOLS) {
+    if (!merged.has(tool.name)) merged.set(tool.name, tool);
+  }
+  return [...merged.values()];
+}
 
 const out = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
 const clientOk = (id, result) => out({ jsonrpc: '2.0', id, result });
@@ -80,45 +93,117 @@ process.on('exit', () => { try { fs.rmSync(LEASE, { force: true }); } catch { /*
 // ── the warm child + private protocol ───────────────────────────────────────────────────────────
 let child = null;            // { proc, generation, nextId, pending: Map<childId, {resolve, reject}> }
 let pendingCount = 0;        // client tools/call requests currently in flight (drain gate for swaps)
+let childRetirement = Promise.resolve();
+let childStartup = null;
+const CHILD_TERM_GRACE_MS = 3_000;
+const CHILD_INIT_TIMEOUT_MS = Number(process.env.RUVNET_BRAIN_INIT_TIMEOUT_MS) || 60_000;
 
 function killChild(reason) {
-  if (!child) return;
+  if (!child) return childRetirement;
   const c = child; child = null;
   for (const [, p] of c.pending) p.reject(new Error(`brain worker ${reason}`));
   c.pending.clear();
+  childRetirement = new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(force);
+      resolve();
+    };
+    c.proc.once('exit', finish);
+    const force = setTimeout(() => {
+      try { c.proc.kill('SIGKILL'); } catch { /* already gone */ }
+    }, CHILD_TERM_GRACE_MS);
+    force.unref?.();
+  });
   try { c.proc.kill('SIGTERM'); } catch { /* already dead */ }
+  return childRetirement;
 }
 
 async function ensureChild() {
   const gen = currentGeneration();
-  if (child && child.generation !== gen && pendingCount === 0) killChild('superseded by a newer generation');
+  if (child && child.generation !== gen && pendingCount === 0) await killChild('superseded by a newer generation');
   if (child) return child;
+  await childRetirement;
   if (!fs.existsSync(CHILD_MCP)) return null;
 
-  const env = { ...process.env, KB_DIR: KB };
-  if (!env.KB_MODEL_CACHE) env.KB_MODEL_CACHE = path.join(BRAIN_HOME, 'models');
-  const proc = spawn(process.execPath, [CHILD_MCP], { stdio: ['pipe', 'pipe', 'inherit'], env });
-  const c = { proc, generation: gen, nextId: 1, pending: new Map() };
-  const rl = readline.createInterface({ input: proc.stdout });
-  rl.on('line', (line) => {
-    let msg; try { msg = JSON.parse(line); } catch { return; }
-    const waiter = c.pending.get(msg.id);
-    if (waiter) { c.pending.delete(msg.id); waiter.resolve(msg); }
-  });
-  proc.on('exit', () => { if (child === c) child = null; for (const [, p] of c.pending) p.reject(new Error('brain worker exited')); c.pending.clear(); });
-  proc.on('error', () => { if (child === c) child = null; });
-  child = c;
-
-  // PRIVATE handshake — parent-owned id, never the client's (finding 8).
-  try { await childRequest(c, 'initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'ruvnet-brain-shell', version: SERVER_INFO.version } }, 10_000); }
-  catch { killChild('failed initialize'); return null; }
-  return c;
+  if (!childStartup) {
+    childStartup = (async () => {
+      const env = { ...process.env, KB_DIR: KB };
+      if (!env.KB_MODEL_CACHE) env.KB_MODEL_CACHE = path.join(BRAIN_HOME, 'models');
+      const proc = spawn(process.execPath, [CHILD_MCP], { stdio: ['pipe', 'pipe', 'inherit'], env });
+      const c = { proc, generation: currentGeneration(), nextId: 1, pending: new Map() };
+      const rl = readline.createInterface({ input: proc.stdout });
+      rl.on('line', (line) => {
+        let msg; try { msg = JSON.parse(line); } catch { return; }
+        const waiter = c.pending.get(msg.id);
+        if (waiter) { c.pending.delete(msg.id); waiter.resolve(msg); }
+      });
+      proc.on('exit', () => {
+        if (child === c) child = null;
+        for (const [, p] of c.pending) p.reject(new Error('brain worker exited'));
+        c.pending.clear();
+      });
+      proc.on('error', () => { if (child === c) child = null; });
+      child = c;
+
+      try {
+        await childRequest(c, 'initialize', {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: { name: 'ruvnet-brain-shell', version: SERVER_INFO.version },
+        }, CHILD_INIT_TIMEOUT_MS);
+      } catch (e) {
+        await killChild('failed initialize');
+        throw new Error(`brain worker failed to initialize: ${e.message}`);
+      }
+      return c;
+    })();
+  }
+  const attempt = childStartup;
+  try { return await attempt; }
+  finally { if (childStartup === attempt) childStartup = null; }
 }
 
-function childRequest(c, method, params, timeoutMs = 120_000) {
+// A TIMEOUT IS AN OUTAGE, and it must both STOP and be RECORDED. Measured 2026-07-27: the timeout
+// below deleted its pending entry and rejected, and did nothing else — so
+//   (a) the child kept computing an answer nobody would ever read, at ~95% CPU, and on the
+//       all-repos path (605 cross-encoder pairs, a fan-out that alone exceeds this deadline) that
+//       is minutes of burn per abandoned query, which then slows the RETRY, which times out too; and
+//   (b) nothing wrote health.json, so a total retrieval failure read as healthy. The live file
+//       said "status":"ok" dated four days earlier while every query was timing out.
+// (b) is the worse half: the product reporting green while it is down is the one thing it may
+// never do. The child's own alarm cannot cover this — it only rings when a search RETURNS failure,
+// and a timeout is precisely the case where it never returns at all. Only the parent can see it.
+async function onChildTimeout(method, timeoutMs) {
+  killChild(`timed out after ${timeoutMs / 1000}s on ${method}`); // stop the burn; ensureChild() respawns
+  try {
+    const alarm = await import(new URL('../../kb/brain-alarm.mjs', import.meta.url).href);
+    await alarm.reportBrainDown({
+      error: `brain worker timed out after ${timeoutMs / 1000}s on ${method} (no answer returned)`,
+      source: 'mcp-parent-timeout',
+    });
+  } catch (e) {
+    // REPORTED, never swallowed: brain-alarm.mjs lives in the KB, which can legitimately be absent
+    // or half-installed — but a health reporter that fails silently is the same lie one layer down.
+    console.error(`[ruvnet-brain] timeout on ${method} could not be recorded to health.json: ${e.message}`);
+  }
+}
+
+// Overridable so the outage path above can actually be TESTED — a 120s default is untestable, and
+// an untestable failure path is how this one went four days reporting "ok" while it was down. Also
+// genuinely useful in the field: a slow machine can raise it, and a CI runner can lower it.
+const CALL_TIMEOUT_MS = Number(process.env.RUVNET_BRAIN_CALL_TIMEOUT_MS) || 120_000;
+
+function childRequest(c, method, params, timeoutMs = CALL_TIMEOUT_MS) {
   return new Promise((resolve, reject) => {
     const id = c.nextId++;
-    const timer = setTimeout(() => { c.pending.delete(id); reject(new Error(`brain worker timeout on ${method}`)); }, timeoutMs);
+    const timer = setTimeout(() => {
+      c.pending.delete(id);
+      reject(new Error(`brain worker timeout on ${method}`));
+      void onChildTimeout(method, timeoutMs); // after the reject — the caller must not wait on the alarm
+    }, timeoutMs);
     c.pending.set(id, { resolve: (m) => { clearTimeout(timer); resolve(m); }, reject: (e) => { clearTimeout(timer); reject(e); } });
     try { c.proc.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); }
     catch (e) { clearTimeout(timer); c.pending.delete(id); reject(e); }
@@ -135,17 +220,33 @@ async function handleClient(msg) {
     case 'ping':
       return clientOk(id, {});
     case 'tools/list': {
-      const c = await ensureChild();
-      if (c) {
-        try { const r = await childRequest(c, 'tools/list', {}, 15_000); if (r.result?.tools?.length) return clientOk(id, r.result); }
-        catch { /* fall through to the static declaration */ }
-      }
+      try {
+        const c = await ensureChild();
+        if (c) {
+          try {
+            const r = await childRequest(c, 'tools/list', {}, 15_000);
+            if (r.result?.tools?.length) return clientOk(id, { ...r.result, tools: withLocalTools(r.result.tools) });
+          }
+          catch { /* fall through to the static declaration */ }
+        }
+      } catch { /* fall through to the static declaration during a transient startup outage */ }
       return clientOk(id, { tools: FALLBACK_TOOLS });
     }
     case 'tools/call': {
+      if (params?.name === 'ruvnet_cli_help' || params?.name === 'ruvnet_cli_run') {
+        return clientOk(id, await callManagedCli(params.name, params.arguments || {}));
+      }
       if (params?.name !== 'search_ruvnet') return clientErr(id, -32602, `unknown tool: ${params?.name}`);
       refreshLease();
-      const c = await ensureChild();
+      let c;
+      try {
+        c = await ensureChild();
+      } catch (e) {
+        return clientOk(id, {
+          content: [{ type: 'text', text: `search_ruvnet error: brain worker temporarily unavailable (${e.message})` }],
+          isError: true,
+        });
+      }
       if (!c) {
         return clientOk(id, { content: [{ type: 'text', text: `search_ruvnet error: the brain bundle is not installed at ${KB}. Install it with: npx github:stuinfla/ruvnet-brain  (or set RUVNET_BRAIN_KB to your brain's kb dir).` }], isError: true });
       }

package/plugin/scripts/codex-hook-wrapper.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const brainHome = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
+const versions = path.join(brainHome, 'versions');
+
+function activeRoot() {
+  try {
+    const active = JSON.parse(fs.readFileSync(path.join(brainHome, 'active.json'), 'utf8'));
+    if (!active || typeof active.codeRoot !== 'string') return null;
+    const candidate = path.isAbsolute(active.codeRoot)
+      ? active.codeRoot
+      : path.join(brainHome, active.codeRoot);
+    const real = fs.realpathSync(candidate);
+    const versionsReal = fs.realpathSync(versions);
+    return real.startsWith(`${versionsReal}${path.sep}`) ? real : null;
+  } catch {
+    return null;
+  }
+}
+
+const input = fs.readFileSync(0);
+const root = activeRoot();
+const adapter = root && path.join(root, 'scripts', 'codex-hook-adapter.mjs');
+if (!adapter || !fs.existsSync(adapter)) process.exit(0);
+
+const result = spawnSync(process.execPath, [adapter, ...process.argv.slice(2)], {
+  input,
+  encoding: 'utf8',
+  env: process.env,
+});
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+process.exit(result.status ?? 0);