relaybrain 0.0.0-stage → 0.2.0

package/backend/lib/falkor/routes.js

@@ -0,0 +1,81 @@
+const { runNamed, names } = require("./query");
+const { projectIdFor } = require("./coord");
+const { loadRoom } = require("../room");
+const { loadRegistry, loadSession } = require("../store");
+
+let api = null;
+
+function argsFrom(req) {
+  const q = { ...(req.query || {}), ...(req.body || {}) };
+  if (typeof q.paths === "string") q.paths = q.paths.split(",").filter(Boolean);
+  return q;
+}
+
+function resolveProjectId(args) {
+  if (args.projectId) return String(args.projectId);
+  const byPath = projectIdFor(args.workspace);
+  if (byPath) return byPath;
+  const reg = loadRegistry();
+  const session = loadSession();
+  return reg.projects.find((p) => p.id === session.projectId)?.id || reg.projects[0]?.id || null;
+}
+
+function projectPath(projectId) {
+  return loadRegistry().projects.find((p) => p.id === projectId)?.path || null;
+}
+
+/** A guest's graph lives on the host; ask it through the room's existing read-only MCP endpoint. */
+async function askHost(room, name, args) {
+  const body = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name: "relay_graph_query", arguments: { ...args, query: name, projectId: undefined, workspace: undefined } },
+  };
+  const res = await api.state.deps.fetchHost(room.url, "/mcp", { method: "POST", body: JSON.stringify(body), timeoutMs: 4000 });
+  const json = await res.json();
+  if (json.error) throw Object.assign(new Error(json.error.message || "host query failed"), { status: 502 });
+  const text = json.result?.content?.[0]?.text;
+  return { ...JSON.parse(text || "{}"), source: "host" };
+}
+
+/** Local graph first unless this machine is a room guest, in which case the host's graph is the room brain. */
+async function query(name, args) {
+  const projectId = resolveProjectId(args);
+  const room = loadRoom(args.workspace || projectPath(projectId) || undefined);
+  if (room?.role === "guest" && room.url && api.state.deps.fetchHost && !args.local) {
+    try {
+      return await askHost(room, name, args);
+    } catch (err) {
+      if (!api.state.started) {
+        throw Object.assign(new Error(`room host unreachable (${err.message || err}) and this machine has no memory graph of its own`), {
+          status: 503,
+        });
+      }
+      /* tunnel down: fall back to whatever this machine's own graph knows */
+    }
+  }
+  if (!api.state.started) return { ok: false, reason: "falkor_disabled", hint: "set RELAY_FALKOR_URL and restart relay serve" };
+  if (!api.client.available()) return { ok: false, reason: "falkor_unavailable", breaker: api.client.status() };
+  await api.ensureProject(projectId);
+  return { ok: true, projectId, source: "local", ...(await runNamed(api.client, projectId, name, args)) };
+}
+
+function register(app, falkor) {
+  api = { ...falkor, get client() {
+    return falkor.state.client;
+  } };
+  const guard = falkor.state.deps.requireRoomMember || ((_req, _res, next) => next());
+  const handler = async (req, res) => {
+    try {
+      res.json(await query(req.params.name, argsFrom(req)));
+    } catch (err) {
+      res.status(err.status || 500).json({ ok: false, reason: String(err.message || err), queries: names() });
+    }
+  };
+  app.get("/api/graph/queries", (_req, res) => res.json({ queries: names() }));
+  app.get("/api/graph/query/:name", guard, handler);
+  app.post("/api/graph/query/:name", guard, handler);
+}
+
+module.exports = { register, query };

package/backend/lib/falkor/schema.js

@@ -0,0 +1,108 @@
+const { ConstraintType, EntityType } = require("falkordb");
+
+const SCHEMA_VERSION = 1;
+// Bump when projector/key logic changes in a way that would re-key existing nodes.
+const INGEST_VERSION = 6;
+
+const KEYED_LABELS = ["Person", "Agent", "Session", "Turn", "Edit", "File", "Decision", "Task", "Contention", "Overlap", "Meta"];
+
+const RANGE_INDEXES = [
+  ...KEYED_LABELS.map((label) => [label, "key"]),
+  ["Edit", "ts"],
+  ["Turn", "ts"],
+  ["Contention", "ts"],
+  ["Session", "lastAt"],
+  ["Session", "label"],
+];
+
+const FULLTEXT_INDEXES = [
+  ["Turn", "text"],
+  ["Decision", "content"],
+  ["Task", "description"],
+];
+
+const ensured = new Map();
+
+function has(existing, label, prop, type) {
+  return existing.some((row) => row.label === label && (row.types?.[prop] || []).includes(type));
+}
+
+async function bootstrap(client, projectId) {
+  // Writing Meta first creates the graph; read-only calls on a missing graph error.
+  const meta = await client.write(
+    projectId,
+    `MERGE (m:Meta {key: 'meta'})
+     ON CREATE SET m.schemaVersion = $schema, m.ingestVersion = $ingest, m.createdAt = $now
+     RETURN m.schemaVersion AS schemaVersion, m.ingestVersion AS ingestVersion, m.createdAt AS createdAt,
+            m.lastIngestAt AS lastIngestAt`,
+    { schema: SCHEMA_VERSION, ingest: INGEST_VERSION, now: Date.now() }
+  );
+
+  const existing = await client.read(projectId, "CALL db.indexes() YIELD label, properties, types RETURN label, properties, types");
+  for (const [label, prop] of RANGE_INDEXES) {
+    if (has(existing, label, prop, "RANGE")) continue;
+    await client.write(projectId, `CREATE INDEX FOR (n:${label}) ON (n.${prop})`);
+  }
+  for (const [label, prop] of FULLTEXT_INDEXES) {
+    if (has(existing, label, prop, "FULLTEXT")) continue;
+    await client.write(projectId, `CREATE FULLTEXT INDEX FOR (n:${label}) ON (n.${prop})`);
+  }
+
+  // Unique constraints are a backstop (MERGE already guarantees one node per key). Awaited
+  // on purpose: CONSTRAINT CREATE returns PENDING at once, and a fire-and-forget call that
+  // lands after the graph was deleted silently recreates it.
+  try {
+    const graph = await client.graph(projectId);
+    const current = await client.read(projectId, "CALL db.constraints() YIELD label, properties RETURN label, properties");
+    for (const label of KEYED_LABELS) {
+      if (current.some((c) => c.label === label && (c.properties || []).includes("key"))) continue;
+      await graph.constraintCreate(ConstraintType.UNIQUE, EntityType.NODE, label, "key").catch(() => undefined);
+    }
+  } catch {
+    /* constraints are optional */
+  }
+
+  const { runMigrations } = require("./migrations");
+  let migResult = { applied: [], ran: [] };
+  try {
+    migResult = await runMigrations(client, projectId, {
+      schemaVersion: SCHEMA_VERSION,
+      ingestVersion: INGEST_VERSION,
+    });
+  } catch {
+    /* keep existing meta row if migrations cannot run */
+  }
+
+  const refreshed = await client.read(
+    projectId,
+    "MATCH (m:Meta {key: 'meta'}) RETURN m.schemaVersion AS schemaVersion, m.ingestVersion AS ingestVersion, m.createdAt AS createdAt, m.lastIngestAt AS lastIngestAt"
+  );
+  const row = refreshed[0] || meta[0] || {};
+  return {
+    schemaVersion: row.schemaVersion,
+    ingestVersion: row.ingestVersion,
+    createdAt: row.createdAt,
+    lastIngestAt: row.lastIngestAt || 0,
+    migrations: migResult.applied,
+    migrated: migResult.ran,
+    needsRebuild: row.schemaVersion !== SCHEMA_VERSION || row.ingestVersion !== INGEST_VERSION,
+  };
+}
+
+/** Idempotent, once per process per project; a failed attempt is retried on the next call. */
+function ensure(client, projectId) {
+  if (!ensured.has(projectId)) {
+    const pending = bootstrap(client, projectId).catch((err) => {
+      ensured.delete(projectId);
+      throw err;
+    });
+    ensured.set(projectId, pending);
+  }
+  return ensured.get(projectId);
+}
+
+function forget(projectId) {
+  ensured.delete(projectId);
+}
+
+module.exports = { ensure, forget, bootstrap, SCHEMA_VERSION, INGEST_VERSION, KEYED_LABELS };

package/backend/lib/falkor/write.js

@@ -0,0 +1,281 @@
+// Parameterized batch writers. Labels/relationship types are constants here; every
+// value travels as a parameter. Counters are only bumped for nodes this batch created
+// (batch token), so replaying any batch is a no-op.
+const crypto = require("crypto");
+
+const CHUNK = 400;
+const TRANSCRIPT_EDIT_AGENTS = new Set(["Claude Code", "Cursor", "Codex", "Antigravity", "Copilot"]);
+
+function token() {
+  return crypto.randomBytes(8).toString("hex");
+}
+
+function chunks(rows, size = CHUNK) {
+  const out = [];
+  for (let i = 0; i < rows.length; i += size) out.push(rows.slice(i, i + size));
+  return out;
+}
+
+function dedupe(rows, key) {
+  const seen = new Map();
+  for (const row of rows) if (row && row[key] != null) seen.set(row[key], row);
+  return [...seen.values()];
+}
+
+async function each(client, projectId, query, rows, extra = {}) {
+  const results = [];
+  for (const part of chunks(rows)) {
+    const data = await client.write(projectId, query, { rows: part, ...extra });
+    results.push(...data);
+  }
+  return results;
+}
+
+const SESSIONS = `
+UNWIND $rows AS r
+MERGE (p:Person {key: r.login})
+  ON CREATE SET p.login = r.loginRaw, p.firstSeen = r.startedAt
+SET p.lastSeen = CASE WHEN p.lastSeen IS NULL OR r.lastAt > p.lastSeen THEN r.lastAt ELSE p.lastSeen END
+MERGE (a:Agent {key: r.agentKey})
+  ON CREATE SET a.label = r.label, a.login = r.login, a.firstSeen = r.startedAt
+SET a.lastSeen = CASE WHEN a.lastSeen IS NULL OR r.lastAt > a.lastSeen THEN r.lastAt ELSE a.lastSeen END
+MERGE (p)-[:RUNS]->(a)
+MERGE (s:Session {key: r.sessionKey})
+  ON CREATE SET s.sessionId = r.sessionId, s.label = r.label, s.bucket = r.bucket,
+                s.turnCount = 0, s.editCount = 0, s.startedAt = r.startedAt
+SET s.login = r.login, s.stub = false,
+    s.startedAt = CASE WHEN s.startedAt IS NULL OR r.startedAt < s.startedAt THEN r.startedAt ELSE s.startedAt END,
+    s.lastAt = CASE WHEN s.lastAt IS NULL OR r.lastAt > s.lastAt THEN r.lastAt ELSE s.lastAt END,
+    s.thinkingCount = CASE WHEN s.thinkingCount IS NULL OR r.thinkingCount > s.thinkingCount THEN r.thinkingCount ELSE s.thinkingCount END,
+    s.title = coalesce(s.title, r.title)
+FOREACH (_ IN CASE WHEN r.intentAt IS NOT NULL AND (s.intentAt IS NULL OR r.intentAt >= s.intentAt) THEN [1] ELSE [] END |
+  SET s.intent = r.intent, s.intentAt = r.intentAt)
+MERGE (a)-[:RAN]->(s)
+RETURN count(s) AS n`;
+
+const TURNS = `
+UNWIND $rows AS r
+MATCH (s:Session {key: r.sessionKey})
+MERGE (t:Turn {key: r.turnKey})
+  ON CREATE SET t.ts = r.ts, t.role = r.role, t.kind = r.kind, t.text = r.text,
+                t.seq = r.seq, t.tsSynthetic = r.tsSynthetic, t._b = $batch
+MERGE (s)-[:HAS_TURN]->(t)
+RETURN r.sessionKey AS sessionKey, coalesce(t._b = $batch, false) AS created`;
+
+const EDITS = `
+UNWIND $rows AS r
+MERGE (p:Person {key: r.login})
+  ON CREATE SET p.login = r.loginRaw, p.firstSeen = r.ts
+MERGE (a:Agent {key: r.agentKey})
+  ON CREATE SET a.label = r.label, a.login = r.login, a.firstSeen = r.ts
+MERGE (p)-[:RUNS]->(a)
+MERGE (e:Edit {key: r.editKey})
+  ON CREATE SET e.source = r.source, e.ts = r.ts, e.tool = r.tool, e.diffHead = r.diffHead,
+                e.added = r.added, e.removed = r.removed, e.tsSynthetic = r.tsSynthetic,
+                e.orphan = r.orphan, e.lamport = r.lamport, e.sha256 = r.sha256, e._b = $batch
+MERGE (e)-[:BY]->(a)
+WITH r, e
+OPTIONAL MATCH (s:Session {key: r.sessionKey})
+FOREACH (_ IN CASE WHEN s IS NULL THEN [] ELSE [1] END | MERGE (s)-[:MADE]->(e))
+RETURN r.editKey AS editKey, coalesce(e._b = $batch, false) AS created`;
+
+// One real change often arrives twice: transcript code_edit (intent) and watcher patch (disk truth).
+const SAME_CHANGE = `
+UNWIND $rows AS r
+MATCH (p:Edit {source: 'patch'})-[:MODIFIED]->(f:File {key: r.fileKey})
+MATCH (p)-[:BY]->(a:Agent {key: r.agentKey})
+WHERE NOT (p)-[:SAME_CHANGE]->()
+MATCH (t:Edit {source: 'transcript'})-[:MODIFIED]->(f)
+MATCH (t)-[:BY]->(a)
+WHERE abs(t.ts - p.ts) <= $windowMs
+RETURN p.key AS patchKey, t.key AS editKey, abs(t.ts - p.ts) AS gap,
+       p.diffHead AS patchDiff, t.diffHead AS editDiff, coalesce(t.tsSynthetic, false) AS synthetic`;
+
+const LINK_SAME_CHANGE = `
+UNWIND $rows AS r
+MATCH (p:Edit {key: r.patchKey})
+MATCH (t:Edit {key: r.editKey})
+MERGE (p)-[s:SAME_CHANGE]->(t)
+SET s.gapMs = r.gap, s.method = r.method
+RETURN count(s) AS n`;
+
+const SAME_CHANGE_EXACT_MS = 15_000;
+const SAME_CHANGE_CONTENT_MS = 10 * 60 * 1000;
+
+function addedLines(diff) {
+  const out = new Set();
+  for (const line of String(diff || "").split("\n")) {
+    if (!line.startsWith("+") || line.startsWith("+++")) continue;
+    const s = line.slice(1).trim();
+    if (s.length >= 8) out.add(s);
+  }
+  return out;
+}
+
+/**
+ * Picks the transcript edit each watcher patch duplicates: the nearest one within 15 s, or,
+ * when transcript times are approximate (Cursor's minute-precision stamps), one within 10 min
+ * that added the same lines.
+ */
+function matchSameChange(candidates) {
+  const byPatch = new Map();
+  for (const c of candidates) {
+    if (!byPatch.has(c.patchKey)) byPatch.set(c.patchKey, []);
+    byPatch.get(c.patchKey).push(c);
+  }
+  const links = [];
+  for (const list of byPatch.values()) {
+    const timed = list.filter((c) => c.gap <= SAME_CHANGE_EXACT_MS).sort((a, b) => a.gap - b.gap)[0];
+    if (timed) {
+      links.push({ patchKey: timed.patchKey, editKey: timed.editKey, gap: timed.gap, method: "time" });
+      continue;
+    }
+    const patchLines = addedLines(list[0].patchDiff);
+    if (!patchLines.size) continue;
+    let best = null;
+    for (const c of list) {
+      let shared = 0;
+      for (const l of addedLines(c.editDiff)) if (patchLines.has(l)) shared += 1;
+      if (shared && (!best || shared > best.shared || (shared === best.shared && c.gap < best.gap))) best = { ...c, shared };
+    }
+    if (best) links.push({ patchKey: best.patchKey, editKey: best.editKey, gap: best.gap, method: "content" });
+  }
+  return links;
+}
+
+const EDIT_FILES = `
+UNWIND $rows AS r
+MATCH (e:Edit {key: r.editKey})
+MERGE (f:File {key: r.fileKey})
+  ON CREATE SET f.editCount = 0
+SET f.path = r.path, f.ext = r.ext
+MERGE (e)-[:MODIFIED]->(f)
+RETURN count(e) AS n`;
+
+const FILE_COUNTS = `
+UNWIND $rows AS r
+MATCH (f:File {key: r.fileKey})
+SET f.editCount = coalesce(f.editCount, 0) + r.n,
+    f.lastEditAt = CASE WHEN f.lastEditAt IS NULL OR r.lastAt > f.lastEditAt THEN r.lastAt ELSE f.lastEditAt END
+RETURN count(f) AS n`;
+
+const TOUCHED = `
+UNWIND $rows AS r
+MATCH (a:Agent {key: r.agentKey})
+MATCH (f:File {key: r.fileKey})
+MERGE (a)-[t:TOUCHED]->(f)
+  ON CREATE SET t.count = 0, t.firstAt = r.firstAt, t.lastAt = r.lastAt
+SET t.count = t.count + r.n,
+    t.firstAt = CASE WHEN r.firstAt < t.firstAt THEN r.firstAt ELSE t.firstAt END,
+    t.lastAt = CASE WHEN r.lastAt > t.lastAt THEN r.lastAt ELSE t.lastAt END
+RETURN count(t) AS n`;
+
+const SESSION_COUNTS = `
+UNWIND $rows AS r
+MATCH (s:Session {key: r.sessionKey})
+SET s.turnCount = coalesce(s.turnCount, 0) + r.turns,
+    s.editCount = coalesce(s.editCount, 0) + r.edits
+RETURN count(s) AS n`;
+
+const PROMPTS = `
+UNWIND $rows AS r
+MATCH (e:Edit {key: r.editKey})
+OPTIONAL MATCH (u:Turn {key: r.promptKey})
+FOREACH (_ IN CASE WHEN u IS NULL THEN [] ELSE [1] END |
+  MERGE (e)-[p:PROMPTED_BY]->(u)
+  SET p.gapMs = r.promptGap, p.stale = r.promptStale, p.confidence = r.promptConfidence, p.via = r.promptVia)
+WITH e, r
+OPTIONAL MATCH (x:Turn {key: r.explainKey})
+FOREACH (_ IN CASE WHEN x IS NULL THEN [] ELSE [1] END |
+  MERGE (e)-[q:EXPLAINED_BY]->(x)
+  SET q.gapMs = r.explainGap)
+RETURN count(e) AS n`;
+
+function tally(rows, keyOf, init, add) {
+  const map = new Map();
+  for (const row of rows) {
+    const k = keyOf(row);
+    if (k == null) continue;
+    if (!map.has(k)) map.set(k, init(row));
+    add(map.get(k), row);
+  }
+  return [...map.values()];
+}
+
+/**
+ * Writes one projected history batch in dependency order:
+ * people/agents/sessions → turns → edits → files/touches → counters → prompt links.
+ */
+async function writeProjection(client, projectId, projection) {
+  const batch = token();
+  const sessions = dedupe(projection.sessions, "sessionKey");
+  const turns = dedupe(projection.turns, "turnKey");
+  const edits = dedupe(projection.edits, "editKey").map((e) => ({ source: "transcript", lamport: null, sha256: null, ...e }));
+
+  if (sessions.length) await each(client, projectId, SESSIONS, sessions);
+
+  const turnResults = turns.length ? await each(client, projectId, TURNS, turns, { batch }) : [];
+  const editResults = edits.length ? await each(client, projectId, EDITS, edits, { batch }) : [];
+
+  const createdEdit = new Set(editResults.filter((r) => r.created).map((r) => r.editKey));
+  const fileRows = edits.filter((e) => e.fileKey);
+  if (fileRows.length) await each(client, projectId, EDIT_FILES, fileRows);
+
+  // These agents' transcripts already record each edit, so their watcher patch is the same change twice.
+  const counted = (e) => e.source !== "patch" || !TRANSCRIPT_EDIT_AGENTS.has(e.label);
+  const freshFileRows = fileRows.filter((e) => createdEdit.has(e.editKey) && counted(e));
+  const fileCounts = tally(
+    freshFileRows,
+    (e) => e.fileKey,
+    (e) => ({ fileKey: e.fileKey, n: 0, lastAt: e.ts }),
+    (acc, e) => {
+      acc.n += 1;
+      acc.lastAt = Math.max(acc.lastAt, e.ts);
+    }
+  );
+  if (fileCounts.length) await each(client, projectId, FILE_COUNTS, fileCounts);
+
+  const touches = tally(
+    freshFileRows,
+    (e) => `${e.agentKey}|${e.fileKey}`,
+    (e) => ({ agentKey: e.agentKey, fileKey: e.fileKey, n: 0, firstAt: e.ts, lastAt: e.ts }),
+    (acc, e) => {
+      acc.n += 1;
+      acc.firstAt = Math.min(acc.firstAt, e.ts);
+      acc.lastAt = Math.max(acc.lastAt, e.ts);
+    }
+  );
+  if (touches.length) await each(client, projectId, TOUCHED, touches);
+
+  const counters = new Map();
+  const bump = (sessionKey, field) => {
+    if (!counters.has(sessionKey)) counters.set(sessionKey, { sessionKey, turns: 0, edits: 0 });
+    counters.get(sessionKey)[field] += 1;
+  };
+  for (const r of turnResults) if (r.created) bump(r.sessionKey, "turns");
+  for (const e of edits) if (e.sessionKey && createdEdit.has(e.editKey) && counted(e)) bump(e.sessionKey, "edits");
+  if (counters.size) await each(client, projectId, SESSION_COUNTS, [...counters.values()]);
+
+  const linked = edits.filter((e) => e.promptKey || e.explainKey);
+  if (linked.length) await each(client, projectId, PROMPTS, linked);
+
+  const pairs = dedupe(
+    fileRows.map((e) => ({ k: `${e.agentKey}|${e.fileKey}`, agentKey: e.agentKey, fileKey: e.fileKey })),
+    "k"
+  );
+  if (pairs.length) {
+    const candidates = await each(client, projectId, SAME_CHANGE, pairs, { windowMs: SAME_CHANGE_CONTENT_MS });
+    const links = matchSameChange(candidates);
+    if (links.length) await each(client, projectId, LINK_SAME_CHANGE, links);
+  }
+
+  return {
+    sessions: sessions.length,
+    turns: turns.length,
+    turnsCreated: turnResults.filter((r) => r.created).length,
+    edits: edits.length,
+    editsCreated: createdEdit.size,
+  };
+}
+
+module.exports = { writeProjection, each, chunks, dedupe, token, matchSameChange };

package/backend/lib/githubLogin.js

@@ -0,0 +1,108 @@
+const { spawn } = require("child_process");
+const { loadRegistry, saveRegistry, saveSession, loadSession } = require("./store");
+const { authorizeUrl, exchangeCode } = require("./githubOAuth");
+
+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 = "";
+    child.stdout.on("data", (c) => (out += c));
+    child.stderr.on("data", (c) => (err += c));
+    child.on("error", () => reject(new Error("GitHub CLI (gh) is not installed")));
+    child.on("exit", (code) => {
+      if (code === 0) resolve(out.trim());
+      else reject(new Error(err.trim() || `gh exited ${code}`));
+    });
+  });
+}
+
+function upsertUser(user) {
+  const reg = loadRegistry();
+  const idx = reg.users.findIndex((u) => u.login === user.login || u.id === user.id);
+  if (idx >= 0) reg.users[idx] = { ...reg.users[idx], ...user };
+  else reg.users.unshift(user);
+  saveRegistry(reg);
+  saveSession({ ...loadSession(), userId: user.id, login: user.login });
+  return user;
+}
+
+async function loginFromGh() {
+  const raw = await runGh(["api", "user"]);
+  const gh = JSON.parse(raw);
+  return upsertUser({
+    id: `gh_${gh.id}`,
+    login: gh.login,
+    name: gh.name || gh.login,
+    avatarUrl: gh.avatar_url,
+  });
+}
+
+async function loginDeviceFlow() {
+  const clientId = process.env.GITHUB_CLIENT_ID;
+  if (!clientId) throw new Error("no_device_flow");
+  const res = await fetch("https://github.com/login/device/code", {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify({ client_id: clientId, scope: "read:user repo" }),
+  });
+  const device = await res.json();
+  if (!device.device_code) throw new Error(device.error || "device_code_failed");
+  return device;
+}
+
+async function pollDevice(device) {
+  const clientId = process.env.GITHUB_CLIENT_ID;
+  const started = Date.now();
+  const interval = (device.interval || 5) * 1000;
+  while (Date.now() - started < (device.expires_in || 900) * 1000) {
+    await new Promise((r) => setTimeout(r, interval));
+    const res = await fetch("https://github.com/login/oauth/access_token", {
+      method: "POST",
+      headers: { Accept: "application/json", "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id: clientId,
+        device_code: device.device_code,
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      }),
+    });
+    const body = await res.json();
+    if (body.access_token) {
+      const userRes = await fetch("https://api.github.com/user", {
+        headers: { Authorization: `Bearer ${body.access_token}`, "User-Agent": "relay-it" },
+      });
+      const gh = await userRes.json();
+      return upsertUser({
+        id: `gh_${gh.id}`,
+        login: gh.login,
+        name: gh.name || gh.login,
+        avatarUrl: gh.avatar_url,
+      });
+    }
+    if (body.error === "authorization_pending") continue;
+    if (body.error === "slow_down") continue;
+    throw new Error(body.error_description || body.error || "device_denied");
+  }
+  throw new Error("device_expired");
+}
+
+function logout() {
+  saveSession({ userId: null, login: null, projectId: loadSession().projectId });
+}
+
+function whoami() {
+  const session = loadSession();
+  const user = loadRegistry().users.find((u) => u.id === session.userId || u.login === session.login);
+  return { session, user: user || null };
+}
+
+module.exports = {
+  loginFromGh,
+  loginDeviceFlow,
+  pollDevice,
+  upsertUser,
+  logout,
+  whoami,
+  authorizeUrl,
+  exchangeCode,
+};

package/backend/lib/githubOAuth.js

@@ -0,0 +1,42 @@
+async function exchangeCode(code, redirectUri) {
+  const clientId = process.env.GITHUB_CLIENT_ID;
+  const secret = process.env.GITHUB_CLIENT_SECRET;
+  if (!clientId || !secret) return { error: "oauth_not_configured" };
+  const tokenRes = await fetch("https://github.com/login/oauth/access_token", {
+    method: "POST",
+    headers: { Accept: "application/json", "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: clientId,
+      client_secret: secret,
+      code,
+      redirect_uri: redirectUri,
+    }),
+  });
+  const token = await tokenRes.json();
+  if (!token.access_token) return { error: "token_failed", detail: token };
+  const userRes = await fetch("https://api.github.com/user", {
+    headers: { Authorization: `Bearer ${token.access_token}`, "User-Agent": "relay-it" },
+  });
+  const gh = await userRes.json();
+  return {
+    user: {
+      id: `gh_${gh.id}`,
+      login: gh.login,
+      name: gh.name || gh.login,
+      avatarUrl: gh.avatar_url,
+    },
+  };
+}
+
+function authorizeUrl(redirectUri) {
+  const clientId = process.env.GITHUB_CLIENT_ID;
+  if (!clientId) return null;
+  const q = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope: "read:user",
+  });
+  return `https://github.com/login/oauth/authorize?${q}`;
+}
+
+module.exports = { exchangeCode, authorizeUrl };