beatrina 0.8.6

package/host/planes/mcp.mjs

@@ -0,0 +1,493 @@
+// mcp.mjs — the agent plane, and the subscription chat that rides it the other
+// way. A port of the MCP half of spike/serve.R.
+//
+// ── the plane ──────────────────────────────────────────────────────────────
+//
+// A local agent (Claude Code / Codex through tools/mcp/carmar-mcp.mjs) connects
+// through the SAME loopback/Origin/Host gates a page does, then DECLARES itself
+// with `mcp-hello`. From then on it may only ASK — `mcp-request`, routed to the
+// active notebook window — and use the read-side forwarded ops; pages may only
+// ANSWER. A declared agent is refused exec/interrupt/restart elsewhere on
+// purpose: an agent's runs go through a chunk in the notebook, where the user
+// can see them, or they do not happen.
+//
+// Three rules that look like plumbing and are not.
+//
+//   · A request carries BOTH ENDS AND A CLOCK. The asker is who the answer goes
+//     to; the PAGE is the only thing that can produce one, so its disappearance
+//     is the precise end of that request — reported immediately, as a fact —
+//     while the clock is only the backstop for a page that is alive and silent.
+//     `MCP_PENDING_MAX_S` matches the ceiling carmar-mcp.mjs lets a caller ask
+//     for (chunk_run's timeout_s caps at 3600), so the supervisor never gives up
+//     on a call the agent is still legitimately waiting for.
+//   · The roster is REPLAYED to a page that connects late. Same lesson as the
+//     ready frame: a page opened after an agent connected must still learn the
+//     agent is there, or its chip lies by omission.
+//   · `mcp-request` and `mcp-response` are forwarded as BYTES, never re-encoded.
+//     relay_frame's lesson, one door along: a JSON round trip through a
+//     convenience encoder is where `args: {}` becomes `args: []`.
+//
+// ── the subscription chat ──────────────────────────────────────────────────
+//
+// One conversation turn = one `claude -p` (or `codex exec`) process, spawned
+// HERE, never in the worker: a model turn must not block or be blocked by a
+// running cell. The CLI owns its own login — the host passes a prompt on STDIN
+// (argv is visible to every local user in `ps`), streams the CLI's stream-json
+// lines back to the ASKING page verbatim, and that is the whole exchange.
+// CarmaR reads, stores and proxies no credential. Pages only: a declared agent
+// asking the kernel to spawn another agent is a loop nobody ordered.
+//
+// Two deliberate differences from serve.R, both mechanism rather than policy.
+// (1) There is no `pump_chats()` poll: a spawned child's stdout is an event
+// here, so lines are forwarded as they arrive and the `done` frame is sent on
+// `close`, which fires after the streams have drained — the same ordering the
+// pump achieved by reading what was left before reporting the exit. (2) `node`
+// is looked for on PATH as there, but falls back to THIS process's own
+// executable, which an app-bundle supervisor knows and `Sys.which` cannot.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+
+const OPS = ["mcp-hello", "mcp-active", "mcp-request", "mcp-response", "agent-chat", "agent-chat-stop"];
+/** The ceiling carmar-mcp.mjs allows a caller to ask for. */
+const MCP_PENDING_MAX_S = 3600;
+const MAX_CHATS = 3;
+/** The spawned session gets the DOCUMENT tools: it is an author, not a chatbot. */
+const AGENT_CHAT_TOOLS = [
+  "mcp__carmar__carmar_status", "mcp__carmar__notebook_read",
+  "mcp__carmar__chunk_read", "mcp__carmar__chunk_insert",
+  "mcp__carmar__chunk_update", "mcp__carmar__chunk_run",
+  "mcp__carmar__file_list", "mcp__carmar__file_read",
+].join(",");
+
+/* ── the AI policy, only as far as this plane needs it ────────────────────── */
+//
+// spike/ai-policy.R is a whole file and a whole work package of its own (the
+// `ai-policy`, `ai-key` and `ai-audit` ops are not this one's). What IS this
+// plane's is the door the supervisor genuinely owns: a CLI turn is a process
+// THIS process spawns, so "not permitted" means never spawned, with no
+// page-side spawn to work around. That question needs only the provider list,
+// which is what is ported here — the three-state rule included.
+
+const ON_MACHINE_PROVIDERS = ["chrome", "webgpu", "ollama", "lmstudio", "jan"];
+const KEY_PROVIDERS = ["openai", "anthropic", "google", "groq", "together", "openrouter", "azure", "custom"];
+const CLI_PROVIDERS = ["claudecode", "codex"];
+const ALL_PROVIDERS = [...ON_MACHINE_PROVIDERS, ...KEY_PROVIDERS, ...CLI_PROVIDERS];
+
+/** @returns {{set:boolean, providers:string[], note:string}} */
+export function aiProviderPolicy(env) {
+  const file = env("CARMAR_AI_POLICY", "").trim();
+  let named = [];
+  let localOnly = env("CARMAR_AI_LOCAL_ONLY", "") === "1";
+  let note = "";
+  let source = "";
+  const errors = [];
+  if (file) {
+    source = file;
+    if (!fs.existsSync(file)) errors.push("missing");
+    else {
+      try {
+        const doc = JSON.parse(fs.readFileSync(file, "utf8"));
+        named = [].concat(doc.providers ?? []).map(String);
+        if (doc.local_only === true) localOnly = true;
+        note = String(doc.note ?? "").trim();
+      } catch { errors.push("unreadable"); }
+    }
+  } else if (env("CARMAR_AI_PROVIDERS", "")) {
+    source = "env";
+    named = String(env("CARMAR_AI_PROVIDERS", "")).split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+  } else if (localOnly) {
+    source = "env";
+  }
+  const asked = named.length > 0;
+  named = named.filter((p) => ALL_PROVIDERS.includes(p));
+  let providers = named.length ? named : asked ? [] : ALL_PROVIDERS.slice();
+  if (localOnly) providers = providers.filter((p) => ON_MACHINE_PROVIDERS.includes(p));
+  let set = Boolean(source) && !errors.length;
+  if (set && !providers.length) errors.push("empty");
+  if (errors.length) { set = false; providers = ALL_PROVIDERS.slice(); }
+  // eslint-disable-next-line no-control-regex
+  note = note.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400).trim();
+  return { set, providers, note };
+}
+
+/** May this provider be used at all? */
+export const aiProviderAllowed = (provider, policy) =>
+  policy.set !== true || (Boolean(provider) && policy.providers.includes(provider));
+
+/** The sentence the notebook shows when something is refused. */
+export const aiPolicyReason = (policy) => {
+  const base = `This CarmaR is configured to allow only: ${policy.providers.join(", ")}.`;
+  return policy.note ? `${base} ${policy.note}` : base;
+};
+
+/* ── finding things on this machine ───────────────────────────────────────── */
+
+/**
+ * Find a binary the way a launcher must: an app-bundle supervisor inherits a
+ * minimal PATH, so the PATH scan alone misses user-local installs.
+ */
+export function findBinary(name, extra = []) {
+  const exe = process.platform === "win32" ? `${name}.exe` : name;
+  for (const dir of String(process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    const cand = path.join(dir, exe);
+    try { fs.accessSync(cand, fs.constants.X_OK); if (fs.statSync(cand).isFile()) return cand; } catch { /* next */ }
+  }
+  for (const p of [...extra, path.join(os.homedir(), ".local", "bin", name),
+    path.join("/opt/homebrew/bin", name), path.join("/usr/local/bin", name)]) {
+    if (fs.existsSync(p)) return p;
+  }
+  return "";
+}
+
+/**
+ * Where the carmar-mcp stdio server lives on THIS machine, so the setup dialog
+ * can show a command that works verbatim. Repo layout first (tools/mcp beside
+ * spike/), then a distribution copy beside the kernel.
+ */
+export function mcpServerPath(here) {
+  for (const p of [path.join(here, "..", "tools", "mcp", "carmar-mcp.mjs"),
+    path.join(here, "mcp", "carmar-mcp.mjs")]) {
+    if (fs.existsSync(p)) return fs.realpathSync(p);
+  }
+  return "";
+}
+
+/* ── the plane ────────────────────────────────────────────────────────────── */
+
+export function createPlane({ spike, env, audit }) {
+  const here = spike;
+  const aiPolicy = aiProviderPolicy(env);
+  /** id → {rec, page, at} — an agent's tool call parked on one page. */
+  const pending = new Map();
+  /** id → one running CLI turn, owned by the page socket that asked. */
+  const chats = new Map();
+  let activePage = null;
+  let sweeper = null;
+  let ctxRef = null;
+
+  const claudeBin = () => {
+    const override = env("CARMAR_CLAUDE_BIN", "");
+    if (override && fs.existsSync(override)) return override;
+    return findBinary("claude");
+  };
+  const codexBin = () => {
+    const override = env("CARMAR_CODEX_BIN", "");
+    if (override && fs.existsSync(override)) return override;
+    return findBinary("codex");
+  };
+
+  const mcpRecs = (ctx) => ctx.sockets.filter((r) => r.role === "mcp");
+
+  /**
+   * The page an agent's request should land on: the one the user most recently
+   * focused, else the most recently opened page. NULL when no notebook window is
+   * connected at all — which is an ANSWER (the agent is told), never silence.
+   */
+  const targetPage = (ctx) => {
+    if (activePage && ctx.sockets.includes(activePage)) return activePage;
+    const pages = ctx.pageRecs();
+    return pages.length ? pages[pages.length - 1] : null;
+  };
+
+  /** Tell every notebook page who is connected, so the UI can show it. */
+  const notifyMcpClients = (ctx) => {
+    const agents = mcpRecs(ctx);
+    const frame = ctx.enc({ type: "mcp-clients", count: agents.length,
+      names: agents.map((r) => r.name || "agent") });
+    ctx.pageRecs().forEach((r) => r.ws.send(frame));
+  };
+
+  const chatSend = (rec, id, payload) =>
+    rec.ws.send(ctxRef.enc({ type: "agent-chat", id, ...payload }));
+
+  /** The two subscription CLIs the pane can ride. */
+  const chatClient = (cmd) => (cmd.client === "codex" ? "codex" : "claude");
+  const chatLabel = (client) => (client === "codex" ? "Codex" : "Claude Code");
+
+  function chatKill(id, notify = false) {
+    const ch = chats.get(id);
+    if (!ch) return;
+    ch.finished = true;
+    chats.delete(id);
+    try { ch.proc.kill("SIGKILL"); } catch { /* gone */ }
+    if (ch.cfg) fs.rmSync(ch.cfg, { recursive: true, force: true });
+    if (notify) chatSend(ch.rec, id, { done: true, code: -2, stopped: true });
+  }
+
+  function chatStart(rec, cmd, ctx) {
+    const id = cmd.id;
+    // Reviewed source proposals must never get the notebook's MUTATING MCP
+    // tools. Enforced at the process boundary, not merely in a prompt.
+    const textOnly = cmd.text_only === true;
+    const client = chatClient(cmd);
+    const label = chatLabel(client);
+    // THE DOOR WITH NO PAGE-SIDE BYPASS AT ALL: if the policy does not name the
+    // provider, the process is never spawned — there is nothing in the browser
+    // to work around, because the spawn was never there.
+    if (!aiProviderAllowed(client, aiPolicy)) {
+      audit("agent-chat-refused", { client, reason: "policy" });
+      chatSend(rec, id, { done: true, code: -1, error: `${label} is not permitted here. ${aiPolicyReason(aiPolicy)}` });
+      return;
+    }
+    const bin = client === "codex" ? codexBin() : claudeBin();
+    if (!bin) {
+      chatSend(rec, id, { done: true, code: -1,
+        error: `${label} is not installed on this machine (the \`${client === "codex" ? "codex" : "claude"}\` CLI was not found).` });
+      return;
+    }
+    if (chats.size >= MAX_CHATS) {
+      chatSend(rec, id, { done: true, code: -1, error: "Too many agent conversations are already running. Stop one first." });
+      return;
+    }
+
+    let cfg = "";                 // claude: the 0600 mcp-config; codex: the 0700 workdir
+    const server = mcpServerPath(here);
+    const node = findBinary("node") || process.execPath;
+    const originOk = `http://${ctx.deployment.loopback ? ctx.deployment.bind : "127.0.0.1"}:${ctx.port()}`;
+    const scalar = (v) => typeof v === "string" && v !== "";
+    let args;
+    if (client === "codex") {
+      cfg = fs.mkdtempSync(path.join(os.tmpdir(), "carmar-codex-"));
+      fs.chmodSync(cfg, 0o700);
+      // The values are TOML — a JSON string literal IS a TOML basic string —
+      // and carry no secret: the MCP URL is the kernel origin, nothing more.
+      const toml = (x) => JSON.stringify(x);
+      args = ["exec", "--json", "--ephemeral", "--skip-git-repo-check", "--ignore-user-config", "-C", cfg];
+      args.push(...(textOnly
+        ? ["--sandbox", "read-only", "--disable", "shell_tool", "-c", 'web_search="disabled"']
+        : ["--approve-for-me"]));
+      if (scalar(cmd.system)) args.push("-c", `developer_instructions=${toml(cmd.system)}`);
+      if (scalar(cmd.model) && cmd.model !== "default") args.push("-m", cmd.model);
+      if (!textOnly && server && node) {
+        args.push("-c", `mcp_servers.carmar.command=${toml(node)}`,
+          "-c", `mcp_servers.carmar.args=[${toml(server)}]`,
+          "-c", `mcp_servers.carmar.env={CARMAR_MCP_URL=${toml(`${originOk}/`)}}`);
+      }
+      args.push("-");                     // the prompt arrives on stdin
+    } else {
+      args = ["-p", "--output-format", "stream-json", "--verbose", "--include-partial-messages"];
+      if (scalar(cmd.system)) args.push("--append-system-prompt", cmd.system);
+      if (scalar(cmd.model) && cmd.model !== "default") args.push("--model", cmd.model);
+      if (textOnly) {
+        args.push("--tools", "", "--mcp-config", '{"mcpServers":{}}', "--strict-mcp-config", "--setting-sources", "");
+      } else if (server && node) {
+        cfg = path.join(os.tmpdir(), `carmar-chat-${crypto.randomBytes(8).toString("hex")}.json`);
+        fs.writeFileSync(cfg, `${JSON.stringify({ mcpServers: { carmar: {
+          command: node, args: [server], env: { CARMAR_MCP_URL: `${originOk}/` },
+        } } })}\n`, { mode: 0o600 });
+        fs.chmodSync(cfg, 0o600);
+        args.push("--mcp-config", cfg, "--strict-mcp-config", "--allowedTools", AGENT_CHAT_TOOLS);
+      }
+    }
+
+    let proc = null;
+    try { proc = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] }); }
+    catch (e) {
+      if (cfg) fs.rmSync(cfg, { recursive: true, force: true });
+      chatSend(rec, id, { done: true, code: -1, error: `Could not start ${label}: ${e.message}` });
+      return;
+    }
+    const ch = { proc, rec, cfg, stderrTail: [], out: "", finished: false };
+    chats.set(id, ch);
+
+    proc.once("error", (e) => {
+      if (ch.finished) return;
+      ch.finished = true;
+      chats.delete(id);
+      if (cfg) fs.rmSync(cfg, { recursive: true, force: true });
+      chatSend(rec, id, { done: true, code: -1, error: `Could not start ${label}: ${e.message}` });
+    });
+    proc.stdout.setEncoding("utf8");
+    proc.stderr.setEncoding("utf8");
+    proc.stdout.on("data", (d) => {
+      ch.out += d;
+      let nl = ch.out.indexOf("\n");
+      while (nl >= 0) {
+        const line = ch.out.slice(0, nl);
+        ch.out = ch.out.slice(nl + 1);
+        if (line) chatSend(rec, id, { line });
+        nl = ch.out.indexOf("\n");
+      }
+    });
+    proc.stderr.on("data", (d) => {
+      ch.stderrTail = [...ch.stderrTail, ...String(d).split("\n").filter(Boolean)].slice(-20);
+    });
+    proc.once("close", (code) => {
+      if (ch.finished) return;
+      ch.finished = true;
+      chats.delete(id);
+      if (ch.out.trim()) chatSend(rec, id, { line: ch.out.trim() });
+      const exit = Number.isInteger(code) ? code : -1;
+      if (exit !== 0 && ch.stderrTail.length) {
+        chatSend(rec, id, { done: true, code: exit, error: ch.stderrTail.join("\n") });
+      } else {
+        chatSend(rec, id, { done: true, code: exit });
+      }
+      audit("agent-chat-done", { id, detail: String(exit) });
+      if (cfg) fs.rmSync(cfg, { recursive: true, force: true });
+    });
+
+    // The prompt goes on stdin (argv leaks to `ps`, and long contexts overflow
+    // it); EOF tells the CLI the prompt is complete.
+    proc.stdin.on("error", () => { /* the CLI closed stdin early; `close` reports it */ });
+    try { proc.stdin.end(`${cmd.prompt}\n`); }
+    catch {
+      chatKill(id);
+      chatSend(rec, id, { done: true, code: -1, error: `${label} did not accept the prompt.` });
+      return;
+    }
+    audit("agent-chat", { id, client });
+  }
+
+  /**
+   * A page that is gone is a FACT — nothing can answer that request ever — and
+   * is reported immediately. The clock is only the backstop for a page that is
+   * alive and silent.
+   */
+  const sweep = (ctx) => {
+    if (!pending.size) return;
+    const now = Date.now();
+    for (const [id, entry] of [...pending]) {
+      if (!entry || !entry.rec) { pending.delete(id); continue; }
+      const pageGone = !entry.page || !ctx.sockets.includes(entry.page);
+      const stale = (now - entry.at) / 1000 >= MCP_PENDING_MAX_S;
+      if (!pageGone && !stale) continue;
+      const why = pageGone
+        ? "The CarmaR notebook window that was answering this request closed before it replied."
+        : `The notebook did not answer within ${MCP_PENDING_MAX_S} seconds.`;
+      audit("mcp-abandoned", { id, reason: pageGone ? "page closed" : "timeout" });
+      pending.delete(id);
+      entry.rec.ws.send(ctx.enc({ type: "mcp-response", id, ok: false, error: why }));
+    }
+  };
+
+  return {
+    name: "mcp",
+    ops: OPS,
+    // `agent-chat` is deliberately NOT here: serve.R refuses a non-page socket
+    // in SILENCE (an agent asking for another agent gets no frame at all), and
+    // the seam's refusal would answer it. The role check is in `handle`.
+    agentRefused: [],
+    commands: ["mcp-hello", "mcp-active", "agent-chat", "agent-chat-stop"],
+    capabilities: ["agent-plane-v1"],
+
+    init(ctx) {
+      ctxRef = ctx;
+      sweeper = setInterval(() => { try { sweep(ctx); } catch (e) { audit("plane-error", { plane: "mcp", detail: e.message }); } }, 1000);
+      sweeper.unref();
+    },
+
+    onOpen(rec, ctx) {
+      ctxRef = ctx;
+      // Replay the agent roster — same lesson as the ready frame.
+      const agents = mcpRecs(ctx);
+      if (agents.length) {
+        rec.ws.send(ctx.enc({ type: "mcp-clients", count: agents.length,
+          names: agents.map((r) => r.name || "agent") }));
+      }
+    },
+
+    onClose(rec, ctx) {
+      if (activePage === rec) activePage = null;
+      // A page that goes away takes its conversations with it — an orphan
+      // `claude -p` would keep billing a turn nobody can see.
+      for (const [id, ch] of [...chats]) if (ch.rec === rec) chatKill(id);
+      // An agent that vanishes must not leave its request ids parked forever.
+      // The PAGE dying is the other half and is NOT handled here: it cannot be,
+      // because the answer owed to the agent is "the window you asked is gone",
+      // which the sweep says on its next turn.
+      for (const [id, entry] of [...pending]) if (entry.rec === rec) pending.delete(id);
+      if (rec.role === "mcp") notifyMcpClients(ctx);
+    },
+
+    /** Loopback-only: where the MCP server is, and whether discovery is in place. */
+    http(req, res, pathname, ctx) {
+      if (pathname !== "/mcp-info") return false;
+      const blocked = ctx.controlRejection(req, { allowFile: true });
+      if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+      const dir = env("CARMAR_RUNTIME_DIR") || path.join(os.homedir(), ".carmar", "run");
+      const runtime = env("CARMAR_NO_RUNTIME_FILE") !== "1"
+        && fs.existsSync(path.join(dir, `kernel-${ctx.port()}.json`));
+      ctx.respond(res, 200, "application/json", ctx.enc({
+        server: mcpServerPath(here), runtime, text_only_chat: true,
+        claude: Boolean(claudeBin()), codex: Boolean(codexBin()),
+      }), { "Access-Control-Allow-Origin": "null" });
+      return true;
+    },
+
+    handle(cmd, rec, ctx, rawMessage) {
+      ctxRef = ctx;
+      const { enc, scalarChr } = ctx;
+
+      if (cmd.type === "mcp-hello") {
+        rec.role = "mcp";
+        rec.name = scalarChr(cmd.client) ? cmd.client.slice(0, 64) : "agent";
+        audit("mcp-hello", { detail: rec.name });
+        rec.ws.send(enc({ type: "mcp-hello", id: scalarChr(cmd.id) ? cmd.id : "hello",
+          ok: true, pages: ctx.pageRecs().length }));
+        notifyMcpClients(ctx);
+        return undefined;
+      }
+      if (cmd.type === "mcp-active") {
+        if (rec.role === "page") activePage = rec;
+        return undefined;
+      }
+      if (cmd.type === "mcp-request") {
+        if (rec.role !== "mcp") {
+          audit("mcp-refused", { reason: "mcp-request from a non-agent socket" });
+          return undefined;
+        }
+        if (!scalarChr(cmd.id) || !scalarChr(cmd.tool)) return undefined;
+        const page = targetPage(ctx);
+        audit("mcp-request", { id: cmd.id, detail: cmd.tool });
+        if (!page) {
+          rec.ws.send(enc({ type: "mcp-response", id: cmd.id, ok: false,
+            error: "No CarmaR notebook window is connected to this kernel. Open the notebook first." }));
+          return undefined;
+        }
+        pending.set(cmd.id, { rec, page, at: Date.now() });
+        page.ws.send(rawMessage);                       // forwarded verbatim
+        return undefined;
+      }
+      if (cmd.type === "mcp-response") {
+        if (rec.role === "mcp") return undefined;        // agents ask, pages answer
+        if (!scalarChr(cmd.id)) return undefined;
+        const waiting = pending.get(cmd.id);
+        if (waiting) {
+          pending.delete(cmd.id);
+          waiting.rec.ws.send(rawMessage);               // forwarded verbatim
+        }
+        return undefined;
+      }
+      if (cmd.type === "agent-chat") {
+        if (rec.role !== "page") {
+          audit("mcp-refused", { reason: "agent-chat from a non-page socket" });
+          return undefined;
+        }
+        if (!scalarChr(cmd.id) || !scalarChr(cmd.prompt)) return undefined;
+        if (chats.has(cmd.id)) return undefined;         // id reuse: ignore
+        chatStart(rec, cmd, ctx);
+        return undefined;
+      }
+      if (cmd.type === "agent-chat-stop") {
+        if (!scalarChr(cmd.id)) return undefined;
+        const ch = chats.get(cmd.id);
+        // Only the socket that started a conversation may stop it.
+        if (ch && ch.rec === rec) {
+          audit("agent-chat-stop", { id: cmd.id });
+          chatKill(cmd.id, true);
+        }
+        return undefined;
+      }
+      return undefined;
+    },
+
+    // A Quit needs no hook of its own: host.close() closes every socket, each
+    // close fires onClose above, and a page's conversations die with its page.
+    // The sweeper is unref'd, so it never holds the process open either.
+  };
+}