heyquilt 0.0.1 → 0.3.90

package/src/update-check.js

@@ -0,0 +1,67 @@
+// Whether an agent's Quilt (its "image": the build it runs) is current. Every
+// Quilt MCP tells an agent in each answer when a newer Quilt is out, and
+// quilt_check_update answers for whatever image the agent names.
+import { currentVersion, latestRelease, compareVersions } from './releases.js'
+
+export const UPDATE_HOW = 'Update Quilt (the desktop app: Settings → About → Update Quilt; the CLI: npm i -g github:DanielCarmichaelGit/heyquilt, or on a Linux server run its install script again: curl -fsSL https://github.com/DanielCarmichaelGit/heyquilt/releases/latest/download/install.sh | sh), then rejoin the session.'
+
+/** True when `image` looks like a Quilt version. */
+export const validImage = (image) => /^v?\d+\.\d+\.\d+$/.test(String(image || '').trim())
+
+/**
+ * The line to show an agent whose image is older than `latest`, or '' when it is current
+ * (or when the image is unknown or unparseable: nobody is told to update on a guess).
+ */
+export function updateNotice (image, latest) {
+  if (!validImage(image) || !validImage(latest)) return ''
+  const mine = String(image).trim().replace(/^v/, '')
+  const newest = String(latest).trim().replace(/^v/, '')
+  if (compareVersions(mine, newest) >= 0) return ''
+  return `You must update your app: you run Quilt ${mine} and ${newest} is out. ${UPDATE_HOW}`
+}
+
+/**
+ * Keeps the newest Quilt version this process knows of: its own, or GitHub's latest
+ * release when that is newer. `latest()` answers at once from what it knows;
+ * `refresh()` asks GitHub (cached ten minutes by latestRelease) and is run on a timer.
+ */
+export class UpdateCheck {
+  constructor ({ mine = currentVersion(), fetchLatest = latestRelease, everyMs = 10 * 60 * 1000 } = {}) {
+    this.mine = mine
+    this.newest = mine
+    this.fetchLatest = fetchLatest
+    this.everyMs = everyMs
+    this.timer = null
+  }
+
+  async refresh () {
+    const r = await this.fetchLatest().catch(() => null)
+    if (r && validImage(r.version) && compareVersions(r.version, this.newest) > 0) this.newest = r.version
+    return this.newest
+  }
+
+  /** Starts refreshing in the background (never blocks a tool call). */
+  start () {
+    if (this.timer) return this
+    this.refresh().catch(() => {})
+    this.timer = setInterval(() => this.refresh().catch(() => {}), this.everyMs)
+    this.timer.unref()
+    return this
+  }
+
+  stop () { if (this.timer) clearInterval(this.timer); this.timer = null }
+
+  latest () { return this.newest }
+
+  /** The update line for `image` (this process's own version when none is given), or ''. */
+  notice (image = this.mine) { return updateNotice(image, this.newest) }
+
+  /** What quilt_check_update answers. */
+  describe (image) {
+    const given = image != null && String(image).trim() !== ''
+    if (given && !validImage(image)) return `"${String(image).trim().slice(0, 40)}" is not a Quilt version (expected something like ${this.newest}). ${this.describe()}`
+    const mine = given ? String(image).trim().replace(/^v/, '') : this.mine
+    const n = updateNotice(mine, this.newest)
+    return n || `Quilt ${mine} is current (the newest release is ${this.newest}).`
+  }
+}

package/src/upstream.js

@@ -0,0 +1,155 @@
+// Catching a folder's branch up with commits it doesn't have yet (pushed from
+// a worktree, merged on GitHub, moved by another worktree), without anyone
+// running git pull. Quilt never merges git history: the branch only ever moves
+// forward to a commit it is behind. What it merges is the session's
+// uncommitted work into those commits' files, file by file, the way
+// `git pull --autostash` would, except nothing is written unless every file
+// merges cleanly.
+//
+// planCatchUp is pure: session.js reads git and the disk, asks for a plan,
+// and applies it (bringIn there).
+import crypto from 'node:crypto'
+import { mergeAdditive as merge3 } from './merge3.js'
+
+const isText = (k) => typeof k === 'string' && !k.startsWith('bin:')
+
+/**
+ * A file's content id as Quilt records what it published (`published` in the room document):
+ * the sha1 of its bytes. A key here is text or "bin:<sha1>" (the sha1 of the bytes already).
+ */
+export const contentId = (k) => typeof k !== 'string' ? null : k.startsWith('bin:') ? k.slice(4) : crypto.createHash('sha1').update(Buffer.from(k, 'utf8')).digest('hex')
+
+/**
+ * Whether `key` is a version of `rel` the session itself published to GitHub (a commit the relay
+ * made from the session's copy, on any branch). `published`: Map path -> [content ids], or null.
+ */
+export const wasPublished = (published, rel, key) => {
+  if (!published || key === null || key === undefined) return false
+  const ids = published.get(rel)
+  return !!ids && ids.includes(contentId(key))
+}
+
+/**
+ * How the folder at commit `from` (its files on disk: the commit plus the
+ * session's uncommitted work) becomes the folder at `to` with that work kept.
+ *
+ * - changes: Map path -> git status letter (A, M, D, T...) between the commits.
+ * - base / theirs: Map path -> the file at `from` / at `to` (text, "bin:<sha1>",
+ *   null when absent, undefined when git couldn't read it).
+ * - disk(rel): the file in the folder now (same keys).
+ * - moved: candidates for a file the session moved: Map path -> its text, for
+ *   files on disk that `from` didn't have (new or moved here).
+ * - emptied: folders the session emptied (had files at `from`, none on disk now).
+ *
+ * Returns { writes: Map path -> key (null: delete), moves: [{ from, to }],
+ * conflicts: [{ path, why }], strays: [path] }. With conflicts, writes is empty:
+ * a catch-up is all or nothing.
+ */
+/** What the session published (relay commits), read from the room document: Map path -> [content ids]. */
+export function publishedOf (doc) {
+  const out = new Map()
+  try { doc.getMap('published').forEach((v, k) => { if (Array.isArray(v)) out.set(k, v.filter((x) => typeof x === 'string')) }) } catch {}
+  return out
+}
+
+/** Records that these files' contents (path -> bytes, null for deleted) were published; the last 20 per path are kept. */
+export function notePublished (doc, files, origin) {
+  const entries = []
+  for (const [rel, buf] of files) if (buf) entries.push([rel, crypto.createHash('sha1').update(buf).digest('hex')])
+  notePublishedIds(doc, entries, origin)
+}
+
+/** The same, by content id (sha1 of the bytes): [[path, id]], as a folder reports what it pushed. */
+export function notePublishedIds (doc, entries, origin) {
+  const map = doc.getMap('published')
+  doc.transact(() => {
+    for (const [rel, id] of entries) {
+      if (typeof rel !== 'string' || !/^[0-9a-f]{40}$/.test(id || '')) continue
+      const was = Array.isArray(map.get(rel)) ? map.get(rel) : []
+      if (was.includes(id)) continue
+      map.set(rel, [...was, id].slice(-20))
+    }
+  }, origin)
+}
+
+export function planCatchUp ({ changes, base, theirs, disk, moved = new Map(), emptied = new Set(), published = null }) {
+  const writes = new Map()
+  const conflicts = []
+  const moves = []
+  const strays = []
+  const taken = new Set()
+  for (const rel of changes.keys()) {
+    const b = base.get(rel)
+    const t = theirs.get(rel)
+    const o = disk(rel)
+    if (b === undefined || t === undefined || o === undefined) {
+      conflicts.push({ path: rel, why: 'git could not read it (too large, or behind a filter such as Git LFS)' })
+      continue
+    }
+    if (o === b) { // untouched here: the commits' version
+      if (t !== o) writes.set(rel, t)
+      if (b === null && t !== null && emptied.has(dirOf(rel))) strays.push(rel)
+      continue
+    }
+    if (o === t) continue // the session already has it
+    // The commits bring a version of this file the session itself published (an agent committed it
+    // to a branch, and the branch was merged, squashed or rebased in): the session's copy is that
+    // version or newer, so it stays as it is. Matched by content, so every merge strategy counts.
+    if (o !== null && wasPublished(published, rel, t)) continue
+    if (o === null && isText(b) && isText(t)) {
+      // Gone here, changed there: the session may have moved it. Followed by content, as git
+      // follows a rename, into the moved copy, which takes the commits' change.
+      const to = findMove(rel, b, moved, taken)
+      if (to) {
+        const r = merge3(b, moved.get(to), t)
+        if (!r.conflicts.length) { taken.add(to); moves.push({ from: rel, to }); if (r.text !== moved.get(to)) writes.set(to, r.text); continue }
+        conflicts.push({ path: rel, why: `moved to ${to} here, and changed in the same lines there` })
+        continue
+      }
+      conflicts.push({ path: rel, why: 'deleted here, changed in the new commits' })
+      continue
+    }
+    if (t === null) { conflicts.push({ path: rel, why: 'changed here, deleted in the new commits' }); continue }
+    if (b === null) { conflicts.push({ path: rel, why: 'added both here and in the new commits, differently' }); continue }
+    if (!isText(b) || !isText(o) || !isText(t)) { conflicts.push({ path: rel, why: 'a binary file changed both here and in the new commits' }); continue }
+    const r = merge3(b, o, t)
+    if (r.conflicts.length) { conflicts.push({ path: rel, why: 'changed in the same lines here and in the new commits' }); continue }
+    if (r.text !== o) writes.set(rel, r.text)
+  }
+  if (conflicts.length) return { writes: new Map(), moves: [], conflicts, strays: [] }
+  return { writes, moves, conflicts, strays }
+}
+
+const dirOf = (rel) => rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : ''
+const nameOf = (rel) => rel.slice(rel.lastIndexOf('/') + 1)
+
+/** The moved copy of a file: same name, and at least half its lines the same. */
+function findMove (rel, text, moved, taken) {
+  let best = null
+  let score = 0.5
+  for (const [to, t] of moved) {
+    if (taken.has(to) || nameOf(to) !== nameOf(rel) || !isText(t)) continue
+    const s = similarity(text, t)
+    if (s >= score) { best = to; score = s }
+  }
+  return best
+}
+
+/** Share of lines in common (multiset), against the longer file. */
+export function similarity (a, b) {
+  const count = new Map()
+  const la = a.split('\n')
+  const lb = b.split('\n')
+  for (const l of la) count.set(l, (count.get(l) || 0) + 1)
+  let same = 0
+  for (const l of lb) { const n = count.get(l); if (n) { same++; count.set(l, n - 1) } }
+  return same / Math.max(la.length, lb.length, 1)
+}
+
+/** One line for the AI and the log about why a catch-up waits. */
+export function catchUpAdvice ({ branch, upstream, behind, conflicts, diverged, ahead }) {
+  const n = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`
+  if (diverged) return `${branch} and ${upstream} have both moved on (${n(ahead, 'commit')} here, ${n(behind, 'commit')} there). Quilt never merges git history: pull or rebase it yourself in this folder, and the session takes in whatever that changes.`
+  const list = conflicts.slice(0, 4).map((c) => `${c.path} (${c.why})`).join('; ') + (conflicts.length > 4 ? `; and ${conflicts.length - 4} more` : '')
+  return `${branch} is ${n(behind, 'commit')} behind ${upstream}, and the session's uncommitted work clashes with them in ${list}. Quilt brought nothing in. Run git pull in this folder and resolve those; the session takes in the result.`
+}

package/src/webhooks.js

@@ -0,0 +1,235 @@
+// Webhooks: an agent asks to be told, by an HTTP POST to a URL of its own, when
+// it is mentioned in chat (@name), sent a direct message, or handed a task. The
+// agent sets the subscription itself (quilt_webhook_subscribe), so a cloud agent
+// with a routine behind a webhook trigger wakes up instead of polling quilt_inbox.
+//
+// One POST per event, JSON, signed with the subscription's secret so the agent can
+// check it came from Quilt (`x-quilt-signature: sha256=<hmac>` over `<ts>.<body>`).
+// A failed delivery is tried again a few times; after that the event is still in
+// quilt_inbox, which never depends on the webhook.
+//
+// The pure parts (shapes, signing, validation) are shared by the relay, which
+// delivers for hosted agents, and the local session, which delivers for agents
+// joined from a computer.
+import crypto from 'node:crypto'
+import dns from 'node:dns'
+import net from 'node:net'
+
+export const WEBHOOK_EVENTS = ['chat.mention', 'chat.dm', 'task.assigned']
+export const EVENT_OF_KIND = { mention: 'chat.mention', dm: 'chat.dm', task: 'task.assigned' }
+export const MAX_URL = 2000
+export const MAX_SECRET = 200
+export const MIN_SECRET = 16
+export const MAX_BEARER = 500
+export const DELIVERY_TIMEOUT_MS = 10_000
+// Waits before the second, third and fourth tries.
+export const RETRY_DELAYS_MS = [1000, 5000, 25_000]
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0'])
+const isPrivateIp = (host) => {
+  const h = host.replace(/^\[|\]$/g, '')
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(h)) {
+    const [a, b] = h.split('.').map(Number)
+    return a === 10 || a === 127 || a === 0 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168)
+  }
+  if (h.includes(':')) return /^(::1|::|fc|fd|fe80)/i.test(h)
+  return false
+}
+
+// Addresses that are not on the public internet: unspecified, loopback, private, shared
+// (CGNAT), link-local, benchmarking, multicast and reserved; for IPv6 also unique-local,
+// link-local, site-local, multicast, IPv4-compatible and NAT64. Two lists, because a
+// BlockList matches IPv4 rules against IPv4-mapped IPv6 addresses (wanted) and IPv6 rules
+// covering ::ffff:0:0/96 against every IPv4 address (not wanted).
+const PRIVATE_V4 = new net.BlockList()
+for (const [a, p] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15], ['224.0.0.0', 3]]) PRIVATE_V4.addSubnet(a, p, 'ipv4')
+const PRIVATE_V6 = new net.BlockList()
+for (const [a, p] of [['::', 96], ['64:ff9b::', 96], ['fc00::', 7], ['fe80::', 10], ['fec0::', 10], ['ff00::', 8]]) PRIVATE_V6.addSubnet(a, p, 'ipv6')
+
+/** Whether `address` (an IP, as DNS answers it) is not on the public internet. Anything that isn't an address counts as private. */
+export function isPrivateAddress (address) {
+  let a = String(address || '').replace(/^\[|\]$/g, '').split('%')[0]
+  const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)
+  if (mapped) a = mapped[1]
+  const kind = net.isIP(a)
+  if (kind === 4) return PRIVATE_V4.check(a, 'ipv4')
+  if (kind === 6) return PRIVATE_V6.check(a, 'ipv6') || PRIVATE_V4.check(a, 'ipv6')
+  return true
+}
+
+/**
+ * Whether a webhook URL's host is on the public internet as it resolves now: { ok: true }, or
+ * { ok: false, reason }. A trailing dot is the same host; a local name or address never reaches
+ * DNS; every address the name resolves to must be public. Never throws. `lookup` is for tests.
+ * (parseWebhookUrl only reads the URL as written; this is for sends from Quilt's own servers.)
+ */
+export async function publicWebhookHost (url, { lookup = dns.promises.lookup } = {}) {
+  let host
+  try { host = new URL(url).hostname.toLowerCase() } catch { return { ok: false, reason: 'not a valid URL' } }
+  const bare = host.replace(/^\[|\]$/g, '').replace(/\.+$/, '')
+  if (!bare || LOCAL_HOSTS.has(bare) || bare.endsWith('.localhost')) return { ok: false, reason: `${host} is a local address` }
+  if (net.isIP(bare)) return isPrivateAddress(bare) ? { ok: false, reason: `${host} is a local or private address` } : { ok: true }
+  let addrs
+  try { addrs = await lookup(bare, { all: true, verbatim: true }) } catch (err) { return { ok: false, reason: `${host} did not resolve (${err?.code || err?.message || err})` } }
+  if (!Array.isArray(addrs) || !addrs.length) return { ok: false, reason: `${host} did not resolve` }
+  const bad = addrs.find((a) => isPrivateAddress(a?.address))
+  if (bad) return { ok: false, reason: `${host} resolves to a local or private address (${bad.address})` }
+  return { ok: true }
+}
+
+/**
+ * The URL a subscription may POST to: https, no credentials, and not the relay's own
+ * network. `allowLocal` (the local session) also takes http to this computer, for an
+ * agent whose receiver runs here.
+ */
+export function parseWebhookUrl (raw, { allowLocal = false } = {}) {
+  const s = String(raw || '').trim()
+  if (!s) throw new Error('Give the URL Quilt should POST to.')
+  if (s.length > MAX_URL) throw new Error('That URL is too long.')
+  let u
+  try { u = new URL(s) } catch { throw new Error('That is not a valid URL.') }
+  if (u.username || u.password) throw new Error('The URL may not carry a user name or password.')
+  const host = u.hostname.toLowerCase()
+  const local = LOCAL_HOSTS.has(host) || host.endsWith('.localhost') || isPrivateIp(host)
+  if (u.protocol === 'http:') {
+    if (!allowLocal || !local) throw new Error('The URL must use https (http is only for a receiver on this computer).')
+  } else if (u.protocol !== 'https:') {
+    throw new Error('The URL must start with https://.')
+  } else if (local && !allowLocal) {
+    throw new Error('The URL must be reachable from the internet, not a local or private address.')
+  }
+  return u.toString()
+}
+
+/** The event names in `list` (default: all), or an error naming a bad one. */
+export function parseWebhookEvents (list) {
+  if (list == null) return WEBHOOK_EVENTS.slice()
+  if (!Array.isArray(list)) throw new Error(`events: give a list of ${WEBHOOK_EVENTS.join(', ')}.`)
+  const out = []
+  for (const e of list) {
+    const n = String(e || '').trim()
+    if (!WEBHOOK_EVENTS.includes(n)) throw new Error(`Unknown event "${n}". Events: ${WEBHOOK_EVENTS.join(', ')}.`)
+    if (!out.includes(n)) out.push(n)
+  }
+  if (!out.length) throw new Error(`events: give at least one of ${WEBHOOK_EVENTS.join(', ')}.`)
+  return out
+}
+
+export const newSecret = () => crypto.randomBytes(24).toString('hex')
+
+/**
+ * A subscription from what an agent gave: { url, secret, events, since }. A secret the
+ * agent chose is kept (16 to 200 characters); without one, a new one is made and the
+ * agent is shown it once, in the tool's answer.
+ */
+export function makeSubscription ({ url, secret, events, bearer } = {}, { allowLocal = false, now = Date.now } = {}) {
+  const u = parseWebhookUrl(url, { allowLocal })
+  const ev = parseWebhookEvents(events)
+  let s = secret == null ? '' : String(secret)
+  if (s && (s.length < MIN_SECRET || s.length > MAX_SECRET)) throw new Error(`The secret must be ${MIN_SECRET} to ${MAX_SECRET} characters (or leave it out and Quilt makes one).`)
+  const made = !s
+  if (made) s = newSecret()
+  // A key the receiver wants on every POST (a Grok Bot routine's sender key, for example), sent as Authorization: Bearer <key>.
+  const b = bearer == null ? '' : String(bearer).trim()
+  if (b.length > MAX_BEARER || /[\r\n]/.test(b)) throw new Error(`The bearer key must be one line of at most ${MAX_BEARER} characters.`)
+  return { url: u, secret: s, events: ev, since: now(), made, ...(b ? { bearer: b } : {}) }
+}
+
+/** The subscription as an agent sees it (its secret only when it was just made). */
+export function describeSubscription (sub, { showSecret = false } = {}) {
+  if (!sub) return 'No webhook: Quilt only answers quilt_inbox when you ask.'
+  const lines = [`Webhook: Quilt POSTs to ${sub.url} on ${sub.events.join(', ')}${sub.bearer ? ', with your bearer key in the Authorization header' : ''}.`]
+  if (showSecret) lines.push(`Secret (shown once; check x-quilt-signature with it): ${sub.secret}`)
+  lines.push('Each POST is JSON ({ event, id, session, workspace, room, to, by, text, ts, task?, context? }; session: the session it is from, which you name as `session` in the tools you answer with, so an answer never lands in another session; workspace: { id } or null; context: the messages before this one between you and its sender, oldest first) with x-quilt-event, x-quilt-delivery, x-quilt-timestamp and ' +
+    'x-quilt-signature: sha256=HMAC-SHA256(secret, "<timestamp>.<body>"). Answer 2xx quickly; a failed POST is retried a few times. ' +
+    'What you are told is still in quilt_inbox. Stop with quilt_webhook_unsubscribe.')
+  return lines.join('\n')
+}
+
+/**
+ * The body for one inbox event (see inbox.js) to `to`, in `room`: `session` is the room (the id
+ * to answer in, with every tool's `session`), `workspace` the workspace it is in, when known.
+ */
+export function webhookPayload (e, { room = '', to = '', workspace = '' } = {}) {
+  const p = { event: EVENT_OF_KIND[e.kind] || e.kind, id: String(e.id || ''), room, session: room, workspace: workspace ? { id: String(workspace) } : null, to, by: String(e.by || ''), text: String(e.text || ''), ts: Number(e.ts) || Date.now() }
+  if (e.kind === 'task' && e.task) p.task = { id: e.task.id, title: e.task.title, column: e.task.column, assignee: e.task.assignee ?? null, forAi: !!e.task.forAi, tool: e.task.tool || '', files: e.task.files || [] }
+  if (e.commit) p.commit = true // work this member asked to commit was committed: nothing to answer
+  if (e.nudge) p.nudge = true // a reminder from Quilt (uncommitted work): nothing to answer
+  // The conversation before this with whoever it is from (conversation.js), so an agent woken
+  // fresh knows what "that" refers to; `earlier` older messages are a quilt_conversation away.
+  if (Array.isArray(e.context) && e.context.length) {
+    p.context = e.context.map((m) => ({ id: m.id, by: m.by, ...(m.to ? { to: m.to } : {}), text: m.text, ts: m.ts }))
+    if (e.earlier) p.earlier = e.earlier
+  }
+  return p
+}
+
+/** `sha256=<hex>`: HMAC-SHA256 with `secret` over `<ts>.<body>`. */
+export function signWebhook (secret, ts, body) {
+  return 'sha256=' + crypto.createHmac('sha256', String(secret)).update(`${ts}.${body}`).digest('hex')
+}
+
+/** For receivers: whether `signature` is right for this body and timestamp. */
+export function verifyWebhook (secret, ts, body, signature) {
+  const want = Buffer.from(signWebhook(secret, ts, body))
+  const got = Buffer.from(String(signature || ''))
+  return want.length === got.length && crypto.timingSafeEqual(want, got)
+}
+
+/** Whether a response means "try again later". */
+const retryable = (status) => status === 408 || status === 429 || status >= 500
+
+/**
+ * POSTs `payload` to `sub.url`, signed, trying again after each delay in `delays` when
+ * the receiver is down, slow or answers 5xx/429. Resolves { ok, status, attempts, error? };
+ * never throws. `fetch`, `delays` and `sleep` are for tests.
+ */
+export async function deliverWebhook (sub, payload, { fetch = globalThis.fetch, delays = RETRY_DELAYS_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), timeoutMs = DELIVERY_TIMEOUT_MS, now = Date.now, log = () => {} } = {}) {
+  const body = JSON.stringify(payload)
+  const delivery = crypto.randomUUID()
+  let status = 0
+  let error = ''
+  let attempt = 0
+  while (attempt < delays.length + 1) {
+    attempt++
+    const ts = String(now())
+    try {
+      const res = await fetch(sub.url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'user-agent': 'quilt-webhook',
+          'x-quilt-event': payload.event,
+          'x-quilt-delivery': delivery,
+          'x-quilt-timestamp': ts,
+          'x-quilt-signature': signWebhook(sub.secret, ts, body),
+          ...(sub.bearer ? { authorization: `Bearer ${sub.bearer}` } : {})
+        },
+        body,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(timeoutMs)
+      })
+      status = res.status
+      error = ''
+      if (res.ok) return { ok: true, status, attempts: attempt, delivery }
+      if (!retryable(status)) break
+    } catch (err) {
+      status = 0
+      error = err && err.message ? err.message : String(err)
+    }
+    if (attempt <= delays.length) await sleep(delays[attempt - 1])
+  }
+  log(`webhook to ${sub.url} failed (${payload.event}): ${error || `HTTP ${status}`}`)
+  return { ok: false, status, attempts: attempt, error: error || `HTTP ${status}`, delivery }
+}
+
+/** Delivers each of `events` the subscription asks for, one after another (order kept). */
+export async function deliverEvents (sub, events, { room = '', to = '', workspace = '' } = {}, opts = {}) {
+  const out = []
+  for (const e of events || []) {
+    const p = webhookPayload(e, { room, to, workspace })
+    if (!sub.events.includes(p.event)) continue
+    out.push(await deliverWebhook(sub, p, opts))
+  }
+  return out
+}

package/src/workspace-cli.js

@@ -0,0 +1,62 @@
+// `quilt workspace ...`: the workspace library from a shell, for agents (and people) that work
+// with commands rather than MCP. Each command runs the same tool the MCP offers
+// (workspace-tools.js), as whoever the MCP would act as here (mcp.js workspaceActor): this
+// folder's agent, or the person signed in on this computer.
+import { registerWorkspaceTools } from './workspace-tools.js'
+
+export const WORKSPACE_USAGE = `Usage:
+  quilt workspace list                                    Workspaces you can reach
+  quilt workspace files <workspace> [folder] [--glob g]   What is in its library
+  quilt workspace get <workspace> <path> [--version n]    Read a file (text is printed; anything else is saved and its path printed)
+  quilt workspace put <workspace> <path> <local file> [--note "what it is"]
+                                                          Upload a file from this project (a new version if the path exists)
+  quilt workspace write <workspace> <path> <text> [--note n]
+                                                          Save text as a file
+  quilt workspace mkdir <workspace> <folder>              Make a folder (and any above it)
+  quilt workspace mv <workspace> <path> <new path>        Rename or move a file or folder
+  quilt workspace rm <workspace> <path>                   Delete a file or folder
+  quilt workspace webhook <https url> | webhook-off       Workspace events to your URL (agents)
+<workspace> is its name or id.`
+
+/** Pulls `--name value` options out of `args`: { opts, rest }. */
+function options (args, names) {
+  const opts = {}
+  const rest = []
+  for (let i = 0; i < args.length; i++) {
+    const m = String(args[i]).match(/^--([a-z]+)(?:=(.*))?$/)
+    if (m && names.includes(m[1])) {
+      opts[m[1]] = m[2] !== undefined ? m[2] : args[++i]
+      if (opts[m[1]] === undefined) throw new Error(`--${m[1]} needs a value`)
+    } else rest.push(args[i])
+  }
+  return { opts, rest }
+}
+
+/** Which tool a command runs, with what arguments; throws the usage when it doesn't fit. */
+export function toolCall (sub, args) {
+  const { opts, rest } = options(args, ['glob', 'version', 'note'])
+  const [ws, a, b] = rest
+  const need = (n) => { if (rest.length < n) throw new Error(WORKSPACE_USAGE) }
+  switch (sub) {
+    case 'list': case 'ls': return ['quilt_workspaces', {}]
+    case 'files': need(1); return ['quilt_workspace_files', { workspace: ws, ...(a !== undefined ? { folder: a } : {}), ...(opts.glob ? { glob: opts.glob } : {}) }]
+    case 'get': case 'read': need(2); return ['quilt_workspace_read_file', { workspace: ws, path: a, ...(opts.version ? { version: Number(opts.version) } : {}) }]
+    case 'put': case 'upload': need(3); return ['quilt_workspace_write_file', { workspace: ws, path: a, fromPath: b, ...(opts.note ? { note: opts.note } : {}) }]
+    case 'write': need(3); return ['quilt_workspace_write_file', { workspace: ws, path: a, text: rest.slice(2).join(' '), ...(opts.note ? { note: opts.note } : {}) }]
+    case 'mkdir': need(2); return ['quilt_workspace_make_folder', { workspace: ws, path: a }]
+    case 'mv': case 'move': need(3); return ['quilt_workspace_move_file', { workspace: ws, path: a, to: b }]
+    case 'rm': case 'delete': need(2); return ['quilt_workspace_delete_file', { workspace: ws, path: a }]
+    case 'webhook': need(1); return ['quilt_workspace_webhook', { url: ws }]
+    case 'webhook-off': return ['quilt_workspace_webhook_off', {}]
+    default: throw new Error(WORKSPACE_USAGE)
+  }
+}
+
+/** Runs one command with `access` (localWorkspaceAccess): { ok, text }. */
+export async function runWorkspaceCommand (sub, args, access) {
+  const [name, input] = toolCall(sub, args)
+  const tools = new Map()
+  registerWorkspaceTools({ registerTool: (n, def, fn) => tools.set(n, fn) }, access)
+  const r = await tools.get(name)(input)
+  return { ok: !r.isError, text: r.content.map((c) => c.text).join('\n') }
+}