relaybrain 0.0.0-stage → 0.2.1

package/backend/lib/falkor/intents.js

@@ -0,0 +1,32 @@
+// In-process "what is this session trying to do" cache. Read on the lock deny path,
+// so it must stay a plain Map lookup: no I/O, no database.
+const bySession = new Map();
+const byAgentLabel = new Map();
+const MAX = 2000;
+
+function remember(info) {
+  if (!info?.sessionKey || !info.intent) return;
+  const prev = bySession.get(info.sessionKey);
+  if (prev && (prev.intentAt || 0) > (info.intentAt || 0)) return;
+  bySession.delete(info.sessionKey);
+  bySession.set(info.sessionKey, info);
+  if (bySession.size > MAX) bySession.delete(bySession.keys().next().value);
+  const latest = byAgentLabel.get(info.label);
+  if (!latest || (latest.intentAt || 0) <= (info.intentAt || 0)) byAgentLabel.set(info.label, info);
+}
+
+function forSession(sessionKey) {
+  return bySession.get(sessionKey) || null;
+}
+
+/** Fallback when a lock's session is unknown: the agent's most recent intent, low confidence. */
+function latestForLabel(label) {
+  return byAgentLabel.get(label) || null;
+}
+
+function clear() {
+  bySession.clear();
+  byAgentLabel.clear();
+}
+
+module.exports = { remember, forSession, latestForLabel, clear };

package/backend/lib/falkor/keys.js

@@ -0,0 +1,102 @@
+const crypto = require("crypto");
+
+// Fallback ids relay invents when an agent reports no session (unifyEvent → "session", lockAgentIdFor → "local").
+const SESSION_SENTINELS = new Set(["", "session", "local", "null", "undefined"]);
+const CONTENTION_BUCKET_MS = 10_000;
+
+function hash(parts, len = 20) {
+  return crypto.createHash("sha1").update(parts.map((p) => String(p ?? "")).join("␟")).digest("hex").slice(0, len);
+}
+
+function loginKey(login) {
+  const v = String(login || "").trim().toLowerCase();
+  return v || "local";
+}
+
+function agentKey(login, label) {
+  return `${loginKey(login)}::${String(label || "agent").trim()}`;
+}
+
+function isRealSession(sessionId) {
+  return !SESSION_SENTINELS.has(String(sessionId ?? "").trim().toLowerCase());
+}
+
+function sessionKey(label, sessionId) {
+  if (!isRealSession(sessionId)) return null;
+  return `${String(label || "agent").trim()}::${String(sessionId).trim()}`;
+}
+
+function day(ts) {
+  const d = new Date(Number(ts) || 0);
+  return Number.isNaN(d.getTime()) ? "unknown" : d.toISOString().slice(0, 10);
+}
+
+/** Groups session-less activity per agent, person and day so it never merges across people. */
+function bucketSessionKey(label, login, ts) {
+  return `${String(label || "agent").trim()}::nosession::${loginKey(login)}::${day(ts)}`;
+}
+
+/** `label:host:session` (or `label:host:session@login` from a remote room member). */
+function parseLockAgentId(agentId) {
+  const parts = String(agentId || "").split(":");
+  const label = parts[0] || "";
+  const host = parts[1] || "";
+  const rawSession = parts.slice(2).join(":");
+  const atIdx = rawSession.lastIndexOf("@");
+  const session = atIdx > 0 ? rawSession.slice(0, atIdx) : rawSession;
+  return { label, host, session, sessionKnown: isRealSession(session) };
+}
+
+function fileKey(p) {
+  if (p == null) return null;
+  let s = String(p).trim().replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+  if (!s || /^[a-zA-Z]:\//.test(s) || /^[a-zA-Z]:$/.test(s) || s.startsWith("/")) return null;
+  s = s.replace(/^(\.\/)+/, "").replace(/\/$/, "");
+  if (!s || s === "." || s === ".." || s.startsWith("../") || s.includes("/../")) return null;
+  return s.toLowerCase();
+}
+
+function displayPath(p) {
+  return String(p || "").trim().replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+}
+
+/** Content-addressed so a local turn and the same turn clipped in a peer snapshot converge. */
+function turnKey({ login, label, sessionId, ts, role, kind, text }) {
+  return `t_${hash([loginKey(login), label, sessionId, ts, role, kind, String(text || "").slice(0, 200)])}`;
+}
+
+function contentionKey({ kind, fileKey: fk, wanter, holder, ts }) {
+  const bucket = Math.floor((Number(ts) || 0) / CONTENTION_BUCKET_MS);
+  return `c_${hash([kind, fk, wanter, holder, bucket])}`;
+}
+
+function overlapKey(fk, editA, editB) {
+  const [a, b] = [String(editA), String(editB)].sort();
+  return `o_${hash([fk, a, b])}`;
+}
+
+/**
+ * Parsers record whether each event's time was in the transcript (event.tsSynthetic).
+ * History stored before they did falls back to the old tell: `mtime + index*1000` is fractional.
+ */
+function tsSynthetic(ts, flag) {
+  if (typeof flag === "boolean") return flag;
+  return !Number.isInteger(Number(ts));
+}
+
+module.exports = {
+  hash,
+  loginKey,
+  agentKey,
+  isRealSession,
+  sessionKey,
+  bucketSessionKey,
+  parseLockAgentId,
+  fileKey,
+  displayPath,
+  turnKey,
+  contentionKey,
+  overlapKey,
+  tsSynthetic,
+  CONTENTION_BUCKET_MS,
+};

package/backend/lib/falkor/migrations.js

@@ -0,0 +1,56 @@
+// Versioned in-place graph migrations (#18): run at schema.ensure() and recorded on
+// Meta.migrations so schema/ingest version bumps preserve history older than memory.json's cap
+// instead of requiring a destructive drop-and-rebuild.
+
+const MIGRATIONS = [
+  {
+    id: "001_meta_versions_v6",
+    description: "Ensure Session.stub defaults and stamp Meta to schemaVersion=1, ingestVersion=6 in place",
+    async up(client, projectId, { schemaVersion, ingestVersion }) {
+      await client.write(
+        projectId,
+        `MATCH (s:Session) WHERE s.stub IS NULL SET s.stub = false RETURN count(s) AS n`
+      );
+      await client.write(
+        projectId,
+        `MATCH (m:Meta {key: 'meta'})
+         SET m.schemaVersion = $schema, m.ingestVersion = $ingest, m.migratedAt = $now
+         RETURN 1 AS ok`,
+        { schema: schemaVersion, ingest: ingestVersion, now: Date.now() }
+      );
+    },
+  },
+];
+
+async function runMigrations(client, projectId, { schemaVersion, ingestVersion }) {
+  const rows = await client.read(
+    projectId,
+    "MATCH (m:Meta {key: 'meta'}) RETURN coalesce(m.migrations, []) AS migrations, m.schemaVersion AS s, m.ingestVersion AS i"
+  );
+  const meta = rows[0] || {};
+  const applied = new Set(Array.isArray(meta.migrations) ? meta.migrations : []);
+  const ran = [];
+
+  for (const mig of MIGRATIONS) {
+    if (applied.has(mig.id)) continue;
+    await mig.up(client, projectId, { schemaVersion, ingestVersion });
+    applied.add(mig.id);
+    ran.push(mig.id);
+  }
+
+  // If the graph had an older schemaVersion or ingestVersion, migrate it forward in place
+  // so existing Turn/Edit/Session/Decision history is preserved without dropping the graph.
+  if (ran.length || meta.s !== schemaVersion || meta.i !== ingestVersion) {
+    await client.write(
+      projectId,
+      `MATCH (m:Meta {key: 'meta'})
+       SET m.migrations = $migrations, m.schemaVersion = $schema, m.ingestVersion = $ingest
+       RETURN 1 AS ok`,
+      { migrations: [...applied], schema: schemaVersion, ingest: ingestVersion }
+    );
+  }
+
+  return { applied: [...applied], ran };
+}
+
+module.exports = { MIGRATIONS, runMigrations };

package/backend/lib/falkor/project.js

@@ -0,0 +1,307 @@
+// Pure: memory.history → row batches for write.js. No I/O, no database.
+const path = require("path");
+const { relativeEditPath } = require("../transcripts/sync");
+const keys = require("./keys");
+const { storedText, clip, redact } = require("./redact");
+
+const TURN_TEXT_MAX = 2000;
+const DIFF_HEAD_MAX = 1000;
+const INTENT_MAX = 280;
+const TITLE_MAX = 120;
+const STALE_PROMPT_MS = 30 * 60 * 1000;
+const DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
+// "continue"-style nudges say nothing about intent; the request they continue does.
+const FILLER = /^(please\s+)?(continue|go(\s+on|\s+ahead)?|yes|yep|yeah|y|ok(ay)?|sure|proceed|do\s+it|keep\s+going|carry\s+on|next|try\s+again|retry|go\s+for\s+it|sounds\s+good|lgtm|done\??)[\s.!]*$/i;
+
+const GREETING = /^(hi+|hello|hey+|yo|sup|wassup|hola|thanks|thank\s+you|thx|ty)(\s+(there|wassup|sup|man|bro|all|claude|cursor|again|so\s+much))*[\s.!?,]*$/i;
+
+function isFiller(text) {
+  const s = String(text || "").trim();
+  return s.length <= 30 && (FILLER.test(s) || GREETING.test(s));
+}
+
+function diffStats(diff) {
+  let added = 0;
+  let removed = 0;
+  for (const line of String(diff || "").split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
+  }
+  return { added, removed };
+}
+
+function toolOf(text) {
+  const word = String(text || "").trim().split(/\s+/)[0] || "";
+  return word.slice(0, 40) || null;
+}
+
+function sessionOf(event) {
+  const real = keys.sessionKey(event.agent, event.sessionId);
+  if (real) return { key: real, bucket: false };
+  return { key: keys.bucketSessionKey(event.agent, event.ownerLogin, event.ts), bucket: true };
+}
+
+function oneLine(text, max) {
+  return clip(redact(String(text || "").replace(/\s+/g, " ").trim()), max);
+}
+
+/**
+ * @param {object[]} history unified events (sync.js unifyEvent), ordered by compareEvents
+ * @param {object} opts
+ * @param {string} opts.workspacePath used to make edit paths repo-relative
+ * @param {(id: string) => boolean} [opts.isNew] events not yet ingested; default: all
+ * @param {boolean} [opts.storeText]
+ */
+function projectHistory(history, opts = {}) {
+  const { workspacePath, isNew = () => true, storeText = true } = opts;
+  const groups = new Map();
+  let dropped = 0;
+
+  for (const event of history || []) {
+    if (!event || !event.id || !event.agent) {
+      dropped += 1;
+      continue;
+    }
+    const { key, bucket } = sessionOf(event);
+    if (!groups.has(key)) groups.set(key, { key, bucket, events: [] });
+    groups.get(key).events.push(event);
+  }
+
+  const sessions = [];
+  const turns = [];
+  const edits = [];
+  const intents = new Map();
+
+  for (const group of groups.values()) {
+    const first = group.events[0];
+    const login = keys.loginKey(first.ownerLogin);
+    const agentKey = keys.agentKey(first.ownerLogin, first.agent);
+    let lastUser = null;
+    let lastMeaningful = null;
+    let lastAssistant = null;
+    let firstUser = null;
+    let thinking = 0;
+    let fresh = false;
+    let seq = 0;
+    const recent = new Map();
+    let startedAt = Infinity;
+    let lastAt = 0;
+
+    for (const event of group.events) {
+      const ts = Number(event.ts) || 0;
+      startedAt = Math.min(startedAt, ts);
+      lastAt = Math.max(lastAt, ts);
+      const isFresh = isNew(event.id);
+      if (isFresh) fresh = true;
+
+      if (event.kind === "thinking") {
+        thinking += 1;
+        continue;
+      }
+
+      if (event.kind === "message" && (event.role === "user" || event.role === "assistant")) {
+        if (!String(event.text || "").trim()) continue;
+        // One conversation can be recorded twice (Copilot writes chatSessions and a transcript
+        // for the same session); a repeat of the same message moments later is the same turn.
+        const dupKey = `${event.role}|${String(event.text).replace(/\s+/g, " ").trim().slice(0, 200)}`;
+        const prevTs = recent.get(dupKey);
+        if (prevTs != null && Math.abs(ts - prevTs) <= DUPLICATE_WINDOW_MS) continue;
+        recent.set(dupKey, ts);
+        const turn = {
+          sessionKey: group.key,
+          turnKey: keys.turnKey({
+            login: event.ownerLogin,
+            label: event.agent,
+            sessionId: event.sessionId,
+            ts: event.ts,
+            role: event.role,
+            kind: event.kind,
+            text: event.text,
+          }),
+          ts,
+          role: event.role,
+          kind: "message",
+          text: storedText(event.text, TURN_TEXT_MAX, storeText),
+          seq: seq++,
+          tsSynthetic: keys.tsSynthetic(event.ts, event.tsSynthetic),
+        };
+        if (event.role === "user") {
+          lastUser = { ...turn, raw: event.text };
+          if (!isFiller(event.text)) {
+            lastMeaningful = lastUser;
+            if (!firstUser) firstUser = lastUser;
+          }
+        } else {
+          lastAssistant = turn;
+        }
+        if (isFresh) turns.push(turn);
+        continue;
+      }
+
+      if (event.kind === "code_edit") {
+        const hasPath = Boolean(event.path || event.file);
+        const rel = hasPath ? relativeEditPath(event, workspacePath) : null;
+        // Matches sync.js buildViews: an edit outside the workspace is not this project's activity.
+        if (hasPath && !rel) continue;
+        if (!isFresh) continue;
+        const fk = keys.fileKey(rel);
+        const stats = diffStats(event.diff);
+        const prompt = lastMeaningful || lastUser;
+        const promptGap = prompt ? ts - prompt.ts : null;
+        edits.push({
+          sessionKey: group.key,
+          agentKey,
+          login,
+          loginRaw: String(first.ownerLogin || "local"),
+          label: first.agent,
+          editKey: `e_${event.id}`,
+          fileKey: fk,
+          path: fk ? keys.displayPath(rel) : null,
+          ext: fk ? path.posix.extname(fk).slice(1) || null : null,
+          orphan: !fk,
+          ts,
+          tool: toolOf(event.text),
+          diffHead: storeText ? clip(redact(event.diff || ""), DIFF_HEAD_MAX) : null,
+          added: stats.added,
+          removed: stats.removed,
+          tsSynthetic: keys.tsSynthetic(event.ts, event.tsSynthetic),
+          promptKey: prompt ? prompt.turnKey : null,
+          promptGap,
+          promptStale: promptGap != null && promptGap > STALE_PROMPT_MS,
+          promptConfidence: group.bucket ? "low" : "high",
+          promptVia: lastUser && prompt !== lastUser ? oneLine(lastUser.raw, 40) : null,
+          explainKey: lastAssistant ? lastAssistant.turnKey : null,
+          explainGap: lastAssistant ? ts - lastAssistant.ts : null,
+        });
+      }
+    }
+
+    const intentSource = lastMeaningful || lastUser;
+    const intentText = intentSource ? oneLine(intentSource.raw, INTENT_MAX) : null;
+    const info = {
+      sessionKey: group.key,
+      agentKey,
+      label: first.agent,
+      login,
+      loginRaw: String(first.ownerLogin || "local"),
+      sessionId: group.bucket ? null : String(first.sessionId),
+      bucket: group.bucket,
+      startedAt: Number.isFinite(startedAt) ? startedAt : 0,
+      lastAt,
+      thinkingCount: thinking,
+      title: storeText && firstUser ? oneLine(firstUser.raw, TITLE_MAX) : null,
+      intent: storeText ? intentText : null,
+      intentAt: intentSource ? intentSource.ts : null,
+    };
+    // The cache only lives in this process (deny-reason hints), so it keeps text even when the graph doesn't.
+    intents.set(group.key, { ...info, intent: intentText });
+    if (fresh) sessions.push(info);
+  }
+
+  return { sessions, turns, edits, intents, dropped };
+}
+
+const AGENT_LABELS = new Set(["Claude Code", "Cursor", "Codex", "Copilot", "Antigravity"]);
+// Watcher patches from bulk tree copies are not anyone's edit.
+const BULK_PATCH_AGENTS = new Set(["seed", "snapshot"]);
+const UNATTRIBUTED = "Editor";
+// Files `relay init/clone/add` writes itself; an unattributed change to them is relay, not a person.
+const RELAY_MANAGED = /^(\.claude\/|\.cursor\/|\.codex\/|\.agents\/|\.relay\/|\.github\/hooks\/|\.github\/mcp\.json$|\.github\/copilot-instructions\.md$|\.cursorrules$|claude\.md$|agents\.md$)/;
+
+function patchRow(patch, { storeText = true } = {}) {
+  if (!patch?.id || !patch.file || BULK_PATCH_AGENTS.has(patch.agent)) return null;
+  const fk = keys.fileKey(patch.file);
+  if (!fk) return null;
+  // patch.agent is just "fs.watch"; the lock holder that triggered the flush is the real author.
+  const origin = keys.parseLockAgentId(patch.originAgentId);
+  const labelFromAgent = AGENT_LABELS.has(patch.agent) ? patch.agent : null;
+  const label = AGENT_LABELS.has(origin.label) ? origin.label : labelFromAgent || UNATTRIBUTED;
+  if (label === UNATTRIBUTED && RELAY_MANAGED.test(fk)) return null;
+  const sk = label === origin.label && origin.sessionKnown ? keys.sessionKey(label, origin.session) : null;
+  const diff = String(patch.diff || "");
+  const stats = diffStats(diff);
+  return {
+    sessionKey: sk,
+    agentKey: keys.agentKey(patch.ownerLogin, label),
+    login: keys.loginKey(patch.ownerLogin),
+    loginRaw: String(patch.ownerLogin || "local"),
+    label,
+    editKey: String(patch.id),
+    source: "patch",
+    fileKey: fk,
+    path: keys.displayPath(patch.file),
+    ext: path.posix.extname(fk).slice(1) || null,
+    orphan: false,
+    ts: Number(patch.ts) || Date.now(),
+    tool: "patch",
+    diffHead: storeText && !diff.startsWith("sha256:") ? clip(redact(diff), DIFF_HEAD_MAX) : null,
+    added: stats.added,
+    removed: stats.removed,
+    tsSynthetic: false,
+    lamport: Number.isFinite(Number(patch.lamport)) ? Number(patch.lamport) : null,
+    sha256: patch.sha256 || null,
+    promptKey: null,
+    explainKey: null,
+  };
+}
+
+function projectPatches(patches, opts = {}) {
+  return { sessions: [], turns: [], edits: patches.map((p) => patchRow(p, opts)).filter(Boolean), intents: new Map(), dropped: 0 };
+}
+
+/**
+ * A room peer's snapshot (roomSync.sanitize shape) → the same rows as local history.
+ * Peers ship threads + edit rows but no raw history, and their edit rows carry no
+ * session, so each edit is re-attached to its thread's code_edit message.
+ */
+function projectPeer(snapshot, { login, trustRowOwners = false, isNew = () => true, storeText = true } = {}) {
+  const events = [];
+  const edits = [...(snapshot?.edits || [])];
+  const used = new Set();
+  const ownerOf = (row) => (trustRowOwners ? row?.ownerLogin || login : login);
+
+  for (const thread of snapshot?.chats || []) {
+    if (!thread?.agent) continue;
+    const owner = ownerOf(thread);
+    for (const m of thread.messages || []) {
+      if (!m) continue;
+      const base = { agent: thread.agent, ownerLogin: owner, sessionId: thread.sessionId, ts: Number(m.ts) || 0 };
+      if (m.kind === "code_edit") {
+        const base2 = path.posix.basename(String(m.file || "").replace(/\\/g, "/")).toLowerCase();
+        const idx = edits.findIndex(
+          (e, i) =>
+            !used.has(i) &&
+            e.agent === thread.agent &&
+            Number(e.ts) === base.ts &&
+            path.posix.basename(String(e.file || "").replace(/\\/g, "/")).toLowerCase() === base2
+        );
+        if (idx < 0) continue;
+        used.add(idx);
+        const edit = edits[idx];
+        events.push({ ...base, id: String(edit.id).replace(/^e_/, ""), role: "tool", kind: "code_edit", text: m.text, file: m.file, path: edit.file, diff: edit.diff });
+        continue;
+      }
+      if (m.role !== "user" && m.role !== "assistant") continue;
+      const tk = keys.turnKey({ login: owner, label: thread.agent, sessionId: thread.sessionId, ts: m.ts, role: m.role, kind: "message", text: m.text });
+      events.push({ ...base, id: `peer_${tk}`, role: m.role, kind: "message", text: m.text });
+    }
+  }
+  events.sort((a, b) => a.ts - b.ts);
+  const projection = projectHistory(events, { workspacePath: null, isNew, storeText });
+
+  // Edits whose thread message was trimmed away still count; they just lose their session.
+  for (let i = 0; i < edits.length; i++) {
+    if (used.has(i)) continue;
+    const e = edits[i];
+    const owner = ownerOf(e);
+    const row = String(e.id || "").startsWith("patch_")
+      ? patchRow({ ...e, ownerLogin: owner }, { storeText })
+      : patchRow({ ...e, id: e.id, ownerLogin: owner, originAgentId: null }, { storeText });
+    if (!row || !isNew(row.editKey)) continue;
+    if (!String(e.id || "").startsWith("patch_")) row.source = "transcript";
+    projection.edits.push(row);
+  }
+  return projection;
+}
+
+module.exports = { projectHistory, projectPatches, projectPeer, patchRow, diffStats, TURN_TEXT_MAX, INTENT_MAX, UNATTRIBUTED };