relaybrain 0.0.0-stage → 0.2.0

package/backend/lib/treeSitterImports.js

@@ -0,0 +1,219 @@
+const fs = require("fs");
+const path = require("path");
+const { Parser, Language, Query } = require("@vscode/tree-sitter-wasm");
+
+const WASM_DIR = path.join(
+  path.dirname(require.resolve("@vscode/tree-sitter-wasm/package.json")),
+  "wasm"
+);
+
+const EXT_LANG = {
+  ".js": "javascript",
+  ".jsx": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".py": "python",
+  ".go": "go",
+  ".rs": "rust",
+  ".java": "java",
+  ".cs": "c-sharp",
+  ".cpp": "cpp",
+  ".cc": "cpp",
+  ".cxx": "cpp",
+  ".hpp": "cpp",
+  ".hh": "cpp",
+  ".h": "cpp",
+  ".php": "php",
+  ".rb": "ruby",
+};
+
+const QUERIES = {
+  javascript: `
+    (import_statement source: (string) @path)
+    (export_statement source: (string) @path)
+    (call_expression
+      function: (identifier) @fn
+      arguments: (arguments . (string) @path)
+      (#eq? @fn "require"))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (string) @path))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (_) @dynamic))
+  `,
+  typescript: `
+    (import_statement source: (string) @path)
+    (export_statement source: (string) @path)
+    (call_expression
+      function: (identifier) @fn
+      arguments: (arguments . (string) @path)
+      (#eq? @fn "require"))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (string) @path))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (_) @dynamic))
+  `,
+  tsx: `
+    (import_statement source: (string) @path)
+    (export_statement source: (string) @path)
+    (call_expression
+      function: (identifier) @fn
+      arguments: (arguments . (string) @path)
+      (#eq? @fn "require"))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (string) @path))
+    (call_expression
+      function: (import)
+      arguments: (arguments . (_) @dynamic))
+  `,
+  python: `
+    (import_from_statement module_name: (dotted_name) @name)
+    (import_from_statement module_name: (relative_import) @name)
+    (import_statement name: (dotted_name) @name)
+    (import_statement name: (aliased_import name: (dotted_name) @name))
+    (call
+      function: (attribute attribute: (identifier) @fn)
+      (#match? @fn "^(import_module|__import__)$")
+      arguments: (argument_list . (_) @dynamic))
+  `,
+  go: `
+    (import_spec path: (interpreted_string_literal) @path)
+    (import_spec path: (raw_string_literal) @path)
+  `,
+  rust: `
+    (mod_item name: (identifier) @mod)
+    (use_declaration argument: (scoped_identifier) @use)
+    (use_declaration argument: (identifier) @use)
+    (use_declaration argument: (use_wildcard (scoped_identifier) @use))
+    (use_declaration argument: (use_as_clause path: (_) @use))
+    (macro_invocation
+      macro: (identifier) @macro
+      (#eq? @macro "include")
+      (token_tree (string_literal) @path))
+  `,
+  java: `
+    (import_declaration (scoped_identifier) @name)
+    (import_declaration (identifier) @name)
+  `,
+  "c-sharp": `
+    (using_directive (qualified_name) @name)
+    (using_directive (identifier) @name)
+  `,
+  cpp: `
+    (preproc_include path: (string_literal) @path)
+    (preproc_include path: (system_lib_string) @system)
+  `,
+  php: `
+    (include_expression (string) @path)
+    (require_expression (string) @path)
+    (include_once_expression (string) @path)
+    (require_once_expression (string) @path)
+  `,
+  ruby: `
+    (call
+      method: (identifier) @fn
+      (#match? @fn "^(require|require_relative|load)$")
+      arguments: (argument_list (string) @path))
+  `,
+};
+
+let ready = null;
+const languages = new Map();
+const queries = new Map();
+
+function wasmFile(lang) {
+  return path.join(WASM_DIR, `tree-sitter-${lang}.wasm`);
+}
+
+async function initTreeSitter() {
+  if (ready) return ready;
+  ready = (async () => {
+    await Parser.init({
+      locateFile: (file) => path.join(WASM_DIR, path.basename(file)),
+    });
+    const langs = [...new Set(Object.values(EXT_LANG))];
+    for (const lang of langs) {
+      const file = wasmFile(lang);
+      if (!fs.existsSync(file)) continue;
+      try {
+        const language = await Language.load(file);
+        languages.set(lang, language);
+        const src = QUERIES[lang];
+        if (src) {
+          try {
+            queries.set(lang, new Query(language, src));
+          } catch (err) {
+            console.warn(`[relay] tree-sitter query failed for ${lang}:`, err.message);
+          }
+        }
+      } catch (err) {
+        console.warn(`[relay] tree-sitter language ${lang} failed:`, err.message);
+      }
+    }
+    return true;
+  })();
+  return ready;
+}
+
+function unquote(text) {
+  const t = String(text || "").trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")) || (t.startsWith("`") && t.endsWith("`"))) {
+    return t.slice(1, -1);
+  }
+  if (t.startsWith("<") && t.endsWith(">")) return t.slice(1, -1);
+  return t;
+}
+
+function extractWithQuery(lang, source) {
+  const language = languages.get(lang);
+  const query = queries.get(lang);
+  if (!language) return { staticSpecs: [], dynamic: [], engine: "none" };
+  const parser = new Parser();
+  parser.setLanguage(language);
+  const tree = parser.parse(source);
+  if (!tree) return { staticSpecs: [], dynamic: [], engine: "tree-sitter" };
+  const staticSpecs = [];
+  const dynamic = [];
+  if (query) {
+    for (const cap of query.captures(tree.rootNode)) {
+      const name = cap.name;
+      const text = unquote(cap.node.text);
+      if (!text) continue;
+    if (name === "dynamic") {
+      if (/^['"]/.test(cap.node.text) || text.startsWith(".")) staticSpecs.push(text);
+      else dynamic.push(text);
+    } else if (name === "system") dynamic.push(text);
+      else if (name === "fn" || name === "macro") continue;
+      else staticSpecs.push(text);
+    }
+  }
+  tree.delete();
+  parser.delete();
+  return {
+    staticSpecs: [...new Set(staticSpecs)],
+    dynamic: [...new Set(dynamic)],
+    engine: "tree-sitter",
+  };
+}
+
+function languageForExt(ext) {
+  return EXT_LANG[ext] || null;
+}
+
+function supportedLanguages() {
+  return [...languages.keys()];
+}
+
+module.exports = {
+  initTreeSitter,
+  extractWithQuery,
+  languageForExt,
+  supportedLanguages,
+  EXT_LANG,
+};

package/backend/lib/watchWorkspace.js

@@ -0,0 +1,42 @@
+const fs = require("fs");
+const path = require("path");
+const { EventEmitter } = require("events");
+
+const SKIP = new Set(["node_modules", ".git", ".next", ".relay", "out"]);
+
+class WorkspaceWatcher extends EventEmitter {
+  constructor() {
+    super();
+    this.watchers = new Map();
+  }
+
+  watch(workspacePath, workspaceId) {
+    if (!workspacePath || this.watchers.has(workspacePath) || !fs.existsSync(workspacePath)) return;
+    try {
+      const watcher = fs.watch(workspacePath, { recursive: true }, (event, filename) => {
+        if (!filename) return;
+        const rel = String(filename).replace(/\\/g, "/");
+        if ([...SKIP].some((s) => rel.split("/").includes(s))) return;
+        this.emit("change", { workspacePath, workspaceId, file: rel, event });
+      });
+      watcher.on("error", () => this.unwatch(workspacePath));
+      this.watchers.set(workspacePath, watcher);
+    } catch {
+      /* fs.watch recursive unsupported — skip, Stop hook still fires */
+    }
+  }
+
+  unwatch(workspacePath) {
+    const w = this.watchers.get(workspacePath);
+    if (w) {
+      try {
+        w.close();
+      } catch {
+        /* ignore */
+      }
+      this.watchers.delete(workspacePath);
+    }
+  }
+}
+
+module.exports = { WorkspaceWatcher };

package/backend/mcp/README.md

@@ -0,0 +1,193 @@
+# Querying the room
+
+Relay collects every member's agent transcripts, edits, locks and presence into
+one place. This is how an agent — or a shell script, or you — asks that store a
+question.
+
+Relay does not answer questions. It scopes and returns facts; whoever asked does
+the interpreting. That is deliberate: the caller is already a language model, so
+a second one in the middle would only add cost, latency and a way to be wrong.
+
+## The one thing to know
+
+**Reads are room-wide. Writes are local.**
+
+Anything that reads — chat history, edits, locks, conflicts — answers for every
+member of the room. Anything that writes — claiming a lock, reporting a change —
+only ever runs against the relay on your own machine, over the transport that
+still works when the tunnel does not.
+
+## Two transports, one tool surface
+
+Both are served by [`tools.js`](./tools.js). They expose the same seventeen tools.
+
+### stdio — what your agents already use
+
+`backend/mcp/server.js`, started by the agent itself. Nothing to configure; if
+relay is installed, this already works, and after this change its reads span the
+room instead of just this machine.
+
+### HTTP — through the room tunnel
+
+`POST /mcp` on the host. For an agent on another machine, or one on a box with
+no relay installed at all. Print the config with:
+
+```
+relay mcp-url
+```
+
+```json
+{
+  "mcpServers": {
+    "relay-room": {
+      "type": "http",
+      "url": "https://<tunnel>.ngrok-free.app/mcp",
+      "headers": {
+        "ngrok-skip-browser-warning": "relay",
+        "x-relay-room-token": "<your member token>"
+      }
+    }
+  }
+}
+```
+
+Stateless — no session id is issued, so there is nothing to expire. `GET /mcp`
+and `DELETE /mcp` answer `405`; a client that asks for the optional event stream
+just stops asking.
+
+**Anyone arriving from off-machine gets the eleven read tools only.** Claiming a
+lock as the host would file it under the host's workspace, the host's user, and
+an agent id the host cannot verify — and would put a second writer on a lock
+table that has exactly one on purpose. `tools/list` hides the other six, so a
+remote agent never sees a tool it cannot call.
+
+## What you can ask
+
+| Tool | Answers |
+|---|---|
+| `relay_session_brief` | memory-graph brief before editing files: who's on them now and why, blocks, decisions, prompts behind changes |
+| `relay_graph_query` | named Cypher queries over the FalkorDB memory graph (`file_story`, `who_to_ask`, `contention_trace`, `search_memory`, `hotspots`, …) |
+| `relay_get_chat_history` | what everyone told their agents to do, and what the agents said back |
+| `relay_room_brief` | teammate activity brief — **`/relay ask`** in Cursor, Claude, Codex, Copilot, Antigravity |
+| `relay_get_recent_changes` | which files changed, by whom, with diffs |
+| `relay_status` | who holds which lock right now |
+| `relay_get_conflicts` | who edited the same file as someone else in the last 5 minutes |
+| `relay_get_collision_stats` | lifetime counters for collisions Relay prevented |
+| `relay_get_project_context` | Central's view: changes, decisions, tasks, agents |
+| `relay_get_decisions` / `relay_get_active_tasks` | the decision and task logs |
+
+Writers (local only): `relay_claim_file`, `relay_release_file`,
+`relay_report_change`, `relay_report_decision`, `relay_update_task`,
+`relay_sync`.
+
+### Scoping a question
+
+`relay_get_chat_history` takes `agent`, `ownerLogin` and `limit`. Those three
+are the whole query language — "who, which agent, how much".
+
+```jsonc
+// What is ana's Antigravity working on?
+{ "ownerLogin": "ana", "agent": "Antigravity", "limit": 20 }
+
+// Everything Claude Code has done in this room, whoever is driving it
+{ "agent": "Claude Code" }
+
+// The last 5 events from anyone
+{ "limit": 5 }
+```
+
+`limit` defaults to 50 and is capped at 200 — memory.json is much larger than
+any context window, and a remote read has to cross a tunnel to get here.
+
+### What comes back
+
+```jsonc
+{
+  "history": [ /* oldest first, so the last entry is the newest */
+    {
+      "ts": 1786996380114,
+      "tsIso": "2026-08-17T19:53:00.114Z",
+      "agent": "Claude Code",
+      "ownerLogin": "prakrititz",
+      "sessionId": "03e3a558-…",
+      "role": "tool",
+      "kind": "code_edit",
+      "text": "Edit lockgraph.module.css",
+      "file": "lockgraph.module.css",
+      "diff": "--- a/lockgraph.module.css\n+++ b/…"
+    }
+  ],
+  "chats":  [ { "id": "chat_claude-code_03e3…", "agent": "Claude Code",
+                "ownerLogin": "prakrititz", "mine": true,
+                "updatedAt": 1786996380114, "messages": [ /* … */ ] } ],
+  "timeline": [ /* … */ ],
+  "room": { "source": "host", "peers": ["ana"], "peer_snapshot_age_ms": 0 }
+}
+```
+
+`relay_get_recent_changes` returns `edits`, each with `file`, `agent`,
+`ownerLogin`, `ts` and `diff`. `relay_get_conflicts` returns `conflicts`. Both
+carry the same `room` block.
+
+## Reading the `room` block
+
+Every read says where its answer came from and how old it is, because the
+freshness is genuinely uneven: locks move room-wide in ~150ms, but transcripts
+only travel on the 8s dashboard poll, and only when they changed. "What file are
+they in" is live; "what did they ask it to do" can be a few seconds behind. That
+is a judgment call about whether it's fresh enough for what you're about to do,
+so the caller gets to make it.
+
+| `source` | Means |
+|---|---|
+| `host` | asked the host just now; `peer_snapshot_age_ms` is under a second |
+| `local_snapshot` | the host did not answer — this is the last sync, `peer_snapshot_age_ms` says how old |
+| `solo` | not in a room; there are no peers to see |
+
+**A guest whose host is offline still gets an answer.** roomSync parks every
+peer's snapshot in your own `memory.json`, so the fallback is stale rather than
+empty. The tunnel being down costs one short timeout and never an error.
+
+Four reads in a row make one trip through the tunnel — the host response is
+cached for a second, which is short enough that nothing is meaningfully staler
+than a single request would have been.
+
+## Worked example
+
+An agent about to edit a locked file, asking who is in its way:
+
+```jsonc
+// relay_status — keyed "<workspaceId>::<filePath>"
+{ "locks": {
+    "C:\\repos\\relay.it::src/auth.ts": {
+      "filePath": "src/auth.ts", "holder": "ana", "agentId": "antigravity:ana",
+      "mode": "write", "claimedAt": 1786996352000, "ttlMs": 40000,
+      "expiresAt": 1786996392000, "readers": [], "escalated": false
+    } },
+  "uptime": 812.4 }
+
+// relay_get_chat_history { "ownerLogin": "ana", "agent": "Antigravity", "limit": 5 }
+// → "make the session cookie httpOnly"
+
+// relay_get_recent_changes → ana has touched auth.ts, session.ts, auth.test.ts
+```
+
+Three calls, no model in the middle, and the agent can decide for itself: work
+on the other module, or wait deliberately. The lock stopped being a wall and
+started being an explanation.
+
+## Troubleshooting
+
+**`"source": "solo"` but you are in a room.** `loadRoom()` found no room for
+this workspace. Check `.relay/room.json` in the repo, or `~/.relay/room.json`.
+
+**`401 not_a_member` on the HTTP endpoint.** The host made the room
+invite-only and your member token is missing or revoked. Re-join with the invite
+link, then `relay mcp-url` again.
+
+**A remote call returns "not available to remote callers".** Working as
+intended — that tool writes. Call it against your own relay over stdio.
+
+**Peers visible in Mission Control but not from MCP.** Both read the same merge
+now, so this should not happen; if it does, `relay doctor` on the machine that
+sees nothing is the place to start.

package/backend/mcp/server.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * MCP stdio — newline JSON-RPC. Chat history + locks. No markdown compile.
+ *
+ * The tools themselves live in ./tools.js so the room host can serve the same
+ * surface over HTTP; this file is only the stdio framing.
+ */
+const { handleRpc, defaultCtx } = require("./tools");
+
+function sendResult(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+}
+
+function sendErr(id, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message } }) + "\n");
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", async (chunk) => {
+  buf += chunk;
+  const lines = buf.split("\n");
+  buf = lines.pop() || "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    try {
+      // Rebuilt per message so a project registered after this process started
+      // still resolves, exactly as the inline lookup used to.
+      const reply = await handleRpc(msg, defaultCtx());
+      if (reply) sendResult(reply.id, reply.result);
+    } catch (err) {
+      sendErr(msg?.id, err.message);
+    }
+  }
+});