heyquilt 0.0.1 → 0.3.106

package/src/procs.js

@@ -0,0 +1,70 @@
+// Registry of running quilt processes (relays, the app, folder syncs) so
+// `quilt stop` and the app's Shut down button can stop all of them.
+// Each process writes ~/.quilt/procs/<pid>.json and removes it on exit.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { quiltHome } from './legacy.js'
+
+const procsDir = () => path.join(quiltHome(), 'procs')
+
+const alive = (pid) => {
+  try { process.kill(pid, 0); return true } catch (err) { return err.code === 'EPERM' }
+}
+
+/** Records this process as a running quilt `kind` ('relay', 'app', 'sync'). */
+export function registerProcess (kind, info = {}) {
+  const file = path.join(procsDir(), `${process.pid}.json`)
+  fs.mkdirSync(procsDir(), { recursive: true, mode: 0o700 })
+  // Private: an app's entry carries its link (with the per-launch token).
+  fs.writeFileSync(file, JSON.stringify({ pid: process.pid, kind, ...info, startedAt: Date.now() }), { mode: 0o600 })
+  fs.chmodSync(file, 0o600)
+  process.on('exit', () => { try { fs.rmSync(file, { force: true }) } catch {} })
+}
+
+/** Running quilt processes, oldest first. Cleans up entries for dead ones. */
+export function listProcesses () {
+  let files = []
+  try { files = fs.readdirSync(procsDir()).filter((f) => f.endsWith('.json')) } catch { return [] }
+  const out = []
+  for (const f of files) {
+    const file = path.join(procsDir(), f)
+    let info
+    try { info = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { info = null }
+    if (info && alive(info.pid)) out.push(info)
+    else fs.rmSync(file, { force: true })
+  }
+  return out.sort((a, b) => a.startedAt - b.startedAt)
+}
+
+/**
+ * Stops every registered quilt process except `exclude` (a pid). Asks nicely
+ * first (so syncs flush and relays save), then force-kills stragglers.
+ * Returns the processes that were stopped.
+ */
+export async function stopProcesses ({ exclude = process.pid, timeoutMs = 5000 } = {}) {
+  const targets = listProcesses().filter((p) => p.pid !== exclude)
+  for (const p of targets) { try { process.kill(p.pid, 'SIGTERM') } catch {} }
+  const deadline = Date.now() + timeoutMs
+  while (targets.some((p) => alive(p.pid)) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 100))
+  for (const p of targets) {
+    if (alive(p.pid)) { try { process.kill(p.pid, 'SIGKILL') } catch {} }
+    fs.rmSync(path.join(procsDir(), `${p.pid}.json`), { force: true })
+  }
+  return targets
+}
+
+/** The newest running app's private link, preferring the desktop app; null if none. */
+export function runningAppUrl () {
+  const apps = listProcesses().filter((p) => p.kind === 'app' && p.url)
+  const pick = apps.filter((p) => p.desktop).pop() || apps.pop()
+  return pick ? pick.url : null
+}
+
+/** One-line description of a registered process, for `quilt stop`. */
+export function describeProcess (p) {
+  if (p.kind === 'relay') return `relay on :${p.port} (pid ${p.pid})`
+  if (p.kind === 'app') return `app on :${p.port} (pid ${p.pid})`
+  if (p.kind === 'sync') return `sync of ${p.dir} (pid ${p.pid})`
+  return `${p.kind} (pid ${p.pid})`
+}

package/src/project-rules.js

@@ -0,0 +1,178 @@
+// The project's own rules for AI, gathered from whichever tool's files hold them, so every
+// agent reads the same thing whatever tool it runs in (quilt_project_rules, on the local and
+// hosted MCP): AGENTS.md at the root and in folders (or CLAUDE.md when there is none), the
+// Cursor rules that always apply, and the design system.
+//
+// Pure: `list` is the session's file paths, `read(path)` their text (or null).
+
+const START = '<!-- quilt:start -->'
+const END = '<!-- quilt:end -->'
+const MAX_FILE = 20000
+const MAX_TOTAL = 60000
+const SKIP = /(^|\/)(node_modules|\.git|\.quilt|dist|build|vendor)\//
+// The design system: named in AGENTS.md ("Design system: docs/brand.md"), else a usual name.
+const DESIGN_NAMES = ['DESIGN.md', 'design.md', 'DESIGN_SYSTEM.md', 'design-system.md', 'docs/DESIGN.md', 'docs/design.md', 'docs/design-system.md']
+const DESIGN_LINE = /^\s*(?:[-*]\s*)?\**design system\**\s*:\s*`?([^\s`]+\.(?:md|mdx|txt))`?/im
+
+/** A rules file without Quilt's own guide block (agents have that from Quilt already). */
+export function withoutQuiltBlock (text) {
+  const s = String(text || '')
+  const a = s.indexOf(START)
+  const b = s.indexOf(END)
+  if (a === -1 || b === -1 || b < a) return s.trim()
+  return (s.slice(0, a) + s.slice(b + END.length)).replace(/\n{3,}/g, '\n\n').trim()
+}
+
+/** A Cursor rule's front matter: { alwaysApply, globs, description } and its body. */
+export function parseCursorRule (text) {
+  const s = String(text || '')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(s)
+  const meta = { alwaysApply: false, globs: [], description: '' }
+  if (!m) return { meta, body: s.trim() }
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^(\w+)\s*:\s*(.*)$/.exec(line.trim())
+    if (!kv) continue
+    const [, k, v] = kv
+    if (k === 'alwaysApply') meta.alwaysApply = /^true$/i.test(v.trim())
+    else if (k === 'description') meta.description = v.trim().replace(/^["']|["']$/g, '')
+    else if (k === 'globs') meta.globs = v.replace(/^\[|\]$/g, '').split(',').map((g) => g.trim().replace(/^["']|["']$/g, '')).filter(Boolean)
+  }
+  return { meta, body: s.slice(m[0].length).trim() }
+}
+
+/** Whether a CLAUDE.md (or GEMINI.md) only points at AGENTS.md, with nothing of its own. */
+export const onlyPointer = (text) => withoutQuiltBlock(text).replace(/^\s*@AGENTS\.md\s*$/m, '').trim() === ''
+
+/**
+ * The rules: { files: [{ path, kind, text }], design: { path, text } | null, missing: [] }.
+ * `kind`: 'agents' (AGENTS.md), 'claude' (CLAUDE.md, when there is no AGENTS.md), 'cursor'.
+ */
+export function projectRules ({ list = [], read = () => null } = {}) {
+  const paths = [...new Set(list)].filter((p) => typeof p === 'string' && !SKIP.test(p)).sort((a, b) => depth(a) - depth(b) || a.localeCompare(b))
+  const files = []
+  let total = 0
+  const add = (path, kind, text) => {
+    const t = String(text || '').trim()
+    if (!t || total >= MAX_TOTAL) return
+    const cut = t.length > MAX_FILE ? `${t.slice(0, MAX_FILE)}\n\n… (cut: read ${path} for the rest)` : t
+    total += cut.length
+    files.push({ path, kind, text: cut })
+  }
+  const agents = paths.filter((p) => p === 'AGENTS.md' || p.endsWith('/AGENTS.md'))
+  for (const p of agents) add(p, 'agents', withoutQuiltBlock(read(p)))
+  // No AGENTS.md: a CLAUDE.md holds the rules (Claude Code's own file), at the root and in folders.
+  if (!files.length) for (const p of paths.filter((x) => x === 'CLAUDE.md' || x.endsWith('/CLAUDE.md'))) add(p, 'claude', withoutQuiltBlock(read(p)))
+  // Cursor's rules that apply everywhere; ones for some files only are named, to read when working on those.
+  const scoped = []
+  for (const p of paths.filter((x) => /^\.cursor\/rules\/.+\.mdc?$/.test(x))) {
+    const { meta, body } = parseCursorRule(read(p))
+    if (meta.alwaysApply) add(p, 'cursor', body)
+    else if (body) scoped.push({ path: p, globs: meta.globs, description: meta.description })
+  }
+  if (paths.includes('.cursorrules')) add('.cursorrules', 'cursor', read('.cursorrules'))
+  // The design system: named in the rules, else a usual file name.
+  let design = null
+  const named = files.map((f) => DESIGN_LINE.exec(f.text)?.[1]).find(Boolean)
+  const designPath = [named, ...DESIGN_NAMES].find((p) => p && paths.includes(p.replace(/^\.\//, '')))
+  if (designPath) {
+    const t = String(read(designPath.replace(/^\.\//, '')) || '').trim()
+    if (t) design = { path: designPath.replace(/^\.\//, ''), text: t.length > MAX_FILE ? `${t.slice(0, MAX_FILE)}\n\n… (cut: read ${designPath} for the rest)` : t }
+  }
+  return { files, scoped, design }
+}
+
+const depth = (p) => p.split('/').length
+
+/** The rules as one text for an agent. */
+export function renderRules (r) {
+  if (!r.files.length && !r.design && !r.scoped.length) {
+    return 'This project has no rules for AI yet (no AGENTS.md, CLAUDE.md or Cursor rules) and no design system file. Follow the code around what you change.'
+  }
+  const out = ['The project\'s rules for AI, the same for every tool. Folder AGENTS.md files apply to the files under that folder.', '']
+  for (const f of r.files) out.push(`## ${f.path}`, '', f.text, '')
+  if (r.scoped.length) {
+    out.push('## Rules for some files only (Cursor)', '')
+    for (const s of r.scoped) out.push(`- ${s.path}${s.globs.length ? ` (for ${s.globs.join(', ')})` : ''}${s.description ? `: ${s.description}` : ''}`)
+    out.push('', 'Read one with your file tools when you work on files it covers.', '')
+  }
+  if (r.design) out.push(`## Design system (${r.design.path})`, '', r.design.text, '')
+  return out.join('\n').trim()
+}
+
+// ------------------------------------------------- gathering into AGENTS.md --
+
+/** The one folder every glob of a Cursor rule is under ("src/api/**\/*.ts" → "src/api"), or null. */
+export function globFolder (globs) {
+  const dirs = (globs || []).map((g) => {
+    const parts = String(g).replace(/^\.\//, '').split('/')
+    const fixed = []
+    for (const p of parts.slice(0, -1)) { if (/[*?[{]/.test(p)) break; fixed.push(p) }
+    return fixed.join('/')
+  })
+  if (!dirs.length || dirs.some((d) => !d)) return null
+  return dirs.every((d) => d === dirs[0]) ? dirs[0] : null
+}
+
+const section = (title, body) => `## ${title}\n\n${String(body).trim()}\n`
+const joinTo = (before, parts) => [String(before || '').replace(/\s*$/, ''), ...parts.map((p) => p.trim())].filter(Boolean).join('\n\n').replace(/^\n+/, '') + '\n'
+
+/**
+ * What gathering the project's rules into AGENTS.md would change, for the person to look at
+ * before it is applied: { changes: [{ path, before, after }] (after null: the file goes),
+ * manual: [{ path, why }] }. CLAUDE.md and GEMINI.md keep only a pointer at AGENTS.md (and
+ * Quilt's guide); Cursor rules that always apply, and .cursorrules, move into AGENTS.md; a
+ * rule for files in one folder moves into that folder's AGENTS.md; anything else is listed for
+ * the person to place by hand.
+ */
+export function gatherPlan ({ list = [], read = () => null } = {}) {
+  const paths = [...new Set(list)].filter((p) => typeof p === 'string' && !SKIP.test(p)).sort()
+  const has = new Set(paths)
+  const writes = new Map() // path -> { before, parts: [] }
+  const removes = new Map() // path -> before
+  const pointers = new Map() // path -> { before, after }
+  const manual = []
+  const into = (folder, title, body) => {
+    const p = folder ? `${folder}/AGENTS.md` : 'AGENTS.md'
+    if (!writes.has(p)) writes.set(p, { before: has.has(p) ? String(read(p) ?? '') : null, parts: [] })
+    writes.get(p).parts.push(section(title, body))
+    return p
+  }
+  // A tool's own file (CLAUDE.md, GEMINI.md) at the root or in a folder: its rules go to that folder's AGENTS.md.
+  for (const p of paths.filter((x) => /(^|\/)(CLAUDE|GEMINI)\.md$/.test(x))) {
+    const before = String(read(p) ?? '')
+    const own = withoutQuiltBlock(before).replace(/^\s*@AGENTS\.md\s*$/m, '').trim()
+    if (!own) continue
+    const folder = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : ''
+    into(folder, `From ${p.split('/').pop()}`, own)
+    const block = before.match(/<!-- quilt:start -->[\s\S]*?<!-- quilt:end -->/)
+    pointers.set(p, { before, after: `@AGENTS.md\n${block ? `\n${block[0]}\n` : ''}` })
+  }
+  for (const p of paths.filter((x) => /^\.cursor\/rules\/.+\.mdc?$/.test(x))) {
+    const before = String(read(p) ?? '')
+    const { meta, body } = parseCursorRule(before)
+    if (!body) continue
+    const title = meta.description || p.split('/').pop().replace(/\.mdc?$/, '')
+    if (meta.alwaysApply) { removes.set(p, { before, to: into('', title, body) }); continue }
+    const folder = globFolder(meta.globs)
+    if (folder) { removes.set(p, { before, to: into(folder, title, body) }); continue }
+    manual.push({ path: p, why: meta.globs.length ? `it applies to ${meta.globs.join(', ')}, which isn't one folder` : 'Cursor applies it when asked for, not to a folder' })
+  }
+  if (has.has('.cursorrules')) {
+    const before = String(read('.cursorrules') ?? '')
+    if (before.trim()) removes.set('.cursorrules', { before, to: into('', 'From .cursorrules', before) })
+  }
+  const changes = []
+  for (const [p, w] of writes) changes.push({ path: p, before: w.before, after: joinTo(w.before, w.parts) })
+  for (const [p, c] of pointers) if (c.after !== c.before) changes.push({ path: p, before: c.before, after: c.after })
+  for (const [p, r] of removes) changes.push({ path: p, before: r.before, after: null, to: r.to })
+  changes.sort((a, b) => (a.path === 'AGENTS.md' ? -1 : b.path === 'AGENTS.md' ? 1 : a.path.localeCompare(b.path)))
+  return { changes, manual }
+}
+
+/** A short fingerprint of a plan, so what is applied is what was shown. */
+export function planKey (plan) {
+  let h = 0x811c9dc5
+  const s = JSON.stringify(plan.changes.map((c) => [c.path, c.before, c.after]))
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)
+  return `${s.length}:${(h >>> 0).toString(36)}`
+}

package/src/protocol.js

@@ -0,0 +1,92 @@
+// Wire protocol shared by the relay server and clients.
+// Compatible with the standard y-websocket message layout.
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import * as syncProtocol from 'y-protocols/sync'
+import * as awarenessProtocol from 'y-protocols/awareness'
+
+export const MSG_SYNC = 0
+export const MSG_AWARENESS = 1
+export const MSG_QUERY_AWARENESS = 3
+// quilt extensions (ignored by plain y-websocket clients):
+export const MSG_AUTH = 10 // relay -> client: nonce; client -> relay: signature
+export const MSG_CLAIM = 11 // client -> relay: JSON { id, op: 'claim'|'release', pattern, note }
+export const MSG_CLAIMS = 12 // relay -> client: JSON { claims, reply?: { id, ok, error, released } }
+export const MSG_ACCESS = 13 // relay -> client: JSON { state: 'pending'|'approved', role, scopes, scopesExcept, talk, owner, controlled, refresh?, refused?, why? }
+export const MSG_ADMIN = 14 // client (owner) -> relay: JSON { id, op: 'approve'|'deny'|'set'|'remove'|'end'|'name', key, role, scopes, access?, typeId?, name }
+export const MSG_MEMBERS = 15 // relay -> client: JSON { members, sessionName, pending?, reply?: { id, ok, error } }
+export const MSG_PASS = 16 // client -> relay: JSON { pass }: a fresh session pass, sent at least every 5 minutes
+export const MSG_BRANCH = 17 // client -> relay: JSON { id, op: 'join'|'confirm'|'remove', branch, base?, adopt?, sv? }
+export const MSG_BRANCHES = 18 // relay -> client: JSON { branches, reply?: { id, op, ok, error?, branch?, created?, base? } }
+
+// Every sync message names its document: the room's (chat, tasks, the feed, commit requests,
+// activity) is '', a branch's (its files) is the branch key. Git never allows an empty branch name.
+export const ROOM_DOC = ''
+
+// What this app can do, sent when it connects. The relay turns away apps without what a session needs.
+export const FEATURES = 'large-files,branches'
+
+// WebSocket close codes the relay uses to refuse a client for good.
+export const CLOSE_AUTH_FAILED = 4401
+export const CLOSE_NAME_TAKEN = 4403
+export const CLOSE_DENIED = 4406 // the owner said no, or removed you
+
+// WebSocket close code the relay uses when a room is over its size quota.
+export const CLOSE_ROOM_FULL = 4413
+
+export const CLOSE_ENDED = 4410 // the owner ended the session and it was deleted
+
+// The connection's session pass ran out without a new one. Clients reconnect with a fresh pass.
+export const CLOSE_PASS_EXPIRED = 4419
+
+// Sent to apps too old for a session that now stores large files. It reuses
+// 4401 because every app that knows close codes stops on it and shows the
+// reason; the oldest ones reconnect instead, and the relay refuses that
+// reconnect with the same message.
+export const CLOSE_NEEDS_UPDATE = CLOSE_AUTH_FAILED
+
+// Largest file that can be sent in chat.
+export const MAX_SHARED_FILE_BYTES = 100 * 1024 * 1024
+
+export { encoding, decoding, syncProtocol, awarenessProtocol }
+
+/** An encoder with a sync message's header written: the type and the document it is for. */
+export function syncHeader (docId = ROOM_DOC) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, MSG_SYNC)
+  encoding.writeVarString(enc, docId)
+  return enc
+}
+
+export function syncStep1Message (doc, docId = ROOM_DOC) {
+  const enc = syncHeader(docId)
+  syncProtocol.writeSyncStep1(enc, doc)
+  return encoding.toUint8Array(enc)
+}
+
+export function updateMessage (update, docId = ROOM_DOC) {
+  const enc = syncHeader(docId)
+  syncProtocol.writeUpdate(enc, update)
+  return encoding.toUint8Array(enc)
+}
+
+export function awarenessMessage (awareness, clients) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, MSG_AWARENESS)
+  encoding.writeVarUint8Array(enc, awarenessProtocol.encodeAwarenessUpdate(awareness, clients))
+  return encoding.toUint8Array(enc)
+}
+
+export function bytesMessage (type, bytes) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, type)
+  encoding.writeVarUint8Array(enc, bytes)
+  return encoding.toUint8Array(enc)
+}
+
+export function jsonMessage (type, value) {
+  const enc = encoding.createEncoder()
+  encoding.writeVarUint(enc, type)
+  encoding.writeVarString(enc, JSON.stringify(value))
+  return encoding.toUint8Array(enc)
+}

package/src/quiet-warnings.js

@@ -0,0 +1,9 @@
+// Node prints "SQLite is an experimental feature" the moment node:sqlite loads, which
+// Quilt does to read Cursor's chat database. The warning is known and harmless, so it is
+// kept off people's terminals; every other warning is still printed as Node would.
+const printers = process.listeners('warning')
+process.removeAllListeners('warning')
+process.on('warning', (warning) => {
+  if (warning && warning.name === 'ExperimentalWarning' && /sqlite/i.test(String(warning.message))) return
+  for (const print of printers) print.call(process, warning)
+})

package/src/relay-ai-vm.js

@@ -0,0 +1,82 @@
+// The relay wakes a person's cloud AI (routes/ai-vm.js on the API) when something waits for it
+// and it isn't connected (its machine suspends when idle): an @mention, a direct message or a
+// task for it, or for "<person>'s AI" while none of the person's AI sessions on a computer is
+// live. A room remembers each cloud AI that joined it (meta.cloudAis, keyed by its person's
+// account) with what it has been told of, so a wake is asked for once per new event, and the
+// machine's own inbox finds the event when it is back.
+import { scanInbox } from './inbox.js'
+import { readTasks } from './tasks.js'
+import { cloudReader } from './cloud-ai.js'
+
+const PERSON = /^person:[A-Za-z0-9_-]{1,64}$/
+
+/** Notes the cloud AI a pass is for in `meta.cloudAis`; returns whether anything changed. */
+export function noteCloudAi (meta, pass, name) {
+  if (!pass || pass.kind !== 'agent' || !PERSON.test(String(pass.of || '')) || typeof pass.ofName !== 'string') return false
+  meta.cloudAis ||= {}
+  const old = meta.cloudAis[pass.of]
+  const agent = `agent:${pass.sub}`
+  if (old && old.agent === agent && old.name === name && old.ofName === pass.ofName) return false
+  meta.cloudAis[pass.of] = { agent, name, ofName: pass.ofName, inbox: old && old.agent === agent ? old.inbox : null }
+  return true
+}
+
+/** Whether a connection in `room` is `account` ('agent:<id>'). */
+const connected = (room, account) => [...room.conns.keys()].some((ws) => ws.pass && `${ws.pass.kind}:${ws.pass.sub}` === account)
+
+/**
+ * Looks at `room` for each cloud AI it knows: what is new for it. Returns the cloud AIs to wake
+ * ([{ agent, room }]); `changed` says whether meta needs saving. Pure but for the room it reads.
+ */
+export function cloudAisToWake (room) {
+  const out = []
+  let changed = false
+  const list = room.meta.cloudAis || {}
+  if (!Object.keys(list).length) return { wake: out, changed }
+  const states = [...room.awareness.getStates().values()]
+  const chat = room.doc.getArray('chat').toArray()
+  const tasks = readTasks(room.doc.getMap('tasks'))
+  for (const entry of Object.values(list)) {
+    if (!entry || !entry.agent) continue
+    const reader = cloudReader({ name: entry.name, person: entry.ofName, states })
+    const messages = chat.filter((m) => m && m.id && (!m.to || m.to === entry.name || reader.aliases.includes(m.to) || m.by === entry.name))
+    const got = scanInbox({ messages, tasks, reader }, entry.inbox || null)
+    const seeded = !entry.inbox
+    entry.inbox = got.state
+    changed = true
+    if (seeded || !got.events.length) continue
+    if (!connected(room, entry.agent)) out.push({ agent: entry.agent.slice('agent:'.length), room: room.name })
+  }
+  return { wake: out, changed }
+}
+
+/**
+ * Watches rooms' chat and boards and asks the API (`apiUrl`, signed with `secret`) to wake each
+ * cloud AI something waits for. `fetch` is for tests.
+ */
+export function cloudAiWaker ({ apiUrl, secret, fetch: fetchImpl = globalThis.fetch, log = () => {} }) {
+  const watched = new WeakSet()
+  const base = String(apiUrl).replace(/\/+$/, '')
+  const ask = (w) => fetchImpl(`${base}/v1/relay/ai-vm/wake`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${secret}` },
+    body: JSON.stringify(w),
+    signal: AbortSignal.timeout(30_000)
+  }).then((res) => { if (!res.ok) log(`[${w.room}] could not wake a cloud AI (${res.status})`) }, (err) => log(`[${w.room}] could not wake a cloud AI: ${err.message}`))
+
+  const check = (room) => {
+    const { wake, changed } = cloudAisToWake(room)
+    if (changed) room.saveMeta()
+    return Promise.all(wake.map(ask))
+  }
+
+  const watch = (room) => {
+    if (watched.has(room)) return
+    watched.add(room)
+    const run = () => { try { check(room) } catch (err) { log(`[${room.name}] cloud AI wake: ${err.message}`) } }
+    room.doc.getArray('chat').observe(run)
+    room.doc.getMap('tasks').observeDeep(run)
+  }
+
+  return { watch, check }
+}

package/src/relay-ask.js

@@ -0,0 +1,141 @@
+// Questions for the relay, "Quilt" in chat. Anyone in a session can @mention @Quilt (or message it directly)
+// and it answers from what it knows: how the session's branches stand against git, who is
+// connected, which branches it keeps, and (for the owner) trimming branches nobody uses. No
+// model runs here: each question is matched by its words and answered by code. Pure but for
+// `room`, which the relay passes in (server.js answerRelay).
+
+import { RELAY_BY, isRelay } from './branches.js'
+import { mentioned } from './inbox.js'
+import { RELAY_QUESTIONS, RELAY_OLD_NAMES } from './ui/chat.js'
+
+export { RELAY_QUESTIONS }
+
+/** A branch nobody has been on for this long, with nobody on it now, is unused (trim). */
+export const TRIM_IDLE_MS = 24 * 60 * 60 * 1000
+
+/** Whether chat message `m` is for the relay: sent to it directly, or @mentioning it. */
+export function asksRelay (m) {
+  if (!m || typeof m !== 'object' || typeof m.text !== 'string' || isRelay(m.by)) return false
+  if (m.to) return isRelay(m.to)
+  return mentioned(m.text, [RELAY_BY, ...RELAY_OLD_NAMES]).length > 0
+}
+
+/** Which question `text` asks (an id of RELAY_QUESTIONS), or 'help' when it is none of them. */
+export function questionOf (text) {
+  const t = String(text || '').replace(/@(the relay|quilt)\b/gi, ' ').toLowerCase()
+  if (/\b(trim|prune|clean ?up|remove)\b/.test(t)) return 'trim'
+  if (/\b(git|github|upstream|commits?|behind|synced?)\b/.test(t)) return 'git'
+  if (/\b(members?|connected|online|who|people|agents?)\b/.test(t)) return 'members'
+  if (/\bbranch(es)?\b/.test(t)) return 'branches'
+  return 'help'
+}
+
+const plural = (n, w) => `${n} ${w}${n === 1 ? '' : /(ch|sh|s|x)$/.test(w) ? 'es' : 's'}`
+
+/** "3 min ago", "2 h ago", "4 days ago". */
+export function ago (ts, now = Date.now()) {
+  const s = Math.max(0, Math.round((now - ts) / 1000))
+  if (s < 60) return 'just now'
+  if (s < 3600) return `${Math.round(s / 60)} min ago`
+  if (s < 86400) return `${Math.round(s / 3600)} h ago`
+  return plural(Math.round(s / 86400), 'day') + ' ago'
+}
+
+const list = (names) => names.length <= 2 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`
+
+/** Who is on each branch now: Map key -> [names], from connected apps and hosted agents active now. */
+function whoIsOn (room) {
+  const on = new Map()
+  const add = (k, n) => { if (k && n && !(on.get(k) || []).includes(n)) on.set(k, [...(on.get(k) || []), n]) }
+  for (const ws of room.conns.keys()) add(ws.branch, room.names.get(ws))
+  for (const h of room.hostedOnline()) add(room.hostedBranch(h.id), h.name)
+  return on
+}
+
+function gitAnswer (room, now) {
+  const ups = room.meta.upstreams || {}
+  const lines = []
+  for (const key of Object.keys(room.meta.branches)) {
+    const r = ups[key]
+    if (!r || !r.name) continue
+    const parts = [`${key} follows ${r.name}${r.repo ? ` (${r.repo})` : ''}`]
+    if (r.sha) parts.push(`at ${r.sha.slice(0, 7)}${r.checkedAt ? `, checked ${ago(r.checkedAt, now)}` : ''}`)
+    if (r.brought && r.brought.at) parts.push(`brought in ${plural(r.brought.count || 0, 'commit')} ${ago(r.brought.at, now)}`)
+    if (r.clash && r.clash.task) parts.push(`waiting on merge task ${r.clash.task}`)
+    if (r.problem) parts.push(`problem: ${typeof r.problem === 'string' ? r.problem : r.problem.message || 'see the branch menu'}`)
+    const why = r.github && GITHUB_BLOCKED[r.github.state]
+    if (why) parts.push(`agents can't commit: ${why}`)
+    lines.push(parts.join('; '))
+  }
+  if (!lines.length) return 'No branch here follows a GitHub repository yet. It starts when a member with a git folder joins.'
+  return lines.length === 1 ? `${lines[0]}.` : `Against git:\n${lines.map((l) => `- ${l}`).join('\n')}`
+}
+
+// Why agents can't commit to a branch's repository, by its GitHub connection's state (relay-upstream.js noteConnection).
+const GITHUB_BLOCKED = {
+  'not-connected': 'nobody here has connected GitHub',
+  'not-installed': 'the Quilt app isn\'t installed on the repository',
+  'no-access': 'the connected GitHub account can\'t write to it'
+}
+
+function membersAnswer (room) {
+  const people = new Set()
+  for (const ws of room.conns.keys()) { const n = room.names.get(ws); if (n) people.add(n) }
+  for (const h of room.hostedOnline()) people.add(h.name)
+  const total = Object.keys(room.meta.members || {}).length + 1 // members, and the owner
+  const names = [...people].sort()
+  if (!names.length) return `Nobody is connected right now (${plural(total, 'member')} in the session).`
+  return `${plural(names.length, 'member')} connected of ${total}: ${list(names)}.`
+}
+
+function branchesAnswer (room, now) {
+  const on = whoIsOn(room)
+  const keys = Object.keys(room.meta.branches)
+  const lines = keys.sort((a, b) => (b === room.defaultKey) - (a === room.defaultKey) || a.localeCompare(b)).map((k) => {
+    const b = room.meta.branches[k]
+    const here = on.get(k) || []
+    const tag = k === room.defaultKey ? ' (default)' : ''
+    return `- ${k}${tag}: ${here.length ? `${list(here)} on it` : `nobody on it${b.used ? `, last used ${ago(b.used, now)}` : ''}`}`
+  })
+  return keys.length === 1 ? `1 branch tracked: ${lines[0].slice(2)}.` : `${plural(keys.length, 'branch')} tracked:\n${lines.join('\n')}`
+}
+
+/**
+ * The branches trim would remove: not the default, nobody on it or holding a file there, no
+ * hosted agent's choice, and no member on it for TRIM_IDLE_MS. A branch from before `used` was
+ * kept counts from its last `seen` (the relay's own saves move that too, so it only waits longer).
+ */
+export function unusedBranches (room, now = Date.now()) {
+  const on = whoIsOn(room)
+  const claimed = new Set(Object.values(room.meta.claims || {}).map((c) => room.branchOf(c)))
+  const chosen = new Set(Object.values(room.meta.hostedBranch || {}))
+  return Object.entries(room.meta.branches)
+    .filter(([k, b]) => k !== room.defaultKey && !on.has(k) && !claimed.has(k) && !chosen.has(k) && now - (b.used || b.seen || b.at || 0) >= TRIM_IDLE_MS)
+    .map(([k]) => k)
+}
+
+function trimAnswer (room, asker, now) {
+  if (!asker.mayTrim) return 'Only the session owner can trim branches.'
+  const gone = unusedBranches(room, now)
+  if (!gone.length) return 'Nothing to trim: every branch is in use or was used in the last day.'
+  for (const k of gone) room.removeBranch(k, { save: false })
+  room.saveMeta()
+  room.broadcastBranches()
+  room.log(`[${room.name}] ${asker.name} trimmed ${plural(gone.length, 'unused branch')}: ${gone.join(', ')}`)
+  return `Trimmed ${plural(gone.length, 'branch')} nobody used for a day: ${list(gone)}. Git keeps them, and a branch comes back when someone checks it out.`
+}
+
+const HELP = `I can answer:\n${RELAY_QUESTIONS.map((q) => `- ${q.text}${q.owner ? ' (owner only)' : ''}`).join('\n')}`
+
+/**
+ * The relay's answer to message `m`. `asker`: { name, mayTrim }. Returns the text.
+ */
+export function relayAnswer (room, m, asker, now = Date.now()) {
+  switch (questionOf(m.text)) {
+    case 'git': return gitAnswer(room, now)
+    case 'members': return membersAnswer(room)
+    case 'branches': return branchesAnswer(room, now)
+    case 'trim': return trimAnswer(room, asker, now)
+    default: return HELP
+  }
+}