heyquilt 0.0.1 → 0.3.90

package/src/api/routes/agents.js

@@ -0,0 +1,157 @@
+// Agents: swapping a refresh key, who an agent is, and a person's personal agents,
+// with the app keys (qk_) that let an app like Pipedream sign one in.
+import { HttpError, needId, cleanName } from '../http.js'
+import { parsePublicKey, verifyAgentResume } from '../../identity.js'
+import { keyStatus } from '../agent-auth.js'
+import { encodeAgentEnvKey } from '../../ui/agent-env-key.js'
+
+// Live app keys an agent may hold at once.
+export const MAX_APP_KEYS = 10
+const keyName = (v) => cleanName(typeof v === 'string' ? v : '', 40, 'name the key (up to 40 characters), e.g. Pipedream')
+const keyView = (k) => ({ id: k.id, name: k.name, createdAt: k.createdAt, lastUsedAt: k.lastUsedAt })
+
+// Never the key itself, just whether it has one. With a key it joins sessions from a computer
+// running Quilt; without one it is hosted: it joins through the API's /mcp. Either way it can join.
+const profileOf = (a) => ({ id: a.id, name: a.name, provider: a.provider, type: a.type, description: a.description, canJoinSessions: true, hosted: !a.publicKey })
+
+export function agentRoutes ({ store, user, person, now, limit, limitTokens, limitStarts, spendResume, resumeWindowMs, agentAuth, apiUrl }) {
+  // A personal agent of this person's that isn't revoked; anyone else's gets the same 404 as a missing one.
+  async function mine (req, id, who = user) {
+    const u = await who(req)
+    const agent = await store.agentById(needId(id, 'agent'))
+    if (!agent || agent.ownerUserId !== u.userId || agent.revokedAt) throw new HttpError(404, 'no such agent')
+    return agent
+  }
+  async function newAppKey (agent, name) {
+    if ((await store.listAgentAppKeys(agent.id)).length >= MAX_APP_KEYS) throw new HttpError(409, `an agent can have ${MAX_APP_KEYS} app keys; revoke one first`)
+    return agentAuth.mintAppKey(agent.id, name)
+  }
+  const connect = (agent, key) => ({ agent: profileOf(agent), key, mcp: `${apiUrl}/mcp` })
+  // A sandbox's QUILT_AGENT_KEY (ui/agent-env-key.js): a new app key with the API and the session it works in.
+  async function envKeyFor (agent, session, name) {
+    let envKey
+    const check = { api: apiUrl, key: 'qk_check', session, name: agent.name }
+    try { encodeAgentEnvKey(check) } catch (err) { throw new HttpError(400, err.message) }
+    const key = await newAppKey(agent, keyName(name || 'Sandbox'))
+    try { envKey = encodeAgentEnvKey({ ...check, key: key.key }) } catch (err) { throw new HttpError(400, err.message) }
+    return { envKey, key: keyView(key) }
+  }
+
+  return [
+    ['POST', /^\/v1\/agents\/token$/, async (req, body) => {
+      limitTokens(req)
+      return agentAuth.refresh(body.refreshKey)
+    }],
+
+    // An agent whose refresh key stopped working gets new keys with its resume key (every
+    // agent gets one when it joins), or by signing for the key it joined with (agents on a
+    // computer that joined before resume keys). A stolen refresh key alone can't do this,
+    // and an agent a person revoked can't either: it's invited again.
+    ['POST', /^\/v1\/agents\/resume$/, async (req, body) => {
+      limitStarts(req)
+      if (body.resumeKey !== undefined) return agentAuth.resumeByKey(body.resumeKey)
+      const at = Number(body.at)
+      if (!Number.isFinite(at) || Math.abs(now() - at) > resumeWindowMs) throw new HttpError(400, "this computer's clock is off; check its date and time")
+      const agent = await store.agentById(needId(body.agentId, 'agent'))
+      const key = agent && parsePublicKey(agent.publicKey)
+      if (!key) throw new HttpError(404, 'no such agent')
+      if (!verifyAgentResume(key, agent.id, at, body.signature)) throw new HttpError(401, "this agent's signature doesn't match")
+      await spendResume(String(body.signature), at)
+      return agentAuth.resume(agent)
+    }],
+
+    ['GET', /^\/v1\/agents\/me$/, async (req) => {
+      const { agent } = await agentAuth.agentFromRequest(req)
+      const mcp = `${apiUrl}/mcp`
+      if (!agent.orgId) return { agent: { ...profileOf(agent), kind: 'personal', org: null }, teams: [], role: null, mcp }
+      const [org, m, teams] = await Promise.all([store.orgById(agent.orgId), store.memberByAgent(agent.orgId, agent.id), store.listTeams(agent.orgId)])
+      const [role, mine] = await Promise.all([m?.roleId ? store.roleById(agent.orgId, m.roleId) : null, m ? store.teamsOfMember(m.id) : []])
+      const names = new Map(teams.map((x) => [x.id, x.name]))
+      return {
+        agent: { ...profileOf(agent), kind: 'org', org: { slug: org.slug, name: org.name } },
+        teams: mine.map((x) => ({ id: x.teamId, name: names.get(x.teamId) || '', access: x.access, scopes: x.scopes })),
+        role: role ? { name: role.name } : null,
+        mcp
+      }
+    }],
+
+    // Listed on the website and in the app (a linked computer's token counts as its person).
+    ['GET', /^\/v1\/agents$/, async (req) => {
+      const u = await person(req)
+      // The person's cloud AI (routes/ai-vm.js) has its own card, so its agent isn't listed with the others.
+      const vm = store.aiVmOf ? await store.aiVmOf(u.userId) : null
+      // Until the machine first asks for work, its agent is known by the one-time invite it joined with.
+      const invite = vm && !vm.agentId && vm.inviteId ? await store.agentInviteById(vm.inviteId) : null
+      const cloudId = (vm && vm.agentId) || (invite && invite.usedByAgentId) || null
+      const agents = (await store.listPersonalAgents(u.userId)).filter((a) => a.id !== cloudId)
+      return {
+        agents: await Promise.all(agents.map(async (a) => ({
+          ...profileOf(a),
+          createdAt: a.createdAt,
+          lastUsedAt: a.lastUsedAt,
+          // Why an agent is signed out (reused or expired keys), so the dashboard can say so.
+          // A live app key keeps it signed in whatever its own keys did.
+          status: (await store.listAgentAppKeys(a.id)).length ? 'active' : keyStatus(await store.listAgentKeys(a.id), now())
+        })))
+      }
+    }],
+
+    // Connecting an app (Pipedream, Zapier, Make, n8n, a script): a new hosted agent of this
+    // person's, named for the app, and its first app key. The key is shown once.
+    ['POST', /^\/v1\/agents\/apps$/, async (req, body) => {
+      const u = await user(req)
+      limit(req)
+      const name = cleanName(typeof body.name === 'string' ? body.name : '', 40, 'give the agent a name (up to 40 characters), e.g. Pipedream')
+      const provider = body.provider == null || body.provider === '' ? name : cleanName(String(body.provider), 40, 'provider: up to 40 characters')
+      const agent = await store.createAgent({ name, provider, type: 'app', ownerUserId: u.userId, invitedBy: u.userId })
+      return connect(agent, await newAppKey(agent, provider))
+    }],
+
+    // An agent making an app key for itself, signed in with its access key (never an app key: a
+    // key pasted into an app or a sandbox can't make more). For `quilt agent join --print-env` and
+    // `quilt agent env`: its owner sees the key with its others on heyquilt.com and can revoke it.
+    // With `session`, the answer is a whole QUILT_AGENT_KEY.
+    ['POST', /^\/v1\/agents\/me\/keys$/, async (req, body) => {
+      const { agent, keyRow } = await agentAuth.agentFromRequest(req)
+      if (!keyRow) throw new HttpError(403, 'sign in with the agent\'s access key (an app key can\'t make keys)')
+      if (!agent.ownerUserId) throw new HttpError(403, 'only a personal agent makes its own keys; an org agent\'s are made by its org')
+      limit(req)
+      if (body.session != null && body.session !== '') return envKeyFor(agent, String(body.session), body.name)
+      return newAppKey(agent, keyName(body.name || 'Sandbox'))
+    }],
+
+    // A person making a sandbox's QUILT_AGENT_KEY for their agent (the website, the app): a new app key
+    // with the session it works in. Shown once; revoked like any of the agent's app keys.
+    ['POST', /^\/v1\/agents\/([^/]+)\/env-key$/, async (req, body, [id]) => {
+      const agent = await mine(req, id, person)
+      limit(req)
+      return envKeyFor(agent, String(body.session || ''), body.name)
+    }],
+
+    ['GET', /^\/v1\/agents\/([^/]+)\/keys$/, async (req, body, [id]) => {
+      const agent = await mine(req, id)
+      return { keys: (await store.listAgentAppKeys(agent.id)).map(keyView) }
+    }],
+
+    ['POST', /^\/v1\/agents\/([^/]+)\/keys$/, async (req, body, [id]) => {
+      const agent = await mine(req, id)
+      limit(req)
+      return connect(agent, await newAppKey(agent, keyName(body.name)))
+    }],
+
+    ['DELETE', /^\/v1\/agents\/([^/]+)\/keys\/([^/]+)$/, async (req, body, [id, keyId]) => {
+      const agent = await mine(req, id)
+      if (!await store.revokeAgentAppKey(agent.id, needId(keyId, 'key'))) throw new HttpError(404, 'no such key')
+      return { ok: true }
+    }],
+
+    ['DELETE', /^\/v1\/agents\/([^/]+)$/, async (req, body, [id]) => {
+      const u = await user(req)
+      const agent = await store.agentById(needId(id, 'agent'))
+      // Someone else's agent gets the same answer as a missing one.
+      if (!agent || agent.ownerUserId !== u.userId || agent.revokedAt) throw new HttpError(404, 'no such agent')
+      await store.revokeAgent(agent.id)
+      return { ok: true }
+    }]
+  ]
+}

package/src/api/routes/ai-vm.js

@@ -0,0 +1,369 @@
+// A person's AI on its own cloud machine (docs/superpowers/specs/2026-10-17-ai-vm.md): Quilt
+// starts one Fly Machine with one volume per person, which signs in as an agent of theirs (keys
+// only on the machine) and signs their AI tool in with the tool's own login. These routes are
+// the person's (connect, settings, the sign-in, sessions to follow, wake, disconnect), the
+// machine's own (what is waiting for it, its reports, "suspend me"), and the relay's (wake it).
+//
+// Links to sessions, sign-in steps and pasted codes live here in memory only, until the machine
+// or the app collects them: none is ever stored. Quilt never sees a Claude, OpenAI or Cursor token.
+import crypto from 'node:crypto'
+import { HttpError, UUID } from '../http.js'
+import { newToken, hashToken } from '../tokens.js'
+import { AGENT_INVITE_TTL_MS } from './agent-invites.js'
+import { parseInvite, buildInvite } from '../../ui/invite.js'
+import { isHostedRelay, HOSTED_RELAY } from '../../settings.js'
+import { autoToolFor } from '../../autowork-tools.js'
+
+export const AI_VM_TOOLS = ['Claude Code', 'Codex', 'Cursor']
+// The machine reports about once a minute; one not heard from for this long may have stopped.
+const QUIET_MS = 3 * 60 * 1000
+// How long a waiting GET is held before it answers with nothing new.
+export const WAIT_MS = 25 * 1000
+// The relay asks again for each new event; once a minute per machine is plenty.
+const RELAY_WAKE_MS = 60 * 1000
+const MAX_PENDING = 50
+// Control characters, kept out of anything shown in the app.
+const CONTROL = /[\u0000-\u001f\u007f]/g // eslint-disable-line no-control-regex
+const STEPS = ['starting', 'link', 'code', 'waiting', 'done', 'failed']
+const CODE = /^[A-Za-z0-9-]{1,40}$/
+const ROOM = /^[A-Za-z0-9_-]{1,64}$/
+const digest = (s) => crypto.createHash('sha256').update(String(s)).digest()
+
+/** What the person's app shows of a sign-in step: a link, a device code, whether to paste a code back. */
+export function cleanSignIn (s) {
+  if (!s || typeof s !== 'object' || !STEPS.includes(s.step)) return null
+  let url = ''
+  try { const u = new URL(String(s.url || '')); if (u.protocol === 'https:' && u.href.length <= 2000) url = u.href } catch {}
+  const code = typeof s.code === 'string' && CODE.test(s.code) ? s.code : ''
+  const error = typeof s.error === 'string' ? s.error.replace(CONTROL, ' ').slice(0, 300) : ''
+  return { step: s.step, url, code, needsCode: s.needsCode === true, error }
+}
+
+const cleanUsage = (u) => {
+  if (!u || typeof u !== 'object') return {}
+  const n = (x) => (Number.isFinite(Number(x)) && Number(x) >= 0 ? Math.floor(Number(x)) : 0)
+  return { tokens: n(u.tokens), runs: n(u.runs) }
+}
+
+const cleanSessions = (list) => (Array.isArray(list) ? list : []).slice(0, 50)
+  .filter((x) => x && ROOM.test(String(x.room)))
+  .map((x) => ({ room: String(x.room), name: String(x.name || '').replace(CONTROL, '').slice(0, 80) }))
+
+/**
+ * The cloud AI machine record whose agent `agent` is, or null. The agent that used a machine's
+ * one-time invite is its agent: the record learns so the first time it is asked.
+ */
+export async function cloudAiOf (store, agent) {
+  if (!agent) return null
+  const vm = await store.aiVmByAgent(agent.id)
+  if (vm || !agent.ownerUserId) return vm
+  const theirs = await store.aiVmOf(agent.ownerUserId)
+  const invite = theirs && !theirs.agentId && theirs.inviteId ? await store.agentInviteById(theirs.inviteId) : null
+  if (!invite || invite.usedByAgentId !== agent.id) return null
+  return store.updateAiVm(theirs.userId, { agentId: agent.id })
+}
+
+export function aiVmRoutes ({ store, person, agentAuth, bearer, now, apiUrl, log = () => {}, limit, relaySecret = '', relayUrl = HOSTED_RELAY, fly = null, waitMs = WAIT_MS }) {
+  // user id -> { version, signIn, sessions, waiters, forVm: { follow, leave, signIn, code, waiters } }
+  const live = new Map()
+  const ownRelay = String(relayUrl).replace(/\/+$/, '').replace(/^http(s?):\/\//, 'ws$1://')
+  const relayWokeAt = new Map()
+
+  const liveOf = (userId) => {
+    let l = live.get(userId)
+    if (!l) { l = { version: 1, signIn: null, sessions: [], waiters: new Set(), forVm: { follow: [], leave: [], signIn: false, code: null, waiters: new Set() } }; live.set(userId, l) }
+    return l
+  }
+  const wakeWaiters = (set) => { for (const w of [...set]) w(); set.clear() }
+  /** Something the app shows changed: its waiting GET answers. */
+  const bump = (userId) => { const l = liveOf(userId); l.version++; wakeWaiters(l.waiters) }
+  /** Something is waiting for the machine: its waiting GET answers. */
+  const poke = (userId) => wakeWaiters(liveOf(userId).forVm.waiters)
+  const hold = (set, ms) => new Promise((resolve) => {
+    const done = () => { clearTimeout(timer); set.delete(done); resolve() }
+    const timer = setTimeout(done, ms)
+    set.add(done)
+  })
+
+  const needFly = () => { if (!fly) throw new HttpError(503, "Cloud AI isn't set up on this server.") }
+  async function mine (req) {
+    const u = await person(req)
+    const vm = await store.aiVmOf(u.userId)
+    if (!vm) throw new HttpError(404, "You haven't connected a cloud AI.")
+    return { u, vm }
+  }
+
+  /** The machine's record as the person's app shows it. */
+  function view (vm) {
+    const l = liveOf(vm.userId)
+    return {
+      tool: vm.tool,
+      model: vm.model,
+      models: autoToolFor(vm.tool)?.models || [],
+      prompt: vm.prompt,
+      cap: vm.cap,
+      state: vm.state,
+      error: vm.error,
+      signedIn: vm.signedIn,
+      signIn: l.signIn,
+      sessions: l.sessions,
+      usageToday: vm.usageToday || {},
+      region: vm.region,
+      lastReportAt: vm.lastReportAt,
+      connectedAt: vm.createdAt,
+      version: l.version
+    }
+  }
+
+  /**
+   * Resumes the machine (or starts it after a crash) unless it is running and was heard from
+   * lately. A Fly failure is logged and the machine is left as it was: the next wake tries again.
+   */
+  async function wake (vm, why) {
+    if (!fly || !vm.machineId) return vm
+    const quiet = !vm.lastReportAt || now() - vm.lastReportAt > QUIET_MS
+    if (vm.state === 'running' && !quiet) return vm
+    if (vm.state === 'starting' && vm.updatedAt && now() - vm.updatedAt < QUIET_MS) return vm
+    try {
+      await fly.start(vm.machineId)
+      log(`cloud AI ${vm.userId}: woken (${why})`)
+      const up = await store.updateAiVm(vm.userId, { state: 'starting', error: '' })
+      bump(vm.userId)
+      return up || vm
+    } catch (err) {
+      log(`cloud AI ${vm.userId}: could not wake it (${why}): ${err.message}`)
+      return vm
+    }
+  }
+
+  /** Deletes the person's machine, its disk and its agent. Fly answering "already gone" is fine. */
+  async function destroy (vm) {
+    if (fly && vm.machineId) await fly.destroyMachine(vm.machineId)
+    if (fly && vm.volumeId) await fly.destroyVolume(vm.volumeId)
+    if (vm.agentId) await store.revokeAgent(vm.agentId)
+    if (vm.inviteId) await store.cancelAgentInvite(vm.inviteId).catch(() => {})
+    await store.deleteAiVm(vm.userId)
+    wakeWaiters(liveOf(vm.userId).forVm.waiters)
+    bump(vm.userId)
+    live.delete(vm.userId)
+  }
+
+  /** The machine calling, with the person's record: its agent must be the person's cloud AI. */
+  async function machine (req) {
+    const { agent } = await agentAuth.agentFromRequest(req)
+    const vm = await cloudAiOf(store, agent)
+    if (!vm) throw new HttpError(404, "this agent isn't a cloud AI")
+    return { agent, vm }
+  }
+
+  const pendingFor = (f) => f.follow.length || f.leave.length || f.signIn || f.code !== null
+
+  function cleanSettings (b, vm) {
+    const out = {}
+    if (b.tool !== undefined) {
+      if (!AI_VM_TOOLS.includes(b.tool)) throw new HttpError(400, `tool is one of ${AI_VM_TOOLS.join(', ')}`)
+      // A new tool signs in again and starts from its own models.
+      if (b.tool !== vm.tool) Object.assign(out, { tool: b.tool, signedIn: false, model: '' })
+    }
+    if (b.model !== undefined) {
+      if (typeof b.model !== 'string' || b.model.length > 80 || /[\s<>]/.test(b.model)) throw new HttpError(400, 'model: up to 80 characters, no spaces')
+      out.model = b.model
+    }
+    if (b.prompt !== undefined) {
+      if (typeof b.prompt !== 'string' || b.prompt.length > 4000) throw new HttpError(400, 'prompt: up to 4000 characters')
+      out.prompt = b.prompt.replace(/\r\n/g, '\n')
+    }
+    if (b.cap !== undefined) {
+      if (!Number.isInteger(b.cap) || b.cap < 0 || b.cap > 1e10) throw new HttpError(400, 'cap: tokens a day, a whole number (0 for none)')
+      out.cap = b.cap
+    }
+    return out
+  }
+
+  const routes = [
+    ['GET', /^\/v1\/me\/ai-vm$/, async (req) => {
+      const { u, vm } = await mine(req)
+      const wait = Number(new URL(req.url, 'http://x').searchParams.get('wait'))
+      // The app's long poll: held while nothing changed since the version it has.
+      if (Number.isFinite(wait) && wait > 0 && wait >= liveOf(u.userId).version) {
+        await hold(liveOf(u.userId).waiters, waitMs)
+        const again = await store.aiVmOf(u.userId)
+        if (!again) throw new HttpError(404, "You haven't connected a cloud AI.")
+        return view(again)
+      }
+      return view(vm)
+    }],
+
+    ['POST', /^\/v1\/me\/ai-vm$/, async (req, body) => {
+      const u = await person(req)
+      needFly()
+      limit(req)
+      if (!AI_VM_TOOLS.includes(body.tool)) throw new HttpError(400, `tool is one of ${AI_VM_TOOLS.join(', ')}`)
+      if (await store.aiVmOf(u.userId)) throw new HttpError(409, 'You already have a cloud AI. Disconnect it first.')
+      // The machine joins as the person's agent with a one-time link, so its keys are made there.
+      const token = newToken('qj_')
+      const invite = await store.createAgentInvite({ tokenHash: hashToken(token), ownerUserId: u.userId, createdBy: u.userId, expiresAt: now() + AGENT_INVITE_TTL_MS })
+      let vm = await store.createAiVm({ userId: u.userId, tool: body.tool, region: fly.region })
+      vm = await store.updateAiVm(u.userId, { inviteId: invite.id })
+      const short = crypto.createHash('sha256').update(u.userId).digest('hex').slice(0, 20)
+      let volume = null
+      try {
+        volume = await fly.createVolume({ name: `ai_${short}` })
+        const m = await fly.createMachine({
+          name: `ai-${short}`,
+          volumeId: volume.id,
+          env: { QUILT_API: apiUrl, QUILT_AI_VM_JOIN: `${apiUrl}/v1/join/${token}`, HOME: '/data/home' }
+        })
+        vm = await store.updateAiVm(u.userId, { machineId: m.id, volumeId: volume.id, region: m.region || volume.region || fly.region, state: 'starting' })
+      } catch (err) {
+        log(`cloud AI ${u.userId}: could not create it: ${err.message}`)
+        if (volume) await fly.destroyVolume(volume.id).catch(() => {})
+        await store.cancelAgentInvite(invite.id).catch(() => {})
+        await store.deleteAiVm(u.userId)
+        throw new HttpError(502, `Couldn't start your cloud AI. ${err.message}`)
+      }
+      log(`cloud AI ${u.userId}: created ${vm.machineId} (${vm.tool})`)
+      bump(u.userId)
+      return view(vm)
+    }],
+
+    ['PATCH', /^\/v1\/me\/ai-vm$/, async (req, body) => {
+      const { u, vm } = await mine(req)
+      const patch = cleanSettings(body, vm)
+      if (!Object.keys(patch).length) return view(vm)
+      let up = await store.updateAiVm(u.userId, patch)
+      bump(u.userId)
+      poke(u.userId)
+      up = await wake(up, 'settings')
+      return view(up)
+    }],
+
+    // Starts (or restarts) the tool's sign-in on the machine; with `code`, the code the tool's
+    // page showed, for the tool to take (Claude's). Held in memory until the machine collects it.
+    ['POST', /^\/v1\/me\/ai-vm\/sign-in$/, async (req, body) => {
+      const { u, vm } = await mine(req)
+      const f = liveOf(u.userId).forVm
+      if (body.code !== undefined) {
+        const code = typeof body.code === 'string' ? body.code.trim() : ''
+        if (!code || code.length > 2000 || /\s/.test(code)) throw new HttpError(400, 'paste the code the sign-in page showed')
+        f.code = code
+      } else {
+        f.signIn = true
+        liveOf(u.userId).signIn = { step: 'starting', url: '', code: '', needsCode: false, error: '' }
+        bump(u.userId)
+      }
+      poke(u.userId)
+      await wake(vm, 'sign-in')
+      return { ok: true }
+    }],
+
+    // The person's app hands over the link of a session they joined (or says they left one for
+    // good). Not kept here: the machine collects it, and keeps it on its own disk.
+    ['POST', /^\/v1\/me\/ai-vm\/follow$/, async (req, body) => {
+      const { u, vm } = await mine(req)
+      const f = liveOf(u.userId).forVm
+      if (body.leave === true) {
+        if (!ROOM.test(String(body.room || ''))) throw new HttpError(400, 'room must be a session name')
+        f.follow = f.follow.filter((l) => parseInvite(l, { allowRelay: () => true }).room !== body.room)
+        if (!f.leave.includes(body.room)) f.leave = [...f.leave, body.room].slice(-MAX_PENDING)
+      } else {
+        let invite
+        try { invite = parseInvite(String(body.link || ''), { allowRelay: (s) => isHostedRelay(s) || String(s).replace(/\/+$/, '') === ownRelay }) } catch { throw new HttpError(400, "link must be a Quilt session's invite link") }
+        if (!invite.secret) throw new HttpError(400, "link must be a Quilt session's invite link")
+        const link = buildInvite({ server: invite.relay || HOSTED_RELAY, room: invite.room, secret: invite.secret }, isHostedRelay)
+        f.leave = f.leave.filter((r) => r !== invite.room)
+        f.follow = [...f.follow.filter((l) => parseInvite(l, { allowRelay: () => true }).room !== invite.room), link].slice(-MAX_PENDING)
+      }
+      poke(u.userId)
+      await wake(vm, 'follow')
+      return { ok: true }
+    }],
+
+    ['POST', /^\/v1\/me\/ai-vm\/wake$/, async (req) => {
+      const { vm } = await mine(req)
+      needFly()
+      return view(await wake({ ...vm, lastReportAt: 0 }, 'asked'))
+    }],
+
+    ['DELETE', /^\/v1\/me\/ai-vm$/, async (req) => {
+      const { vm } = await mine(req)
+      try { await destroy(vm) } catch (err) {
+        log(`cloud AI ${vm.userId}: could not delete it: ${err.message}`)
+        throw new HttpError(502, `Couldn't delete your cloud AI machine; try again. ${err.message}`)
+      }
+      log(`cloud AI ${vm.userId}: disconnected`)
+      return { ok: true }
+    }],
+
+    // The machine: its settings, and what waits for it, each handed over once. `?wait=1` holds
+    // the request while nothing waits.
+    ['GET', /^\/v1\/ai-vm\/next$/, async (req) => {
+      const { vm } = await machine(req)
+      const f = liveOf(vm.userId).forVm
+      if (new URL(req.url, 'http://x').searchParams.get('wait') && !pendingFor(f)) await hold(f.waiters, waitMs)
+      const fresh = (await store.aiVmOf(vm.userId)) || vm
+      const p = await store.profile(vm.userId)
+      const out = {
+        config: { tool: fresh.tool, model: fresh.model, prompt: fresh.prompt, cap: fresh.cap, person: (p && p.name) || 'Quilt user' },
+        follow: f.follow,
+        leave: f.leave,
+        signIn: f.signIn,
+        code: f.code
+      }
+      Object.assign(f, { follow: [], leave: [], signIn: false, code: null })
+      return out
+    }],
+
+    ['POST', /^\/v1\/ai-vm\/report$/, async (req, body) => {
+      const { vm } = await machine(req)
+      const l = liveOf(vm.userId)
+      const patch = { state: 'running', error: '', lastReportAt: now() }
+      if (typeof body.signedIn === 'boolean') patch.signedIn = body.signedIn
+      if (body.usageToday !== undefined) patch.usageToday = cleanUsage(body.usageToday)
+      if (body.signIn !== undefined) l.signIn = cleanSignIn(body.signIn)
+      if (body.sessions !== undefined) l.sessions = cleanSessions(body.sessions)
+      await store.updateAiVm(vm.userId, patch)
+      bump(vm.userId)
+      return { ok: true }
+    }],
+
+    // The machine has nothing to do: suspend it (unless something came for it meanwhile).
+    ['POST', /^\/v1\/ai-vm\/idle$/, async (req) => {
+      const { vm } = await machine(req)
+      if (pendingFor(liveOf(vm.userId).forVm)) throw new HttpError(409, 'work is waiting for you')
+      needFly()
+      await store.updateAiVm(vm.userId, { state: 'suspended' })
+      bump(vm.userId)
+      try { await fly.suspend(vm.machineId) } catch (err) {
+        log(`cloud AI ${vm.userId}: could not suspend it: ${err.message}`)
+        await store.updateAiVm(vm.userId, { state: 'running' })
+        throw new HttpError(502, err.message)
+      }
+      return { ok: true }
+    }],
+
+    // The relay: a mention, a message or a task waits for a cloud AI that isn't connected.
+    ['POST', /^\/v1\/relay\/ai-vm\/wake$/, async (req, body) => {
+      if (!relaySecret) throw new HttpError(503, 'the relay is not set up on this server')
+      if (!crypto.timingSafeEqual(digest(bearer(req)), digest(relaySecret))) throw new HttpError(401, 'only the relay may do that')
+      const agentId = String(body.agent || '')
+      const agent = UUID.test(agentId) ? await store.agentById(agentId) : null
+      const vm = agent && !agent.revokedAt ? await cloudAiOf(store, agent) : null
+      if (!vm) throw new HttpError(404, 'no such cloud AI')
+      const last = relayWokeAt.get(agentId) || 0
+      if (now() - last < RELAY_WAKE_MS) return { ok: true, already: true }
+      relayWokeAt.set(agentId, now())
+      if (relayWokeAt.size > 10_000) relayWokeAt.delete(relayWokeAt.keys().next().value)
+      await wake(vm, `waiting in ${ROOM.test(String(body.room)) ? body.room : 'a session'}`)
+      return { ok: true }
+    }]
+  ]
+
+  /** For account deletion: the person's machine goes with them. */
+  async function destroyFor (userId) {
+    const vm = await store.aiVmOf(userId)
+    if (vm) await destroy(vm)
+  }
+
+  return { routes, destroyFor }
+}