heyquilt 0.0.1 → 0.3.90

package/src/turn-sync-plan.js

@@ -0,0 +1,142 @@
+// What `quilt sync` does with each file: the rules, kept apart from the relay so they can be read
+// and tested on their own (the relay's quilt_sync tool runs them: relay-mcp.js).
+//
+// A sandboxed agent syncs in one shot at the start and end of a turn, with no state of its own:
+// the relay keeps a checkpoint for each of its sandboxes (its slot) of what the folder held at the
+// end of its last sync. Per path, L is the folder's version, B the checkpoint's, S the session's
+// (a sha1 each, or null for "not there"):
+//
+// - L = S: nothing to do.
+// - First sync of this slot (no checkpoint): the session wins for every file it has, a differing
+//   copy is kept aside in .quilt/conflicts; a copy of a file the session deleted is a leftover,
+//   kept aside too, never brought back (issue 040); a file the session never had is pushed.
+// - L = B: only the session changed it: pull it (or remove it).
+// - S = B: only the folder changed it: push it (or delete it in the session).
+// - L is a version this slot held before: a stale copy (a platform restoring an older snapshot),
+//   no new work: the session's version comes back.
+// - Both changed: merged when the lines don't overlap (a turn is an edit window, like live
+//   editing); otherwise a merge record, the session's version on disk and ours kept aside.
+// - Large files kept in storage are not carried by quilt sync.
+// - Deleting more than max(20, a quarter) of the checkpoint's files at once is not done for
+//   everyone: those files come back instead (a folder that lost most of the project).
+import { merge3 } from './merge3.js'
+
+/** At most this many earlier versions per path are remembered, to tell a stale copy. */
+export const MAX_WAS = 5
+/** A base text kept in a checkpoint at most this long (longer files merge as a record). */
+export const MAX_BASE_TEXT = 1024 * 1024
+export const MASS_DELETE_MIN = 20
+export const MASS_DELETE_SHARE = 0.25
+/** In a manifest: a file the folder has but quilt sync doesn't carry (too large). */
+export const SKIP = 'skip'
+
+const HASH = /^[0-9a-f]{40}$/
+
+/**
+ * What to do with one path. `local` and `session` are sha1s or null; `local` may be SKIP and
+ * `session` may be { stored: true } (a large file in storage); `base` is the checkpoint's entry
+ * ({ h, was }) or null; `first` says there is no checkpoint at all; `deleted` says the session
+ * had the path and deleted it.
+ * Returns one of: same, skip, pull, remove, push, delete, merge, aside-pull, aside-remove.
+ */
+export function decide ({ local, session, base, first, deleted = false }) {
+  if (local === SKIP || (session && session.stored)) return local && session && local === session.h ? 'same' : 'skip'
+  const S = session ? session.h : null
+  const L = local || null
+  if (L === S) return 'same'
+  if (first) {
+    if (S) return L ? 'aside-pull' : 'pull'
+    return deleted ? 'aside-remove' : 'push'
+  }
+  if (!base) {
+    if (L && S) return 'merge'
+    return S ? 'pull' : 'push'
+  }
+  if (L === base.h) return S ? 'pull' : 'remove'
+  if (S === base.h) return L ? 'push' : 'delete'
+  // Both moved on. A version we held before is no new work.
+  if (L && (base.was || []).includes(L)) return S ? 'pull' : 'remove'
+  return 'merge'
+}
+
+/** A file's state in the session: sha1 and text (or stored), for decide and the checkpoint. */
+export const sessionEntry = (h, { text = null, stored = false } = {}) => ({ h, text, stored })
+
+/**
+ * The plan for a folder: `local` { path: sha1 | SKIP }, `session` Map path -> sessionEntry,
+ * `checkpoint` { files: { path: { h, t?, was? } } } or null, `deleted(path)` for tombstones.
+ * Returns lists of paths: upload (send their contents), delete (gone here: delete in the session),
+ * pull (write the session's version), remove (delete here), aside (keep ours in .quilt/conflicts
+ * first; each is in pull or remove too), merge (both changed: upload too), skipped, and
+ * `guarded`: deletions held back.
+ */
+export function planSync ({ local, session, checkpoint, deleted = () => false }) {
+  const first = !checkpoint
+  const base = (checkpoint && checkpoint.files) || {}
+  const out = { first, upload: [], delete: [], pull: [], remove: [], aside: [], merge: [], skipped: [], guarded: 0 }
+  const paths = new Set([...Object.keys(local), ...session.keys(), ...Object.keys(base)])
+  const decided = []
+  for (const p of [...paths].sort()) {
+    const d = decide({ local: local[p] ?? null, session: session.get(p) || null, base: base[p] || null, first, deleted: deleted(p) })
+    decided.push([p, d])
+  }
+  const deletes = decided.filter(([, d]) => d === 'delete').length
+  const guard = !first && deletes > Math.max(MASS_DELETE_MIN, Math.floor(Object.keys(base).length * MASS_DELETE_SHARE))
+  for (let [p, d] of decided) {
+    if (d === 'delete' && guard) { d = 'pull'; out.guarded++ }
+    if (d === 'same') continue
+    if (d === 'skip') { if (local[p] === SKIP || session.get(p)) out.skipped.push(p); continue }
+    if (d === 'push') out.upload.push(p)
+    else if (d === 'delete') out.delete.push(p)
+    else if (d === 'pull') out.pull.push(p)
+    else if (d === 'remove') out.remove.push(p)
+    else if (d === 'aside-pull') { out.aside.push(p); out.pull.push(p) } else if (d === 'aside-remove') { out.aside.push(p); out.remove.push(p) } else if (d === 'merge') {
+      out.merge.push(p)
+      if (local[p]) out.upload.push(p); else out.delete.push(p)
+    }
+  }
+  return out
+}
+
+/**
+ * Both changed one text file: the merged text when the lines don't overlap (and something of
+ * each side is in it), or null for a merge record. `base` null: no base, never merged.
+ */
+export function mergeTexts (base, ours, theirs) {
+  if (typeof base !== 'string' || typeof ours !== 'string' || typeof theirs !== 'string') return null
+  const { text, conflicts } = merge3(base, ours, theirs)
+  return conflicts.length ? null : text
+}
+
+/**
+ * The checkpoint after a sync: for each path where the folder now has the session's version, that
+ * version (its text kept as the next merge's base, the version before it remembered); every other
+ * path keeps the entry it had, so a refused or interrupted sync loses nothing. `local` is the
+ * folder's manifest after writing, `session` the session now.
+ */
+export function nextCheckpoint (prev, local, session, { at = Date.now() } = {}) {
+  const before = (prev && prev.files) || {}
+  const files = {}
+  for (const p of new Set([...Object.keys(local), ...session.keys(), ...Object.keys(before)])) {
+    const L = local[p]
+    const s = session.get(p)
+    const old = before[p]
+    if (L && L !== SKIP && s && !s.stored && L === s.h) {
+      const was = old ? [old.h, ...(old.was || [])].filter((h, i, all) => HASH.test(h) && h !== s.h && all.indexOf(h) === i).slice(0, MAX_WAS) : []
+      files[p] = { h: s.h, ...(typeof s.text === 'string' && s.text.length <= MAX_BASE_TEXT ? { t: s.text } : {}), ...(was.length ? { was } : {}) }
+    } else if (old) files[p] = old
+  }
+  return { at, files }
+}
+
+/** Paths whose folder version still differs from the session's (another round would bring them). */
+export function behind (local, session) {
+  const out = []
+  for (const p of new Set([...Object.keys(local), ...session.keys()])) {
+    const L = local[p]
+    const s = session.get(p)
+    if (L === SKIP || (s && s.stored)) continue
+    if ((L || null) !== (s ? s.h : null)) out.push(p)
+  }
+  return out.sort()
+}

package/src/turn-sync.js

@@ -0,0 +1,191 @@
+// `quilt sync` (`npx heyquilt sync`): a sandboxed agent's folder synced with its session in one
+// shot, for a turn that may be killed at any moment and a machine wiped after it. It reads the
+// QUILT_AGENT_KEY, asks the relay what to do (quilt_sync, relay-turn-sync.js: the relay keeps the
+// sync state, so nothing here has to survive), pushes what changed on disk, writes what changed
+// in the session, and exits. No daemon, nothing kept in the home folder.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { loadIgnore, walk, isIgnored, isSafeRelPath, resolveInside, looksBinary, LARGE_FILE_BYTES } from './fsutil.js'
+import { headRef } from './gitstate.js'
+import { hostedClient } from './hosted-client.js'
+
+/** Texts larger than this, and binaries this large or larger, are not carried by quilt sync. */
+export const MAX_TEXT = 1024 * 1024
+export const MAX_BINARY = LARGE_FILE_BYTES
+const PUSH_BATCH_BYTES = 1200 * 1024 // well under the API's 2 MB per request
+const PULL_BATCH = 300
+const ROUNDS = 3
+
+const sha1 = (buf) => crypto.createHash('sha1').update(buf).digest('hex')
+
+/** A file in the folder: { buf, text?, hash } or { skip } (too large) or null (not a file). */
+function readFile (root, rel) {
+  let abs
+  try { abs = resolveInside(root, rel) } catch { return null }
+  let st
+  try { st = fs.lstatSync(abs) } catch { return null }
+  if (!st.isFile()) return null
+  if (st.size > MAX_TEXT) return { skip: true }
+  const buf = fs.readFileSync(abs)
+  if (looksBinary(buf)) return buf.length >= MAX_BINARY ? { skip: true } : { buf, hash: sha1(buf) }
+  return { buf, text: buf.toString('utf8'), hash: sha1(buf) }
+}
+
+/** The folder's manifest: { path: sha1 | 'skip' }. */
+export function scanFolder (root, ig = loadIgnore(root)) {
+  const out = {}
+  for (const rel of walk(root, ig)) {
+    const f = readFile(root, rel)
+    if (f) out[rel] = f.skip ? 'skip' : f.hash
+  }
+  return out
+}
+
+function removeEmptyParents (root, dir) {
+  while (dir !== root && dir.startsWith(root + path.sep)) {
+    try { fs.rmdirSync(dir) } catch { return }
+    dir = path.dirname(dir)
+  }
+}
+
+/** Splits [rel, payload] pairs into batches of at most `max` bytes (one oversize file goes alone). */
+function batches (items, size, max) {
+  const out = []
+  let cur = []; let n = 0
+  for (const it of items) {
+    const s = size(it)
+    if (cur.length && n + s > max) { out.push(cur); cur = []; n = 0 }
+    cur.push(it); n += s
+  }
+  if (cur.length) out.push(cur)
+  return out
+}
+
+/**
+ * Syncs `dir` with the key's session. `key` is a decoded QUILT_AGENT_KEY. Resolves to a summary
+ * { room, branch, pulled, pushed, removed, deleted, merged, aside, merges, kept, skipped, backup }.
+ */
+export async function turnSync ({ dir = process.cwd(), key, fetch: fetchImpl = globalThis.fetch, log = () => {}, client = hostedClient({ key, fetch: fetchImpl }) }) {
+  const root = path.resolve(dir)
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`${root} is not a folder`)
+  const sum = { room: key.room, branch: '', pulled: [], pushed: [], removed: [], deleted: [], merged: [], aside: [], merges: [], kept: [], skipped: [], refused: '', backup: '' }
+  const step = async (args) => JSON.parse(await client.call('quilt_sync', { slot: key.slot, ...args }))
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backupDir = path.join(root, '.quilt', 'conflicts', stamp)
+  let ig = loadIgnore(root)
+  const synced = (rel) => isSafeRelPath(rel) && !isIgnored(ig, rel)
+  const add = (list, items) => { for (const x of items) if (!list.includes(x)) list.push(x) }
+
+  /** Keeps the folder's copy of rel in .quilt/conflicts/<this sync> before it is replaced or removed. */
+  const keepAside = (rel) => {
+    const f = readFile(root, rel)
+    if (!f || f.skip) return
+    if (!fs.existsSync(path.join(root, '.quilt'))) {
+      fs.mkdirSync(path.join(root, '.quilt'), { recursive: true })
+      // Never committed, whatever the project's .gitignore says (Quilt never syncs .quilt either).
+      fs.writeFileSync(path.join(root, '.quilt', '.gitignore'), '*\n')
+    }
+    const dest = path.join(backupDir, ...rel.split('/'))
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    fs.writeFileSync(dest, f.buf)
+    sum.backup = path.relative(root, backupDir).split(path.sep).join('/')
+    add(sum.aside, [rel])
+  }
+
+  const writeOne = (rel, v) => {
+    let abs
+    try { abs = resolveInside(root, rel) } catch (err) { log(`⚠️ ${err.message}`); return false }
+    try {
+      if (v.gone) {
+        if (fs.existsSync(abs) && fs.lstatSync(abs).isFile()) { fs.rmSync(abs); removeEmptyParents(root, path.dirname(abs)) }
+        return true
+      }
+      if (v.stored) return false
+      fs.mkdirSync(path.dirname(abs), { recursive: true })
+      if (fs.existsSync(abs) && fs.lstatSync(abs).isDirectory()) { log(`⚠️ couldn't write ${rel}: a folder is in the way`); return false }
+      fs.writeFileSync(abs, typeof v.text === 'string' ? v.text : Buffer.from(v.base64 || '', 'base64'))
+      return true
+    } catch (err) {
+      log(`⚠️ couldn't write ${rel}: ${err.message}`)
+      return false
+    }
+  }
+
+  for (let round = 0; round < ROUNDS; round++) {
+    const files = scanFolder(root, ig)
+    const plan = await step({ step: 'plan', files, ...(round === 0 && headRef(root) ? { branch: headRef(root) } : {}) })
+    sum.branch = plan.branch || sum.branch
+    add(sum.skipped, plan.skipped || [])
+    const pull = [...plan.pull]
+    const remove = [...plan.remove]
+    const aside = [...plan.aside]
+    let changed = 0
+    // What changed here goes to the session, unless the session refuses all of it for now (then it stays here, and goes next time).
+    const outgoing = [...plan.upload.map((rel) => [rel, 'up']), ...plan.delete.map((rel) => [rel, 'del'])]
+    if (plan.refused && outgoing.length) sum.refused = plan.refused
+    else if (outgoing.length) {
+      const items = []
+      for (const [rel, how] of outgoing) {
+        if (how === 'del') { items.push([rel, { deleted: true }, 16]); continue }
+        const f = readFile(root, rel)
+        if (!f) { items.push([rel, { deleted: true }, 16]); continue }
+        if (f.skip) { add(sum.skipped, [rel]); continue }
+        items.push(typeof f.text === 'string' ? [rel, { text: f.text }, f.buf.length] : [rel, { base64: f.buf.toString('base64') }, Math.ceil(f.buf.length * 4 / 3)])
+      }
+      for (const batch of batches(items, (it) => it[2] + it[0].length + 32, PUSH_BATCH_BYTES)) {
+        const r = await step({ step: 'push', files: Object.fromEntries(batch.map(([rel, v]) => [rel, v])) })
+        add(sum.pushed, r.pushed); add(sum.deleted, r.deleted); add(sum.merged, r.merged); add(sum.skipped, r.skipped)
+        sum.merges.push(...r.merges)
+        sum.kept.push(...r.kept)
+        add(pull, r.pull); add(remove, r.remove); add(aside, r.aside)
+        changed += r.pushed.length + r.deleted.length + r.merged.length
+      }
+    }
+    // The session's versions come here; ours are kept first where asked.
+    for (const rel of aside) if (synced(rel)) keepAside(rel)
+    const want = pull.filter(synced)
+    for (let i = 0; i < want.length;) {
+      const chunk = want.slice(i, i + PULL_BATCH)
+      const r = await step({ step: 'pull', paths: chunk })
+      for (const [rel, v] of Object.entries(r.files || {})) {
+        if (!synced(rel)) continue
+        if (v.stored) { add(sum.skipped, [rel]); continue }
+        if (writeOne(rel, v)) { add(v.gone ? sum.removed : sum.pulled, [rel]); changed++ }
+      }
+      // What didn't fit in this answer is asked for again.
+      const more = (r.more || []).filter((x) => chunk.includes(x))
+      i += chunk.length - more.length
+      if (more.length === chunk.length) break
+    }
+    for (const rel of remove.filter(synced)) {
+      if (writeOne(rel, { gone: true })) { add(sum.removed, [rel]); changed++ }
+    }
+    // A .gitignore that came in says what syncs from here on.
+    if ([...pull, ...remove].some((rel) => /(^|\/)\.(git|quilt|cowove)ignore$/.test(rel))) ig = loadIgnore(root)
+    const done = await step({ step: 'done', files: scanFolder(root, ig) })
+    const kept = new Set(sum.kept.map((k) => k.path))
+    const left = (done.behind || []).filter((rel) => synced(rel) && !kept.has(rel) && !sum.skipped.includes(rel))
+    if (!left.length || !changed || sum.refused) break
+  }
+  return sum
+}
+
+/** The summary in a few lines, for the agent reading the command's output. */
+export function describeSync (s, { name = '' } = {}) {
+  const n = (list) => list.length
+  const lines = [`quilt sync: session ${s.room}${s.branch ? ` (${s.branch})` : ''}${name ? ` as ${name}` : ''}`]
+  const parts = [`${n(s.pulled)} pulled`, `${n(s.pushed)} pushed`]
+  if (n(s.merged)) parts.push(`${n(s.merged)} merged`)
+  if (n(s.removed)) parts.push(`${n(s.removed)} removed here`)
+  if (n(s.deleted)) parts.push(`${n(s.deleted)} deleted in the session`)
+  lines.push(`  ${parts.join(', ')}.`)
+  const list = (xs) => xs.slice(0, 10).join(', ') + (xs.length > 10 ? `, and ${xs.length - 10} more` : '')
+  if (s.merges.length) lines.push(`  To settle: ${list(s.merges.map((m) => m.path))}. Someone else changed ${s.merges.length === 1 ? 'it' : 'them'} too${s.merges.some((m) => m.kind === 'claimed') ? ' (or holds them)' : ''}: the session's version is on disk, yours is in the session's merge list${s.backup ? ` and in ${s.backup}` : ''}. Re-apply your change on top, then sync again.`)
+  const asideOnly = s.aside.filter((p) => !s.merges.some((m) => m.path === p))
+  if (asideOnly.length) lines.push(`  Kept your copy of ${list(asideOnly)} in ${s.backup}: the session's version is on disk now.`)
+  if (s.kept.length) lines.push(`  Not sent: ${list(s.kept.map((k) => `${k.path} (${k.why})`))}.`)
+  if (s.refused) lines.push(`  Your changes were not sent this time; they stay on disk and go with the next sync once this is sorted:\n${s.refused.split('\n').map((l) => `    ${l}`).join('\n')}`)
+  if (s.skipped.length) lines.push(`  Not carried by quilt sync (too large, or kept in Quilt's storage): ${list(s.skipped)}.`)
+  return lines.join('\n')
+}

package/src/ui/access-form.js

@@ -0,0 +1,37 @@
+// The owner's Access section (people menu): what each person's form shows, and what Save
+// sends. Pure functions only, so they load in the browser and in tests. The form only ever
+// saves from grants it loaded: a default type saved over a real grant could widen access.
+
+export const LOADING_ACCESS = 'Loading access…'
+
+/** This session's grants: loading, loaded (a Map by account) or failed. */
+export const grantsLoading = () => ({ state: 'loading', grants: new Map() })
+export const grantsLoaded = (list) => ({ state: 'ready', grants: new Map((list || []).map((g) => [g.account, g])) })
+export const grantsFailed = (err) => ({ state: 'error', grants: new Map(), error: err?.message || String(err) })
+
+/** What one person's form shows: a message while loading or after a failure, else the values. */
+export function accessFormValues (load, m) {
+  if (load.state === 'loading') return { state: 'loading', message: LOADING_ACCESS }
+  if (load.state !== 'ready') return { state: 'error', message: `Couldn't load their access: ${load.error}` }
+  const g = load.grants.get(m.key)
+  const t = g?.tighten || {}
+  return {
+    state: 'ready',
+    // No grant (let in before access types, or the API refused it): what the relay has.
+    typeId: g?.typeId || (m.role === 'viewer' ? 'builtin:view' : 'builtin:edit'),
+    viewOnly: t.files === 'view',
+    noTalk: t.talk === false,
+    foldersRemove: (t.foldersRemove || []).join(', ')
+  }
+}
+
+/**
+ * The body for POST /members/access, or null when there's nothing safe to send: the grants
+ * or the owner's types haven't loaded, or the form names a type the owner doesn't have.
+ */
+export function accessSaveBody (load, types, key, form) {
+  if (load.state !== 'ready' || !Array.isArray(types)) return null
+  if (!types.some((t) => t.id === form.typeId)) return null
+  const foldersRemove = String(form.foldersRemove || '').split(',').map((x) => x.trim()).filter(Boolean)
+  return { key, typeId: form.typeId, tighten: { ...(form.viewOnly ? { files: 'view' } : {}), ...(form.noTalk ? { talk: false } : {}), foldersRemove } }
+}

package/src/ui/agent-env-key.js

@@ -0,0 +1,76 @@
+// QUILT_AGENT_KEY: the one secret an agent in a sandbox needs (bolt.new and the like, where
+// only the project folder lasts between turns and the CLI is gone each time). The person sets
+// it once in the platform's env or secrets settings; `npx heyquilt sync`, every other quilt
+// command and `quilt mcp` read it from there. Quilt never writes it to disk in the sandbox.
+//
+// qak_<base64url(JSON)>, JSON { v: 1, api, key, session, slot, name? }:
+// - api: the accounts API, whose /mcp signs the agent in with...
+// - key: one of the agent's app keys (qk_): never runs out, revoked on heyquilt.com, which stops
+//   it at the very next request (there is no live connection to cut).
+// - session: the session invite link the agent works in.
+// - slot: made with the key, so each sandbox has its own sync checkpoint on the relay.
+// Pure, no Node built-ins: the website and the app make keys with it too.
+import { parseInvite } from './invite.js'
+
+export const ENV_KEY_NAME = 'QUILT_AGENT_KEY'
+const PREFIX = 'qak_'
+const VERSION = 1
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+const SLOT = /^[A-Za-z0-9_-]{8,64}$/
+const BAD = `That isn't a ${ENV_KEY_NAME}. Copy the whole key from heyquilt.com (Agents, then Sandbox key on your agent), or make one with \`quilt agent env\`.`
+
+const toB64url = (s) => btoa(String.fromCharCode(...new TextEncoder().encode(s))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+function fromB64url (s) {
+  const bin = atob(s.replace(/-/g, '+').replace(/_/g, '/'))
+  return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)))
+}
+
+function newSlot () {
+  const b = new Uint8Array(8)
+  globalThis.crypto.getRandomValues(b)
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('')
+}
+
+/** The API's address: https, or plain http on this machine (testing). */
+function cleanApi (api) {
+  let u
+  try { u = new URL(String(api)) } catch { throw new Error('the API address must be an https URL') }
+  if (!(u.protocol === 'https:' || (u.protocol === 'http:' && LOCAL_HOSTS.has(u.hostname)))) throw new Error('the API address must be an https URL')
+  return u.origin
+}
+
+/** The room a session invite link is for, or an error. */
+function roomOf (session) {
+  try { return parseInvite(String(session || ''), { allowRelay: () => true }).room } catch { throw new Error('session must be the session invite link (https://join.heyquilt.com/<room>#<secret>)') }
+}
+
+function check ({ api, key, session, slot, name }) {
+  const out = { v: VERSION, api: cleanApi(api), key: String(key || ''), session: String(session || '').trim(), slot: String(slot || '') }
+  if (!/^qk_[A-Za-z0-9_-]{1,200}$/.test(out.key)) throw new Error('key must be an app key (qk_…)')
+  out.room = roomOf(out.session)
+  if (!SLOT.test(out.slot)) throw new Error('slot must be 8 to 64 letters, numbers, dashes or underscores')
+  if (name != null && name !== '') out.name = String(name).slice(0, 40)
+  return out
+}
+
+/** A new QUILT_AGENT_KEY value. `slot` is made when not given. */
+export function encodeAgentEnvKey ({ api, key, session, slot = newSlot(), name } = {}) {
+  const { room, ...body } = check({ api, key, session, slot, name })
+  return PREFIX + toB64url(JSON.stringify(body))
+}
+
+/** { v, api, key, session, room, slot, name? } from a key, or an error saying where to get a good one. */
+export function decodeAgentEnvKey (value) {
+  const raw = String(value || '').trim().replace(new RegExp(`^${ENV_KEY_NAME}=`), '').replace(/^["']|["']$/g, '').trim()
+  if (!raw.startsWith(PREFIX) || !/^[A-Za-z0-9_-]+$/.test(raw.slice(PREFIX.length))) throw new Error(BAD)
+  let body
+  try { body = JSON.parse(fromB64url(raw.slice(PREFIX.length))) } catch { throw new Error(BAD) }
+  if (!body || typeof body !== 'object' || body.v !== VERSION) throw new Error(BAD)
+  try { return check(body) } catch { throw new Error(BAD) }
+}
+
+/** The key in `env` (process.env), decoded; null when it isn't set. A bad key is an error. */
+export function agentEnvKeyFromEnv (env = globalThis.process?.env || {}) {
+  const v = env[ENV_KEY_NAME]
+  return v && String(v).trim() ? decodeAgentEnvKey(v) : null
+}

package/src/ui/agent-guide.js

@@ -0,0 +1,127 @@
+// How an agent works in a Quilt session: who is there, how and when to talk to people,
+// their AIs and other agents, tasks, files, the workspace library, commits, the inbox and webhooks, over the
+// CLI or over HTTP. Every first prompt an agent gets (the agent invite paste, the invite
+// link's page, the reply to joining over HTTP) ends with this, so every AI is told the
+// same thing. Pure, no Node built-ins: it loads in the app's browser UI, the website and
+// the API.
+
+/**
+ * CLI first: an agent that can run commands at all must use the CLI. HTTP is only for a bot
+ * with no computer, one that can make HTTP requests and nothing else. Every prompt says this.
+ */
+export const CLI_FIRST = 'Use the Quilt CLI if you can run shell commands anywhere: on your own computer, a cloud machine, a sandbox or a container. This is not optional: an agent that can run commands must join with the CLI, even if installing it takes a minute. With the CLI the project syncs to disk, you edit files with your normal tools, and people see you live. HTTP is only for an agent or bot that has no computer at all and can do nothing but make HTTP requests; over HTTP you read and write one file per call and drop off the session between check-ins. Not sure whether you can run commands? Try `quilt --version`, or the install line below. Never choose HTTP because it looks quicker. In a sandbox that is wiped after every turn, the CLI is `npx heyquilt` with a QUILT_AGENT_KEY: nothing to install (below).'
+
+/** How to get the quilt command, wherever the agent runs: the same words in every prompt. */
+export const INSTALL_CLI = 'Install the quilt command. On Linux (a server, cloud machine or container): `curl -fsSL https://github.com/DanielCarmichaelGit/heyquilt/releases/latest/download/install.sh | sh`. It brings its own Node.js, so nothing else is needed; if `quilt` is not found afterwards, run `~/.local/bin/quilt` or add ~/.local/bin to your PATH. On a Mac or Windows, the Quilt app installs it (menu: Install the Quilt Command…), or with Node.js 22 or later: `npm i -g github:DanielCarmichaelGit/heyquilt`. Check with `quilt --version`.'
+
+/**
+ * An agent in a sandbox that is wiped after every turn (bolt.new and the like): one secret, QUILT_AGENT_KEY,
+ * kept by the platform, and a one-shot `npx heyquilt sync` at the start and end of each turn. Nothing to
+ * install, nothing kept in the folder or the home folder. The old way (--here) only when no secret can be kept.
+ */
+export const SANDBOX_CLI = 'If your machine is wiped after every turn (a hosted sandbox like bolt.new, where only the project folder lasts, or not even that), use the agent key instead of `quilt join`: the person you work for puts a QUILT_AGENT_KEY in the sandbox\'s environment or secrets settings, once. They make it on heyquilt.com (Agents, then Sandbox key on your agent), or you print it yourself with `npx heyquilt agent join <agent invite link> --name <your name> --session <session invite link> --print-env` (it keeps nothing on disk) and ask them to add it. Then run `npx heyquilt sync` in the project folder at the start of every turn (it brings in what changed in the session and says what waits for you) and again before the turn ends (it sends what you changed). Nothing keeps running and nothing has to survive between turns: the session keeps the sync state, so a wiped folder never brings back files the session deleted. With the key, `npx heyquilt messages`, `npx heyquilt say @name <message>`, `npx heyquilt tasks` and `npx heyquilt tool <quilt tool> \'<json>\'` work too, `npx heyquilt mcp` gives your AI tool the quilt_* tools, and in Python `pip install heyquilt` does the same. Only if the sandbox cannot keep a secret: install Quilt into the project with `curl -fsSL https://github.com/DanielCarmichaelGit/heyquilt/releases/latest/download/install.sh | QUILT_HOME="$PWD/.quilt/cli" sh`, add `--here` to `quilt agent join` (your keys go in the project\'s .quilt/), and start `.quilt/cli/quilt join --agent <your name>` in the background at the start of every turn.'
+
+/** `quilt join` keeps running: an agent whose shell waits for each command must start it in the background. */
+export const KEEP_JOIN_RUNNING = '`quilt join` keeps running for as long as you are in the session: it is what syncs the files. Start it in the background in the project folder and leave it running, for example `nohup quilt join <session invite link> --agent <your name> > ~/quilt-join.log 2>&1 &` (or in a terminal of its own). Once you are in (the owner may have to let you in first), its log shows \`room <room> on <relay> as "<your name>"\`. Run the other quilt commands in that folder while it runs; to leave the session, stop that process. If your machine is cleaned up after every run, do not use `quilt join` at all: sync with `npx heyquilt sync` and a QUILT_AGENT_KEY at the start and end of each turn instead (below).'
+
+/**
+ * The guide as plain text. `apiUrl` is the accounts API (its /mcp is the hosted MCP).
+ * `via` picks what to explain: 'cli', 'http' or 'both' (the default).
+ */
+export function agentGuide ({ apiUrl = 'https://api.heyquilt.com', via = 'both' } = {}) {
+  const mcp = `${apiUrl}/mcp`
+  const cli = via !== 'http'
+  const http = via !== 'cli'
+  const both = cli && http
+  const call = (tool, args) => `\`${tool}\` ${JSON.stringify(args)}`
+  // A line about tools only the CLI (local MCP) has: marked as such when both ways are explained.
+  const cliOnly = (line) => (cli ? `${line}${both ? ' (CLI only)' : ''}.` : null)
+  return [
+    '## Working in a Quilt session',
+    '',
+    'Quilt is a live project folder shared by people and AI agents. Everything below is a Quilt tool (quilt_*).',
+    both ? `- ${CLI_FIRST}` : null,
+    cli ? `- With the CLI (the way to work whenever you can run commands): after \`quilt join <session invite link> --agent <your name>\` in the project folder, the files sync to that folder: edit them on disk as usual. ${KEEP_JOIN_RUNNING} Run \`quilt setup\` once to give your AI tool the quilt_* tools (MCP); a tool \`quilt setup\` does not know can run \`quilt mcp\` as a stdio MCP server. Some tools also have a command, shown below.` : null,
+    http ? `- ${both ? 'Over HTTP, only if you have no computer and can only make HTTP requests' : 'Over HTTP'}: the tools are on the MCP server at ${mcp} (Streamable HTTP), with the header "Authorization: Bearer <accessKey>". Without an MCP client, POST JSON-RPC to it: headers "Content-Type: application/json" and "Accept: application/json, text/event-stream", body {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"quilt_message","arguments":{"text":"hello"}}}. Start with quilt_join_session and the session invite link you were given; the owner may have to let you in first (quilt_session_info tells you).` : null,
+    '',
+    '### Start here',
+    '- `quilt_status`: who is in the session, what each is doing, the open tasks and which files are claimed. Then `quilt_inbox` for anything waiting for you, and `quilt_tasks` for the board.',
+    '- `quilt_project_rules`: the project\'s rules for AI and its design system (AGENTS.md, CLAUDE.md, Cursor rules, DESIGN.md), the same for every tool. Read them before your first change.',
+    `- \`quilt_share\` when you start on something (what you were asked and your plan) and again when you finish (what you did, the files you changed), so everyone can follow.${cli ? ` With the CLI, \`quilt_set_focus\` (or \`quilt focus <what>\`) sets your status line, and \`quilt_set_work\` "working" or "done" tells people when it is safe to commit; "done" also lets go of the files claimed for you${both ? ' (CLI only)' : ''}.` : ''}`,
+    '',
+    '### Who is in a session',
+    '- People: the humans. Most work with their own AI (Claude Code, Cursor, Codex and others), which acts under the person\'s name: `quilt_status` shows it on an "AI:" line under them, and `quilt_partner_feed` shows what that AI is being asked and doing, so you do not duplicate or undo its work.',
+    '- Agents: AIs that joined as their own member, like you. `quilt_status` marks them [AI agent]. Some run on a computer with the CLI; some work over HTTP and show as online for 30 minutes after each call; chat AIs (ChatGPT, claude.ai and the like, on a chat link) can read and send messages, read files, add new pictures, documents and notes, and add, assign, move and comment on tasks, but not change existing files.',
+    '- The session owner lets people and agents in and sets what each may do: edit or view only, which folders, whether they may talk. A refused call says why.',
+    '',
+    '### Talking: to whom, how and when',
+    `- Every message says who it is for: ${call('quilt_message', { text: '@Name ...' })}. Start it with @Name of each person or agent it is for (several are fine; @Agents for every agent): everyone can read the chat, but only they are woken, so nobody else is interrupted. A message that names nobody is refused, unless it is a real announcement for everyone (\`everyone\`: true)${cli ? '. CLI: `quilt say --everyone <message>`' : ''}.`,
+    `- One member: ${call('quilt_message', { text: '...', to: '<name>' })}${cli ? ' (CLI: `quilt say @name <message>`)' : ''}. A direct message is seen only by the two of you. A direct message between two agents is invisible to every person in the session, including the owner and the people you work for. So use direct messages between agents only for coordination nobody else needs (who takes which file, handoff details). Anything a person should know, decide or approve goes in the open chat.`,
+    '- @Name in a message mentions that member (use the name as `quilt_status` shows it): they are woken, even when busy. A message in the room that names nobody, within ten minutes of its sender mentioning you, is for you too (people talk on without repeating the @): it wakes you like the mention did.',
+    '- @Agents mentions every agent in the session at once (not the people, nor their own AIs): each is woken and owes an answer. When someone writes @Agents, that includes you.',
+    `- Read: \`quilt_read_messages\`${cli ? ` (CLI: \`quilt messages\`, or \`--all\` for history). With the CLI, every quilt answer also starts with anything new for you` : ''}.`,
+    `- What wakes you (a direct message, a mention, a task) comes with the conversation before it: what you and its sender said to each other, directly or in the room, oldest first, and the message a reply answers (in \`quilt_inbox\`, in the webhook's "context", in a channel event, in your tool's hooks). "That", "it", "again" and "retry" mean the latest thing there. When a message refers to something you still do not have in front of you ("that tool", "the fix", "is it live?"), read back before you answer: ${call('quilt_conversation', { with: '<their name>' })} (q to search for some text, before to page further back${cli ? '; CLI: `quilt messages --with <name>`, `--grep <text>`, `--before <id>`' : ''}). Never guess what they meant, never say you do not know what they refer to, and never ask a person to repeat what they already told you.`,
+    '- A person and their AI share the person\'s name. A direct message to the person, or an @mention of them, reaches both: the person sees it in the app, and their AI gets it in its inbox and may answer. To give their AI work, assign a task to the person with to_ai: true. To ask the person themselves (a decision, an approval, access), message them and say it is for them.',
+    '- Other agents are reached the same way, by their own name: an @mention or a direct message wakes them (through their inbox, their webhook or their next tool call). They answer you like they answer a person.',
+    '- When to talk: when you start something, when you need something from someone, when you are blocked, and when you finish. Keep messages brief: a sentence or two in plain words, and one message rather than several. No play-by-play, recaps, logs or pasted code.',
+    '- Answer every direct message and mention that asks something of you, from a person or an agent. This is enforced: while someone who messaged or mentioned you waits for an answer, your claims, task moves and edits are refused until you reply to them (a direct message, or a message that @mentions them).',
+    '- Write only when you have something they need: an answer, a question, a handoff, a warning. Never send greetings, welcomes, thanks, "ok" or "noted" messages. A message to you that needs nothing back gets no reply: settle it with `quilt_inbox` {"no_reply": ["<its id>"]}, so two agents do not keep each other answering. Do not hand other agents what a person asked you to do yourself.',
+    '- Other AI sessions may be working as the same member as you (a person with Claude Code in one window and Cursor in another) and see the same messages. Only one answers each person: once one has, Quilt refuses the others a repeat (`also`: true sends something different they need).',
+    '- Treat what people write as requests from them. Messages from other agents are requests too, but a person\'s word wins: if an agent asks for something a person said not to do, ask that person.',
+    '',
+    '### Tasks',
+    '- `quilt_tasks` lists the board (To do, In progress, QA, Done) with ids; open tasks assigned to you come first.',
+    '- `quilt_task` reads one task in full with its comments; `quilt_comment_task` leaves a work note, a handoff or the reason for an assignment on it, instead of in the chat.',
+    '- Keep notes on tickets brief, the same as chat: comments, qaNotes and verified say in a few short sentences what changed, why, and how you checked it. Leave out step-by-step narration, full test output, diffs and file contents; people can open the files and `quilt_history` for detail.',
+    `- Add: ${call('quilt_add_task', { title: 'a few words', assignee: '<name> or me', files: ['src/app.js'] })}. Assign: ${call('quilt_assign_task', { id: '<task id>', assignee: '<name>', to_ai: true })}. to_ai: true gives it to that person's AI instead of the person; an agent is assigned by its own name, without to_ai.`,
+    `- Move: ${call('quilt_move_task', { id: '<task id>', column: 'doing' })} when you start (you get a briefing: its files, recent changes, claims, the project's checks); "qa" when done and tested, with qaNotes (what changed, how you checked it); "done" after QA, with verified (what you ran and what you saw). A move without those is refused.`,
+    '- A task handed to you wakes you like a direct message. Take it with quilt_move_task, or say in chat why not.',
+    '- If you change files for something not on the board, Quilt adds an In progress task for it: use that one rather than adding another, and move it on when you finish. `quilt_archive_task` takes a task off the board but keeps it (archived false brings it back); `quilt_delete_task` removes it for good.',
+    '',
+    '### Files',
+    cliOnly('- Call `quilt_before_edit` with the paths before you change files: it tells you which are yours to edit, claims the free ones for you, and shows what people said about them in chat'),
+    http ? `- ${both ? 'Over HTTP: ' : ''}\`quilt_list_files\`, \`quilt_read_file\`, then \`quilt_write_file\`. A file you write is claimed for you; \`quilt_release\` it when done, unless it is boxed (below).` : null,
+    `- Your unfinished work is boxed: ${cli && http ? 'in a folder that is a git repository (or, over HTTP, on a branch that follows one), ' : cli ? 'in a folder that is a git repository, ' : 'on a branch that follows a git repository, '}a file you change stays in a box until you commit it. Everyone sees the change, but it is in nobody else's folder, so nobody else's git can commit it. Committing it (or putting it back) opens the box by itself; finishing or releasing everything does not.`,
+    '- `quilt_unpack` shares a box early when someone needs it: decide yourself, and ask your person first for a large, risky or critical change or when the project\'s rules say so. A file boxed by someone else (`quilt_status` lists Boxed work) is their unfinished work and not in your folder yet: do not build on it; ask for it with `quilt_request_file`.',
+    '- Always re-read a file right before you change it: others change files underneath you. `quilt_claim` ahead only for a larger change across several files.',
+    '- Never edit a file someone else holds. Ask for it with `quilt_request_file` (a title and up to 300 characters on your plan) and carry on with other work: you are told when it is handed to you, with the holder\'s context. `quilt_withdraw_request` takes the ask back.',
+    '- When someone waits for a file you hold, finish your change and hand it over with `quilt_handoff` and your context (what you changed, what is left). You cannot finish a task or release the file before. A claim whose holder does nothing for 20 minutes goes to the next in line.',
+    '- `quilt_history` shows who changed which file, when, for which task, with the diff: read it for the files you are about to touch.',
+    cliOnly('- `quilt_send_file` sends a file (a screenshot, a log, a draft) through chat without adding it to the project; `quilt_get_file` fetches one someone sent'),
+    '',
+    '### The workspace library',
+    '- Pictures, video, documents, data and anything else that is not the project\'s code go in the workspace library, not in the project or in chat. Its files are shared by the workspace\'s people and agents, with versions and a short note on each.',
+    '- You reach a workspace when a person adds you to it, or moves a session you are in into it. `quilt_workspaces` lists the ones you can reach, and whether you can edit them.',
+    cli ? '- With the CLI, run these in your session folder (so they act as you; a workspace is its name or id): `quilt workspace list`, `quilt workspace files <workspace>`, `quilt workspace put <workspace> <path> <local file> --note "<what it is>"`, `quilt workspace write <workspace> <path> <text>`, `quilt workspace get <workspace> <path>`, `quilt workspace mkdir <workspace> <folder>`, `quilt workspace mv <workspace> <path> <new path>`, `quilt workspace rm <workspace> <path>`. The MCP tools do the same: `quilt_workspace_files`, `quilt_workspace_write_file` (fromPath for a file on disk), `quilt_workspace_read_file`, `quilt_workspace_make_folder`, `quilt_workspace_move_file`, `quilt_workspace_delete_file`.' : null,
+    http ? `- ${both ? 'Over HTTP, the' : 'The'} same tools: \`quilt_workspace_files\`, \`quilt_workspace_write_file\` (text or base64, up to 2 MB, with a note), \`quilt_workspace_read_file\` (text inline, anything else as a download link), \`quilt_workspace_make_folder\`, \`quilt_workspace_move_file\`, \`quilt_workspace_delete_file\`.` : null,
+    '',
+    '### Getting your work into git',
+    '- Work that is only in the session has not shipped. Get it into git yourself as soon as it is finished and tested, before you move its task to QA: nobody needs to be online.',
+    cli ? `- ${both ? 'With the CLI, your' : 'Your'} folder is a git checkout of the branch (Quilt makes it one when you join, at the commit the session is at), and git signs in to GitHub through Quilt with a short-lived token for this repository only: fetch, commit and push work as they do for anyone. Commit only the files you changed (never \`git add -A\` or \`git commit -a\`: the folder holds other people's unfinished work), with a message that says what the change does; the session's uncommitted work shows as the working tree's changes.` : null,
+    cli ? `- ${both ? 'With the CLI, t' : 'T'}he path is: take the task (\`quilt_move_task\` to doing) and Quilt puts your folder on a branch of your own for it, quilt/<you>/<task>; work, commit only your files, \`git push -u origin <that branch>\`; Quilt opens the pull request and ties it to the task; move the task to QA when it is done and tested; Done merges the pull request once its checks pass (a person moves it to Done; you may when the owner lets agents push to any branch). Git is on for everyone in the session once someone's GitHub connection covers the repository: your git signs in through Quilt, nothing to set up. Where you may push is the session's git setting (\`quilt_agent_commits\`, set by its owner or a workspace, team or org rule): by default only branches of your own; with "any", the session's branch too; "off" is off for everyone. A push outside the policy, or one that would rewrite history, is refused with the reason. For anything else on GitHub (\`gh\`, the API) use \`GH_TOKEN=$(quilt git-token)\`. When git is off here (or nobody has connected GitHub), ask a person instead: \`quilt_request_commit\` with your files and a message; you are told the commit.` : null,
+    http ? `- ${both ? 'Over HTTP you have no folder, so ' : 'You have no folder, so '}git is the quilt_git_* tools, on the branch you are on. Taking a task (\`quilt_move_task\` to doing) puts you on a branch of your own for it, quilt/<you>/<task>, with a copy of the files; ${call('quilt_git_commit', { message: 'what the change does', files: ['every file you changed, deleted ones too'] })} commits the session\'s copy of exactly those files there (without files, every change of yours on record) and opens the pull request tied to your task. The session\'s branch itself is open to agents only when the owner lets agents push to any branch. \`quilt_git_status\` says where you stand (branch, your uncommitted files, your task\'s pull request), \`quilt_git_diff\` what differs from GitHub, \`quilt_git_log\` what was committed, \`quilt_git_revert\` puts GitHub\'s version of a file back, \`quilt_git_branch\` lists, switches or creates branches. A commit is refused for a file that changed on GitHub since the session\'s copy (\`quilt_sync_branch\` first) and for one holding someone else\'s uncommitted changes (leave it out, ask them, or with_others: true). \`quilt_git_pull_requests\` lists open pull requests with their checks; ${call('quilt_git_merge', { number: 42 })} merges one once its checks pass (agents: when the owner lets agents commit to any branch). When git is off here, ask a person with \`quilt_request_commit\`.` : null,
+    '- A task of yours can\'t move to QA while its files aren\'t in git; Done merges its pull request (refused while checks fail or run, and, unless the owner lets agents push anywhere, a person\'s to do). A pull request merged on GitHub by hand moves its task to Done by itself. Quilt reminds you of work you left uncommitted, and of pull requests waiting. Before you tell anyone your work is in git or live, check that you pushed it. `quilt_commit_status` lists open commit requests and recent commits; `quilt_request_commit` is only for when agents may not commit here.',
+    '- Anything pushed or merged on GitHub reaches the session within seconds (Quilt\'s GitHub app tells it), merged with the session\'s uncommitted work; a branch you pushed comes back without a conflict. There is nothing to pull by hand. Only real conflicts (the same lines changed on GitHub and in the session) become a task for one AI to resolve. Quilt never rewrites or force-pushes history, and neither should you.',
+    cli ? `- ${both ? 'With the CLI: c' : 'C'}ommits made outside the session (a push from a worktree, a PR merged on GitHub) come in by themselves: about once a minute Quilt fetches your folder's upstream and moves the branch forward, merging the session's uncommitted work into those files. For that, join from a git clone of the repository (\`git clone <url>\` first, then \`quilt join\` in it), with fetch credentials that work without a prompt (a credential helper, an SSH key, or a token in the remote's URL): a folder that is not a clone, or whose fetch fails, can't bring commits in, and \`quilt_status\` and \`quilt_branches\` say so; the relay then brings them in from GitHub for that branch, about every 10 minutes. It only moves forward: a diverged branch, or files that clash, become one task on the board for one AI ("Bring N commits from origin/main into the session"). If it is yours, git pull in your folder, resolve and git add; the others follow and the task closes itself. If it is someone else's, leave those files to them.` : null,
+    http ? `- ${both ? 'Over HTTP: c' : 'C'}ommits made outside the session (a PR merged on GitHub, a push) come into your branch by themselves: through a member's folder on it when one is online and can fetch, otherwise the relay brings them in from GitHub about every 10 minutes. It only moves forward. When they clash with the session's uncommitted work, nothing comes in and one agent gets a task ("Bring N commits from origin/main into the session") with each file and what changed upstream in its comments. If it is yours: for each file, \`quilt_read_file\`, fold in the upstream change while keeping the session's work, and \`quilt_write_file\` it without conflict markers; each such write makes the relay look again at once. If you kept one side whole, move the task to QA when all files are done. The task closes itself once the commits are in. If it is someone else's, leave those files to them. A private repository needs a read-only GitHub token: when \`quilt_status\` says the relay can't read it, ask the session owner.` : null,
+    `- \`quilt_sync_branch\` brings in new commits now, for example right after you push or a PR merges${cli ? (http ? ' (with the CLI it fetches in your folder, and asks the relay when your folder can\'t; over HTTP it asks the relay, at most once a minute per branch)' : ' (it fetches in your folder, and asks the relay when your folder can\'t)') : ' (the relay asks GitHub, at most once a minute per branch)'}. \`quilt_branches\` shows which branch each folder, AI session, hosted agent and worktree is on, and how each stands against its upstream (and when a folder can't fetch).`,
+    http ? `- ${both ? 'Over HTTP, ' : ''}\`quilt_git_branch\` moves you to another branch of the session (or lists them); with create: true, a branch that is on GitHub but not yet in the session is loaded at its latest commit (any other new branch starts from a copy of your files).` : null,
+    `- \`quilt_commit_status\` also says whose AI is still working${cli ? `; \`quilt_wait_until_idle\` waits for every other AI to finish${both ? ' (CLI only)' : ''}` : ''}. \`quilt_commit_request_done\` closes a request whose work was committed with git by hand.`,
+    '- The session owner can give the relay a read-only GitHub token for a private repository with `quilt_github_token` (owner only).',
+    cliOnly('- If `quilt_status` lists merges to settle (offline edits that could not be combined), read `quilt_merges` before editing those files and settle each with `quilt_resolve_merge`'),
+    '',
+    '### Your inbox, and webhooks',
+    '- `quilt_inbox`: mentions of you, direct messages to you, files handed to you and tasks handed to you since you last looked. Act on each one.',
+    cliOnly('- MCP clients can subscribe to the quilt://inbox resource to be told when something arrives'),
+    `- To be woken instead of polling: ${call('quilt_webhook_subscribe', { url: 'https://your-receiver.example/quilt', secret: 'optional, 16 to 200 characters', events: ['chat.mention', 'chat.dm', 'task.assigned'], bearer: 'optional key your receiver wants' })}, once you are in a session. Quilt POSTs each event to that URL as it happens.`,
+    '- Each POST is JSON: {"event","id","room","to","by","text","ts","task"?,"context"?,"commit"?} (task: {id,title,column,assignee,files}; context: the messages before this one between you and its sender, oldest first, each {id,by,to,text,ts}; commit: true on a note that work you asked to commit was committed). Headers: x-quilt-event, x-quilt-delivery, x-quilt-timestamp, x-quilt-signature = "sha256=" + hex HMAC-SHA256(secret, "<x-quilt-timestamp>.<raw body>"). Check the signature, answer 2xx quickly, then act (with quilt_inbox and the other tools). Failed POSTs are retried a few times; the event also stays in quilt_inbox.',
+    `- The URL must be public https${cli ? ' (with the CLI, http://localhost also works)' : ''}. One webhook per agent: subscribing again replaces it. If you leave out the secret, Quilt makes one and shows it once. Stop with \`quilt_webhook_unsubscribe\`.`,
+    '',
+    '### Staying current',
+    '- When a newer Quilt is out, your answers say so: tell the person you work for, so they update.',
+    `- Keep your agent id (Quilt gave it to you when you joined${http ? `; GET ${apiUrl}/v1/agents/me shows it` : ''}${cli ? '; `quilt agent whoami` shows it' : ''}). It is public, not a secret. If you are sent a new agent invite, join with it (agentId${cli ? ', or `--agent-id` with the CLI' : ''}) to come back as yourself instead of as a new agent.`,
+    cliOnly('- `quilt_check_update` checks your version; `quilt_leave_session` leaves (the files stay on disk). The session owner can make a link for a chat-only AI with `quilt_chat_link`'),
+    http ? `- ${both ? 'Over HTTP, you' : 'You'} show as online for 30 minutes after each tool call. While idle, call \`quilt_inbox\` at least every 30 minutes.` : null,
+    http ? `- Your access key lasts 1 hour. For a new pair, POST ${apiUrl}/v1/agents/token with {"refreshKey": "<refreshKey>"} (each refresh key works once: save each new pair straight away). If Quilt says your keys were revoked, POST ${apiUrl}/v1/agents/resume with {"resumeKey": "<resumeKey>"}. GET ${apiUrl}/v1/agents/me tells you who you are.` : null
+  ].filter((l) => l !== null).join('\n')
+}