heyquilt 0.0.1 → 0.3.106

package/src/inbox.js

@@ -0,0 +1,237 @@
+// What is waiting for a member of a session: mentions of them in chat, direct
+// messages to them, and tasks handed to them. Agents wake on these: Claude Code
+// gets them pushed as channel events by `quilt mcp`, every tool can read them
+// with quilt_inbox, and the Claude Code hooks show them while Claude works.
+//
+// `scanInbox` is pure (state in, state out) so the local daemon, the hosted
+// relay MCP and tests all find the same events the same way.
+import { assignedToReader } from './tasks.js'
+
+export const INBOX_CAP = 100
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * Which of `names` are mentioned as @Name in `text`. Case-insensitive; the @
+ * must start a word (so an email address is not a mention) and the name must
+ * end one (so @Dan is not a mention of Dan inside @Daniel). @Daniel's AI is not a mention of Daniel.
+ */
+export function mentioned (text, names) {
+  const t = String(text || '')
+  const out = []
+  for (const name of names || []) {
+    const n = String(name || '').trim()
+    if (!n) continue
+    // "@Daniel's AI" is for Daniel's AI, not for Daniel.
+    const re = new RegExp(`(^|[^\\w@])@${escapeRe(n)}(?![\\w-])(?!'s AI(?![\\w-]))`, 'iu')
+    if (re.test(t)) out.push(n)
+  }
+  return out
+}
+
+/** Typing @Agents in chat mentions every agent in the session at once. */
+export const ALL_AGENTS = 'Agents'
+
+/** Whether `text` @mentions anyone at all (an email address is not a mention). */
+export const mentionsAnyone = (text) => /(^|[^\w@])@[\p{L}\p{N}]/u.test(String(text || ''))
+
+// A room message that names nobody, this soon after its sender @mentioned an agent, carries
+// on with that agent ("can you retry that?"): it wakes the agent like the mention did.
+export const FOLLOW_UP_MS = 10 * 60 * 1000
+
+/**
+ * Whether `text` mentions `me`: @me, or @Agents when `agent` (the reader joined as an agent).
+ * A member actually named "Agents" is still mentioned by name, like anyone else.
+ */
+export function mentionsMe (text, me, { agent = false } = {}) {
+  return mentioned(text, agent ? [me, ALL_AGENTS] : [me]).length > 0
+}
+
+/**
+ * Events for `reader` that `state` has not seen. Pure: returns { events, state }.
+ * - messages: chat the reader can see, oldest first ({ id, by, to, text, ts }).
+ * - tasks: the board ({ id, title, column, by, assignee, forAi, tool, files }).
+ * - reader: { name, asAi, agent, aliases, of }: agent means the reader joined as an
+ *   agent, so @Agents mentions it too. asAi means the reader is that person's AI, so
+ *   tasks for "their AI" are the reader's and tasks for the person are not. One of
+ *   several AI sessions working through a person's app (persona.js) has its own name,
+ *   the names it had before (`aliases`), and `of`, its person: tasks for "their AI" are its.
+ *   `own`: names of the reader's own AI sessions. What they say never wakes the reader: a
+ *   session writing to its own person is talking to the person, not to their other sessions.
+ * The first scan (no state) only takes stock: nothing that is already there
+ * wakes anyone. A task fires once when it becomes the reader's while open;
+ * handing it away and back fires again.
+ * A direct message carries `re`, the reader's message it answers, when it has one. For an agent
+ * reader, a room message naming nobody within FOLLOW_UP_MS of its sender's last @mention of the
+ * reader is a mention too (`follows`: that message's id).
+ */
+export function scanInbox ({ messages = [], tasks = [], reader, now = Date.now() }, state = null) {
+  const me = reader && reader.name
+  const names = me ? [me, ...((reader && reader.aliases) || [])] : []
+  const own = new Set((reader && reader.own) || [])
+  const seed = !state
+  const seenMsgs = new Set(state?.messages || [])
+  const assigned = new Set(state?.assigned || [])
+  const events = []
+  const msgIds = []
+  const lastAsk = new Map() // sender -> their latest room message that @mentions someone: when, and was it for me
+  for (const m of messages) {
+    if (!m || typeof m.id !== 'string' || !m.id) continue
+    msgIds.push(m.id)
+    const text = typeof m.text === 'string' ? m.text : ''
+    let follows = ''
+    if (!m.to && !m.kind && reader && reader.agent && me) {
+      if (mentionsAnyone(text)) lastAsk.set(m.by, { id: m.id, ts: m.ts || 0, mine: names.some((n) => mentionsMe(text, n, { agent: true })) })
+      else {
+        const ask = lastAsk.get(m.by)
+        if (ask && ask.mine && (m.ts || 0) - ask.ts <= FOLLOW_UP_MS) follows = ask.id
+      }
+    }
+    if (seed || seenMsgs.has(m.id) || !me || names.includes(m.by) || own.has(m.by)) continue
+    // File queue messages (a request for a file the reader holds, or a file handed to them) wake
+    // them like a direct message, but ask for a handoff rather than a reply (duties.js).
+    const queue = m.kind === 'queue' || m.kind === 'handoff' ? { queue: m.kind, file: typeof m.path === 'string' ? m.path : '' } : {}
+    // A note that work the reader asked to commit was committed (commit.js): it wakes them, and asks for no reply.
+    if (m.kind === 'commit') queue.commit = typeof m.commit === 'string' ? m.commit : true
+    // A reminder from Quilt (uncommitted work): it wakes the reader, and asks for no reply.
+    if (m.kind === 'nudge') queue.nudge = true
+    const re = typeof m.re === 'string' && m.re ? { re: m.re } : {}
+    if (names.includes(m.to)) events.push({ id: m.id, kind: 'dm', by: m.by, text, ts: m.ts, ...re, ...queue })
+    else if (!m.to && names.some((n) => mentionsMe(text, n, { agent: !!reader.agent }))) events.push({ id: m.id, kind: 'mention', by: m.by, text, ts: m.ts })
+    else if (follows) events.push({ id: m.id, kind: 'mention', by: m.by, text, ts: m.ts, follows })
+  }
+  const mine = []
+  for (const t of tasks) {
+    // An AI session's tasks: given to it by name (as a member), or to its person's AI.
+    const its = assignedToReader(t, reader) || names.slice(1).some((n) => assignedToReader(t, { ...reader, name: n })) ||
+      (reader && reader.of && (t.assignee === me || assignedToReader(t, { name: reader.of, asAi: true })))
+    if (!t || typeof t.id !== 'string' || !its) continue
+    mine.push(t.id)
+    if (seed || assigned.has(t.id) || t.column === 'done' || t.archived) continue
+    events.push({
+      id: t.id,
+      kind: 'task',
+      by: t.by,
+      text: t.title,
+      ts: now,
+      task: { id: t.id, title: t.title, column: t.column, assignee: t.assignee, forAi: !!t.forAi, tool: t.tool || '', files: t.files || [] }
+    })
+  }
+  // A task that is done, archived, or no longer the reader's, can wake them again later.
+  const open = new Set(tasks.filter((t) => t && t.column !== 'done' && !t.archived).map((t) => t.id))
+  return { events, state: { messages: msgIds.slice(-500), assigned: mine.filter((id) => open.has(id)) } }
+}
+
+// How much of each message a wake's context shows (conversation.js picks the messages).
+export const CONTEXT_MESSAGE_CHARS = 600
+
+const lowerNames = (names) => new Set((names || []).filter(Boolean).map((n) => String(n).toLowerCase()))
+const clip = (text, max) => {
+  const t = String(text || '').trim()
+  return t.length > max ? t.slice(0, max - 1).trimEnd() + '…' : t
+}
+
+const ago = (ts, now) => {
+  const m = Math.max(0, Math.round((now - (ts || now)) / 60000))
+  if (m < 1) return 'just now'
+  if (m < 60) return `${m}m ago`
+  const h = Math.round(m / 60)
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`
+}
+
+/** One message as a line: "[id] 3h ago Daniel → you: text". `me`: the reader's names, shown as "you". */
+export function messageLine (m, { me = [], now = Date.now(), max = 2000 } = {}) {
+  const mine = lowerNames(me)
+  const who = (n) => mine.has(String(n || '').toLowerCase()) ? 'you' : n
+  const to = m.to ? ` → ${who(m.to)}` : ''
+  return `- [${m.id}] ${ago(m.ts, now)} ${who(m.by)}${to}: ${clip(m.text, max).replace(/\n+/g, ' ⏎ ')}`
+}
+
+/** The context an event carries, as lines under it; '' when there is none. */
+export function renderContext (e, { me = [], now = Date.now() } = {}) {
+  if (!e || !Array.isArray(e.context) || !e.context.length) return ''
+  const head = `Earlier between you and ${e.by} (oldest first${e.earlier ? `; ${e.earlier} older: quilt_conversation with "${e.by}"` : ''}):`
+  return [head, ...e.context.map((m) => '  ' + messageLine(m, { me, now, max: CONTEXT_MESSAGE_CHARS }))].join('\n')
+}
+
+// A message's id, which quilt_inbox no_reply takes to settle it.
+const idOf = (e) => e.id ? ` (id ${e.id})` : ''
+
+/** One event as a line an agent can act on. */
+export function describeEvent (e) {
+  const who = e.by || 'someone'
+  if (e.queue === 'queue') return `${who} asked for ${e.file} in its file queue: ${e.text} Finish what you are doing in it, then hand it off with quilt_handoff and your context.`
+  if (e.queue === 'handoff') return `${who} handed you ${e.file}, which you asked for: it is yours to edit now. ${e.text}`
+  if (e.nudge) return `Quilt reminds you (no reply needed): ${e.text}`
+  if (typeof e.commit === 'string') return `${who} asked you for a commit (request ${e.commit}; it waits here until the request is done, no reply needed): ${e.text}`
+  if (e.commit) return `${who} committed work you asked for (no reply needed): ${e.text}`
+  if (e.kind === 'dm') return `${who} sent you a direct message${e.id ? ` (id ${e.id}${e.re ? `, answering your message ${e.re}` : ''})` : ''}: ${e.text}`
+  if (e.kind === 'mention') return `${who} ${e.follows ? 'wrote again in chat after mentioning you' : 'mentioned you in chat'}${idOf(e)}: ${e.text}`
+  if (e.kind === 'task') {
+    const t = e.task || {}
+    const files = t.files && t.files.length ? ` Files: ${t.files.join(', ')}.` : ''
+    return `${who} handed you a task: "${e.text}" (id ${e.id}).${files} Pick it up with quilt_move_task (doing) when you start.`
+  }
+  return `${who}: ${e.text || ''}`
+}
+
+// What "that" means: the rule every wake carries, so no agent asks a person to repeat themselves.
+export const REFERS_HOW = '"That", "it", "again" and "retry" in a message mean the latest thing in the conversation shown under it: act on that. ' +
+  'Never ask what they meant, and never say you do not know what they refer to before reading back with quilt_conversation.'
+
+export const INBOX_HOW = 'Answer a message that asks something of you with quilt_message (re: its id, or set "to", or start with @their name), once. ' +
+  'One that needs nothing back (thanks, a greeting, an FYI, a status report) gets no reply: settle it with quilt_inbox (no_reply: [its id]). Take a task with quilt_move_task. ' + REFERS_HOW
+
+/**
+ * Several events as the text a tool returns, or '' when there are none. Each sender's
+ * conversation before their first event here is shown once, under it (`me`: the reader's names).
+ */
+export function renderInbox (events, opts = {}) {
+  if (!events || !events.length) return ''
+  return `Waiting for you:\n${eventLines(events, opts).join('\n')}\n${INBOX_HOW}`
+}
+
+/** Each event as a line an agent can act on, with its sender's conversation under their first one. */
+export function eventLines (events, { me = [], now = Date.now() } = {}) {
+  const ids = new Set(events.map((e) => e.id))
+  const shown = new Set()
+  const lines = []
+  for (const e of events) {
+    lines.push(`- ${describeEvent(e)}`)
+    if (shown.has(e.by) || !Array.isArray(e.context)) continue
+    shown.add(e.by)
+    const ctx = renderContext({ ...e, context: e.context.filter((m) => !ids.has(m.id)) }, { me, now })
+    if (ctx) lines.push(ctx.replace(/^/gm, '  '))
+  }
+  return lines
+}
+
+/** Keeps the events a member has not been shown yet, each with a sequence number. */
+export class Inbox {
+  constructor () {
+    this.state = null
+    this.events = []
+    this.seq = 0
+  }
+
+  /** Scans for new events. `quiet` takes stock without waking anyone (our own changes). */
+  scan (input, { quiet = false } = {}) {
+    const r = scanInbox(input, this.state)
+    this.state = r.state
+    if (quiet) return []
+    for (const e of r.events) this.events.push({ ...e, seq: ++this.seq })
+    if (this.events.length > INBOX_CAP) this.events.splice(0, this.events.length - INBOX_CAP)
+    return r.events
+  }
+
+  /** Forgets that task `id` was already the reader's, so the next scan wakes them for it (a task they took quietly). */
+  forget (id) {
+    if (this.state && Array.isArray(this.state.assigned)) this.state = { ...this.state, assigned: this.state.assigned.filter((x) => x !== id) }
+  }
+
+  /** Events after sequence number `after`, and the latest number to pass next time. */
+  since (after = 0) {
+    const from = Number(after) || 0
+    return { events: this.events.filter((e) => e.seq > from), seq: this.seq }
+  }
+}

package/src/integrations.js

@@ -0,0 +1,221 @@
+// Wires Quilt into every AI tool on this computer, with nothing for the person to do.
+// Tools that run hooks from their user settings (Gemini CLI) get Quilt's hooks there too, so
+// its rules are applied by the tool itself (see hooks.js); Claude Code and Cursor get theirs
+// from each session folder's .claude/settings.local.json (setup.js installHooks).
+//
+// Each tool that reads MCP servers from a user-level config gets Quilt's server there,
+// pointed at this install by absolute path: GUI tools started from the Dock or Start menu
+// don't see the shell's PATH, and project files can't hold one computer's paths (they
+// sync to everyone). A tool is only touched when it looks installed (its config folder
+// exists), only Quilt's own entry is written, and a file Quilt can't read safely (JSON
+// with comments, say) is left alone and reported. Run whenever the app or a session
+// starts: it's idempotent, and it follows the app when it moves or updates.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { geminiHookSettings, isQuiltHook } from './hooks.js'
+
+const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'quilt.js')
+
+/** How to run this Quilt: { command, args, env }. The desktop app's Electron runs it as Node. */
+export function quiltLaunch ({ execPath = process.execPath, electron = !!process.versions.electron, bin = BIN } = {}) {
+  return { command: execPath, args: [bin], env: electron ? { ELECTRON_RUN_AS_NODE: '1' } : {} }
+}
+
+/** The same, as one shell command line (for Claude Code's hooks), with `extra` arguments. */
+export function quiltShellCommand (extra = [], launch = quiltLaunch(), platform = process.platform) {
+  const q = (s) => `"${platform === 'win32' ? String(s).replace(/\\/g, '/') : String(s)}"`
+  const env = Object.entries(launch.env).map(([k, v]) => `${k}=${v} `).join('')
+  return `${env}${[launch.command, ...launch.args].map(q).join(' ')}${extra.length ? ' ' + extra.join(' ') : ''}`
+}
+
+/** The MCP server entry most tools take: { command, args, env }. */
+export function mcpServer (launch = quiltLaunch()) {
+  return { command: launch.command, args: [...launch.args, 'mcp'], ...(Object.keys(launch.env).length ? { env: launch.env } : {}) }
+}
+
+// ------------------------------------------------------------- files --
+
+/** Reads JSON, tolerating none. `null` means "there, but not plain JSON": not ours to rewrite. */
+function readJson (file) {
+  let text
+  try { text = fs.readFileSync(file, 'utf8') } catch { return { json: {}, text: '' } }
+  if (!text.trim()) return { json: {}, text }
+  try {
+    const json = JSON.parse(text)
+    return json && typeof json === 'object' && !Array.isArray(json) ? { json, text } : { json: null, text }
+  } catch { return { json: null, text } }
+}
+
+function writeAtomic (file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.quilt-${process.pid}.tmp`
+  fs.writeFileSync(tmp, text)
+  fs.renameSync(tmp, file)
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
+
+/** Sets json[key...] = value in a JSON file. Returns 'added' | 'updated' | 'unchanged' | 'skipped'. */
+export function upsertJsonKey (file, keys, value) {
+  const { json, text } = readJson(file)
+  if (json === null) return 'skipped'
+  let at = json
+  for (const k of keys.slice(0, -1)) {
+    if (!at[k] || typeof at[k] !== 'object' || Array.isArray(at[k])) at[k] = {}
+    at = at[k]
+  }
+  const last = keys[keys.length - 1]
+  if (same(at[last], value)) return 'unchanged'
+  const was = at[last] !== undefined
+  at[last] = value
+  // Keep the file's indentation when we can tell it.
+  const indent = (text.match(/\n([ \t]+)"/) || [null, '  '])[1]
+  writeAtomic(file, JSON.stringify(json, null, indent) + '\n')
+  return was ? 'updated' : 'added'
+}
+
+/**
+ * Codex's config.toml: Quilt's [mcp_servers.quilt] table between markers, replaced in place.
+ * A quilt table someone wrote themselves is left alone (TOML refuses a table defined twice).
+ */
+export function upsertCodexToml (file, server) {
+  let text = ''
+  try { text = fs.readFileSync(file, 'utf8') } catch {}
+  const START = '# quilt:start (written by Quilt; edits here are replaced)'
+  const END = '# quilt:end'
+  const str = (s) => JSON.stringify(String(s)) // TOML basic strings take JSON escapes
+  const env = server.env && Object.keys(server.env).length ? `env = { ${Object.entries(server.env).map(([k, v]) => `${k} = ${str(v)}`).join(', ')} }\n` : ''
+  const block = `${START}\n[mcp_servers.quilt]\ncommand = ${str(server.command)}\nargs = [${server.args.map(str).join(', ')}]\n${env}${END}`
+  const re = /# quilt:start[^\n]*\n[\s\S]*?# quilt:end/
+  if (re.test(text)) {
+    const next = text.replace(re, block)
+    if (next === text) return 'unchanged'
+    writeAtomic(file, next)
+    return 'updated'
+  }
+  if (/^\s*\[mcp_servers\.(quilt|"quilt")\]/m.test(text)) return 'unchanged'
+  writeAtomic(file, (text ? text.replace(/\s*$/, '\n\n') : '') + block + '\n')
+  return 'added'
+}
+
+/**
+ * Zed's settings.json usually has comments. When it isn't plain JSON and has no
+ * context_servers yet, Quilt's entry goes in right after the opening brace, leaving every
+ * comment where it was.
+ */
+function upsertZed (file, entry) {
+  const r = upsertJsonKey(file, ['context_servers', 'quilt'], entry)
+  if (r !== 'skipped') return r
+  const text = fs.readFileSync(file, 'utf8')
+  if (/"context_servers"/.test(text)) return 'skipped'
+  const at = text.indexOf('{')
+  if (at < 0) return 'skipped'
+  const body = JSON.stringify({ quilt: entry }, null, 2).replace(/\n/g, '\n  ')
+  writeAtomic(file, `${text.slice(0, at + 1)}\n  "context_servers": ${body},${text.slice(at + 1)}`)
+  return 'added'
+}
+
+/**
+ * Quilt's entries in a JSON settings file's `hooks` (Claude Code's shape, which Gemini CLI shares):
+ * earlier Quilt entries replaced, everyone else's left alone. Returns like upsertJsonKey.
+ */
+export function upsertHooks (file, ours) {
+  const { json } = readJson(file)
+  if (json === null) return 'skipped'
+  const hooks = json.hooks && typeof json.hooks === 'object' && !Array.isArray(json.hooks) ? { ...json.hooks } : {}
+  for (const [event, entries] of Object.entries(ours)) {
+    const kept = (Array.isArray(hooks[event]) ? hooks[event] : [])
+      .map((e) => (e && Array.isArray(e.hooks) ? { ...e, hooks: e.hooks.filter((h) => !isQuiltHook(h)) } : e))
+      .filter((e) => e && (!Array.isArray(e.hooks) || e.hooks.length))
+    hooks[event] = [...kept, ...entries]
+  }
+  return upsertJsonKey(file, ['hooks'], hooks)
+}
+
+/** Both of two writes: 'unchanged' only when both were, the first problem otherwise. */
+const both = (a, b) => ['skipped', 'busy', 'failed'].find((r) => r === a || r === b) || (a === 'unchanged' && b === 'unchanged' ? 'unchanged' : a === 'added' ? 'added' : 'updated')
+
+// ------------------------------------------------------------- tools --
+
+/**
+ * Every AI tool Quilt knows how to wire up: where it keeps MCP servers, and in what shape.
+ * `home` and `platform` are injectable for tests.
+ */
+export function knownTools ({ home = os.homedir(), platform = process.platform, env = process.env } = {}) {
+  const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming')
+  const appSupport = platform === 'darwin' ? path.join(home, 'Library', 'Application Support') : platform === 'win32' ? appData : (env.XDG_CONFIG_HOME || path.join(home, '.config'))
+  const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config')
+  const json = (keys, shape = (s) => s) => (file, s) => upsertJsonKey(file, keys, shape(s))
+  const vscodeLike = (product) => {
+    const user = path.join(appSupport, product, 'User')
+    return [
+      { name: product === 'Code' ? 'VS Code (GitHub Copilot)' : product, dir: user, file: path.join(user, 'mcp.json'), write: json(['servers', 'quilt'], (s) => ({ type: 'stdio', ...s })) },
+      { name: `Cline (${product})`, dir: path.join(user, 'globalStorage', 'saoudrizwan.claude-dev'), file: path.join(user, 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'), write: json(['mcpServers', 'quilt']) },
+      { name: `Roo Code (${product})`, dir: path.join(user, 'globalStorage', 'rooveterinaryinc.roo-cline'), file: path.join(user, 'globalStorage', 'rooveterinaryinc.roo-cline', 'settings', 'mcp_settings.json'), write: json(['mcpServers', 'quilt']) }
+    ]
+  }
+  const codexHome = env.CODEX_HOME || path.join(home, '.codex')
+  return [
+    { name: 'Claude Code', dir: path.join(home, '.claude'), file: path.join(home, '.claude.json'), write: json(['mcpServers', 'quilt'], (s) => ({ type: 'stdio', ...s })), busy: (f) => fs.existsSync(`${f}.lock`) },
+    { name: 'Claude Desktop', dir: path.join(appSupport, 'Claude'), file: path.join(appSupport, 'Claude', 'claude_desktop_config.json'), write: json(['mcpServers', 'quilt']) },
+    { name: 'Cursor', dir: path.join(home, '.cursor'), file: path.join(home, '.cursor', 'mcp.json'), write: json(['mcpServers', 'quilt']) },
+    { name: 'Windsurf', dir: path.join(home, '.codeium', 'windsurf'), file: path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), write: json(['mcpServers', 'quilt']) },
+    { name: 'Codex', dir: codexHome, file: path.join(codexHome, 'config.toml'), write: upsertCodexToml },
+    { name: 'Gemini CLI', dir: path.join(home, '.gemini'), file: path.join(home, '.gemini', 'settings.json'), write: (f, s, launch) => { const r = json(['mcpServers', 'quilt'])(f, s); return r === 'skipped' ? r : both(r, upsertHooks(f, geminiHookSettings(quiltShellCommand(['hook', 'gemini'], launch)))) } },
+    { name: 'GitHub Copilot CLI', dir: path.join(home, '.copilot'), file: path.join(home, '.copilot', 'mcp-config.json'), write: json(['mcpServers', 'quilt'], (s) => ({ type: 'local', ...s, tools: ['*'] })) },
+    { name: 'Zed', dir: platform === 'win32' ? path.join(appData, 'Zed') : path.join(xdg, 'zed'), file: platform === 'win32' ? path.join(appData, 'Zed', 'settings.json') : path.join(xdg, 'zed', 'settings.json'), write: (f, s) => upsertZed(f, { source: 'custom', command: s.command, args: s.args, env: s.env || {} }) },
+    { name: 'opencode', dir: path.join(xdg, 'opencode'), file: path.join(xdg, 'opencode', 'opencode.json'), write: json(['mcp', 'quilt'], (s) => ({ type: 'local', command: [s.command, ...s.args], enabled: true, ...(s.env ? { environment: s.env } : {}) })) },
+    { name: 'Kiro', dir: path.join(home, '.kiro'), file: path.join(home, '.kiro', 'settings', 'mcp.json'), write: json(['mcpServers', 'quilt']) },
+    { name: 'Amp', dir: path.join(xdg, 'amp'), file: path.join(xdg, 'amp', 'settings.json'), write: json(['amp.mcpServers', 'quilt']) },
+    { name: 'Junie', dir: path.join(home, '.junie'), file: path.join(home, '.junie', 'mcp', 'mcp.json'), write: json(['mcpServers', 'quilt']) },
+    { name: 'Continue', dir: path.join(home, '.continue'), file: path.join(home, '.continue', 'mcpServers', 'quilt.json'), write: json(['mcpServers', 'quilt']) },
+    ...vscodeLike('Code'),
+    ...vscodeLike('Code - Insiders')
+  ]
+}
+
+/**
+ * Registers Quilt's MCP server with every AI tool installed here. Never throws.
+ * Returns [{ name, file, result }] for every tool found ('added' | 'updated' |
+ * 'unchanged' | 'skipped' | 'busy' | 'failed', with `error` for failed).
+ */
+export function registerEverywhere ({ launch = quiltLaunch(), ...where } = {}) {
+  const server = mcpServer(launch)
+  const out = []
+  for (const t of knownTools(where)) {
+    if (!fs.existsSync(t.dir)) continue
+    try {
+      if (t.busy && t.busy(t.file)) { out.push({ name: t.name, file: t.file, result: 'busy' }); continue }
+      out.push({ name: t.name, file: t.file, result: t.write(t.file, server, launch) })
+    } catch (err) {
+      out.push({ name: t.name, file: t.file, result: 'failed', error: err.message })
+    }
+  }
+  return out
+}
+
+/** One line for logs: which tools just got Quilt, and which need a look. Empty when nothing changed. */
+export function describeRegistration (results) {
+  const done = results.filter((r) => r.result === 'added' || r.result === 'updated').map((r) => r.name)
+  const left = results.filter((r) => r.result === 'skipped' || r.result === 'failed').map((r) => `${r.name} (${r.file})`)
+  const parts = []
+  if (done.length) parts.push(`🔌 Quilt is now available to ${done.join(', ')}; restart a tool that was open to pick it up`)
+  if (left.length) parts.push(`could not safely edit: ${left.join(', ')}`)
+  return parts.join('. ')
+}
+
+/**
+ * What the app, a session and `quilt login` run as they start: register, and log what changed.
+ * Skipped under the test runner (it would write to the developer's own tool settings) unless
+ * QUILT_REGISTER_TOOLS=1 asks for it.
+ */
+export function registerOnStart (log = () => {}, opts = {}) {
+  if (process.env.NODE_TEST_CONTEXT && process.env.QUILT_REGISTER_TOOLS !== '1') return []
+  let results = []
+  try { results = registerEverywhere(opts) } catch { return [] }
+  const line = describeRegistration(results)
+  if (line) log(line)
+  return results
+}

package/src/key-cli.js

@@ -0,0 +1,115 @@
+// The quilt commands in a sandbox: no `quilt join` runs there, so with a QUILT_AGENT_KEY each
+// command is one call to the hosted tools (hosted-client.js), as the agent, in the key's session.
+// bin/quilt.js comes here when no session runs in the folder and the key is set.
+
+/** Commands that work with the key. tasks, task and tool exist only here. */
+export const KEY_COMMANDS = new Set(['status', 'messages', 'inbox', 'say', 'history', 'claim', 'release', 'focus', 'commits', 'commit-request', 'tasks', 'task', 'tool'])
+
+export const KEY_USAGE = `With QUILT_AGENT_KEY (an agent in a sandbox, no quilt join running):
+  quilt sync                             Sync this folder with the session once (start and end of every turn)
+  quilt status | inbox | tasks | commits What is going on, what waits for you, the board, commit requests
+  quilt messages [--with name] [--grep text] [--before id] [-n 30]
+  quilt say [@name] <message> [--everyone] [--also]
+  quilt task <id>                        One task in full, with its comments
+  quilt history [path] [--by name] [--since 2h] [--task id] [--diff] [-n 30]
+  quilt claim <path|glob> [note]  |  quilt release [path|glob]
+  quilt focus <what you are doing>       Shared with everyone (quilt_share)
+  quilt commit-request <message> [--files a,b] [--task id]
+  quilt tool <quilt_tool_name> [json]    Any Quilt tool, e.g. quilt tool quilt_move_task '{"id":"t1","column":"doing"}'
+  quilt tool                             Lists the tools
+  quilt mcp                              The same tools as a stdio MCP server`
+
+/** --flag value pairs and positionals, for the few flags these commands take. */
+function parse (argv, flags, bools = []) {
+  const values = {}
+  const rest = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const name = a.replace(/^--?/, '')
+    if (a.startsWith('-') && flags.includes(name)) { values[name] = argv[++i]; continue }
+    if (a.startsWith('--') && bools.includes(name)) { values[name] = true; continue }
+    rest.push(a)
+  }
+  return { values, rest }
+}
+
+const num = (v, d) => (v === undefined ? d : Math.max(1, Math.min(200, Number(v) || d)))
+
+/** The tool and arguments a command stands for, or { list: true } for `quilt tool` alone. */
+export function toolFor (cmd, argv, { stdin = '' } = {}) {
+  switch (cmd) {
+    case 'status': return ['quilt_status', {}]
+    case 'inbox': return ['quilt_inbox', {}]
+    case 'commits': return ['quilt_commit_status', {}]
+    case 'tasks': return ['quilt_tasks', parse(argv, [], ['archived']).values.archived ? { archived: true } : {}]
+    case 'task': {
+      if (!argv[0]) throw new Error('usage: quilt task <id>')
+      return ['quilt_task', { id: argv[0] }]
+    }
+    case 'messages': {
+      const { values } = parse(argv, ['with', 'grep', 'before', 'n'], ['all'])
+      if (values.with || values.grep || values.before) return ['quilt_conversation', { ...(values.with ? { with: values.with } : {}), ...(values.grep ? { q: values.grep } : {}), ...(values.before ? { before: values.before } : {}), limit: num(values.n, 30) }]
+      return ['quilt_read_messages', { limit: Math.min(100, num(values.n, 50)) }]
+    }
+    case 'say': {
+      const { values, rest } = parse(argv, ['to', 're'], ['everyone', 'also'])
+      let to = values.to
+      // "@bob text" is a direct message to bob, as with a running session (bin/quilt.js splitRecipient); @Agents is everyone's.
+      if (!to && rest.length > 1 && /^@[^@\s]+$/.test(rest[0]) && !/^@agents$/i.test(rest[0])) to = rest.shift().slice(1)
+      const text = rest.join(' ').trim()
+      if (!text) throw new Error('usage: quilt say [@name] <message>  (a message names who it is for with @Name, or add --everyone)')
+      return ['quilt_message', { text, ...(to ? { to } : {}), ...(values.everyone ? { everyone: true } : {}), ...(values.also ? { also: true } : {}), ...(values.re ? { re: values.re } : {}) }]
+    }
+    case 'history': {
+      const { values, rest } = parse(argv, ['by', 'since', 'task', 'n'], ['diff'])
+      return ['quilt_history', { ...(rest[0] ? { path: rest[0] } : {}), ...(values.by ? { by: values.by } : {}), ...(values.since ? { since: values.since } : {}), ...(values.task ? { task: values.task } : {}), ...(values.diff ? { with_diff: true } : {}), limit: num(values.n, 30) }]
+    }
+    case 'claim': {
+      if (!argv[0]) throw new Error('usage: quilt claim <path|glob> [note]')
+      return ['quilt_claim', { pattern: argv[0], ...(argv.length > 1 ? { note: argv.slice(1).join(' ') } : {}) }]
+    }
+    case 'release': return ['quilt_release', argv[0] ? { pattern: argv[0] } : {}]
+    case 'focus': {
+      if (!argv.length) throw new Error('usage: quilt focus <what you are doing>')
+      return ['quilt_share', { summary: argv.join(' ') }]
+    }
+    case 'commit-request': {
+      const { values, rest } = parse(argv, ['files', 'task'])
+      const files = values.files ? values.files.split(',').map((f) => f.trim()).filter(Boolean) : undefined
+      return ['quilt_request_commit', { ...(rest.length ? { message: rest.join(' ') } : {}), ...(files ? { files } : {}), ...(values.task ? { task: values.task } : {}) }]
+    }
+    case 'tool': {
+      if (!argv[0]) return { list: true }
+      const raw = argv[1] === '-' ? stdin : argv.slice(1).join(' ')
+      let args = {}
+      if (raw && raw.trim()) {
+        try { args = JSON.parse(raw) } catch { throw new Error(`The arguments must be JSON, e.g. quilt tool ${argv[0]} '{"key":"value"}'`) }
+        if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error('The arguments must be a JSON object.')
+      }
+      return [argv[0], args]
+    }
+  }
+  throw new Error(`quilt ${cmd} isn't a command here.\n\n${KEY_USAGE}`)
+}
+
+/** Runs one command with the key's client: prints the answer, resolves to the exit code. */
+export async function runKeyCommand (cmd, argv, { client, out = console.log, err = console.error, stdin = '' } = {}) {
+  let what
+  try { what = toolFor(cmd, argv, { stdin }) } catch (e) { err(e.message); return 1 }
+  try {
+    if (what.list) {
+      const r = await client.rpc('tools/list', {})
+      out((r.tools || []).map((t) => `${t.name}: ${String(t.description || '').split('. ')[0]}`).join('\n'))
+      return 0
+    }
+    const [name, args] = what
+    const r = await client.callRaw(name, args)
+    const text = client.textOf(r)
+    if (r && r.isError) { err(text || `${name} was refused.`); return 1 }
+    out(text)
+    return 0
+  } catch (e) {
+    err(e.message)
+    return 1
+  }
+}