heyquilt 0.0.1 → 0.3.90

package/src/autowork.js

@@ -0,0 +1,387 @@
+// "Work on its own": when work comes to "<person>'s AI" (a task given to it, a merge sent to
+// it) and none of the person's AI sessions is live, Quilt can start the person's own AI tool
+// in its non-interactive mode, on their computer, in the session's folder — only when they
+// turned it on in Settings. The run talks through Quilt chat: it asks with quilt_message and
+// stops; a reply to it carries the same tool chat on. Every run is logged with its tokens.
+//
+// One AutoWork per app: one run at a time, whatever the session; work that arrives meanwhile
+// waits its turn. The tools themselves are presets in autowork-tools.js.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { getSettings } from './settings.js'
+import { quiltHome } from './legacy.js'
+import { autoToolFor, findExe } from './autowork-tools.js'
+import { claudeCli, installedEditors, openIn } from './editors.js'
+
+export const AUTO_MODES = ['chat', 'open', 'auto']
+const RUN_MS = 30 * 60 * 1000 // a run that takes longer is stopped
+const KEEP_CHATS = 30 // runs whose chat a reply can still carry on
+const KEEP_CHAT_MS = 7 * 24 * 60 * 60 * 1000
+const MAX_OUT = 4 * 1024 * 1024
+
+const day = (ts) => new Date(ts).toISOString().slice(0, 10)
+// What tools say when nobody is signed in to them (their own words differ; none of their fixes are repeated).
+const SIGNED_OUT = /not (logged|signed) in|log ?in|sign ?in|authenticat|unauthori[sz]ed|api key|credentials|oauth/i
+
+/** This computer's "Work on its own" settings, with defaults. */
+export function autoConfig (s = getSettings()) {
+  const mode = AUTO_MODES.includes(s.autoWork) ? s.autoWork : 'chat'
+  const preset = autoToolFor(s.tool)
+  return {
+    mode,
+    tool: s.tool || '',
+    preset,
+    model: String(s.autoModel || '').trim() || (preset ? preset.models[0] : ''),
+    changeFiles: !!s.autoFiles,
+    cap: Number(s.autoCap) > 0 ? Math.floor(Number(s.autoCap)) : 0,
+    // The person's own instructions for every run (their cloud AI's settings).
+    prompt: String(s.autoPrompt || '').trim().slice(0, 4000)
+  }
+}
+
+/** Totals from log lines: { [day]: { [tool]: { runs, input, output, costUsd } } }. */
+export function usageTotals (entries) {
+  const out = {}
+  for (const e of entries) {
+    if (!e || !e.ts) continue
+    const d = (out[day(e.ts)] ||= {})
+    const t = (d[e.tool] ||= { runs: 0, input: 0, output: 0, costUsd: 0 })
+    t.runs++
+    t.input += e.input || 0
+    t.output += e.output || 0
+    t.costUsd += e.costUsd || 0
+  }
+  return out
+}
+
+/** Tokens used on `ts`'s day, every tool together. */
+export function tokensOn (entries, ts) {
+  const d = usageTotals(entries)[day(ts)] || {}
+  return Object.values(d).reduce((n, t) => n + t.input + t.output, 0)
+}
+
+/** What a run is asked to do: the work, and how to talk while nobody watches. */
+export function runPrompt ({ person, job, changeFiles, prompt = '' }) {
+  const lines = [
+    `You are ${person}'s AI in the Quilt session in this folder, working on your own: nobody is watching this chat, and it isn't a conversation.`,
+    ''
+  ]
+  if (job.kind === 'task') {
+    lines.push(`${job.by || 'Someone'} gave ${person}'s AI a task on the board:`, `Task ${job.id}: ${job.title}`, '',
+      'Read it in full with quilt_task, move it to "doing" with quilt_move_task when you start (that briefs you), and to "qa" with qaNotes when it is done and checked.')
+  } else if (job.kind === 'merge') {
+    lines.push(job.prompt.trim())
+  } else if (job.kind === 'message') {
+    lines.push(`${job.by || 'Someone'} wrote to ${person}'s AI in Quilt chat:`, '', String(job.text || '').trim(), '',
+      `Answer ${job.by || 'them'} with quilt_message. If they ask for work, do it as ${person}'s AI would, and say in chat what you did.`)
+  }
+  if (prompt) lines.push('', `${person}'s own instructions for you:`, prompt)
+  lines.push('', 'Before your first change, read the project\'s rules with quilt_project_rules.')
+  if (!changeFiles) lines.push(`${person} hasn't let you change files: read, plan, comment on the task (quilt_comment_task) or ask, and leave the changes to a person or another session.`)
+  lines.push(
+    'If you need an answer from someone, ask them with quilt_message and stop: when they reply, this chat continues with their answer.',
+    'When you finish, or stop to wait, end with a sentence or two on where things stand.'
+  )
+  return lines.join('\n')
+}
+
+/** How a reply carries a run on: the message, and for a tool that can't resume, what came before. */
+export function replyPrompt ({ run, reply, resumes }) {
+  const said = `${reply.by} replied in Quilt chat: ${reply.text}`
+  if (resumes) return `${said}\n\nCarry on with the work.`
+  return `${run.prompt}\n\nEarlier, in this work, you said:\n${run.lastText || '(nothing)'}\n\n${said}\n\nCarry on from there.`
+}
+
+function defaultSpawn (exe, args, { cwd, onStart }) {
+  return new Promise((resolve) => {
+    let out = ''; let err = ''
+    let child
+    try {
+      child = spawn(exe, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: process.env, windowsHide: true })
+    } catch (e) { resolve({ code: -1, stdout: '', stderr: e.message }); return }
+    const timer = setTimeout(() => { try { child.kill() } catch {} }, RUN_MS)
+    child.stdout.on('data', (d) => { if (out.length < MAX_OUT) out += d })
+    child.stderr.on('data', (d) => { if (err.length < 64 * 1024) err += d })
+    child.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, stdout: out, stderr: e.message }) })
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout: out, stderr: err }) })
+    if (child.pid && onStart) onStart(child.pid)
+  })
+}
+
+export class AutoWork {
+  /**
+   * `settings()`, `spawnRun(exe, args, { cwd, onStart(pid) })`, `exeFor(preset)`, `dir` and
+   * `now()` are injectable for tests.
+   */
+  constructor ({ settings = getSettings, spawnRun = defaultSpawn, exeFor = null, open = null, dir = path.join(quiltHome(), 'autowork'), now = Date.now, cloudAi = () => false } = {}) {
+    this.settings = settings
+    // Whether the person has a cloud AI (the app asks the API now and then): its work is not this computer's.
+    this.cloudAi = cloudAi
+    // "Open it in my tool": the person's AI app, opened in the folder with the work as its prompt (editors.js).
+    this.open = open || (async (tool, dir, prompt) => {
+      const ed = installedEditors().find((e) => e.tool === tool)
+      if (!ed) throw new Error(`${tool || 'Your AI tool'} isn't installed on this computer`)
+      return openIn(ed.id, dir, { prompt })
+    })
+    this.spawnRun = spawnRun
+    this.exeFor = exeFor || ((p) => (p.id === 'claude' ? claudeCli() : findExe(p.exe)))
+    this.dir = dir
+    this.now = now
+    this.queue = []
+    this.running = null
+    this.idle = Promise.resolve()
+    this.sessions = new Set()
+    this.chats = this.loadChats()
+    this.toldCap = ''
+  }
+
+  config () { return autoConfig(this.settings()) }
+
+  /**
+   * Watches a person's session: work for their AI, and replies to runs. Agents' sessions work for
+   * themselves, except a person's cloud AI (cloud-ai.js), whose session is that person's AI.
+   */
+  attach (session) {
+    if (this.sessions.has(session)) return
+    this.sessions.add(session)
+    const onInbox = (events) => this.onInbox(session, events)
+    const onPersona = (p, events) => this.onReply(session, p, events)
+    session.on('inbox', onInbox)
+    session.on('persona-inbox', onPersona)
+  }
+
+  /** Whether work for the person's AI should run here now. */
+  on () {
+    const c = this.config()
+    return c.mode === 'auto' && !!c.preset
+  }
+
+  onInbox (session, events) {
+    if (!worksFor(session)) return
+    const c = this.config()
+    if (c.mode === 'open') { this.openTasks(session, events, c); return }
+    if (!this.on()) return
+    for (const e of events) {
+      // A reply to something a run said, written to "<me>'s AI": that run carries on.
+      if ((e.kind === 'dm' || e.kind === 'mention') && e.re) {
+        const run = this.chats.find((r) => r.room === session.room && r.said && r.said.includes(e.re))
+        if (run) { this.enqueue({ kind: 'reply', session, run, reply: { by: e.by, text: e.text, id: e.id } }); continue }
+      }
+      // A live AI session of theirs takes its own work (the inbox wakes it); this is for when none is.
+      // Their cloud AI, when it is in the session, takes it instead of this computer.
+      if (e.kind === 'task' && session.forMyAi(e) && !session.leadPersona() && !this.leaveToCloud(session)) {
+        if (this.queue.some((j) => j.kind === 'task' && j.id === e.task.id) || (this.running && this.running.job.id === e.task.id)) continue
+        this.enqueue({ kind: 'task', session, id: e.task.id, title: e.task.title, by: e.by })
+        continue
+      }
+      // A person's cloud AI answers what is written to it (its inbox only has it while no AI session of theirs is live).
+      if (session.aiOf && (e.kind === 'dm' || e.kind === 'mention') && !e.queue && !e.commit && !e.nudge && session.forMyAi(e)) {
+        if (this.queue.some((j) => j.kind === 'message' && j.id === e.id)) continue
+        this.enqueue({ kind: 'message', session, id: e.id, title: `message from ${e.by}`, by: e.by, text: e.text })
+      }
+    }
+  }
+
+  /** Whether work for the person's AI is their cloud AI's, not this computer's: it is in the session, or they have one. */
+  leaveToCloud (session) {
+    if (session.aiOf) return false
+    return !!((session.cloudAiLive && session.cloudAiLive()) || this.cloudAi())
+  }
+
+  /** "Open it in my tool": a task for my AI, with no AI session of mine live, opens my tool on it. */
+  openTasks (session, events, c) {
+    if (session.aiOf) return // a cloud machine has no tool window to open
+    for (const e of events) {
+      if (e.kind !== 'task' || !session.forMyAi(e) || session.leadPersona() || this.leaveToCloud(session)) continue
+      const prompt = runPrompt({ person: session.name, job: { kind: 'task', id: e.task.id, title: e.task.title, by: e.by }, changeFiles: true })
+        .replace(', working on your own: nobody is watching this chat, and it isn\'t a conversation.', '.')
+      Promise.resolve(this.open(c.tool, session.root, prompt)).catch((err) => this.notice(session, `Couldn't open ${c.tool || 'your AI tool'} for ${e.task.title}: ${err.message}.`))
+    }
+  }
+
+  onReply (session, p, events) {
+    if (!worksFor(session) || !this.on()) return
+    const run = this.chats.find((r) => r.room === session.room && r.via === p.rid)
+    if (!run) return
+    for (const e of events) {
+      if (e.kind !== 'dm' && e.kind !== 'mention') continue
+      this.enqueue({ kind: 'reply', session, run, reply: { by: e.by, text: e.text, id: e.id } })
+    }
+  }
+
+  /** A merge sent to the person's AI. Resolves once it is queued; the run follows. */
+  sendMerge (session, { id, path: file, prompt }) {
+    const c = this.config()
+    if (!c.preset) throw new Error(`${c.tool || 'Your AI tool'} can't work on its own: open the merge in it instead`)
+    this.enqueue({ kind: 'merge', session, id, path: file, title: `merge ${file}`, prompt, by: session.name })
+    return { queued: true, tool: c.tool }
+  }
+
+  enqueue (job) {
+    this.queue.push(job)
+    this.idle = this.idle.then(() => this.next()).catch(() => {})
+    return this.idle
+  }
+
+  async next () {
+    const job = this.queue.shift()
+    if (!job) return
+    this.running = { job }
+    try { await this.run(job) } finally { this.running = null }
+  }
+
+  /** Runs one piece of work to its end (or its question). */
+  async run (job) {
+    const { session } = job
+    const c = this.config()
+    if (session.stopped) this.sessions.delete(session)
+    if (c.mode !== 'auto' || !c.preset || !this.sessions.has(session)) return
+    const p = c.preset
+    // Over today's cap: the work waits for the person's chat, and they are told once a day.
+    if (c.cap && tokensOn(this.log(), this.now()) >= c.cap) {
+      if (this.toldCap !== day(this.now())) {
+        this.toldCap = day(this.now())
+        this.notice(session, `Your AI has used today's ${c.cap.toLocaleString('en-US')} tokens for working on its own, so new work waits for you in your chat until tomorrow. Change the limit in Settings → Your AI.`)
+      }
+      return
+    }
+    const exe = this.exeFor(p)
+    let run = job.kind === 'reply' ? job.run : null
+    const resumes = p.resumes !== false && !!(run && run.chatId)
+    if (!run) {
+      const prompt = runPrompt({ person: personOf(session), job, changeFiles: c.changeFiles, prompt: c.prompt })
+      run = { id: crypto.randomBytes(6).toString('hex'), via: `auto${crypto.randomBytes(6).toString('hex')}`, room: session.room, dir: session.root, tool: p.tool, kind: job.kind, work: job.id, path: job.path || '', title: job.title, by: job.by, prompt, chatId: p.newChatId(), said: [], ts: this.now() }
+    }
+    if (!exe) {
+      this.fail(session, run, `${p.exe} isn't installed on this computer`)
+      return
+    }
+    const o = { model: c.model, changeFiles: c.changeFiles, chatId: run.chatId }
+    const args = resumes
+      ? p.resume({ ...o, prompt: replyPrompt({ run, reply: job.reply, resumes: true }) })
+      : p.start({ ...o, prompt: job.kind === 'reply' ? replyPrompt({ run, reply: job.reply, resumes: false }) : run.prompt })
+    const label = job.kind === 'merge' ? job.title : (run.title || 'work')
+    const started = this.now()
+    let persona = null
+    const r = await this.spawnRun(exe, args, {
+      cwd: run.dir,
+      onStart: (pid) => { try { persona = session.autoPersona(run.via, { tool: p.tool, label: `on its own: ${label}`, pid }) } catch {} }
+    })
+    if (!persona) persona = session.autoPersonaOf(run.via)
+    const out = p.parse(r.stdout)
+    if (out.chatId) run.chatId = out.chatId
+    this.record({ ts: started, ms: this.now() - started, room: run.room, run: run.id, tool: p.tool, model: c.model, kind: job.kind, work: run.work || '', title: run.title || '', input: out.usage ? out.usage.input : 0, output: out.usage ? out.usage.output : 0, costUsd: out.usage && out.usage.costUsd ? out.usage.costUsd : 0, reported: !!out.usage, chatId: run.chatId || null, outcome: out.error || r.code ? 'failed' : 'ok' })
+    if (out.error || (r.code && !out.text)) {
+      // What the tool printed as its result says most; with nothing printed, its error output does.
+      const why = (String(r.stdout || '').trim() && out.error) || firstLine(r.stderr) || out.error || `${p.exe} stopped (exit ${r.code})`
+      this.fail(session, run, why)
+      return
+    }
+    run.lastText = out.text
+    // What the run said in chat, so a reply to any of it carries this chat on.
+    const name = persona ? [persona.name, ...persona.aliases] : []
+    const mine = session.chat.toArray().filter((m) => m && m.ts >= started && name.includes(m.by)).map((m) => m.id)
+    run.said = [...new Set([...run.said, ...mine])].slice(-50)
+    // A run that said nothing in chat: its last words go to whoever gave it the work.
+    if (!mine.length && out.text && persona) {
+      try {
+        const to = run.by && run.by !== session.name ? run.by : personOf(session)
+        const m = session.say(out.text.slice(0, 3000), { to, via: persona.via })
+        if (m && m.id) run.said.push(m.id)
+      } catch {}
+    }
+    this.keepChat(run)
+  }
+
+  /**
+   * One plain line in chat for the person; the work stays where it was (a merge lets go of its
+   * file again). A tool that isn't signed in is said so plainly, never with one tool's fix.
+   */
+  fail (session, run, why) {
+    const where = session.aiOf ? 'your cloud AI (Settings → Your AI)' : 'this computer'
+    const text = SIGNED_OUT.test(String(why)) ? `${run.tool || 'your AI tool'} isn't signed in on ${where}` : String(why).replace(/[.\s]+$/, '').slice(0, 300)
+    this.notice(session, `Couldn't run your AI for ${run.title || 'that work'}: ${text}. It's still waiting for your AI in your chat.`, run)
+    session.dropAutoPersona(run.via)
+    if (run.kind === 'merge' && run.path) session.releaseMergeClaim(run.path).catch(() => {})
+  }
+
+  notice (session, text, run = null) {
+    try {
+      const rid = run ? run.via : 'autowork'
+      const p = session.autoPersona(rid, { tool: this.config().tool, label: 'on its own' })
+      session.say(text, { to: personOf(session), via: p.via })
+      if (!run) session.dropAutoPersona(rid)
+    } catch (err) { session.log(`Work on its own: ${text} (${err.message})`) }
+  }
+
+  // ------------------------------------------------------------ records --
+
+  file (name) { return path.join(this.dir, name) }
+
+  record (entry) {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true })
+      fs.appendFileSync(this.file('runs.jsonl'), JSON.stringify(entry) + '\n')
+    } catch {}
+  }
+
+  /** Every logged run, oldest first. */
+  log () {
+    let text = ''
+    try { text = fs.readFileSync(this.file('runs.jsonl'), 'utf8') } catch { return [] }
+    return text.split('\n').map((l) => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+  }
+
+  /** For Settings: the config, today's totals per tool, and the latest runs. */
+  usage () {
+    const log = this.log()
+    const today = usageTotals(log)[day(this.now())] || {}
+    return { config: publicConfig(this.config()), today, runs: log.slice(-20).reverse() }
+  }
+
+  loadChats () {
+    try {
+      const list = JSON.parse(fs.readFileSync(this.file('chats.json'), 'utf8'))
+      return Array.isArray(list) ? list.filter((r) => r && this.now() - r.ts < KEEP_CHAT_MS) : []
+    } catch { return [] }
+  }
+
+  keepChat (run) {
+    this.chats = [...this.chats.filter((r) => r.id !== run.id), run].filter((r) => this.now() - r.ts < KEEP_CHAT_MS).slice(-KEEP_CHATS)
+    try {
+      fs.mkdirSync(this.dir, { recursive: true })
+      fs.writeFileSync(this.file('chats.json'), JSON.stringify(this.chats), { mode: 0o600 })
+    } catch {}
+  }
+
+  /** How the person carries a logged run's chat on in their tool: { link, command } or null. */
+  takeOver (runId) {
+    const e = [...this.log()].reverse().find((x) => x.run === runId && x.chatId)
+    const preset = e && autoToolFor(e.tool)
+    return preset ? preset.takeOver(e.chatId) : null
+  }
+}
+
+/** Whose AI a session works as: its person's, for a person's cloud AI; else its own member's. */
+const personOf = (session) => session.aiOf || session.name
+
+/** Whether "Work on its own" works for this session: a person's, or a person's cloud AI's. */
+const worksFor = (session) => session.kind !== 'agent' || !!session.aiOf
+
+function firstLine (s) {
+  return String(s || '').split('\n').map((l) => l.trim()).find(Boolean)?.slice(0, 300) || ''
+}
+
+/** The settings as Settings shows them. */
+export function publicConfig (c) {
+  return { mode: c.mode, tool: c.tool, supported: !!c.preset, models: c.preset ? c.preset.models : [], model: c.model, changeFiles: c.changeFiles, limitsFiles: c.preset ? c.preset.limitsFiles : true, cap: c.cap }
+}
+
+let shared = null
+/** The app's one AutoWork. */
+export function autowork () {
+  shared ||= new AutoWork()
+  return shared
+}

package/src/blobstore.js

@@ -0,0 +1,99 @@
+// Where the relay keeps large files. The files are already encrypted by the
+// apps; the relay only hands out short-lived links and deletes what's unused.
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { createClient } from '@supabase/supabase-js'
+
+const LINK_MS = 10 * 60 * 1000
+const MAX_REMOVE_ROUNDS = 1000
+
+/** Files on the relay's own disk, reached through signed links to the relay. */
+export class DiskStore {
+  constructor (dir) {
+    this.dir = dir
+    this.signing = crypto.randomBytes(32)
+  }
+
+  file (room, id) { return path.join(this.dir, room, id) }
+
+  sign (room, id, method, exp, size) {
+    return crypto.createHmac('sha256', this.signing).update(`${method} ${room}/${id} ${exp} ${size ?? ''}`).digest('hex')
+  }
+
+  link (room, id, method, size) {
+    const exp = Date.now() + LINK_MS
+    const n = size === undefined ? '' : `&n=${size}`
+    return `/blobs/${room}/${id}/data?m=${method}&exp=${exp}&sig=${this.sign(room, id, method, exp, size)}${n}`
+  }
+
+  verify (room, id, method, exp, sig, size) {
+    if (!(Number(exp) > Date.now())) return false
+    const want = Buffer.from(this.sign(room, id, method, exp, size), 'hex')
+    const got = Buffer.from(String(sig || ''), 'hex')
+    return got.length === want.length && crypto.timingSafeEqual(got, want)
+  }
+
+  // The declared size is signed into the PUT link, so a client can't upload
+  // more than it told the relay it would; GET links carry no size.
+  async uploadTarget (room, id, size) { return { method: 'PUT', url: this.link(room, id, 'PUT', size) } }
+  async downloadTarget (room, id) { return { url: this.link(room, id, 'GET') } }
+  async remove (room, ids) { for (const id of ids) fs.rmSync(this.file(room, id), { force: true }) }
+  async removeRoom (room) { fs.rmSync(path.join(this.dir, room), { recursive: true, force: true }) }
+}
+
+/** Files in a private Supabase Storage bucket; apps upload and download directly. */
+export class SupabaseStore {
+  constructor ({ url, key, bucket }) {
+    this.bucket = createClient(url, key, { auth: { persistSession: false, autoRefreshToken: false } }).storage.from(bucket)
+  }
+
+  static path (room, id) { return `${room}/${id}` }
+
+  // `size` is accepted but ignored: Supabase signed uploads can't bound size; the bucket's file_size_limit caps each object.
+  // Write-once: ids come from the content, so an upload never replaces what's stored.
+  async uploadTarget (room, id, size) {
+    const { data, error } = await this.bucket.createSignedUploadUrl(SupabaseStore.path(room, id), { upsert: false })
+    // Storage may refuse to sign at all when the file is already there.
+    if (error && alreadyExists(error)) return { exists: true }
+    if (error) throw new Error(`storage: ${error.message}`)
+    return { method: 'PUT', url: data.signedUrl }
+  }
+
+  async downloadTarget (room, id) {
+    const { data, error } = await this.bucket.createSignedUrl(SupabaseStore.path(room, id), LINK_MS / 1000)
+    if (error) throw new Error(`storage: ${error.message}`)
+    return { url: data.signedUrl }
+  }
+
+  /** Deletes stored files; resolves to how many were deleted. */
+  async remove (room, ids) {
+    if (!ids.length) return 0
+    const { data, error } = await this.bucket.remove(ids.map((id) => SupabaseStore.path(room, id)))
+    if (error) throw new Error(`storage: ${error.message}`)
+    return (data || []).length
+  }
+
+  // Deleted 1000 at a time. A round that deletes nothing (say, something
+  // that isn't a file is in the way) stops it, rather than looping forever.
+  async removeRoom (room) {
+    for (let round = 0; round < MAX_REMOVE_ROUNDS; round++) {
+      const { data, error } = await this.bucket.list(room, { limit: 1000 })
+      if (error) throw new Error(`storage: ${error.message}`)
+      if (!data.length) return
+      if (!await this.remove(room, data.map((f) => f.name))) throw new Error(`storage: could not delete the stored files of ${room}; ${data.length} remain`)
+    }
+    throw new Error(`storage: gave up deleting the stored files of ${room} after ${MAX_REMOVE_ROUNDS} rounds`)
+  }
+}
+
+const alreadyExists = (error) => String(error.statusCode) === '409' || /exists|duplicate/i.test(String(error.message))
+
+export function makeStore (cfg, dir) {
+  // Half set up is a mistake: falling back to the disk would quietly fill it.
+  if (!cfg.storageUrl !== !cfg.storageKey) {
+    throw new Error('Large-file storage is half set up: set both QUILT_STORAGE_URL and QUILT_STORAGE_KEY to use Supabase Storage, or neither to keep files on the relay\'s disk.')
+  }
+  if (cfg.storageUrl && cfg.storageKey) return new SupabaseStore({ url: cfg.storageUrl, key: cfg.storageKey, bucket: cfg.storageBucket })
+  return new DiskStore(dir)
+}

package/src/boxes.js

@@ -0,0 +1,37 @@
+// Boxes as the app shows them (docs/superpowers/specs/2026-10-16-git-boxes-design.md): a box is
+// someone's unfinished work on one file. For each, what it changes from the version the viewer's
+// folder has (theirs: from before the box; ours: what git last committed), counted line by line.
+import { lineDiff } from './history.js'
+
+const isBin = (v) => !!v && typeof v === 'object' && v.binary === true
+const textOf = (v) => (v == null || isBin(v) ? '' : String(v))
+
+/**
+ * One box for the app. `before` and `after` are the file's text, null (no file) or { binary: true }.
+ * The diff is capped as history's are; added and removed count every line all the same.
+ */
+export function boxEntry ({ claim, mine = false, before = null, after = null }) {
+  const kind = before == null && after != null ? 'new' : after == null && before != null ? 'deleted' : isBin(before) || isBin(after) ? 'binary' : 'edited'
+  let added = 0
+  let removed = 0
+  let diff = ''
+  if (kind !== 'binary') {
+    diff = lineDiff(textOf(before), textOf(after))
+    for (const line of lineDiff(textOf(before), textOf(after), { context: 0, max: Infinity }).split('\n')) {
+      if (line.startsWith('+')) added++
+      else if (line.startsWith('-')) removed++
+    }
+  }
+  return {
+    path: claim.pattern,
+    by: claim.by,
+    ...(claim.of ? { of: claim.of } : {}),
+    ts: claim.ts || 0,
+    mine: !!mine,
+    kind,
+    added,
+    removed,
+    diff,
+    queue: Array.isArray(claim.queue) ? claim.queue.map((r) => ({ id: r.id, by: r.by })) : []
+  }
+}