relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/relayOsBlock.js

@@ -0,0 +1,84 @@
+/**
+ * Single source of truth for the relay-os agent instruction block.
+ * Patched into every agent's instruction surface on `relay add` / `relay init`.
+ */
+
+const RELAY_OS_BEGIN = "<!-- BEGIN:relay-os -->";
+const RELAY_OS_END = "<!-- END:relay-os -->";
+
+function relayOsBlock() {
+  return `${RELAY_OS_BEGIN}
+# Relay (auto-installed)
+
+This project uses **Relay** for cross-agent memory. Do not ask the user to configure agent files manually.
+
+**Every session — read first:** \`.relay/AGENT_BOOTSTRAP.md\`
+
+| Phase | Action |
+|-------|--------|
+| Session start | Read \`.relay/relay_context.md\` (handoff). Never paste raw transcripts. |
+| After agent work | **You** update \`.relay/*.md\` from \`compile_brief.md\` (stop hook triggers this) |
+| Background sync | \`relay watch .\` keeps \`memory.json\` + \`compile_brief.md\` fresh |
+| Not installed? | Run \`relay add .\` or \`relay init\` in project root |
+
+**Stop hooks:** Cursor, Claude Code, Codex, Copilot CLI, Antigravity — installed by \`relay add\` / \`relay init\`.
+**Relay MCP:** \`relay_room_brief\`, locks, chat history — installed into each agent's MCP config by \`relay add\`.
+
+## Shared memory graph (Relay MCP)
+
+- **Before editing files you have not touched in this session**, call \`relay_session_brief\` with their paths. It tells you who is editing them right now and why, past collisions, decisions, and the prompts behind recent changes from every agent and teammate. Respect what it says.
+- When you make an architectural or design decision, call \`relay_report_decision\` with \`decision\` and the \`files\` it affects.
+- When a claim is denied, the reason says what the holder is working on. Pick other work, or ask the user.
+- To explain why code looks the way it does, call \`relay_graph_query\` with \`query: "file_story"\` and the \`path\`.
+
+## Relay pseudo-commands (user chat)
+
+These are **not** built-in slash commands. They are a **project convention** — phrases the user types so agents recognize Relay intent.
+
+When the user sends any of these phrases (with or without a leading \`/\`), treat them as Relay instructions — not casual chat:
+
+| User says | You do |
+|-----------|--------|
+| \`/relay update\` or \`relay update\` | \`relay sync .\` → \`relay compile .\` → read \`.relay/compile_brief.md\` → update \`.relay/project.md\`, \`current_task.md\`, \`decisions.md\`, \`failures.md\` → \`relay context .\` → confirm "Relay updated." |
+| \`/relay context\` or \`relay context\` | Read \`.relay/relay_context.md\` (run \`relay context .\` first if stale). Summarize handoff briefly. |
+| \`/relay ask\` or \`relay ask\` | Call Relay MCP tool **\`relay_room_brief\`** (MCP server **\`relay\`**). Required on **Cursor, Claude Code, Codex, Copilot CLI, and Antigravity** — not a terminal command for the human. Summarize teammate chat, code edits, locks, and file-sync notes. Tell the user before you edit shared files. If \`relay\` MCP is missing, say so and suggest \`relay add .\` + agent restart (do not ask the user to run \`relay ask\`). |
+| \`/relay init\` or \`relay init\` | Run \`relay init\` in project root if \`.relay/\` missing; else confirm already installed. |
+
+Use \`npx relay\` if the \`relay\` command is not on PATH. Do not ask the user to edit agent config files manually.
+
+Cursor: \`@relay-sync\` skill at \`.cursor/skills/relay-sync/\`.
+${RELAY_OS_END}
+`;
+}
+
+function agentBootstrap(workspacePath) {
+  const ws = workspacePath.replace(/\\/g, "/");
+  return `# Relay agent bootstrap
+
+Project: \`${ws}\`
+
+## /relay ask (all agents)
+
+When the user says **\`/relay ask\`** or **\`relay ask\`**:
+
+1. Call MCP tool **\`relay_room_brief\`** on the **\`relay\`** MCP server (stdio — installed by \`relay add\`).
+2. Summarize peer chat, code edits, live locks, and the file-sync note for the user.
+3. **Do not** tell the human to run a CLI command.
+
+| Agent | Instructions file | Relay MCP config |
+|-------|-------------------|------------------|
+| **Cursor** | \`.cursor/rules/relay.mdc\`, \`.cursorrules\`, \`AGENTS.md\` | \`.cursor/mcp.json\` |
+| **Claude Code** | \`CLAUDE.md\`, \`.claude/settings.json\` | \`.claude/settings.json\` → \`mcpServers.relay\` |
+| **Codex** | \`AGENTS.md\` | \`.codex/config.toml\` → \`[mcp_servers.relay]\` |
+| **Copilot CLI** | \`.github/copilot-instructions.md\` | \`.github/mcp.json\` |
+| **Antigravity** | \`AGENTS.md\` | \`.agents/mcp_config.json\` |
+
+If \`relay_room_brief\` is not in your tool list, Relay MCP is not connected — run \`relay add .\` from the repo root and restart this agent session.
+
+## Other pseudo-commands
+
+See the \`relay-os\` block in \`AGENTS.md\` / \`CLAUDE.md\` for \`/relay update\`, \`/relay context\`, and \`/relay init\`.
+`;
+}
+
+module.exports = { RELAY_OS_BEGIN, RELAY_OS_END, relayOsBlock, agentBootstrap };

package/backend/lib/repoSnapshot.js

@@ -0,0 +1,125 @@
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { isBinary, sha256 } = require("./patches");
+
+// Mirrors dirtyFiles' SKIP list. `.relay` is deliberately excluded: it holds the
+// host's room.json and lock files, and shipping those to a guest would point the
+// guest's coordinator at the guest's own tunnel.
+const SKIP_DIR = /^(\.git|\.relay|node_modules|\.next|dist|out|build|\.turbo|\.venv|__pycache__|target)$/i;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_FILES = 4000;
+
+function gitTracked(workspacePath) {
+  try {
+    const out = execFileSync("git", ["-C", workspacePath, "ls-files", "-co", "--exclude-standard"], {
+      encoding: "utf8",
+      timeout: 8000,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    return out.split("\n").map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+function walk(workspacePath, rel = "", out = [], depth = 0) {
+  if (depth > 12 || out.length >= MAX_FILES) return out;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(path.join(workspacePath, rel), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (out.length >= MAX_FILES) break;
+    if (SKIP_DIR.test(entry.name)) continue;
+    const next = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) walk(workspacePath, next, out, depth + 1);
+    else if (entry.isFile()) out.push(next);
+  }
+  return out;
+}
+
+function skipped(rel) {
+  return rel.split("/").some((segment) => SKIP_DIR.test(segment));
+}
+
+/**
+ * Every file a joining peer needs to start from the same tree as the host.
+ * Text files travel as UTF-8, binaries as base64 — a guest that only received
+ * the git-dirty set (what /api/snapshot used to send) starts with an empty
+ * folder unless it happened to already have the repo cloned.
+ */
+function treeFiles(workspacePath) {
+  if (!workspacePath || !fs.existsSync(workspacePath)) return { files: [], truncated: false };
+  const listed = gitTracked(workspacePath) || walk(workspacePath);
+  const files = [];
+  let total = 0;
+  let truncated = false;
+  for (const raw of listed) {
+    const rel = raw.replace(/\\/g, "/");
+    if (!rel || skipped(rel)) continue;
+    if (files.length >= MAX_FILES || total >= MAX_TOTAL_BYTES) {
+      truncated = true;
+      break;
+    }
+    const abs = path.join(workspacePath, rel);
+    let buf;
+    try {
+      const stat = fs.statSync(abs);
+      if (!stat.isFile()) continue;
+      if (stat.size > MAX_FILE_BYTES) {
+        truncated = true;
+        continue;
+      }
+      buf = fs.readFileSync(abs);
+    } catch {
+      continue;
+    }
+    total += buf.length;
+    const binary = isBinary(buf);
+    files.push({
+      path: rel,
+      binary,
+      sha256: sha256(buf),
+      content: binary ? buf.toString("base64") : buf.toString("utf8"),
+      encoding: binary ? "base64" : "utf8",
+    });
+  }
+  return { files, truncated };
+}
+
+/** Materializes a treeFiles() payload into a workspace. Returns what landed. */
+function writeTree(workspacePath, files) {
+  if (!workspacePath || !Array.isArray(files)) return { written: [], failed: [] };
+  const written = [];
+  const failed = [];
+  for (const file of files) {
+    const rel = String(file?.path || "").replace(/\\/g, "/");
+    // A peer is not allowed to escape the workspace root — `../` in a path from
+    // an untrusted room would otherwise write anywhere on this machine.
+    if (!rel || rel.startsWith("/") || rel.split("/").includes("..") || /^[a-zA-Z]:/.test(rel)) {
+      failed.push(rel || "(empty)");
+      continue;
+    }
+    const abs = path.join(workspacePath, rel);
+    const buf = Buffer.from(String(file.content ?? ""), file.encoding === "base64" ? "base64" : "utf8");
+    try {
+      // Same reason as applyPatchToDisk: an identical rewrite still wakes the
+      // watcher, and a whole-tree seed would wake it once per file.
+      if (fs.existsSync(abs) && sha256(fs.readFileSync(abs)) === sha256(buf)) continue;
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, buf);
+      written.push(rel);
+    } catch {
+      failed.push(rel);
+    }
+  }
+  return { written, failed };
+}
+
+module.exports = { treeFiles, writeTree, MAX_FILES, MAX_FILE_BYTES };