relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/roomAsk.js

@@ -0,0 +1,148 @@
+/**
+ * Room brief for the `/relay ask` pseudo-command — what teammates' agents did recently.
+ * Agents fetch this via MCP `relay_room_brief`; humans do not run a CLI for it.
+ */
+
+function sameLogin(a, b) {
+  return Boolean(a) && Boolean(b) && String(a).toLowerCase() === String(b).toLowerCase();
+}
+
+function clip(text, max = 600) {
+  const s = String(text || "").trim();
+  if (!s) return "";
+  return s.length > max ? `${s.slice(0, max)}\n…` : s;
+}
+
+function formatTs(ts) {
+  const n = Number(ts);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  try {
+    return new Date(n).toISOString().replace("T", " ").slice(0, 19);
+  } catch {
+    return "";
+  }
+}
+
+function peerRows(rows, login) {
+  return (rows || []).filter((row) => row && !row.mine && !sameLogin(row.ownerLogin, login));
+}
+
+function threadPeerMessages(chats, login, limit) {
+  const lines = [];
+  for (const thread of chats || []) {
+    if (sameLogin(thread.ownerLogin, login)) continue;
+    const who = thread.ownerLogin ? `@${thread.ownerLogin}` : thread.agent || "peer";
+    const agent = thread.agent ? ` (${thread.agent})` : "";
+    for (const msg of (thread.messages || []).slice(-6)) {
+      if (!msg?.text || msg.role === "system") continue;
+      const stamp = formatTs(msg.ts || thread.updatedAt);
+      lines.push({ ts: msg.ts || thread.updatedAt || 0, line: `- **${who}${agent}** ${stamp}: ${clip(msg.text, 500)}` });
+    }
+  }
+  return lines.sort((a, b) => (b.ts || 0) - (a.ts || 0)).slice(0, limit);
+}
+
+function formatLocks(locks) {
+  const live = (locks || []).filter((l) => l && !l.released);
+  if (!live.length) return "_No files locked right now._\n";
+  return (
+    live
+      .slice(0, 20)
+      .map((l) => {
+        const who = l.holder?.login ? `@${l.holder.login}` : l.holder?.label || l.agentId || "?";
+        return `- \`${l.filePath}\` — ${who} (${l.mode || "write"})`;
+      })
+      .join("\n") + "\n"
+  );
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.view — mergeRoomViews output
+ * @param {object|null} opts.room — loadRoom()
+ * @param {string} opts.login — current GitHub login
+ * @param {Array} opts.locks — live lock rows
+ * @param {number} opts.limit — max peer edit/chat lines
+ */
+function compileRoomAsk({ view, room, login, locks = [], limit = 30 }) {
+  const peerEdits = peerRows(view.edits, login)
+    .sort((a, b) => (b.ts || 0) - (a.ts || 0))
+    .slice(0, limit);
+  const peerActivity = peerRows(view.activity, login)
+    .sort((a, b) => (b.ts || 0) - (a.ts || 0))
+    .slice(0, limit);
+  const chatLines = threadPeerMessages(view.chats, login, limit);
+  const agents = (view.agents || []).filter((a) => a.status === "connected" && !sameLogin(a.ownerLogin, login));
+
+  const roomLine = room?.url
+    ? `Room **${room.role}** · ${room.memberCount || view.peerLogins?.length || 0} member(s) · peers: ${(view.peerLogins || []).join(", ") || "none yet"}`
+    : "Not in a shared room — showing local activity only.";
+
+  const sections = [];
+  sections.push("# Relay ask — teammate activity\n");
+  sections.push(`Generated: ${new Date().toISOString()}`);
+  sections.push(`${roomLine}\n`);
+  sections.push("> Agents load this via MCP `relay_room_brief` when the user says `/relay ask`.\n");
+
+  sections.push("## Connected agents (other machines)\n");
+  if (!agents.length) sections.push("_No other connected agents right now._\n");
+  else {
+    for (const a of agents.slice(0, 12)) {
+      const owner = a.ownerLogin ? `@${a.ownerLogin}` : "";
+      sections.push(`- **${a.label || a.id}** ${owner}`.trim());
+    }
+    sections.push("");
+  }
+
+  sections.push("## Recent teammate chat\n");
+  if (!chatLines.length) sections.push("_No peer chat synced yet — teammate needs `relay serve` + room join._\n");
+  else {
+    for (const row of chatLines) sections.push(row.line);
+    sections.push("");
+  }
+
+  sections.push("## Recent teammate code edits\n");
+  if (!peerEdits.length) sections.push("_No peer edits in the room feed yet._\n");
+  else {
+    for (const e of peerEdits) {
+      const who = e.ownerLogin ? `@${e.ownerLogin}` : "peer";
+      const agent = e.agent ? ` · ${e.agent}` : "";
+      sections.push(`- \`${e.file || "?"}\` — ${who}${agent} · ${formatTs(e.ts)}`);
+      if (e.diff) sections.push(`  \`\`\`diff\n${clip(e.diff, 400)}\n  \`\`\``);
+    }
+    sections.push("");
+  }
+
+  sections.push("## Teammate activity (tools)\n");
+  if (!peerActivity.length) sections.push("_No peer tool activity._\n");
+  else {
+    for (const a of peerActivity.slice(0, 15)) {
+      const who = a.ownerLogin ? `@${a.ownerLogin}` : "peer";
+      sections.push(`- ${who} · ${a.agent || "?"} · ${clip(a.text, 120)} · ${formatTs(a.ts)}`);
+    }
+    sections.push("");
+  }
+
+  sections.push("## Live locks (whole room)\n");
+  sections.push(formatLocks(locks));
+
+  sections.push("## File sync note\n");
+  sections.push(
+    "Chat/activity above sync via the room transcript pipeline. **File contents** land on your disk only when post-tool hooks flush patches (`relay serve` + hooks on each machine). If a file is missing locally, ask the editor to re-save it or run `/api/flush-file` — not `relay push` after a git commit.\n"
+  );
+
+  const markdown = sections.join("\n");
+  const json = {
+    room: room
+      ? { role: room.role, url: room.url, peers: view.peerLogins || [], memberCount: room.memberCount }
+      : null,
+    peerEdits,
+    peerActivity: peerActivity.slice(0, 15),
+    chatLines: chatLines.map((r) => r.line),
+    agents: agents.slice(0, 12),
+    locks: (locks || []).filter((l) => !l.released).slice(0, 20),
+  };
+  return { markdown, json };
+}
+
+module.exports = { compileRoomAsk, peerRows, sameLogin };

package/backend/lib/roomAuth.js

@@ -0,0 +1,215 @@
+const crypto = require("crypto");
+
+// A shared room is reachable by anyone who learns the tunnel URL, and it hands
+// out the whole working tree, every agent transcript, and write access to the
+// lock table. Membership therefore has to be proven, not assumed.
+//
+// Two credentials, with different lifetimes:
+//   invite code  — issued by the host to one named person, single use, expires.
+//   member token — minted when an invite is redeemed, presented on every
+//                  subsequent request for as long as the room lasts.
+// Only hashes are ever written to room.json, so a leaked room file cannot be
+// replayed to rejoin the room.
+
+const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const SECRET_BYTES = 24;
+
+function hash(raw) {
+  return crypto.createHash("sha256").update(String(raw)).digest("hex");
+}
+
+function mint(prefix) {
+  return `${prefix}_${crypto.randomBytes(SECRET_BYTES).toString("hex")}`;
+}
+
+function sameSecret(a, b) {
+  const left = Buffer.from(String(a || ""), "utf8");
+  const right = Buffer.from(String(b || ""), "utf8");
+  if (left.length !== right.length || !left.length) return false;
+  return crypto.timingSafeEqual(left, right);
+}
+
+function normLogin(login) {
+  return String(login || "").trim().toLowerCase();
+}
+
+function invitesOf(room) {
+  return Array.isArray(room?.invites) ? room.invites : [];
+}
+
+function inviteState(invite, now = Date.now()) {
+  if (invite.revokedAt) return "revoked";
+  if (invite.acceptedAt) return "accepted";
+  if (invite.expiresAt && now > invite.expiresAt) return "expired";
+  return "pending";
+}
+
+function createInvite(room, { login, ttlMs, invitedBy } = {}) {
+  const target = normLogin(login);
+  if (!target) return { ok: false, error: "login_required" };
+  const code = mint("rli");
+  const now = Date.now();
+  const invite = {
+    id: `inv_${crypto.randomBytes(6).toString("hex")}`,
+    login: target,
+    codeHash: hash(code),
+    createdAt: now,
+    expiresAt: now + (Number(ttlMs) || INVITE_TTL_MS),
+    invitedBy: normLogin(invitedBy) || null,
+    acceptedAt: null,
+    revokedAt: null,
+  };
+  room.invites = [...invitesOf(room).filter((i) => inviteState(i) !== "expired"), invite];
+  return { ok: true, invite, code };
+}
+
+function revokeInvite(room, id) {
+  const invite = invitesOf(room).find((i) => i.id === id);
+  if (!invite) return { ok: false, error: "not_found" };
+  invite.revokedAt = Date.now();
+  return { ok: true, invite };
+}
+
+/** Safe to send to a client: never includes the code or its hash. */
+function inviteView(room) {
+  return invitesOf(room).map((i) => ({
+    id: i.id,
+    login: i.login,
+    state: inviteState(i),
+    createdAt: i.createdAt,
+    expiresAt: i.expiresAt,
+    invitedBy: i.invitedBy,
+    acceptedAt: i.acceptedAt,
+  }));
+}
+
+function pendingInviteFor(room, login) {
+  const claimed = normLogin(login);
+  return invitesOf(room).find((i) => normLogin(i.login) === claimed && inviteState(i) === "pending") || null;
+}
+
+function acceptedInviteFor(room, login) {
+  const claimed = normLogin(login);
+  return invitesOf(room).find((i) => normLogin(i.login) === claimed && inviteState(i) === "accepted") || null;
+}
+
+/**
+ * Checks an invite code against the room. `login` is who is claiming it — an
+ * invite addressed to one person must not be usable by another, otherwise a
+ * forwarded link is as good as an open door. A code-less redeem is only safe
+ * after GitHub identity proof (see /api/room/redeem).
+ */
+function redeemInvite(room, code, login) {
+  const claimed = normLogin(login);
+  if (!claimed) return { ok: false, reason: "login_required" };
+  if (code) {
+    const hashed = hash(code);
+    const invite = invitesOf(room).find((i) => sameSecret(i.codeHash, hashed));
+    if (!invite) return { ok: false, reason: "invite_invalid" };
+    const state = inviteState(invite);
+    if (state === "revoked") return { ok: false, reason: "invite_revoked" };
+    if (state === "expired") return { ok: false, reason: "invite_expired" };
+    if (state === "accepted") return { ok: false, reason: "invite_already_used" };
+    if (normLogin(invite.login) !== claimed) {
+      return { ok: false, reason: "invite_wrong_user", invitedLogin: invite.login };
+    }
+    return { ok: true, invite };
+  }
+  // Code-less redeem is only safe after GitHub identity proof (see /api/room/redeem).
+  const pending = pendingInviteFor(room, claimed);
+  if (pending) return { ok: true, invite: pending };
+  const accepted = acceptedInviteFor(room, claimed);
+  if (accepted) return { ok: true, invite: accepted, rejoin: true };
+  return { ok: false, reason: "invite_required" };
+}
+
+function markAccepted(invite, login) {
+  invite.acceptedAt = Date.now();
+  invite.acceptedBy = normLogin(login);
+  return invite;
+}
+
+/** Mints the long-lived credential a member presents on every later request. */
+function issueMemberToken(room, login) {
+  const target = normLogin(login);
+  const token = mint("rlm");
+  room.memberTokens = (Array.isArray(room.memberTokens) ? room.memberTokens : []).filter(
+    (t) => normLogin(t.login) !== target
+  );
+  room.memberTokens.push({ login: target, tokenHash: hash(token), issuedAt: Date.now() });
+  return token;
+}
+
+function authorizeMember(room, token) {
+  if (!token) return null;
+  const hashed = hash(token);
+  const row = (Array.isArray(room?.memberTokens) ? room.memberTokens : []).find((t) =>
+    sameSecret(t.tokenHash, hashed)
+  );
+  return row ? { login: row.login, issuedAt: row.issuedAt } : null;
+}
+
+function revokeMember(room, login) {
+  const target = normLogin(login);
+  room.memberTokens = (Array.isArray(room.memberTokens) ? room.memberTokens : []).filter(
+    (t) => normLogin(t.login) !== target
+  );
+  room.invites = invitesOf(room).map((i) =>
+    normLogin(i.login) === target && !i.revokedAt ? { ...i, revokedAt: Date.now() } : i
+  );
+  return room;
+}
+
+/**
+ * The room as it is safe to hand to any client. /api/health and /api/room are
+ * both reachable through the tunnel without credentials, and the raw room
+ * carries invite and member token hashes.
+ */
+function publicRoom(room) {
+  if (!room) return null;
+  const { invites, memberTokens, members, memberToken, nonce, ...rest } = room;
+  return { ...rest, memberCount: Array.isArray(members) ? members.length : 0 };
+}
+
+/** Reads the member credential off a request. */
+function roomToken(req) {
+  const header = req.headers?.["x-relay-room-token"];
+  if (header) return String(header);
+  const auth = String(req.headers?.authorization || "");
+  if (/^Room\s+/i.test(auth)) return auth.replace(/^Room\s+/i, "").trim();
+  return req.query?.token ? String(req.query.token) : null;
+}
+
+/**
+ * True when the request arrived from somewhere other than this machine. ngrok
+ * (and any reverse proxy) stamps X-Forwarded-For, which a remote caller cannot
+ * strip. Local Mission Control and local hooks stay unauthenticated so adding
+ * room security never breaks solo use.
+ */
+function isRemoteRequest(req) {
+  if (req.headers?.["x-forwarded-for"] || req.headers?.["x-original-forwarded-for"]) return true;
+  const addr = String(req.socket?.remoteAddress || req.connection?.remoteAddress || "");
+  if (!addr) return false;
+  const bare = addr.replace(/^::ffff:/, "");
+  return bare !== "127.0.0.1" && bare !== "::1" && bare !== "localhost";
+}
+
+module.exports = {
+  INVITE_TTL_MS,
+  hash,
+  normLogin,
+  createInvite,
+  revokeInvite,
+  inviteView,
+  inviteState,
+  invitesOf,
+  redeemInvite,
+  pendingInviteFor,
+  markAccepted,
+  issueMemberToken,
+  authorizeMember,
+  revokeMember,
+  publicRoom,
+  roomToken,
+  isRemoteRequest,
+};

package/backend/lib/roomControl.js

@@ -0,0 +1,226 @@
+const { WebSocket } = require("ws");
+
+// A guest that releases a lock while the tunnel is down must still be able to
+// tell the host about it, or the file stays locked room-wide until the TTL runs
+// out (up to MAX_TTL_MS, five minutes). The queue is bounded because an outage
+// has no upper bound: past this many pending mutations the oldest are dropped,
+// since a release that stale has been overtaken by TTL expiry anyway.
+const MAX_QUEUED = 200;
+
+/**
+ * Guest-side RPC over the dedicated control socket.
+ * Locks are game inputs: tiny, ordered, never queued behind chat snapshots.
+ */
+class RoomControl {
+  constructor() {
+    this.socket = null;
+    this.pending = new Map();
+    this.seq = 0;
+    this.onLocks = null;
+    // Mutations issued while `open` was false, replayed in order on reconnect.
+    this.queue = [];
+    this.queueSeq = 0;
+    this.onReplay = null;
+    this.flushing = null;
+  }
+
+  attach(socket) {
+    this.socket = socket;
+  }
+
+  get open() {
+    return Boolean(this.socket && this.socket.readyState === WebSocket.OPEN);
+  }
+
+  handle(msg) {
+    if (!msg || typeof msg !== "object") return false;
+    if (msg.type === "locks" && this.onLocks) {
+      this.onLocks(msg);
+      return true;
+    }
+    if ((msg.type === "rpc-ok" || msg.type === "rpc-err") && this.pending.has(msg.id)) {
+      const done = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      let error = null;
+      if (msg.type === "rpc-err") {
+        error = new Error(msg.error || "rpc_failed");
+        // The host answered, and said no. Everything else that can reject an
+        // rpc — a dead socket, a timeout, a send that throws — is the tunnel
+        // failing rather than a verdict, and replay treats the two oppositely.
+        error.fromHost = true;
+      }
+      done(error, msg.result);
+      return true;
+    }
+    return false;
+  }
+
+  rpc(op, body, timeoutMs = 700) {
+    return new Promise((resolve, reject) => {
+      if (!this.open) {
+        reject(new Error("control_offline"));
+        return;
+      }
+      const id = String(++this.seq);
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("control_timeout"));
+      }, timeoutMs);
+      this.pending.set(id, (err, result) => {
+        clearTimeout(timer);
+        if (err) reject(err);
+        else resolve(result);
+      });
+      try {
+        this.socket.send(JSON.stringify({ type: "rpc", op, id, body }));
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Park a mutation that could not be sent, for replay on reconnect.
+   *
+   * Deliberately not used for `claim`: a claim is a question ("may I?"), and
+   * replaying it minutes later would answer a question nobody is still asking —
+   * the agent has long since been told no and moved on. Only the mutations that
+   * are statements of fact ("I am done with this file") are worth replaying.
+   *
+   * Deliberately not used for `heartbeat` either: a heartbeat is a liveness
+   * claim about *now*. Replaying a stale one would resurrect a lock the host has
+   * already expired, which is the opposite of what the sender meant.
+   */
+  enqueue(op, body) {
+    if (op !== "release" && op !== "release-all") return false;
+    const key = dedupeKey(op, body);
+    const existing = this.queue.findIndex((item) => item.key === key);
+    if (existing !== -1) this.queue.splice(existing, 1);
+    this.queue.push({ key, op, body, seq: ++this.queueSeq, at: Date.now() });
+    while (this.queue.length > MAX_QUEUED) this.queue.shift();
+    return true;
+  }
+
+  get queued() {
+    return this.queue.length;
+  }
+
+  /**
+   * Replay the parked mutations, oldest first, and hand back what the host made
+   * of them.
+   *
+   * A host *verdict* (an `rpc-err`, tagged `fromHost`) is final and the entry is
+   * dropped, so a release the host keeps refusing is not retried forever. Any
+   * other rejection — dead socket, timeout, a send that throws — is the tunnel
+   * failing rather than an answer, so those entries go back on the queue for the
+   * next reconnect rather than being silently lost.
+   */
+  flush() {
+    // Concurrent callers share one pass: a second flush would race the first for
+    // the same entries and could replay one twice. This is checked before the
+    // empty-queue guard because #flush drains the queue up front — by the time a
+    // second caller arrives the queue is already empty, and returning a fresh
+    // resolved promise there would report "done" while the replay is still in
+    // flight, which is exactly what settled() must not do.
+    if (this.flushing) return this.flushing;
+    if (!this.queue.length) return Promise.resolve({ replayed: [], rejected: [], requeued: [] });
+    this.flushing = this.#flush().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
+  }
+
+  /**
+   * Resolves once any in-flight replay has finished.
+   *
+   * Anything that claims a lock must wait on this. A queued release and a fresh
+   * claim for the same file both travel this socket, and `release` on the host
+   * only checks `sameOwner` — so if a re-claim lands first, the replayed release
+   * that follows deletes the lock the agent has just been granted and still
+   * believes it holds.
+   */
+  settled() {
+    return this.flushing || Promise.resolve(null);
+  }
+
+  async #flush() {
+    const batch = this.queue.slice().sort((a, b) => a.seq - b.seq);
+    this.queue = [];
+    const replayed = [];
+    const rejected = [];
+    const requeued = [];
+    for (const item of batch) {
+      if (!this.open) {
+        this.#requeue(item);
+        requeued.push({ ...item, error: "control_offline" });
+        continue;
+      }
+      try {
+        const result = await this.rpc(item.op, item.body);
+        replayed.push({ ...item, result });
+      } catch (err) {
+        const error = err?.message || String(err);
+        if (err?.fromHost) rejected.push({ ...item, error });
+        else {
+          this.#requeue(item);
+          requeued.push({ ...item, error });
+        }
+      }
+    }
+    const outcome = { replayed, rejected, requeued };
+    if (this.onReplay) {
+      try {
+        this.onReplay(outcome);
+      } catch {
+        /* a reporting failure must not break reconnection */
+      }
+    }
+    return outcome;
+  }
+
+  // Keeps the original seq, so a re-queued entry still replays ahead of
+  // mutations issued after it.
+  #requeue(item) {
+    if (this.queue.some((q) => q.key === item.key)) return;
+    this.queue.push(item);
+    while (this.queue.length > MAX_QUEUED) this.queue.shift();
+  }
+
+  send(obj) {
+    if (!this.open) return false;
+    try {
+      this.socket.send(JSON.stringify(obj));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// release-all is per agent, not per file, so it collapses to one entry per
+// agent+workspace; a per-file release collapses to one entry per file.
+function dedupeKey(op, body = {}) {
+  const ws = String(body.workspaceId || "");
+  if (op === "release-all") return `release-all::${ws}::${String(body.agentId || "")}`;
+  return `${op}::${ws}::${String(body.file || "")}::${String(body.agentId || "")}`;
+}
+
+function sendSocket(socket, obj) {
+  if (!socket || socket.readyState !== 1) return false;
+  try {
+    socket.send(typeof obj === "string" ? obj : JSON.stringify(obj));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function broadcast(wss, obj) {
+  if (!wss) return;
+  const msg = JSON.stringify(obj);
+  for (const client of wss.clients) sendSocket(client, msg);
+}
+
+module.exports = { RoomControl, sendSocket, broadcast };