relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/installAgentRelay.js

@@ -0,0 +1,235 @@
+/**
+ * Patch relay-os instructions + Relay MCP into every supported agent surface.
+ * Cursor · Claude Code · Codex · Copilot CLI · Antigravity
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { relayOsBlock, agentBootstrap, RELAY_OS_BEGIN, RELAY_OS_END } = require("./relayOsBlock");
+
+function repoRoot() {
+  return path.join(__dirname, "..", "..");
+}
+
+function mcpServerScript() {
+  return path.join(repoRoot(), "backend", "mcp", "server.js");
+}
+
+function relayMcpEnv(workspacePath, agentLabel) {
+  const env = {};
+  if (workspacePath) env.RELAY_WORKSPACE_PATH = path.resolve(workspacePath);
+  // The stdio server can't otherwise tell which agent is calling it.
+  if (agentLabel) env.RELAY_AGENT_LABEL = agentLabel;
+  return env;
+}
+
+function relayStdioMcp(workspacePath, agentLabel) {
+  const script = mcpServerScript();
+  return {
+    command: process.execPath,
+    args: [script],
+    env: relayMcpEnv(workspacePath, agentLabel),
+  };
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+function patchRelayOsBlock(filePath, block) {
+  const existing = readText(filePath);
+  const begin = existing.indexOf(RELAY_OS_BEGIN);
+  const end = existing.indexOf(RELAY_OS_END);
+  if (begin >= 0 && end > begin) {
+    writeText(filePath, `${existing.slice(0, begin)}${block}${existing.slice(end + RELAY_OS_END.length)}`);
+    return "updated";
+  }
+  const trimmed = existing.trimEnd();
+  const sep = trimmed ? "\n\n" : "";
+  writeText(filePath, `${trimmed}${sep}${block}\n`);
+  return trimmed ? "appended" : "created";
+}
+
+function mergeJsonMcp(filePath, entry, { copilotType } = {}) {
+  let data = {};
+  try {
+    data = JSON.parse(readText(filePath) || "{}");
+  } catch {
+    data = {};
+  }
+  data.mcpServers = data.mcpServers && typeof data.mcpServers === "object" ? data.mcpServers : {};
+  const relay = copilotType
+    ? { type: "local", ...entry, tools: ["*"] }
+    : { ...entry };
+  data.mcpServers.relay = relay;
+  writeText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function mergeClaudeMcp(settingsPath, entry) {
+  let data = {};
+  try {
+    data = JSON.parse(readText(settingsPath) || "{}");
+  } catch {
+    data = {};
+  }
+  data.mcpServers = data.mcpServers && typeof data.mcpServers === "object" ? data.mcpServers : {};
+  data.mcpServers.relay = entry;
+  writeText(settingsPath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function mergeCodexMcp(configPath, workspacePath) {
+  const node = process.execPath.replace(/\\/g, "/");
+  const script = mcpServerScript().replace(/\\/g, "/");
+  const ws = path.resolve(workspacePath).replace(/\\/g, "/");
+  const envLines = [`RELAY_WORKSPACE_PATH = "${ws.replace(/"/g, '\\"')}"`, `RELAY_AGENT_LABEL = "Codex"`];
+  const block = `[mcp_servers.relay]
+command = "${node.replace(/"/g, '\\"')}"
+args = ["${script.replace(/"/g, '\\"')}"]
+
+[mcp_servers.relay.env]
+${envLines.join("\n")}
+`;
+  let text = readText(configPath);
+  const marker = "[mcp_servers.relay]";
+  const idx = text.indexOf(marker);
+  if (idx >= 0) {
+    // Skip our own [mcp_servers.relay.env] table, or the old one survives and TOML sees it twice.
+    const next = text.slice(idx + marker.length).search(/\n\[(?!mcp_servers\.relay(\.env)?\])/);
+    text = next >= 0 ? `${text.slice(0, idx)}${block}${text.slice(idx + marker.length + next)}` : `${text.slice(0, idx)}${block}`;
+  } else {
+    text = `${text.trimEnd()}\n\n${block}`;
+  }
+  writeText(configPath, text.endsWith("\n") ? text : `${text}\n`);
+}
+
+function cursorMdc(block) {
+  return `---
+description: Relay coordination — room context, locks, /relay ask
+alwaysApply: true
+---
+
+${block}
+`;
+}
+
+function ensureRelayDir(workspacePath) {
+  fs.mkdirSync(path.join(workspacePath, ".relay"), { recursive: true });
+  writeText(path.join(workspacePath, ".relay", "AGENT_BOOTSTRAP.md"), agentBootstrap(workspacePath));
+}
+
+function installProjectRelay(workspacePath) {
+  if (!workspacePath) return { ok: false, error: "workspace_required" };
+  const resolved = path.resolve(workspacePath);
+  const block = relayOsBlock();
+  const mcpFor = (label) => relayStdioMcp(resolved, label);
+  const results = { instructions: {}, mcp: {} };
+
+  const instructionTargets = [
+    path.join(resolved, "AGENTS.md"),
+    path.join(resolved, "CLAUDE.md"),
+    path.join(resolved, ".github", "copilot-instructions.md"),
+    path.join(resolved, ".cursorrules"),
+  ];
+  for (const file of instructionTargets) {
+    try {
+      results.instructions[path.relative(resolved, file)] = patchRelayOsBlock(file, block);
+    } catch (err) {
+      results.instructions[path.relative(resolved, file)] = String(err.message || err);
+    }
+  }
+
+  try {
+    writeText(path.join(resolved, ".cursor", "rules", "relay.mdc"), cursorMdc(block));
+    results.instructions[".cursor/rules/relay.mdc"] = "created";
+  } catch (err) {
+    results.instructions[".cursor/rules/relay.mdc"] = String(err.message || err);
+  }
+
+  ensureRelayDir(resolved);
+
+  try {
+    mergeJsonMcp(path.join(resolved, ".cursor", "mcp.json"), mcpFor("Cursor"));
+    results.mcp[".cursor/mcp.json"] = "ok";
+  } catch (err) {
+    results.mcp[".cursor/mcp.json"] = String(err.message || err);
+  }
+
+  try {
+    mergeClaudeMcp(path.join(resolved, ".claude", "settings.json"), mcpFor("Claude Code"));
+    results.mcp[".claude/settings.json"] = "ok";
+  } catch (err) {
+    results.mcp[".claude/settings.json"] = String(err.message || err);
+  }
+
+  try {
+    mergeCodexMcp(path.join(resolved, ".codex", "config.toml"), resolved);
+    results.mcp[".codex/config.toml"] = "ok";
+  } catch (err) {
+    results.mcp[".codex/config.toml"] = String(err.message || err);
+  }
+
+  try {
+    mergeJsonMcp(path.join(resolved, ".github", "mcp.json"), mcpFor("Copilot"), { copilotType: true });
+    results.mcp[".github/mcp.json"] = "ok";
+  } catch (err) {
+    results.mcp[".github/mcp.json"] = String(err.message || err);
+  }
+
+  try {
+    mergeJsonMcp(path.join(resolved, ".agents", "mcp_config.json"), mcpFor("Antigravity"));
+    results.mcp[".agents/mcp_config.json"] = "ok";
+  } catch (err) {
+    results.mcp[".agents/mcp_config.json"] = String(err.message || err);
+  }
+
+  return { ok: true, workspace: resolved, results };
+}
+
+function installGlobalRelay() {
+  const home = os.homedir();
+  const mcpFor = (label) => relayStdioMcp(null, label);
+  const results = {};
+  try {
+    mergeJsonMcp(path.join(home, ".cursor", "mcp.json"), mcpFor("Cursor"));
+    results["~/.cursor/mcp.json"] = "ok";
+  } catch (err) {
+    results["~/.cursor/mcp.json"] = String(err.message || err);
+  }
+  try {
+    mergeClaudeMcp(path.join(home, ".claude", "settings.json"), mcpFor("Claude Code"));
+    results["~/.claude/settings.json"] = "ok";
+  } catch (err) {
+    results["~/.claude/settings.json"] = String(err.message || err);
+  }
+  try {
+    mergeCodexMcp(path.join(home, ".codex", "config.toml"), home);
+    results["~/.codex/config.toml"] = "ok";
+  } catch (err) {
+    results["~/.codex/config.toml"] = String(err.message || err);
+  }
+  try {
+    const copilotPath = path.join(home, ".copilot", "mcp-config.json");
+    mergeJsonMcp(copilotPath, mcpFor("Copilot"), { copilotType: true });
+    results["~/.copilot/mcp-config.json"] = "ok";
+  } catch (err) {
+    results["~/.copilot/mcp-config.json"] = String(err.message || err);
+  }
+  return results;
+}
+
+module.exports = {
+  installProjectRelay,
+  installGlobalRelay,
+  relayStdioMcp,
+  patchRelayOsBlock,
+  relayOsBlock,
+};

package/backend/lib/installHooks.js

@@ -0,0 +1,309 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { EDIT, READ } = require("./editMatchers");
+const { installProjectRelay, installGlobalRelay } = require("./installAgentRelay");
+
+function repoRoot() {
+  return path.join(__dirname, "..", "..");
+}
+
+function nodeCmd(scriptRel) {
+  const abs = path.join(repoRoot(), scriptRel).replace(/\\/g, "/");
+  return `node "${abs}"`;
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2));
+}
+
+function installProjectHooks(workspacePath) {
+  if (!workspacePath) return;
+  const claude = nodeCmd("hooks/relay-claude-pre-tool.js");
+  const claudePost = nodeCmd("hooks/relay-claude-post-tool.js");
+  const claudeStop = nodeCmd("hooks/relay-claude-stop.js");
+  const cursor = nodeCmd("hooks/relay-cursor-pre-tool.js");
+  const cursorPost = nodeCmd("hooks/relay-cursor-post-tool.js");
+  const cursorStop = nodeCmd("hooks/relay-cursor-stop.js");
+  const codex = nodeCmd("hooks/relay-codex-pre-tool.js");
+  const codexPost = nodeCmd("hooks/relay-codex-post-tool.js");
+  const codexStop = nodeCmd("hooks/relay-codex-stop.js");
+  const copilot = nodeCmd("hooks/relay-copilot-pre-tool.js");
+  const copilotPost = nodeCmd("hooks/relay-copilot-post-tool.js");
+  const copilotStop = nodeCmd("hooks/relay-copilot-stop.js");
+  const anti = nodeCmd("hooks/relay-antigravity-pre-tool.js");
+  const antiPost = nodeCmd("hooks/relay-antigravity-post-tool.js");
+  const antiStop = nodeCmd("hooks/relay-antigravity-stop.js");
+
+  writeJson(path.join(workspacePath, ".claude", "settings.json"), {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: EDIT.claude,
+          hooks: [{ type: "command", command: claude }],
+        },
+        {
+          matcher: READ.claude,
+          hooks: [{ type: "command", command: nodeCmd("hooks/relay-claude-pre-read.js") }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: EDIT.claude,
+          hooks: [{ type: "command", command: claudePost }],
+        },
+      ],
+      Stop: [{ matcher: "*", hooks: [{ type: "command", command: claudeStop }] }],
+    },
+  });
+
+  writeJson(path.join(workspacePath, ".cursor", "hooks.json"), {
+    version: 1,
+    hooks: {
+      preToolUse: [
+        {
+          command: cursor,
+          matcher: EDIT.cursor,
+          timeout: 10,
+        },
+        {
+          command: nodeCmd("hooks/relay-cursor-pre-read.js"),
+          matcher: READ.cursor,
+          timeout: 10,
+        },
+      ],
+      postToolUse: [
+        {
+          command: cursorPost,
+          matcher: EDIT.cursor,
+          timeout: 10,
+        },
+      ],
+      // Documented Cursor read hook. Payload: { file_path, content }. Matcher
+      // filters by tool type (Read, TabRead, …). Fail-open by default: reporting
+      // a read must never be able to stop the agent from reading.
+      beforeReadFile: [
+        {
+          command: nodeCmd("hooks/relay-cursor-pre-read.js"),
+          matcher: "Read",
+          timeout: 10,
+        },
+      ],
+      stop: [{ command: cursorStop, loop_limit: 1 }],
+    },
+  });
+
+  // No read hook for Codex: it exposes no read or search tool, so file reads
+  // arrive as shell commands under the Bash matcher. Matching Bash to sniff
+  // reads out of a command line would report greps and cats as "reads" and miss
+  // everything else, so Codex contributes edits only.
+  writeJson(path.join(workspacePath, ".codex", "hooks.json"), {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: EDIT.codex,
+          hooks: [{ type: "command", command: codex, timeout: 10 }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: EDIT.codex,
+          hooks: [{ type: "command", command: codexPost, timeout: 10 }],
+        },
+      ],
+      Stop: [{ hooks: [{ type: "command", command: codexStop, timeout: 120 }] }],
+    },
+  });
+
+  writeJson(path.join(workspacePath, ".github", "hooks", "relay-os.json"), {
+    version: 1,
+    hooks: {
+      preToolUse: [
+        {
+          type: "command",
+          bash: copilot,
+          powershell: copilot,
+          matcher: EDIT.copilot,
+          cwd: ".",
+          timeoutSec: 10,
+        },
+        {
+          type: "command",
+          bash: nodeCmd("hooks/relay-copilot-pre-read.js"),
+          powershell: nodeCmd("hooks/relay-copilot-pre-read.js"),
+          matcher: READ.copilot,
+          cwd: ".",
+          timeoutSec: 10,
+        },
+      ],
+      postToolUse: [
+        {
+          type: "command",
+          bash: copilotPost,
+          powershell: copilotPost,
+          matcher: EDIT.copilot,
+          cwd: ".",
+          timeoutSec: 10,
+        },
+      ],
+      agentStop: [
+        {
+          type: "command",
+          bash: copilotStop,
+          powershell: copilotStop,
+          cwd: ".",
+          timeoutSec: 120,
+        },
+      ],
+    },
+  });
+
+  writeJson(path.join(workspacePath, ".agents", "hooks.json"), antigravityHooks(anti, antiPost, antiStop));
+  try {
+    installProjectRelay(workspacePath);
+  } catch {
+    /* instructions + MCP are best-effort */
+  }
+}
+
+/**
+ * Antigravity's config is keyed by hook NAME at the top level, and each name
+ * maps to its events — `{"relay": {"PreToolUse": [...]}}`. We were writing
+ * `{"hooks": {...}}`, which only worked by accident, as a hook that happened to
+ * be named "hooks".
+ *
+ * The event shapes also differ from each other: PreToolUse and PostToolUse take
+ * a matcher group wrapping a `hooks` array, while Stop takes the handler
+ * directly.
+ */
+function antigravityHooks(pre, post, stop) {
+  return {
+    relay: {
+      PreToolUse: [
+        {
+          matcher: EDIT.antigravity,
+          hooks: [{ type: "command", command: pre, timeout: 10 }],
+        },
+        {
+          matcher: READ.antigravity,
+          hooks: [{ type: "command", command: nodeCmd("hooks/relay-antigravity-pre-read.js"), timeout: 10 }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: EDIT.antigravity,
+          hooks: [{ type: "command", command: post, timeout: 10 }],
+        },
+      ],
+      Stop: [{ type: "command", command: stop, timeout: 120 }],
+    },
+  };
+}
+
+function mergeClaudeSettings(file, preCmd, postCmd, stopCmd) {
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    existing = {};
+  }
+  existing.hooks = existing.hooks || {};
+  existing.hooks.PreToolUse = [
+    {
+      matcher: EDIT.claude,
+      hooks: [{ type: "command", command: preCmd }],
+    },
+    {
+      matcher: READ.claude,
+      hooks: [{ type: "command", command: nodeCmd("hooks/relay-claude-pre-read.js") }],
+    },
+  ];
+  existing.hooks.PostToolUse = [
+    {
+      matcher: EDIT.claude,
+      hooks: [{ type: "command", command: postCmd }],
+    },
+  ];
+  existing.hooks.Stop = [{ matcher: "*", hooks: [{ type: "command", command: stopCmd }] }];
+  writeJson(file, existing);
+}
+
+function installGlobalHooks() {
+  const home = os.homedir();
+  mergeClaudeSettings(
+    path.join(home, ".claude", "settings.json"),
+    nodeCmd("hooks/relay-claude-pre-tool.js"),
+    nodeCmd("hooks/relay-claude-post-tool.js"),
+    nodeCmd("hooks/relay-claude-stop.js")
+  );
+  writeJson(path.join(home, ".cursor", "hooks.json"), {
+    version: 1,
+    hooks: {
+      preToolUse: [
+        {
+          command: nodeCmd("hooks/relay-cursor-pre-tool.js"),
+          matcher: EDIT.cursor,
+          timeout: 10,
+        },
+        {
+          command: nodeCmd("hooks/relay-cursor-pre-read.js"),
+          matcher: READ.cursor,
+          timeout: 10,
+        },
+      ],
+      postToolUse: [
+        {
+          command: nodeCmd("hooks/relay-cursor-post-tool.js"),
+          matcher: EDIT.cursor,
+          timeout: 10,
+        },
+      ],
+      beforeReadFile: [
+        {
+          command: nodeCmd("hooks/relay-cursor-pre-read.js"),
+          matcher: "Read",
+          timeout: 10,
+        },
+      ],
+      stop: [{ command: nodeCmd("hooks/relay-cursor-stop.js"), loop_limit: 1 }],
+    },
+  });
+  writeJson(path.join(home, ".codex", "hooks.json"), {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: EDIT.codex,
+          hooks: [{ type: "command", command: nodeCmd("hooks/relay-codex-pre-tool.js"), timeout: 10 }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: EDIT.codex,
+          hooks: [{ type: "command", command: nodeCmd("hooks/relay-codex-post-tool.js"), timeout: 10 }],
+        },
+      ],
+      Stop: [
+        {
+          hooks: [{ type: "command", command: nodeCmd("hooks/relay-codex-stop.js"), timeout: 120 }],
+        },
+      ],
+    },
+  });
+  const antigravity = antigravityHooks(
+    nodeCmd("hooks/relay-antigravity-pre-tool.js"),
+    nodeCmd("hooks/relay-antigravity-post-tool.js"),
+    nodeCmd("hooks/relay-antigravity-stop.js")
+  );
+  // Antigravity reads global hooks from ~/.gemini/config, either directly or
+  // from a plugin bundle under it.
+  writeJson(path.join(home, ".gemini", "config", "plugins", "relay", "hooks.json"), antigravity);
+  writeJson(path.join(home, ".gemini", "config", "hooks.json"), antigravity);
+  try {
+    installGlobalRelay();
+  } catch {
+    /* global MCP is best-effort */
+  }
+}
+
+module.exports = { installProjectHooks, installGlobalHooks };

package/backend/lib/lamport.js

@@ -0,0 +1,14 @@
+const clocks = new Map();
+
+function tick(workspaceId, incoming = 0) {
+  const key = workspaceId || "global";
+  const next = Math.max((clocks.get(key) || 0) + 1, Number(incoming) + 1);
+  clocks.set(key, next);
+  return next;
+}
+
+function peek(workspaceId) {
+  return clocks.get(workspaceId || "global") || 0;
+}
+
+module.exports = { tick, peek };

package/backend/lib/localBrowse.js

@@ -0,0 +1,109 @@
+// Backs the "Add workspace" window: a local directory browser and the signed-in
+// GitHub account's repositories. These used to be Next.js server routes; living
+// here lets Mission Control ship as a static build that `relay serve` hosts.
+// Both are host-only — a room member must never browse the host's disk.
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+
+function listDrives() {
+  const drives = [];
+  for (let c = 65; c <= 90; c++) {
+    const root = `${String.fromCharCode(c)}:\\`;
+    try {
+      if (fs.existsSync(root)) drives.push({ name: root, path: root, isDir: true });
+    } catch {
+      /* drive not ready */
+    }
+  }
+  return drives;
+}
+
+async function listDir(dir) {
+  if (!dir) {
+    const entries = process.platform === "win32" ? listDrives() : [{ name: "/", path: "/", isDir: true }];
+    return { status: 200, body: { path: null, parent: null, entries } };
+  }
+  const resolved = path.resolve(dir);
+  try {
+    const dirents = await fs.promises.readdir(resolved, { withFileTypes: true });
+    const entries = dirents
+      .map((d) => ({ name: d.name, path: path.join(resolved, d.name), isDir: d.isDirectory() }))
+      .sort((a, b) => (a.isDir === b.isDir ? a.name.localeCompare(b.name) : a.isDir ? -1 : 1));
+    const parent = path.dirname(resolved);
+    return { status: 200, body: { path: resolved, parent: parent === resolved ? null : parent, entries } };
+  } catch (err) {
+    return { status: 400, body: { error: err.message } };
+  }
+}
+
+function runGh(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("gh", args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: false });
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error("gh timed out"));
+    }, 25_000);
+    child.stdout.on("data", (c) => (out += c));
+    child.stderr.on("data", (c) => (err += c));
+    child.on("error", () => {
+      clearTimeout(timer);
+      reject(new Error("gh_not_installed"));
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(out.trim());
+      else reject(new Error(err.trim() || `gh exited ${code}`));
+    });
+  });
+}
+
+function classify(message) {
+  if (message === "gh_not_installed") return "gh_not_installed";
+  if (/not logged|authentication|gh auth login|HTTP 401/i.test(message)) return "gh_not_authenticated";
+  return message;
+}
+
+const CACHE_MS = 60_000;
+let cache = null;
+
+async function listGithubRepos({ refresh = false } = {}) {
+  if (!refresh && cache && Date.now() - cache.at < CACHE_MS) return cache.body;
+  try {
+    const raw = await runGh([
+      "api",
+      "user/repos?per_page=100&sort=updated&affiliation=owner,collaborator,organization_member",
+      "--paginate",
+    ]);
+    // --paginate concatenates JSON arrays; normalise "][" joins into one array.
+    const list = JSON.parse(raw.replace(/\]\s*\[/g, ","));
+    const repos = list.map((r) => ({
+      id: `gh_${r.id}`,
+      name: r.name,
+      fullName: r.full_name,
+      owner: r.owner?.login ?? null,
+      ownerAvatarUrl: r.owner?.avatar_url ?? null,
+      description: r.description,
+      private: Boolean(r.private),
+      fork: Boolean(r.fork),
+      language: r.language,
+      defaultBranch: r.default_branch,
+      cloneUrl: r.clone_url,
+      sshUrl: r.ssh_url,
+      htmlUrl: r.html_url,
+      updatedAt: r.pushed_at || r.updated_at,
+      stars: r.stargazers_count || 0,
+    }));
+    const body = { repos, error: null };
+    cache = { at: Date.now(), body };
+    return body;
+  } catch (err) {
+    // Never 500 here — the window renders a helpful empty state off `error`.
+    return { repos: [], error: classify(err.message) };
+  }
+}
+
+module.exports = { listDir, listGithubRepos };