heyquilt 0.0.1 → 0.3.90

package/src/relay-mcp.js

@@ -0,0 +1,1679 @@
+// MCP servers hosted by the relay, working directly on a room's shared document.
+//
+// Hosted agents (handleHostedMcp): an AI with no computer of its own, or one that
+// can't install Quilt, connects to https://<relay>/mcp with a pass from the accounts
+// API (the API's /mcp hands it over with the agent's access key). It joins a session
+// from an invite link, waits for the owner like anyone else, and then reads and
+// writes the shared files, shares what it's doing, messages and claims files. Its
+// file changes are CRDT edits, so they merge with everyone else's.
+//
+// The older link-based server (handleAgentMcp) is kept for relays without sign-in.
+import { projectRules, renderRules } from './project-rules.js'
+import { cleanGit, branchBoard, branchesMarkdown } from './branches.js'
+import crypto from 'node:crypto'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { z } from 'zod'
+import * as Y from 'yjs'
+import { capText, toolLabel } from './agents/common.js'
+import { globMatcher, isSafeRelPath } from './pathrules.js'
+import { readTasks, addTask, updateTask, deleteTask, taskMarkdown, formatTasks, columnName, assigneeLabel, assignmentFields, COLUMNS } from './tasks.js'
+import { readComments, addComment, withComments, formatTaskDetails, MAX_COMMENT } from './task-comments.js'
+import { applyTextDiff } from './textdiff.js'
+import { parseInvite } from './ui/invite.js'
+import { scanInbox, renderInbox } from './inbox.js'
+import { withContext, queryConversation, renderConversation, CONVERSATION_DESCRIPTION } from './conversation.js'
+import { cleanFiles, describeCommitRequests, REQUEST_COMMIT_DESCRIPTION, MAX_REQUEST_FILES } from './commit.js'
+import { commitRequestMessage } from './commit-request.js'
+import { GIT_COMMIT_DESCRIPTION, gitCommitSchema, agentPrefix, slug } from './github-commit.js'
+import { liveSyncOn, agentCommitRefusal, ownFiles } from './relay-outbound.js'
+import { syncStatusText, SYNC_STATUS_DESCRIPTION } from './sync-words.js'
+import { clashAction, heldForClash, CLASH_DESCRIPTION, clashSchema } from './relay-clash.js'
+import { agentCommitsOf, repoRecordFor, POLICY_WORDS, pullRequestsFor, mergeForMember, describePulls, describeMerge, PULLS_DESCRIPTION, MERGE_DESCRIPTION, mergeSchema, agentsCanCommit, unpublishedFor, unpublishedRefusal, finishTaskFor, gitCommitFor, describeGitCommit, gitStatusFor, describeGitStatus, gitLogFor, describeGitLog, gitDiffFor, describeGitDiff, GIT_STATUS_DESCRIPTION, GIT_LOG_DESCRIPTION, GIT_DIFF_DESCRIPTION, GIT_REVERT_DESCRIPTION } from './relay-commit.js'
+import { UpdateCheck } from './update-check.js'
+import { TASK_WORKFLOW, pickupBrief, doneRefusal, verifiedEnough, verifiedLine, qaRefusal, qaNotesEnough, qaNotesLine, pickChecklist, MAX_VERIFIED } from './agent-task-workflow.js'
+import { HistoryLog, queryHistory, parseSince, formatHistory, currentTask, lineDiff } from './history.js'
+import { changeRefusal, TALK_REFUSED } from './session-access.js'
+import { aiName } from './persona.js'
+import { chatAbout, renderChatAbout, waitingOn, needsNoReply, renderUnanswered, heldRefusal, queuedFor, renderQueueNotice, renderQueued, answered, unaddressed, CHAT_RULES, RE_HELP, replyFor, renderReplied } from './duties.js'
+import { describeSubscription, WEBHOOK_EVENTS } from './webhooks.js'
+import { registerWorkspaceTools, bytesFetcher, WORKSPACE_GUIDE_HOSTED } from './workspace-tools.js'
+import { DEFAULT_KEY, validBranchKey } from './branchdocs.js'
+import { LOAD_FILES } from './relay-upstream.js'
+import { hostedRooms, hostedIn, newHosted } from './hosted-agents.js'
+import { turnSyncStep, ROOM_KEY } from './relay-turn-sync.js'
+
+const FEED_CAP = 300
+const ACTIVITY_CAP = 300
+const TAB_STALE_MS = 3 * 60 * 1000
+const MAX_WRITE_BYTES = 1024 * 1024
+const HOSTED_AUTO_CLAIM_QUIET_MS = 10 * 60 * 1000 // a file a hosted agent stopped writing this long ago is let go of
+const MAX_READ_CHARS = 200 * 1024
+// Tools that read or change a branch's files, claims or history: a hosted agent's first one pins its branch (Room.pinHostedBranch).
+const FILE_TOOLS = new Set(['quilt_sync', 'quilt_history', 'quilt_list_files', 'quilt_read_file', 'quilt_project_rules', 'quilt_write_file', 'quilt_claim', 'quilt_release', 'quilt_unpack', 'quilt_request_file', 'quilt_handoff', 'quilt_withdraw_request'])
+const AGENT = 'agent-mcp' // transaction origin
+// The board's columns, from tasks.js: hosted agents move tasks to every one of them (QA included), like the local MCP.
+const COLUMN_IDS_LIST = COLUMNS.map((c) => c.id)
+
+export const INSTRUCTIONS =
+  'You are in a live quilt session: other people, each with their own AI, are editing this same project right now, ' +
+  'and their changes appear in your files as they happen. ' +
+  'When your user asks for something, call quilt_share with their request and a short plan before you start, and call it ' +
+  'again with a short summary when you finish, so collaborators can follow along. ' +
+  'Before starting a task, call quilt_status to see who is working on what, and quilt_tasks for the shared board ' +
+  '(open tasks assigned to you are listed first). Assign work with quilt_assign_task; quilt_task reads one task in full with its comments, and quilt_comment_task leaves a note or handoff on it. ' +
+  'quilt_history tells you who changed which file, when, with the diff: read it for the files you are about to touch. ' +
+  'Claims follow your edits: a file you change that nobody holds is claimed for you until you finish. ' +
+  'Do not edit files someone else has claimed: ask for the file in its file queue with quilt_request_file (a title and up to 300 characters on what you plan), and you are handed it with context when they are done. ' +
+  'When someone waits in the queue for a file you hold, finish your change and hand it off with quilt_handoff and your context; you cannot finish or release it before. Claim ahead only for a larger change across several files. Always re-read a file right before editing it. ' +
+  TASK_WORKFLOW
+
+export const HOSTED_INSTRUCTIONS =
+  'You are an AI agent in Quilt, where people and agents build one project together in real time. ' +
+  'Join a session with quilt_join_session and the invite link you were given; the session owner may have to let you in first ' +
+  '(quilt_session_info tells you). Then: quilt_status to see who is doing what, quilt_list_files and quilt_read_file to look ' +
+  'around, quilt_write_file to change a file (always read it right before; the file is claimed for you while you work on it: release it with quilt_release when done, unless it is boxed, below), quilt_claim ahead of a larger change across several files, quilt_share to ' +
+  'tell everyone what you are doing, and quilt_message to talk. The shared task board is quilt_tasks, quilt_add_task, quilt_assign_task and quilt_move_task; quilt_task reads one in full with its comments, and quilt_comment_task leaves a work note or handoff on it. ' +
+  'quilt_history tells you who changed which file, when, with the diff: read it for the files you are about to touch. ' +
+  'Do not edit files someone else has claimed: a refused write tells you who holds the file; ask for it in its file queue with quilt_request_file (a title, and up to 300 characters on what you plan) and carry on with other work: you are woken when it is handed to you. ' +
+  'When someone waits in the queue for a file you hold, every answer says so: finish your change, then hand it off 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 its queue. ' +
+  'Read what people said about a file before you change it: quilt_read_messages, and each write tells you what was said about that file. ' +
+  'On a branch that follows a GitHub repository, what you write stays in a box until you commit it (quilt_git_commit): everyone sees the change, but it is in nobody else\'s folder, so nobody else\'s git can commit it. Committing opens the box by itself; 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, and quilt_read_file says so) is their unfinished work: do not build on it; ask for it with quilt_request_file. ' +
+  'This rule is enforced: while someone who messaged or mentioned you waits for an answer, writes, claims and task changes are refused until you answer with quilt_message. ' +
+  'Everyone sees your changes on their own disk within moments. ' +
+  'Chat: ' + CHAT_RULES.replace(/^Send a chat message\. /, '') + ' A message that needs nothing back is settled with quilt_inbox (no_reply: [its id]), not answered. ' +
+  'Mentions of you (@yourname), direct messages and tasks handed to you wait in quilt_inbox, each with the conversation before it with its sender; when a message refers to something earlier you do not have, read back with quilt_conversation before you answer, never guess. To be woken instead of polling, ' +
+  'call quilt_webhook_subscribe with a URL of yours: Quilt POSTs each one there as it happens, from every session you are in (and, for a workspace agent, session.started from your workspaces). ' +
+  'You can be in several sessions at once (quilt_join_session each): every tool then takes session: <id> (quilt_session_info lists them; a webhook event or inbox entry says which session it is from), and a call that names none is refused, so an answer never lands in the wrong session. ' +
+  'You are connected over HTTP, so you show as online for 30 minutes after each tool call: while idle, call quilt_inbox at least every 30 minutes so people can see you are still there. ' +
+  'HTTP is only for an agent with no computer. If you can run shell commands anywhere (a computer, a cloud machine, a sandbox), you must use the Quilt CLI there instead (`quilt agent join`, then `quilt join <invite> --agent <your name>`): files sync to disk and you show as live. ' +
+  'A session has a branch for each git branch its members work on, each with its own files: quilt_status and quilt_branches list them and who is on each, and your first call on files puts you on the busiest one, where you stay until you pick another with quilt_git_branch (create: true loads a branch that is on GitHub but not yet in the session, at its latest commit; any other new branch starts from a copy of the files you have). ' +
+  'Commits pushed or merged on GitHub 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. quilt_sync_branch asks for that now (at most once a minute per branch), for example after a PR merged. ' +
+  'When those commits clash with the session\'s uncommitted work, nothing is brought in and the relay gives one agent 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 the merged file without conflict markers; each such write makes the relay look again at once, and the rest of the commits come in when every file merges. If you kept one side whole, move the task to QA once all files are done: the relay then takes the files as merged. The task closes itself. ' +
+  'A private repository needs a read-only GitHub token on the relay: when quilt_status says the relay can\'t read it, ask the session owner (quilt_github_token sets it, owner only). You have no folder here, so git is the quilt_git_* tools: taking a task (quilt_move_task to doing) puts you on a branch of your own, quilt/<you>/<task>; quilt_git_commit commits your changed files there and opens the pull request tied to the task; quilt_git_status says where you stand, quilt_git_diff what differs from GitHub, quilt_git_log what was committed, quilt_git_revert puts GitHub\'s version of a file back. The session\'s branch itself is open to agents only when the owner lets agents push to any branch. Work only in the session has not shipped: commit before you move a task to QA. Done merges the task\'s pull request once its checks pass: a person moves it to Done, or you when the owner lets agents commit to any branch. quilt_git_pull_requests lists open pull requests with their checks; quilt_git_merge merges one (agents: when the owner lets agents commit to any branch). When agents may not commit, ask a person with quilt_request_commit. Pushes and merges on GitHub reach the session within seconds. ' +
+  'When a branch syncs with GitHub (quilt_git_status and quilt_branches say so), pushes and merges on GitHub come into the session by themselves, and nothing goes to GitHub until someone commits: quilt_git_commit commits your own changes (with_others: true takes others\' changes in the same files too, as co-authors). A file GitHub and the session both changed is held, and its merger proposes the merge with quilt_clash (the reviewer accepts). Releasing a file only lets go of your claim: it doesn\'t publish anything by itself. ' +
+  TASK_WORKFLOW
+
+const NOT_LINKED = 'Your user is not in a quilt session in their browser right now. Ask them to open quilt in their ' +
+  'browser and share a folder or join one from an invite link, then try again. (This link is theirs and works for every session.)'
+const NOT_JOINED = 'You are not in a session. Call quilt_join_session with an invite link (https://join.heyquilt.com/<room>#<secret>).'
+// Every hosted tool takes `session`: which of the agent's sessions it is about (an agent can be in several at once).
+const SESSION_ARG = z.string().min(1).max(64).optional().describe('Which of your sessions this is about (the session id from quilt_session_info, or the `session` in a webhook event or inbox entry). Needed when you are in more than one.')
+const WAITING = 'The session owner has not let you in yet. They see you on their list; call quilt_session_info to check again.'
+const DENIED = 'The session owner did not let you in. Ask them for a new invite and call quilt_join_session again.'
+const REMOVED = 'You are no longer in that session. Ask for a new invite and call quilt_join_session again.'
+// Let in by a grant, but the pass named no room: the accounts API retries with one for the
+// room in x-quilt-room. A client that reaches the relay some other way just calls again.
+const NEEDS_ROOM_PASS = 'Reconnecting you to the session. Call the same tool again.'
+
+const id = () => crypto.randomBytes(8).toString('hex')
+const BRING_IN_NOTE = 'Commits pushed or merged elsewhere come into the session by themselves: the folder of a member on that branch fetches about once a minute and brings them in. While no folder on a branch can (none online, or only ones that can\'t fetch, are held or diverged, or are a viewer\'s), the relay brings them in from GitHub itself, about every 10 minutes; quilt_sync_branch asks it to look now.'
+
+/** For a hosted agent: what the relay does about new commits on its branch, and when it last looked; or ''. */
+function relayStatus (room, key) {
+  const rec = room.meta && room.meta.upstreams ? room.meta.upstreams[room.resolveKey ? room.resolveKey(key) : key] : null
+  if (!rec || !rec.repo) return ''
+  const up = rec.name || 'its upstream'
+  if (!rec.checkedAt) return `The relay brings commits from ${up} into \`${key}\` while no folder on it is online; it hasn't looked yet.`
+  const bits = [`The relay last checked ${up} for new commits ${ago(rec.checkedAt)}.`]
+  if (rec.brought && rec.brought.at) bits.push(`It brought in ${rec.brought.count} commit${rec.brought.count === 1 ? '' : 's'} (${rec.brought.files} file${rec.brought.files === 1 ? '' : 's'}) ${ago(rec.brought.at)}.`)
+  if (rec.clash) bits.push(`Its clash with ${up} is task ${rec.clash.task} on the board.`)
+  if (rec.problem) bits.push(`Note: ${rec.problem}.`)
+  return bits.join(' ')
+}
+
+/** The chat `me` can see: public messages, and direct ones to or from them. */
+const chatFor = (doc, me) => doc.getArray('chat').toArray().filter((m) => m && m.id && (!m.to || m.to === me || m.by === me))
+
+/** Takes stock of a room for `me`'s inbox: what is already there wakes nobody. */
+function takeStock (doc, me) {
+  return { state: scanInbox({ messages: chatFor(doc, me), tasks: readTasks(doc.getMap('tasks')), reader: { name: me, asAi: false, agent: true } }).state }
+}
+
+// The link-based server is made anew for every request; a link's inbox lives here between them.
+const linkInboxes = new WeakMap()
+const text = (t) => ({ content: [{ type: 'text', text: t }] })
+const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true })
+
+function ago (ts) {
+  const s = Math.max(0, Math.round((Date.now() - ts) / 1000))
+  if (s < 60) return `${s}s ago`
+  if (s < 3600) return `${Math.round(s / 60)}m ago`
+  return `${Math.round(s / 3600)}h ago`
+}
+
+const cleanPath = (p) => String(p || '').trim().replace(/^\.\//, '').replace(/^\/+/, '')
+
+/**
+ * The tools every relay-hosted MCP offers, on whatever room `ctx.room()` gives now.
+ * ctx: { room(), me, who(), access(), tool(), warn() }: `who` is what claims belong to
+ * ({ name } or { name, id }), `access` the caller's role and folders, `warn` extra text
+ * for status, `withSession(fn)` runs a tool with the current room or explains why not.
+ */
+function sessionTools (server, ctx) {
+  // The agent's image (its Quilt version) came with the request; an old one is told to update in every answer.
+  const stale = (r) => {
+    const n = ctx.updates && ctx.image ? ctx.updates.notice(ctx.image()) : ''
+    if (!n || !r || !Array.isArray(r.content)) return r
+    return { ...r, content: [...r.content, { type: 'text', text: `⚠️ ${n}` }] }
+  }
+  // Someone waiting in the file queue for a file this agent holds is told to it with every answer, until it hands the file off.
+  const queueNote = (room, r) => {
+    const n = renderQueueNotice(queuedFor(claimsOf(room), me))
+    if (!n || !r || !Array.isArray(r.content)) return r
+    return { ...r, content: [...r.content, { type: 'text', text: `📥 ${n}` }] }
+  }
+  // Files, claims and history are a branch's: the agent's own (hosted agents can choose one), or the session's active branch.
+  const branchOf = (room) => ctx.branch ? ctx.branch(room) : room.activeBranch ? room.activeBranch() : null
+  /**
+   * An agent without a folder taking a task goes onto a branch of its own for it (quilt/<agent>/<task>,
+   * a copy of the default branch's files), as a folder agent's checkout does. Stays on a branch of its own
+   * that still has an open task; nothing when agents may not commit, or this relay has no branch documents.
+   */
+  const branchForHostedTask = (room, task) => {
+    if (ctx.kind !== 'agent' || !ctx.setBranch || !task || !task.title || room.meta.layout !== 2) return null
+    if (!agentsCanCommit(room, room.defaultKey)) return null
+    const prefix = agentPrefix(me)
+    const here = branchOf(room) || room.defaultKey
+    if (here.startsWith(prefix) && readTasks(room.doc.getMap('tasks')).some((t) => t && !t.archived && t.column !== 'done' && t.pr && t.pr.branch === here)) return null
+    let name = `${prefix}${slug(task.title)}`
+    for (let n = 2; room.meta.branches[room.resolveKey(name)] && n < 50; n++) name = `${prefix}${slug(task.title)}-${n}`
+    try {
+      if (here !== room.defaultKey) ctx.setBranch(room, room.defaultKey, {})
+      ctx.setBranch(room, name, { create: true, by: me, editor: true })
+      return name
+    } catch { return null }
+  }
+  // The branch document the agent works on (its store entry), or null for a room without branch documents.
+  // The session's default branch may always start; any other new branch only for someone who may change files.
+  const branchEntry = (room) => {
+    if (!room.branchDoc) return null
+    const key = branchOf(room)
+    const editor = room.resolveKey(key) === room.defaultKey || ctx.access(room)?.role !== 'viewer'
+    return room.branchDoc(key, { by: me, editor })
+  }
+  const tool = (name, def, fn) => server.registerTool(name, ctx.multi ? { ...def, inputSchema: { ...(def.inputSchema || {}), session: SESSION_ARG } } : def, async (given) => {
+    // Hosted agents are in several sessions at once: `session` says which this call is about.
+    const { session, ...args } = given || {}
+    return stale(await ctx.withSession((room) => {
+    // A hosted agent with no branch of its own is pinned to the active branch by its first call
+    // on files, so a read and the write after it never land on two different branches.
+    if (ctx.pin && FILE_TOOLS.has(name)) ctx.pin(room)
+    // The audit trail: which tool, on what (a path, a pattern or a task id; never contents).
+    const caller = ctx.who(room)
+    if (caller && caller.id && room.audit) {
+      const a = args || {}
+      const on = [a.path, a.pattern, a.id, a.under].find((x) => typeof x === 'string' && x)
+      room.audit(caller.id, 'tool', on ? `${name} ${on}` : name)
+    }
+    const doc = room.doc
+    const branch = branchEntry(room)
+    const fdoc = branch ? branch.doc : doc
+    const parts = { room, doc, fdoc, branch, feed: doc.getArray('agentFeed'), chat: doc.getArray('chat'), activity: doc.getArray('activity'), files: fdoc.getMap('files'), blobs: fdoc.getMap('blobs') }
+    // Changes the tool makes to the session (files, chat, the board) go in this agent's audit trail.
+    const prev = room.auditAs
+    room.auditAs = caller && caller.id
+    try { return queueNote(room, fn(args || {}, parts)) } finally { room.auditAs = prev }
+    }, session))
+  })
+  if (ctx.updates) {
+    server.registerTool('quilt_check_update', {
+      description: 'Whether the Quilt you run (your image) is current. Give the version you run (or send it as the x-quilt-image header with every request). An out-of-date image is told to update the app.',
+      inputSchema: { image: z.string().max(40).optional().describe('The Quilt version you run, such as 0.3.4') }
+    }, ({ image }) => text(ctx.updates.describe(image || (ctx.image ? ctx.image() : undefined))))
+  }
+  const me = ctx.me
+  const writable = (room) => room.full ? 'This session is over its size limit, so nothing new can be saved.' : null
+  // A branch over its own size limit takes no new files; the rest of the session carries on.
+  const branchWritable = (room, branch) => branch && room.branchFull && room.branchFull(branch.key) ? `${branch.key} is over the session's size limit for one branch, so nothing new can be saved on it. Other branches still take changes. Start a fresh copy with \`git checkout -b <new name>\`: your changes since are kept in your folder.` : null
+  // Which branch a file answer is about, when the session has more than one.
+  const onBranchNote = (room, branch) => branch && room.meta && Object.keys(room.meta.branches || {}).length > 1 ? ` on ${branch.key}` : ''
+  const visible = (m) => m && m.id && (!m.to || m.to === me || m.by === me)
+  // The chat this agent may read, kept past the room's newest 500 (chat-archive.js), oldest first.
+  const keptChat = (room, chat) => (room && room.chatArchive ? room.chatArchive.with(chat.toArray()) : chat.toArray()).filter(visible)
+  const fmtMsg = (m) => `- ${m.by}${m.to ? ` → ${m.to} (direct, id ${m.id}${m.re ? `, answers ${m.re}` : ''})` : ''} (${ago(m.ts)}): ${m.text}${m.file ? ` [file: ${m.file.name}]` : ''}`
+  const peers = (room) => {
+    const out = []
+    for (const s of room.awareness.getStates().values()) if (s && s.name && s.name !== me) out.push(s)
+    // AI sessions working through someone's app (persona.js) are members of their own.
+    for (const s of room.awareness.getStates().values()) {
+      for (const x of (s && Array.isArray(s.personas) ? s.personas : [])) {
+        if (x && typeof x.name === 'string' && x.name && x.name !== me && !out.some((p) => p.name === x.name)) out.push({ name: x.name.slice(0, 80), kind: 'agent', tool: typeof x.tool === 'string' ? x.tool.slice(0, 40) : '', focus: typeof x.focus === 'string' ? x.focus.slice(0, 200) : '', persona: true, of: s.name })
+      }
+    }
+    for (const h of room.hostedOnline ? room.hostedOnline() : []) if (h.name !== me && !out.some((p) => p.name === h.name)) out.push({ name: h.name, kind: h.kind, tool: 'hosted', hosted: true })
+    return out
+  }
+  // Each member's folder tells the room its git (branch, upstream, the repository's branches): one list.
+  const branchesOf = (room) => {
+    const members = []
+    for (const st of room.awareness.getStates().values()) if (st && st.name && st.git) members.push({ name: st.name, git: cleanGit(st.git) })
+    for (const p of peers(room)) if (p.persona) members.push({ name: p.name, git: null, persona: true })
+    return branchBoard(members, room.branchList ? room.branchList() : [])
+  }
+  const claimsOf = (room) => room.claimList ? room.claimList(branchOf(room)) : []
+  // Claims are per branch: who the agent is, on the branch it works on.
+  const who = (room) => ({ ...ctx.who(room), branch: branchOf(room) })
+  // The rules every agent is held to (duties.js), enforced here because hosted agents work through these tools.
+  const seen = (doc) => doc.getArray('chat').toArray().filter(visible)
+  // Messages this agent settled as needing no reply (quilt_inbox no_reply), kept with its inbox.
+  const settledSet = (room) => {
+    const box = ctx.inbox ? ctx.inbox(room) : {}
+    if (!Array.isArray(box.settled)) box.settled = []
+    return new Set(box.settled)
+  }
+  const waitRefusal = (doc, name, room) => renderUnanswered(waitingOn(seen(doc), me, { agent: true, settled: settledSet(room) }), `call ${name} again`)
+  // Everyone this agent could address: who is here and who has been in the chat.
+  const memberNames = (room, doc) => {
+    const names = new Set(peers(room).map((p) => p.name))
+    for (const p of peers(room)) if (p.persona && p.of) names.add(aiName(p.of)) // "Daniel's AI"
+    for (const m of seen(doc)) { if (m.by) names.add(m.by); if (m.to) names.add(m.to) }
+    names.delete(me)
+    return [...names].filter((n) => typeof n === 'string' && n)
+  }
+  // Chat about a file this agent was already shown, by message id: kept with its inbox, since each
+  // request to the hosted MCP gets fresh tools.
+  const toldAbout = (room) => {
+    const box = ctx.inbox ? ctx.inbox(room) : {}
+    if (!Array.isArray(box.told)) box.told = []
+    return box
+  }
+  // Claims follow this agent's writes: a file it changes that nobody holds is claimed for it, and let
+  // go when it hasn't written the file for a while (it has no end of turn Quilt can see).
+  const autoHeld = new Map() // `${roomId}\0${rel}` -> timer
+  const boxable = (room, branch) => !!(room.meta && repoRecordFor(room, branch || room.defaultKey))
+  const roomKey = (room) => `${room.id || room.name || ''}\0${branchOf(room)}` // claims held per branch
+  const autoClaim = (room, rel) => {
+    const key = `${roomKey(room)}\0${rel}`
+    const branch = branchOf(room) // released on this branch, even if the agent has moved on since
+    clearTimeout(autoHeld.get(key))
+    // A box (docs/superpowers/specs/2026-10-16-git-boxes-design.md) where a commit can open it: a branch that follows
+    // a repository. Our own claim with no box (claimed ahead, or unpacked) boxes again with the next write.
+    const box = boxable(room, branch)
+    const own = claimsOf(room).find((c) => c.pattern === rel && c.by === me)
+    if (!autoHeld.has(key) || (box && own && !own.box && !own.clash)) {
+      try { room.claimRequest({ ...who(room), talk: ctx.access(room)?.talk !== false }, { op: 'claim', pattern: rel, note: 'editing', ...(box ? { box: true } : {}) }) } catch { return false }
+      room.broadcastClaims()
+    }
+    const timer = setTimeout(() => {
+      autoHeld.delete(key)
+      // Held for a clash's merge (relay-upstream.js) is not a claim that followed a write: it stays until the merge is done.
+      // A box isn't let go of after a quiet while either: it opens when it's committed or unpacked.
+      if (!(room.claimList ? room.claimList(branch) : []).some((c) => c.pattern === rel && c.by === me && !c.clash && !c.box)) return
+      try { room.claimRequest({ ...ctx.who(room), branch }, { op: 'release', pattern: rel }); room.broadcastClaims() } catch {}
+    }, HOSTED_AUTO_CLAIM_QUIET_MS)
+    if (timer.unref) timer.unref()
+    autoHeld.set(key, timer)
+    return true
+  }
+  // One chronology writer per branch document, shared by every hosted agent's connection.
+  const historyOf = (room) => {
+    const b = branchEntry(room) || room
+    const doc = b.doc
+    if (!b.historyLog) b.historyLog = new HistoryLog(doc, doc.getArray('history'), { origin: AGENT })
+    return b.historyLog
+  }
+
+  tool('quilt_history', {
+    description: 'The chronology of the project: who changed which file, when, what changed (diff) and for which task. ' +
+      'Filter by path or glob, person, task or time. Use it to understand recent changes before building on them, or to find what broke something.',
+    inputSchema: {
+      path: z.string().max(500).optional().describe('A file, a folder ending in "/", or a glob like src/ui/**'),
+      by: z.string().max(80).optional().describe('Only changes by this person or agent'),
+      since: z.string().max(40).optional().describe('"2h", "3d", "today", "yesterday" or a date'),
+      task: z.string().max(40).optional().describe('Only changes made for this task id'),
+      with_diff: z.boolean().optional().describe('Include each change\'s diff (capped per change)'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many of the newest matching changes (default 30)')
+    }
+  }, ({ path: p, by, since, task, with_diff, limit }, { room }) => {
+    const from = parseSince(since)
+    if (from === undefined) return fail('since: use a duration like 2h or 3d, "today", "yesterday", or a date.')
+    const list = queryHistory(historyOf(room).entries(), { path: p ? cleanPath(p) : '', by, since: from ?? undefined, task, limit: limit || 30 })
+    return text(formatHistory(list, { withDiff: !!with_diff }))
+  })
+
+  tool('quilt_status', {
+    description: 'See who else is in the live session, what they and their AIs are doing, recent file changes, claimed files and recent messages. Call this before starting a task.',
+    inputSchema: {}
+  }, (_, { room, doc, chat, activity }) => {
+    const a = ctx.access(room)
+    const lines = [`You are ${me} in a live quilt session (room ${room.name}).`]
+    if (a && a.role === 'viewer') lines.push('You may only view this session: reading, chat and claims work, file changes are refused.')
+    else if (a && a.scopes && a.scopes.length) lines.push(`You may change files only in: ${a.scopes.join(', ')}.`)
+    if (a && a.scopesExcept && a.scopesExcept.length && a.role !== 'viewer') lines.push(`You may not change files in: ${a.scopesExcept.join(', ')}.`)
+    if (a && a.talk === false) lines.push("You may not post in this session: quilt_message and quilt_share are refused.")
+    lines.push('', '## People online')
+    const ps = peers(room)
+    if (!ps.length) lines.push('- Nobody else right now.')
+    for (const p of ps) {
+      const ag = p.agent || {}
+      const ai = ag.sharing === false ? 'AI sharing paused' : ag.status === 'working' ? `${ag.tool || 'AI'} working` : ag.tool ? `${ag.tool} idle` : ''
+      const editing = Object.keys(p.editing || {}).slice(0, 5)
+      lines.push(`- ${p.name} (${p.tool || 'unknown tool'}${p.persona ? `, an AI session of ${p.of}` : p.kind === 'agent' ? ', agent' : ''})${ai ? ` · ${ai}` : ''}${p.focus ? ` · focus: ${p.focus}` : ''}${editing.length ? ` · editing ${editing.join(', ')}` : ''}`)
+    }
+    const away = room.memberList ? room.memberList().filter((m) => m.away && m.name !== me && !ps.some((p) => p.name === m.name)) : []
+    if (away.length) lines.push('', '## Away (agents that work in turns, between turns: they read what you write at their next turn)', ...away.map((m) => `- ${m.name} (agent) · last here ${ago(m.lastSeen)}`))
+    const all = claimsOf(room)
+    const bxs = all.filter((c) => c.box)
+    if (bxs.length) lines.push('', '## Boxed work', ...bxs.map((c) => `- ${c.pattern}: ${c.by === me ? 'your unfinished work, in nobody else\'s folder until you commit it (quilt_git_commit) or quilt_unpack it' : `${c.by}'s unfinished work: not in anyone else's folder until they commit or unpack it`}`))
+    const cl = all.filter((c) => !c.box)
+    lines.push('', '## Claimed files', ...(cl.length ? cl.map((c) => `- ${c.pattern} by ${c.by}${c.note ? ` (${c.note})` : ''}${c.queue.length ? ` · waiting: ${c.queue.map((r) => `${r.by} ("${r.title}")`).join(', ')}` : ''}`) : ['- None.']))
+    const acts = activity.toArray().filter(Boolean).slice(-12).reverse()
+    lines.push('', '## Recent file changes', ...(acts.length ? acts.map((x) => x.kind === 'pulled' ? `- ${x.by} pulled ${x.detail || 'commits'} (${ago(x.ts)})` : x.kind === 'brought' ? `- ${x.by} brought in ${x.detail || 'commits'}${x.branch ? ` on ${x.branch}` : ''} (${ago(x.ts)})` : x.kind === 'switched' ? `- ${x.by} switched to ${x.branch} (${ago(x.ts)})` : `- ${x.by} ${x.kind} ${x.path} (${ago(x.ts)})`) : ['- None yet.']))
+    const msgs = chat.toArray().filter(visible).slice(-8)
+    lines.push('', '## Recent messages', ...(msgs.length ? msgs.map(fmtMsg) : ['- None.']))
+    const asked = [...doc.getMap('commitRequests').values()].filter((r) => r && r.id && r.state === 'open').sort((x, y) => x.ts - y.ts)
+    if (asked.length) lines.push('', '## Commit requests', ...asked.map((r) => `- [${r.id}] ${r.by === me ? 'you' : r.by} (${ago(r.ts)}): ${r.message}${Array.isArray(r.files) ? ` (${r.files.length} files)` : ''}${r.error ? `. Last try: ${r.error}` : ''}`))
+    lines.push('', '## Tasks', taskMarkdown(readTasks(doc.getMap('tasks')), me, { tool: ctx.tool(), asAi: false, mentionYours: true }))
+    const br = branchesOf(room)
+    if (br.length) {
+      lines.push('', '## Branches', branchesMarkdown(br, { limit: 6, mine: branchOf(room) }))
+      if (ctx.branch) lines.push('Work on another branch with quilt_git_branch.')
+      // Hosted agents learn when the relay last looked for new commits on their branch (relay-upstream.js).
+      const said = relayStatus(room, branchOf(room))
+      if (said) lines.push(said)
+    }
+    if (ctx.webhook) { const w = ctx.webhook.get(); lines.push('', w ? `Webhook: Quilt POSTs to ${w.url} on ${w.events.join(', ')}.` : 'No webhook: subscribe with quilt_webhook_subscribe to be told of mentions, direct messages and tasks as they happen.') }
+    return text(lines.join('\n') + ctx.warn(room))
+  })
+
+  tool('quilt_sync_status', {
+    description: SYNC_STATUS_DESCRIPTION,
+    inputSchema: {}
+  }, (_, { room, branch }) => text(syncStatusText(room.branchList ? room.branchList() : [], { mine: branch ? branch.key : '' })))
+
+  tool('quilt_branches', {
+    description: 'The session\'s git branches: which branch each member\'s folder is on, which AI sessions and worktrees work on which branch, how each stands against its upstream (behind, ahead, diverged), and who committed last.',
+    inputSchema: {}
+  }, (_, { room }) => {
+    const br = branchesOf(room)
+    return text(`${branchesMarkdown(br, { limit: 40 })}\n\n${BRING_IN_NOTE}`)
+  })
+
+  const taskMap = (doc) => doc.getMap('tasks')
+
+  const reader = () => ({ name: me, tool: ctx.tool(), asAi: false, agent: true })
+  const taskFields = ({ assignee, to_ai, files }, room) => {
+    const spec = { me, peers: peers(room) }
+    if (assignee != null) spec.assignee = assignee
+    else if (to_ai) spec.assignee = 'me'
+    if (to_ai) spec.to_ai = true
+    if (files !== undefined) spec.files = files
+    const name = spec.assignee === 'me' ? me : spec.assignee
+    if (to_ai && (name == null || name === me)) spec.tool = ctx.tool()
+    return assignmentFields(spec)
+  }
+  const assignedLine = (task) => {
+    const label = assigneeLabel(task, me)
+    const files = task.files?.length ? `\nFiles: ${task.files.join(', ')}` : ''
+    return `${label ? `Assigned to ${label}.` : 'Unassigned.'}${files}`
+  }
+
+  tool('quilt_tasks', {
+    description: 'List the shared task board (To do, In progress, QA, Done), with an id on each task. Open tasks assigned to you are listed first.',
+    inputSchema: {
+      archived: z.boolean().optional().describe('True: list the archived tasks (off the board) instead.')
+    }
+  }, ({ archived } = {}, { doc }) => text(formatTasks(readTasks(taskMap(doc)), reader(), { archived: !!archived })))
+
+  tool('quilt_add_task', {
+    description: 'Add a task to the shared board, in To do. One short line. Optionally assign it to a person or their AI, and name the files it is about. It is added as you.',
+    inputSchema: {
+      title: z.string().describe('What needs doing, in a few words'),
+      assignee: z.string().optional().describe('Who should do it: a person\'s name, or "me". Omit to leave it unassigned.'),
+      to_ai: z.boolean().optional().describe('Assign it to that person\'s AI instead of the person. You are an agent in this session: leave to_ai unset to assign a task to yourself.'),
+      files: z.array(z.string()).max(20).optional().describe('Project files this task is about, relative paths such as src/app.js')
+    }
+  }, ({ title, assignee, to_ai, files }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_add_task', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const task = addTask(doc, taskMap(doc), { title, by: me, ...taskFields({ assignee, to_ai, files }, room) }, AGENT)
+      return text(`Added to To do: ${task.title}\n${task.id}\n${assignedLine(task)}`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  const checklistOf = (files) => pickChecklist(files.get('AGENTS.md')?.toString(), files.get('CLAUDE.md')?.toString())
+  tool('quilt_move_task', {
+    description: 'Move a task on the shared board. "doing" when you start it: you get a briefing (its files, recent changes to them, claims, the project\'s checks). ' +
+      '"qa" when you finish implementing and testing: requires `qaNotes` (what changed and how you self-validated); without it the move is refused. ' +
+      '"done" after QA: requires `verified`, what you ran and what you saw; without it the move is refused.',
+    inputSchema: {
+      id: z.string().describe('Task id from quilt_tasks'),
+      column: z.enum(COLUMN_IDS_LIST).describe(COLUMN_IDS_LIST.join(', ')),
+      qaNotes: z.string().max(MAX_VERIFIED).optional().describe('For "qa": describe the changes you made and how you self-validated them, briefly (a few short sentences, no logs).'),
+      verified: z.string().max(MAX_VERIFIED).optional().describe('For "done": what you ran and what you saw, concretely and briefly (commands, results, what you exercised in the app; no full logs).')
+    }
+  }, async ({ id, column, qaNotes, verified }, { room, doc, files, branch }) => {
+    { const w = waitRefusal(doc, 'quilt_move_task', room); if (w) return fail(w) }
+    // An agent's finished work goes to git before QA, when it can commit itself (relay-commit.js); Done merges the task's pull request.
+    if (column === 'qa' && ctx.kind === 'agent' && !Object.values(room.meta && room.meta.upstreams || {}).some((rec) => rec && rec.clash && rec.clash.task === id)) {
+      const u = await unpublishedFor(room, { key: branch ? branch.key : DEFAULT_KEY, who: me, task: id, column }, { fetch: room.githubFetch })
+      if (u.unpublished.length) return fail(unpublishedRefusal(readTasks(taskMap(doc)).find((t) => t.id === id), u.unpublished, column, []))
+    }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const cur = readTasks(taskMap(doc)).find((t) => t.id === id)
+      if (!cur) return fail('no such task')
+      if (column === 'qa' && !qaNotesEnough(qaNotes)) return fail(qaRefusal({ task: cur, checklist: checklistOf(files) }))
+      if (column === 'done' && !verifiedEnough(verified)) return fail(doneRefusal({ task: cur, checklist: checklistOf(files) }))
+      { const q = (column === 'done' || column === 'qa') && renderQueued(queuedFor(claimsOf(room), me), 'move the task again'); if (q) return fail(q) }
+      let merged = null
+      if (column === 'done' && cur.column !== 'done') {
+        const f = await finishTaskFor(room, { who: { name: me, kind: ctx.kind || 'human', access: ctx.access(room) }, key: branch ? branch.key : DEFAULT_KEY, task: id }, { fetch: room.githubFetch })
+        merged = f.merged
+      }
+      const patch = { id, column }
+      if (column === 'qa') patch.qaNotes = qaNotes
+      if (column === 'done') patch.verified = verified
+      const task = updateTask(doc, taskMap(doc), patch, AGENT)
+      if (column === 'doing') {
+        const tf = task.files || []
+        const all = historyOf(room).entries()
+        const history = (tf.length ? all.filter((e) => tf.includes(e.path)) : all).slice(-8)
+        const claims = claimsOf(room).filter((c) => !tf.length || tf.some((f) => globMatcher(c.pattern)(f)))
+        const onto = branchForHostedTask(room, task)
+        return text(pickupBrief({ task: { ...task, comments: readComments(doc.getMap('taskComments'), task.id) }, history, claims, checklist: checklistOf(files), me }) + (onto ? `\nYou are on ${onto} now (Quilt made it for this task, a copy of ${room.defaultKey}'s files): write your files here and quilt_git_commit them; the pull request opens by itself. Move the task to QA when it is done and tested.` : ''))
+      }
+      if (column === 'qa') return text(`Moved "${task.title}" to QA. Notes: ${qaNotesLine(task)}`)
+      if (column === 'done') return text(`Moved "${task.title}" to Done.${merged ? ` Merged pull request #${merged.number} (${merged.head} → ${merged.base}) as ${String(merged.sha).slice(0, 7)}.` : ''} Verified: ${verifiedLine(task)}`)
+      return text(`Moved "${task.title}" to ${columnName(task.column)}.`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_assign_task', {
+    description: 'Assign a shared task to a person or to their AI, and optionally set the files it is about. assignee "" clears it. You are an agent here: assignee "me" without to_ai assigns it to you.',
+    inputSchema: {
+      id: z.string().describe('Task id from quilt_tasks'),
+      assignee: z.string().describe('A person\'s name, "me", or "" to unassign'),
+      to_ai: z.boolean().optional().describe('True: that person\'s AI. Omit or false: the person.'),
+      files: z.array(z.string()).max(20).optional().describe('Replace the file list. Omit to leave the files unchanged.')
+    }
+  }, ({ id, assignee, to_ai, files }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_assign_task', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const task = updateTask(doc, taskMap(doc), { id, ...taskFields({ assignee, to_ai, files }, room) }, AGENT)
+      return text(assignedLine(task))
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_task', {
+    description: 'One task in full: its column, assignee, files, QA and Done notes, and its comments (work notes and handoffs people left on it).',
+    inputSchema: { id: z.string().describe('Task id from quilt_tasks') }
+  }, ({ id }, { doc }) => {
+    const task = withComments(readTasks(taskMap(doc)), doc.getMap('taskComments')).find((t) => t.id === id)
+    return task ? text(formatTaskDetails(task)) : fail('No such task: read the board with quilt_tasks.')
+  })
+
+  tool('quilt_comment_task', {
+    description: 'Add a comment to a task: a work note, a handoff, or why it went to whom. Put reasoning about a task here instead of in the chat. Keep it brief: a few short sentences, no logs, diffs or play-by-play.',
+    inputSchema: {
+      id: z.string().describe('Task id from quilt_tasks'),
+      text: z.string().max(MAX_COMMENT).describe('The comment')
+    }
+  }, ({ id, text: words }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_comment_task', room); if (w) return fail(w) }
+    if (ctx.access(room)?.talk === false) return fail(TALK_REFUSED)
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const tasks = readTasks(taskMap(doc))
+      addComment(doc, doc.getMap('taskComments'), tasks, { taskId: id, by: me, text: words }, AGENT)
+      const task = tasks.find((t) => t.id === id)
+      return text(`Comment added to "${task.title}" (${readComments(doc.getMap('taskComments'), id).length} on it now).`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_delete_task', {
+    description: 'Remove a task from the shared board.',
+    inputSchema: { id: z.string().describe('Task id from quilt_tasks') }
+  }, ({ id }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_delete_task', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      deleteTask(doc, taskMap(doc), id, AGENT)
+      return text('Removed.')
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_archive_task', {
+    description: 'Archive a task: it leaves the board and every task list, but is kept, and can be brought back. archived false brings it back to the column it was in.',
+    inputSchema: {
+      id: z.string().describe('Task id from quilt_tasks'),
+      archived: z.boolean().optional().describe('Omit or true: archive it. False: bring it back.')
+    }
+  }, ({ id, archived }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_archive_task', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const task = updateTask(doc, taskMap(doc), { id, archived: archived !== false }, AGENT)
+      return text(task.archived ? `Archived "${task.title}".` : `Brought "${task.title}" back to ${columnName(task.column)}.`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_share', {
+    description: 'Share what you are doing with your collaborators; it appears live in their quilt feed. Call it when you start on a request ' +
+      '(`request`: what your user asked, in a sentence; `summary`: your plan) and again when you finish (`summary`: what you did; ' +
+      '`files`: files you changed). Keep it short and never include secrets, keys or file contents.',
+    inputSchema: {
+      request: z.string().max(2000).optional().describe('What your user asked for, in a sentence (only when starting a new request)'),
+      summary: z.string().max(4000).describe('Your plan, progress or result, in one to three sentences'),
+      files: z.array(z.string().max(300)).max(30).optional().describe('Project files you changed, relative paths')
+    }
+  }, ({ request, summary, files: changed }, { room, doc, feed }) => {
+    const err = writable(room)
+    if (err) return fail(err)
+    if (ctx.access(room)?.talk === false) return fail(TALK_REFUSED)
+    const t = ctx.tool()
+    const now = Date.now()
+    const entries = []
+    const base = { by: me, tool: t, conv: `mcp-${t}` }
+    if (request && request.trim()) entries.push({ ...base, id: id(), kind: 'prompt', text: capText(request.trim()), ts: now })
+    if (summary && summary.trim()) entries.push({ ...base, id: id(), kind: 'reply', text: capText(summary.trim()), ts: now })
+    for (const f of changed || []) {
+      const p = cleanPath(f)
+      if (isSafeRelPath(p)) entries.push({ ...base, id: id(), kind: 'action', text: `Edited ${p}`, ts: now })
+    }
+    if (!entries.length) return fail('Nothing to share: give a summary.')
+    doc.transact(() => {
+      feed.push(entries)
+      // Keep the newest FEED_CAP entries per person, like the CLI does.
+      const mine = []
+      feed.forEach((e, i) => { if (e && e.by === me) mine.push(i) })
+      for (let k = mine.length - FEED_CAP - 1; k >= 0; k--) feed.delete(mine[k], 1)
+    }, AGENT)
+    return text(`Shared with the session.${ctx.warn(room)}`)
+  })
+
+  tool('quilt_partner_feed', {
+    description: 'Read what a collaborator\'s AI has been doing: their prompts, the AI\'s replies and actions. Without `who`, lists whose feeds exist.',
+    inputSchema: {
+      who: z.string().optional().describe('Collaborator name'),
+      limit: z.number().int().min(1).max(200).optional()
+    }
+  }, ({ who, limit }, { feed }) => {
+    const all = feed.toArray().filter((e) => e && e.by !== me)
+    if (!who) {
+      const names = [...new Set(all.map((e) => e.by))]
+      return text(names.length ? `Feeds: ${names.join(', ')}. Call again with "who".` : 'No one has shared AI activity yet.')
+    }
+    const theirs = all.filter((e) => e.by === who).slice(-(limit || 40))
+    if (!theirs.length) return text(`No AI activity from ${who} yet.`)
+    return text(theirs.map((e) => {
+      if (e.kind === 'prompt') return `[${ago(e.ts)}] ${who} asked: ${e.text}`
+      if (e.kind === 'reply') return `[${ago(e.ts)}] ${e.tool || 'AI'}: ${e.text}`
+      if (e.kind === 'action') return `[${ago(e.ts)}] · ${e.text}`
+      return `[${ago(e.ts)}] (${e.kind})`
+    }).join('\n'))
+  })
+
+  tool('quilt_inbox', {
+    description: 'What is waiting for you: mentions of you in chat (@yourname), direct messages to you, and tasks handed to you since you last looked. Act on each one: answer with quilt_message, take a task with quilt_move_task.',
+    inputSchema: {
+      no_reply: z.array(z.string().max(40)).max(50).optional().describe('Ids of messages that need nothing back from you (thanks, a greeting, an FYI, a status report): settled without a reply')
+    }
+  }, ({ no_reply }, { room, doc, chat }) => {
+    const box = ctx.inbox ? ctx.inbox(room) : { state: null }
+    const msgs = chat.toArray().filter(visible)
+    let note = ''
+    if (no_reply && no_reply.length) {
+      const known = new Set(msgs.map((m) => m.id))
+      const ok = no_reply.map(String).filter((x) => known.has(x))
+      box.settled = [...new Set([...(Array.isArray(box.settled) ? box.settled : []), ...ok])].slice(-500)
+      note = `Settled as needing no reply: ${ok.length ? ok.join(', ') : 'none (unknown ids)'}.`
+    }
+    const r = scanInbox({ messages: msgs, tasks: readTasks(taskMap(doc)), reader: reader() }, box.state)
+    box.state = r.state
+    if (ctx.saveInbox) ctx.saveInbox()
+    const settled = new Set(box.settled || [])
+    const open = r.events.filter((e) => (e.kind !== 'dm' && e.kind !== 'mention') || e.queue || e.commit || e.nudge || (!settled.has(e.id) && !needsNoReply(e.text) && !answered(msgs, me, e.by, e.ts)))
+    const seen = keptChat(room, chat)
+    return text([note, renderInbox(withContext(open, seen, { names: [me], agent: true }), { me: [me] })].filter(Boolean).join('\n\n') || 'Nothing new for you.')
+  })
+
+  tool('quilt_conversation', {
+    description: CONVERSATION_DESCRIPTION,
+    inputSchema: {
+      with: z.string().max(200).optional().describe('Only the conversation with this person or agent: direct messages either way, and messages that @mention one of you'),
+      q: z.string().max(200).optional().describe('Only messages containing this text (any case)'),
+      before: z.string().max(40).optional().describe('Only messages before this message id (to read further back)'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many of the newest matching messages (default 30)')
+    }
+  }, (args, { room, chat }) => {
+    const r = queryConversation(keptChat(room, chat), { me: [me], with: args.with || null, q: args.q || '', before: args.before || null, limit: args.limit, agent: true })
+    return text(renderConversation(r, { me: [me], with: args.with, q: args.q }))
+  })
+
+  if (ctx.webhook) {
+    // The agent's one webhook, for every session it is in (and its workspaces): no session needed to set it.
+    server.registerTool('quilt_webhook_subscribe', {
+      description: 'Be told as it happens, by an HTTP POST to a URL of yours, when you are mentioned in chat (@yourname), sent a direct message or handed a task, in any session you are in: ' +
+        'no need to poll quilt_inbox. One webhook per agent, for every session (calling again replaces it); for a workspace agent it also gets session.started from its workspaces. Each POST is JSON that names its session and workspace (answer with that session in `session`), signed with the secret ' +
+        '(x-quilt-signature: sha256=HMAC-SHA256(secret, "<x-quilt-timestamp>.<body>")); answer 2xx. Give a secret of your own or get one back (shown once).',
+      inputSchema: {
+        url: z.string().min(1).max(2000).describe('The https URL to POST to (a webhook trigger of your routine, for example)'),
+        secret: z.string().max(200).optional().describe('16 to 200 characters for signing; omit to have Quilt make one'),
+        events: z.array(z.enum(WEBHOOK_EVENTS)).max(WEBHOOK_EVENTS.length).optional().describe(`Which events to send (default: all): ${WEBHOOK_EVENTS.join(', ')}`),
+        bearer: z.string().max(500).optional().describe('A key your receiver wants on every POST, sent as "Authorization: Bearer <key>" (a Grok Bot routine\'s sender key, for example)')
+      }
+    }, async ({ url, secret, events, bearer }) => {
+      try {
+        const sub = ctx.webhook.subscribe({ url, secret, events, bearer })
+        const api = await ctx.webhook.tellApi(sub)
+        return text(describeSubscription(sub, { showSecret: sub.made }) + (api ? `\n${api}` : ''))
+      } catch (e) { return fail(e.message) }
+    })
+
+    server.registerTool('quilt_webhook_unsubscribe', {
+      description: 'Stop the webhook: Quilt no longer POSTs mentions, direct messages, tasks or session.started to you. quilt_inbox still has them.',
+      inputSchema: {}
+    }, async () => text(await ctx.webhook.unsubscribe() ? 'Webhook removed. Mentions, direct messages and tasks still wait in quilt_inbox.' : 'You had no webhook.'))
+  }
+
+  tool('quilt_message', {
+    description: CHAT_RULES + ' Set `to` to message one person directly.',
+    inputSchema: {
+      text: z.string().min(1).max(4000),
+      to: z.string().optional().describe('Name of one person, for a direct message'),
+      everyone: z.boolean().optional().describe('Only for a real announcement to the whole session: lets a message that @mentions nobody go out'),
+      re: z.string().max(40).optional().describe(RE_HELP),
+      also: z.boolean().optional().describe('Only when their message was already answered and yours is about something different they need')
+    }
+  }, ({ text: t, to, everyone, re, also }, { room, doc, chat }) => {
+    const err = writable(room)
+    if (err) return fail(err)
+    if (ctx.access(room)?.talk === false) return fail(TALK_REFUSED)
+    const reply = replyFor(chat.toArray().filter(visible), { names: [me], to: to || null, re: re || '' })
+    if (reply.error) return fail(reply.error)
+    to = reply.to
+    const why = unaddressed(t, { to, everyone: !!everyone, names: memberNames(room, doc) })
+    if (why) return fail(why)
+    if (reply.repeat && !also) return fail(renderReplied(reply.repeat))
+    const msg = { id: id(), by: me, to: to || null, text: t, ts: Date.now() }
+    if (to && reply.re) msg.re = reply.re
+    doc.transact(() => {
+      chat.push([msg])
+      if (chat.length > 500) chat.delete(0, chat.length - 500)
+    }, AGENT)
+    return text(to ? `Sent to ${to}.` : 'Sent to everyone.')
+  })
+
+  tool('quilt_read_messages', {
+    description: 'Read recent chat messages in the session (including direct messages to you).',
+    inputSchema: { limit: z.number().int().min(1).max(100).optional() }
+  }, ({ limit }, { chat }) => {
+    const msgs = chat.toArray().filter(visible).slice(-(limit || 20))
+    return text(msgs.length ? msgs.map(fmtMsg).join('\n') : 'No messages yet.')
+  })
+
+  // ------------------------------------------------------ commit timing --
+  // The same requests as a folder's quilt_request_commit (Session.requestCommit): a message to
+  // whoever commits, so viewers and members who may not post are refused.
+  const commitMap = (doc) => doc.getMap('commitRequests')
+  const commitState = (room, doc) => {
+    const busy = []
+    for (const st of room.awareness.getStates().values()) {
+      if (!st || !st.name || st.name === me) continue
+      const a = st.agent
+      if (a && a.sharing !== false && a.status === 'working') busy.push(`${st.name}'s ${a.tool || 'AI'} is working`)
+      else if (st.work && st.work.state === 'working') busy.push(`${st.name} is working${st.work.note ? `: ${String(st.work.note).slice(0, 200)}` : ''}`)
+    }
+    const requests = [...commitMap(doc).values()].filter((r) => r && r.id).sort((a, b) => a.ts - b.ts)
+    return { busy, open: requests.filter((r) => r.state === 'open'), recent: requests.filter((r) => r.state === 'done').slice(-5) }
+  }
+  const describeCommits = (c) => [
+    c.busy.length ? `⏳ Still working: ${c.busy.join('; ')}` : '✅ Everyone else\'s AI is idle: a good moment to commit.',
+    describeCommitRequests(c)
+  ].join('\n')
+
+  tool('quilt_request_commit', {
+    description: REQUEST_COMMIT_DESCRIPTION,
+    inputSchema: {
+      message: z.string().max(500).optional().describe('The commit message: what the change does (a task\'s title by default)'),
+      files: z.array(z.string().max(1024)).max(500).optional().describe('The files you changed, relative to the project\'s top folder (deleted ones too)'),
+      task: z.string().max(40).optional().describe('The task this work was for: its title is the message and its changes the files, unless you give them')
+    }
+  }, ({ message, files, task }, { room, doc, fdoc }) => {
+    { const w = waitRefusal(doc, 'quilt_request_commit', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    const a = ctx.access(room)
+    if (a && a.role === 'viewer') return fail('Viewers can\'t ask for commits.')
+    if (ctx.kind === 'agent' && agentsCanCommit(room, branchOf(room) || DEFAULT_KEY)) return fail('Commit it yourself: quilt_git_commit (the files you changed and a message) commits them to the branch you are on, with nobody else needed; on a branch of your own the pull request opens by itself. Asking a person is for when agents may not commit here.')
+    if (a && a.talk === false) return fail(TALK_REFUSED)
+    const t = task ? readTasks(taskMap(doc)).find((x) => x.id === String(task)) : null
+    if (task && !t) return fail(`No task ${task} on the board.`)
+    const msg = String(message || (t ? t.title : '')).trim().slice(0, 500)
+    if (!msg) return fail('Say what the commit is for.')
+    let list = cleanFiles(files || [])
+    if (files && files.length && !list.length) return fail('None of those are files in the project (give paths relative to its top folder).')
+    if (!list.length) {
+      // What was changed for the task, or by this agent, on record in the branch's history.
+      for (const e of fdoc.getArray('history').toArray()) {
+        if (!e || e.pulled || typeof e.path !== 'string') continue
+        if (t ? e.task && e.task.id === t.id : e.by === me) { if (!list.includes(e.path)) list.push(e.path) }
+      }
+      if (t) for (const f of t.files || []) if (!list.includes(f)) list.push(f)
+      list = cleanFiles(list.slice(-MAX_REQUEST_FILES))
+    }
+    if (!list.length) return fail(t ? `Task ${t.id} has no changed files on record: give them in files.` : 'Quilt has no changes of yours on record: give the files in files.')
+    const key = branchOf(room)
+    const r = { id: crypto.randomBytes(6).toString('hex'), by: me, message: msg, ...(key ? { branch: key } : {}), ts: Date.now(), state: 'open', files: list, ...(t ? { task: { id: t.id, title: t.title } } : {}) }
+    // The session owner is told with a direct message, as from a folder (commit-request.js).
+    const note = commitRequestMessage(r, { owner: room.meta && room.meta.ownerName, id: id(), defaultBranch: DEFAULT_KEY })
+    doc.transact(() => {
+      const map = commitMap(doc)
+      map.set(r.id, r)
+      if (note) {
+        const chat = doc.getArray('chat')
+        chat.push([note])
+        if (chat.length > 500) chat.delete(0, chat.length - 500)
+      }
+      const done = [...map.values()].filter((x) => x && x.state === 'done').sort((x, y) => x.ts - y.ts)
+      for (const x of done.slice(0, Math.max(0, done.length - 100))) map.delete(x.id)
+    }, AGENT)
+    return text(`Asked for a commit [${r.id}] of ${list.length} file${list.length === 1 ? '' : 's'}: ${list.slice(0, 12).join(', ')}${list.length > 12 ? ', …' : ''}. ` +
+      'A person with git on this branch commits it from their Quilt; you are told the commit when it is made.')
+  })
+
+  if (ctx.kind) {
+    // Git, for an agent with no folder: the quilt_git_* tools work on the branch the agent is on (its branch document).
+    const whoAmI = (room) => ({ name: me, kind: ctx.kind, access: ctx.access(room) })
+    const keyOf = (branch) => branch ? branch.key : DEFAULT_KEY
+
+    tool('quilt_git_commit', {
+      description: GIT_COMMIT_DESCRIPTION,
+      inputSchema: gitCommitSchema(z)
+    }, async (args, { room, doc, branch }) => {
+      { const w = waitRefusal(doc, 'quilt_git_commit', room); if (w) return fail(w) }
+      // A branch that syncs with GitHub through the relay's mirror: your own changes (or the files named, or the task's)
+      // become one commit now, pushed forward only. Others' changes in those files go in only with with_others.
+      // An agent the owner's policy keeps off this branch commits to a branch of its own instead (below, with its pull request).
+      if (room.outbound && liveSyncOn(room, keyOf(branch)) && !(ctx.kind === 'agent' && agentCommitRefusal(room, keyOf(branch), me))) {
+        const key = keyOf(branch)
+        const own = ownFiles(room, key, { who: me, files: args.files, task: args.task })
+        if (own.refused) return fail(own.refused)
+        const t = args.task ? room.doc.getMap('tasks').get(String(args.task)) : null
+        const message = String(args.message || (t && t.title) || '').trim().slice(0, 2000)
+        if (!message) return fail('Say what the commit does (message).')
+        const r = await room.outbound.flush(key, { message, by: me, only: own.list, own: { who: me, withOthers: args.with_others === true } })
+        if (r.state === 'others') return fail(`These files also hold changes by others that are not in git yet: ${[...r.others].map(([rel, names]) => `${rel} (${names.join(', ')})`).join('; ')}. Leave them out (files), ask those people to commit first, or commit them together with with_others: true (they are named as co-authors).`)
+        const rec = (room.meta.upstreams || {})[key] || {}
+        if (r.state === 'pushed') return text(`Pushed ${r.sha.slice(0, 7)} to ${rec.repo || 'GitHub'} ${rec.ref || key}: "${r.subject}" (${r.changed.length} file${r.changed.length === 1 ? '' : 's'}: ${r.changed.slice(0, 10).join(', ')}${r.changed.length > 10 ? ', …' : ''})${r.live ? `, through pull request work on ${r.live}` : ''}.`)
+        if (r.state === 'nothing') return text(`Nothing to commit: ${own.list.length === 1 ? own.list[0] : 'those files'} on ${key} ${own.list.length === 1 ? 'is' : 'are'} already on GitHub as the session has ${own.list.length === 1 ? 'it' : 'them'}${r.skipped && r.skipped.claimed.length ? ` (held by someone: ${r.skipped.claimed.join(', ')})` : ''}.`)
+        if (r.state === 'paused') return fail(`GitHub can't take the commit right now (${rec.problem || r.why}): Quilt keeps it and makes it when GitHub answers.`)
+        if (r.state === 'protected') return fail(`${rec.ref || key} is protected on GitHub: ${r.why}`)
+        if (r.state === 'refused') return fail(`Not committed: ${r.why}.`)
+        return fail(`Could not push ${key} right now (${r.state}${r.why ? `: ${r.why}` : ''}): try quilt_git_commit again in a moment.`)
+      }
+      if (!room.commitFor) return fail('This relay can\'t commit yet.')
+      try {
+        const r = await gitCommitFor(room, { who: whoAmI(room), key: keyOf(branch), message: args.message, files: args.files, task: args.task, withOthers: args.with_others === true }, { fetch: room.githubFetch, log: room.log || (() => {}) })
+        return text(describeGitCommit(r, { policy: agentCommitsOf(room) }))
+      } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_clash', {
+      description: CLASH_DESCRIPTION,
+      inputSchema: clashSchema(z)
+    }, async (args, { room, branch }) => {
+      if (!room.mirrors || !room.cfg || !room.cfg.gitSync) return fail('This session doesn\'t sync live with GitHub, so there are no held clashes here.')
+      try {
+        const r = await clashAction(room, { who: { name: me, kind: ctx.kind === 'agent' ? 'agent' : 'human', access: ctx.access(room) }, key: keyOf(branch), action: args.action, path: args.path || '', content: args.content ?? null, checks: args.checks || null, force: args.force === true })
+        return r.ok ? text(r.text) : fail(r.text)
+      } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_status', {
+      description: GIT_STATUS_DESCRIPTION,
+      inputSchema: {}
+    }, async (_, { room, branch }) => {
+      try { return text(describeGitStatus(await gitStatusFor(room, { who: whoAmI(room), key: keyOf(branch) }, { fetch: room.githubFetch }))) } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_log', {
+      description: GIT_LOG_DESCRIPTION,
+      inputSchema: { n: z.number().int().min(1).max(50).optional().describe('How many commits (default 10)') }
+    }, async ({ n }, { room, branch }) => {
+      try { return text(describeGitLog(await gitLogFor(room, { key: keyOf(branch), n: n || 10 }, { fetch: room.githubFetch }))) } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_diff', {
+      description: GIT_DIFF_DESCRIPTION,
+      inputSchema: { files: z.array(z.string().min(1).max(500)).max(20).optional().describe('The files to compare; default: your uncommitted changes') }
+    }, async ({ files: list }, { room, branch }) => {
+      try { return text(describeGitDiff(await gitDiffFor(room, { who: whoAmI(room), key: keyOf(branch), files: list }, { fetch: room.githubFetch, lineDiff }))) } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_revert', {
+      description: GIT_REVERT_DESCRIPTION,
+      inputSchema: { files: z.array(z.string().min(1).max(500)).min(1).max(20).describe('The files to put back as GitHub has them') }
+    }, async ({ files: list }, { room, doc, fdoc, branch, files, blobs, activity }) => {
+      { const w = waitRefusal(doc, 'quilt_git_revert', room); if (w) return fail(w) }
+      const err = writable(room) || branchWritable(room, branch)
+      if (err) return fail(err)
+      const a = ctx.access(room)
+      if (a && a.role === 'viewer') return fail('You can only view this session; file changes are refused.')
+      try {
+        const d = await gitDiffFor(room, { who: whoAmI(room), key: keyOf(branch), files: list }, { fetch: room.githubFetch, lineDiff })
+        const { githubRepoOf, credentialsFor } = await import('./relay-commit.js')
+        const { githubWriter } = await import('./github-commit.js')
+        const { repo } = githubRepoOf(room, keyOf(branch))
+        const gh = githubWriter({ fetch: room.githubFetch, token: await credentialsFor(room, repo), owner: repo.owner, name: repo.name })
+        const done = []; const skipped = []
+        for (const f of d.files) {
+          const rel = cleanPath(f.path)
+          if (f.note === 'same') { skipped.push(`${rel} (already as on GitHub)`); continue }
+          if (f.note) { skipped.push(`${rel} (${f.note})`); continue }
+          const refusal = a && changeRefusal(a, rel)
+          if (refusal) { skipped.push(`${rel} (${refusal})`); continue }
+          const claim = claimsOf(room).find((c) => c.by !== me && globMatcher(c.pattern)(rel))
+          if (claim) { skipped.push(`${rel} (held by ${claim.by})`); continue }
+          const was = d.head ? await gh.content(d.head, rel) : null
+          fdoc.transact(() => doc.transact(() => {
+            const existed = files.has(rel) || blobs.has(rel)
+            let before = ''
+            if (was === null || was === undefined) {
+              const y = files.get(rel); before = y ? y.toString() : ''
+              files.delete(rel); blobs.delete(rel)
+            } else {
+              blobs.delete(rel)
+              let ytext = files.get(rel)
+              if (!ytext) { ytext = new Y.Text(); files.set(rel, ytext) }
+              before = ytext.toString()
+              applyTextDiff(ytext, was.toString('utf8'))
+            }
+            const kind = was == null ? 'deleted' : existed ? 'edited' : 'created'
+            activity.push([{ by: me, path: rel, kind, detail: `reverted to GitHub (${d.against})`, ...(branch ? { branch: branch.key } : {}), ts: Date.now() }])
+            if (activity.length > ACTIVITY_CAP) activity.delete(0, activity.length - ACTIVITY_CAP)
+            historyOf(room).record({ by: me, path: rel, kind, before, after: was == null ? '' : was.toString('utf8'), task: currentTask(readTasks(taskMap(doc)), me) })
+          }, AGENT), AGENT)
+          done.push(rel)
+        }
+        return text(`${done.length ? `Put back as GitHub's ${d.against} has ${done.length === 1 ? 'it' : 'them'}: ${done.join(', ')}.` : 'Nothing reverted.'}${skipped.length ? ` Left alone: ${skipped.join('; ')}.` : ''}`)
+      } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_pull_requests', {
+      description: PULLS_DESCRIPTION,
+      inputSchema: {}
+    }, async (_, { room, branch }) => {
+      try { return text(describePulls(await pullRequestsFor(room, { key: keyOf(branch) }, { fetch: room.githubFetch }))) } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_git_merge', {
+      description: MERGE_DESCRIPTION,
+      inputSchema: mergeSchema(z)
+    }, async (args, { room, doc, branch }) => {
+      { const w = waitRefusal(doc, 'quilt_git_merge', room); if (w) return fail(w) }
+      try {
+        const r = await mergeForMember(room, { who: whoAmI(room), key: keyOf(branch), number: args.number, branch: args.branch, method: args.method, deleteBranch: args.delete_branch, force: args.force === true }, { fetch: room.githubFetch, log: () => {} })
+        return text(describeMerge(r))
+      } catch (err) { return fail(err.message) }
+    })
+
+    tool('quilt_agent_commits', {
+      description: 'Session owner only: git for this session, for everyone in it (people and agents push with git through one GitHub connection, nothing for them to set up). "off": off for everyone (nobody pushes through Quilt; agents ask a person with quilt_request_commit, who commits from the app); "branches" (the default): on, agents push to branches of their own, quilt/<agent>/…, with pull requests for people to merge; "any": on, agents push to any branch, the session\'s own included. People push any branch while it is on. A rule its org, team or workspace sets is a ceiling: you may be stricter, never looser. For a hard limit on main, protect the branch on GitHub.',
+      inputSchema: { mode: z.enum(['off', 'branches', 'any']) }
+    }, ({ mode }, { room }) => {
+      if (!ctx.access(room)?.owner) return fail('Only the session owner decides whether git is on here.')
+      try { return text(`Now ${POLICY_WORDS[room.setAgentCommits ? room.setAgentCommits(mode) : mode]}.`) } catch (err) { return fail(err.message) }
+    })
+  }
+
+  tool('quilt_commit_status', {
+    description: 'Is it a good moment to commit? Lists open commit requests and whose AI is still working (not counting yours).',
+    inputSchema: {}
+  }, (_, { room, doc }) => text(describeCommits(commitState(room, doc))))
+
+  tool('quilt_commit_request_done', {
+    description: 'Close commit requests whose work was committed with git by hand (or isn\'t needed any more). Without an id, every open request is closed.',
+    inputSchema: {
+      id: z.string().max(40).optional().describe('One request id; omit for all open ones'),
+      hash: z.string().max(64).optional().describe('The commit that did it, if you know it')
+    }
+  }, ({ id: one, hash }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_commit_request_done', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    const open = [...commitMap(doc).values()].filter((r) => r && r.state === 'open' && (!one || r.id === one))
+    if (!open.length) return text(one ? `No open commit request ${one}.` : 'No open commit requests.')
+    const h = typeof hash === 'string' && /^[0-9a-f]{7,64}$/.test(hash) ? hash : ''
+    doc.transact(() => { for (const r of open) commitMap(doc).set(r.id, { ...r, state: 'done', doneBy: me, hash: h, doneAt: Date.now() }) }, AGENT)
+    return text(`Marked ${open.length} commit request${open.length === 1 ? '' : 's'} done.`)
+  })
+
+  tool('quilt_list_files', {
+    description: 'List the shared project files with who is working on them (claims).',
+    inputSchema: { under: z.string().optional().describe('Only files under this folder') }
+  }, ({ under }, { room, files, blobs }) => {
+    const pre = under ? cleanPath(under).replace(/\/+$/, '') + '/' : ''
+    const cl = claimsOf(room).map((c) => ({ ...c, m: globMatcher(c.pattern) }))
+    const paths = [...new Set([...files.keys(), ...blobs.keys()])].filter((p) => isSafeRelPath(p) && (!pre || p.startsWith(pre))).sort()
+    const shown = paths.slice(0, 500).map((p) => {
+      const c = cl.find((x) => x.m(p))
+      return `- ${p}${c ? ` (${c.box ? `boxed by ${c.by}: their unfinished work` : `claimed by ${c.by}`}${c.queue.length ? `, ${c.queue.length} waiting` : ''})` : ''}`
+    })
+    return text(paths.length ? shown.join('\n') + (paths.length > 500 ? `\n… and ${paths.length - 500} more` : '') : 'No files.')
+  })
+
+  tool('quilt_project_rules', {
+    description: 'The project\'s rules for AI and its design system, the same whatever tool you run in: AGENTS.md (root and folders, else CLAUDE.md), Cursor rules that always apply, and DESIGN.md (or the file AGENTS.md names). Read it before your first change in a session.',
+    inputSchema: {}
+  }, (args, { files }) => text(renderRules(projectRules({ list: [...files.keys()], read: (p) => files.get(p)?.toString() ?? null }))))
+
+  tool('quilt_read_file', {
+    description: 'Read a shared project file as text, as it is right now.',
+    inputSchema: { path: z.string().min(1).max(500).describe('Relative path, e.g. src/app.ts') }
+  }, ({ path: p }, { room, files, blobs }) => {
+    const rel = cleanPath(p)
+    if (!isSafeRelPath(rel)) return fail('That is not a path inside the project.')
+    const bx = claimsOf(room).find((c) => c.box && c.by !== me && c.pattern === rel)
+    const boxNote = bx ? `(Boxed by ${bx.by}: their unfinished work, not committed yet and in nobody else's folder. Don't build on it as if it were done; ask for the file with quilt_request_file if you need it.)\n\n` : ''
+    const t = files.get(rel)
+    if (t) {
+      const s = t.toString()
+      return text(boxNote + (s.length > MAX_READ_CHARS ? s.slice(0, MAX_READ_CHARS) + `\n… (${s.length - MAX_READ_CHARS} more characters not shown)` : s))
+    }
+    const b = blobs.get(rel)
+    if (b && b.stored) return fail(`${rel} is a large file kept in storage (${b.size} bytes); it can't be read here.`)
+    if (b) return fail(`${rel} is a binary file (${Buffer.from(b.data || '', 'base64').length} bytes); it can't be read as text.`)
+    return fail(`There is no file called ${rel} in the session.`)
+  })
+
+  tool('quilt_write_file', {
+    description: 'Write a text file in the shared project (new or existing): everyone gets it on their disk within moments. ' +
+      'Give the whole file; it is merged as an edit, so changes others make elsewhere in the file survive. Read the file right before.',
+    inputSchema: {
+      path: z.string().min(1).max(500).describe('Relative path, e.g. src/app.ts'),
+      content: z.string().max(MAX_WRITE_BYTES).describe('The whole new contents of the file')
+    }
+  }, ({ path: p, content }, { room, doc, fdoc, branch, files, blobs, activity }) => {
+    { const w = waitRefusal(doc, 'quilt_write_file', room); if (w) return fail(w) }
+    const err = writable(room) || branchWritable(room, branch)
+    if (err) return fail(err)
+    const rel = cleanPath(p)
+    if (!isSafeRelPath(rel)) return fail('That is not a path inside the project.')
+    const a = ctx.access(room)
+    if (a && a.role === 'viewer') return fail('You can only view this session; file changes are refused.')
+    const refusal = a && changeRefusal(a, rel)
+    if (refusal) return fail(`${refusal[0].toUpperCase()}${refusal.slice(1)}.`)
+    if (ctx.kind === 'agent' && room.meta.sync && heldForClash(room, branch ? branch.key : DEFAULT_KEY, rel)) return fail(`${rel} is held while a clash with GitHub is merged (quilt_clash status): propose the merged file with quilt_clash propose instead of writing it, so nothing half-merged reaches anyone.`)
+    const claim = claimsOf(room).find((c) => c.by !== me && globMatcher(c.pattern)(rel))
+    if (claim) return fail(heldRefusal(rel, claim))
+    if (blobs.get(rel)?.stored) return fail(`${rel} is a large file kept in storage; it can't be changed here.`)
+    const held = claimsOf(room).some((c) => c.by === me && globMatcher(c.pattern)(rel))
+    const claimedNow = !held && autoClaim(room, rel)
+    const unboxed = held && boxable(room, branchOf(room)) && claimsOf(room).some((c) => c.by === me && c.pattern === rel && !c.box && !c.clash)
+    if (held && (autoHeld.has(`${roomKey(room)}\0${rel}`) || unboxed)) autoClaim(room, rel) // still writing it: keep holding (in a box)
+    if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES) return fail('That file is too big to write here (1 MB at most).')
+    const boxedNow = claimsOf(room).some((c) => c.by === me && c.pattern === rel && c.box) && (claimedNow || unboxed)
+    let detail = ''
+    let existed = false
+    fdoc.transact(() => doc.transact(() => {
+      existed = files.has(rel) || blobs.has(rel)
+      blobs.delete(rel)
+      let ytext = files.get(rel)
+      if (!ytext) { ytext = new Y.Text(); files.set(rel, ytext) }
+      const before = ytext.toString()
+      detail = applyTextDiff(ytext, content)
+      const kind = existed ? 'edited' : 'created'
+      activity.push([{ by: me, path: rel, kind, detail, ...(branch ? { branch: branch.key } : {}), ts: Date.now() }])
+      if (activity.length > ACTIVITY_CAP) activity.delete(0, activity.length - ACTIVITY_CAP)
+      historyOf(room).record({ by: me, path: rel, kind, before, after: content, task: currentTask(readTasks(taskMap(doc)), me) })
+    }, AGENT), AGENT)
+    // What people said about this file in chat, so the agent works with it in mind (each message once).
+    const box = toldAbout(room)
+    const said = chatAbout([rel], { messages: seen(doc), me }).filter((m) => m.id && !box.told.includes(m.id))
+    if (said.length) {
+      box.told = [...box.told, ...said.map((m) => m.id)].slice(-200)
+      if (ctx.saveInbox) ctx.saveInbox()
+    }
+    const context = renderChatAbout(said)
+    return text(`${existed ? 'Updated' : 'Created'} ${rel}${onBranchNote(room, branch)}${detail ? ` (${detail} lines)` : ' (no change)'}. Everyone in the session has it now.${boxedNow ? ` ${rel} is boxed for you: in nobody else's folder until you commit it (quilt_git_commit), or quilt_unpack it when someone needs it now.` : claimedNow ? ` ${rel} is claimed for you while you work on it; quilt_release it when you are done.` : ''}${context ? `\n\n${context}` : ''}`)
+  })
+
+  tool('quilt_claim', {
+    description: 'Claim files or folders (a path or glob like src/auth/**) before a larger change, so others know not to edit them.',
+    inputSchema: {
+      pattern: z.string().min(1).max(300),
+      note: z.string().max(500).optional().describe('What you are doing')
+    }
+  }, ({ pattern, note }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_claim', room); if (w) return fail(w) }
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      // Someone who may not post keeps their claim but not its note, which everyone reads.
+      const r = room.claimRequest({ ...who(room), talk: ctx.access(room)?.talk !== false }, { op: 'claim', pattern: pattern.trim(), note: note || '' })
+      if (r.ok === false) return fail(r.error || 'Could not claim that.')
+      const key = `${roomKey(room)}\0${pattern.trim()}`
+      clearTimeout(autoHeld.get(key)); autoHeld.delete(key) // claimed on purpose now: kept until released
+    } catch (e) { return fail(e.message) }
+    room.broadcastClaims()
+    return text(`Claimed ${pattern.trim()}. Release it with quilt_release when done.`)
+  })
+
+  tool('quilt_release', {
+    description: 'Release a claim (or all of your claims when no pattern is given).',
+    inputSchema: { pattern: z.string().optional() }
+  }, ({ pattern }, { room }) => {
+    // Releasing everything keeps boxes: a box opens when it's committed (quilt_git_commit) or unpacked (quilt_unpack).
+    const mine = claimsOf(room).filter((c) => c.by === me && (pattern ? c.pattern === pattern.trim() : !c.box))
+    // A file someone waits for is handed off, not released.
+    const waited = mine.filter((c) => c.queue.length)
+    if (pattern && waited.length) return fail(renderQueued(queuedFor(waited, me), 'release the rest'))
+    const released = []
+    for (const c of mine.filter((x) => !x.queue.length)) {
+      try { room.claimRequest(who(room), { op: 'release', pattern: c.pattern }); released.push(c.pattern) } catch {}
+      const key = `${roomKey(room)}\0${c.pattern}`
+      clearTimeout(autoHeld.get(key)); autoHeld.delete(key)
+    }
+    if (released.length) room.broadcastClaims()
+    const boxes = pattern ? [] : claimsOf(room).filter((c) => c.by === me && c.box).map((c) => c.pattern)
+    return text((released.length ? `Released ${released.join(', ')}.` : 'Nothing to release.') + (waited.length ? ` Kept ${waited.map((c) => c.pattern).join(', ')}: someone is waiting for ${waited.length === 1 ? 'it' : 'them'}; hand off with quilt_handoff.` : '') +
+      (boxes.length ? ` Your boxed work stays boxed (${boxes.slice(0, 10).join(', ')}${boxes.length > 10 ? ', …' : ''}): commit it with quilt_git_commit, or quilt_unpack it.` : ''))
+  })
+
+  tool('quilt_unpack', {
+    description: 'Share boxed work before it is committed. Your writes stay in a box: everyone sees the change, but it is in nobody else\'s folder, so nobody else\'s git can commit it, until you commit it (quilt_git_commit). ' +
+      'Unpack when someone needs your change now: your boxed files reach everyone\'s folder, and you keep them. Decide this yourself; for a large, risky or critical change, or when the project\'s rules say so, ask your person first.',
+    inputSchema: { paths: z.array(z.string().min(1).max(500)).min(1).max(100).describe('Your boxed files, relative paths') }
+  }, ({ paths }, { room, doc }) => {
+    { const w = waitRefusal(doc, 'quilt_unpack', room); if (w) return fail(w) }
+    const done = []
+    const not = []
+    for (const p of [...new Set(paths.map(cleanPath))]) {
+      const c = claimsOf(room).find((x) => x.pattern === p && x.by === me && x.box)
+      if (!c) { not.push(p); continue }
+      try { if (room.claimRequest(who(room), { op: 'unbox', pattern: p, release: false }).unboxed) done.push(p); else not.push(p) } catch { not.push(p) }
+    }
+    if (done.length) room.broadcastClaims()
+    if (!done.length) return fail(`${not.join(', ')} ${not.length === 1 ? 'is' : 'are'} not boxed by you.`)
+    return text(`Unpacked ${done.join(', ')}: in everyone's folder now. Your next write to one boxes it again.${not.length ? ` Not boxed by you: ${not.join(', ')}.` : ''}`)
+  })
+
+  tool('quilt_request_file', {
+    description: 'Ask for a file someone else holds (claimed), instead of editing it: your request joins its file queue, its holder is told, and when they finish they hand it to you with their context. ' +
+      'You are woken (a direct message, in quilt_inbox and your webhook) when it is yours. Asking again for the same file updates your request.',
+    inputSchema: {
+      path: z.string().min(1).max(500).describe('The file you need, relative path'),
+      title: z.string().min(1).max(120).describe('What you will do, e.g. "Working on retry logic for task t-12"'),
+      description: z.string().max(300).optional().describe('Your plan in summary: what you want to change and why (300 characters at most)'),
+      task: z.string().max(80).optional().describe('The task id this is for, if any')
+    }
+  }, ({ path: p, title, description, task }, { room }) => {
+    const err = writable(room)
+    if (err) return fail(err)
+    try {
+      const r = room.claimRequest({ ...who(room), talk: ctx.access(room)?.talk !== false }, { op: 'request', path: cleanPath(p), title, description: description || '', task })
+      room.broadcastClaims()
+      return text(`Asked for ${cleanPath(p)}: you are number ${r.position} in the queue for ${r.pattern} (held by ${r.holder}). ${r.holder} is told; you will be handed it with their context. Carry on with other work.`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_handoff', {
+    description: 'Hand a file you hold to someone waiting for it in its file queue (the first, unless you name them), with your context: what you changed, what is left, anything they should know. ' +
+      'The claim becomes theirs and they get your context in a direct message. Required before you finish or release a file someone is waiting for.',
+    inputSchema: {
+      path: z.string().min(1).max(500).describe('The file (or the claimed pattern) to hand off'),
+      context: z.string().min(1).max(2000).describe('What you changed, what is left, gotchas'),
+      to: z.string().max(80).optional().describe('Who to hand it to (a name or request id); omit for the first in the queue')
+    }
+  }, ({ path: p, context, to }, { room }) => {
+    try {
+      const r = room.claimRequest(who(room), { op: 'handoff', pattern: cleanPath(p), context, to: to || '' })
+      const key = `${roomKey(room)}\0${r.pattern}`
+      clearTimeout(autoHeld.get(key)); autoHeld.delete(key)
+      room.broadcastClaims()
+      return text(`Handed ${r.pattern} to ${r.to} with your context.${r.waiting ? ` ${r.waiting} more waiting: ${r.to} hands it on next.` : ''}`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  tool('quilt_withdraw_request', {
+    description: 'Take back your request for a file (from quilt_request_file) when you no longer need it.',
+    inputSchema: { path: z.string().min(1).max(500).describe('The file you asked for') }
+  }, ({ path: p }, { room }) => {
+    const rel = cleanPath(p)
+    const mine = claimsOf(room).flatMap((c) => c.queue).filter((r) => r.by === me && r.path === rel)
+    let n = 0
+    for (const r of mine) n += room.claimRequest(who(room), { op: 'withdraw', request: r.id }).withdrawn || 0
+    if (n) room.broadcastClaims()
+    return text(n ? `Withdrew your request for ${rel}.` : `You had not asked for ${rel}.`)
+  })
+
+  // `quilt sync` (npx heyquilt sync): a sandboxed agent's folder in one shot, its sync state kept
+  // here (relay-turn-sync.js). Hosted only: the CLI reaches it with the agent's QUILT_AGENT_KEY.
+  if (ctx.multi) {
+    tool('quilt_sync', {
+      description: SYNC_DESCRIPTION,
+      inputSchema: {
+        step: z.enum(['plan', 'push', 'pull', 'done']).describe('plan, then push, pull and done'),
+        slot: z.string().min(8).max(64).describe('The slot in your QUILT_AGENT_KEY'),
+        branch: z.string().max(200).optional().describe('plan: the folder\'s git branch; used when the session has it'),
+        files: z.record(z.string(), z.union([z.string(), z.object({ text: z.string().optional(), base64: z.string().optional(), deleted: z.boolean().optional() })])).optional().describe('plan and done: { path: sha1 }; push: { path: { text } | { base64 } | { deleted: true } }'),
+        paths: z.array(z.string().max(1024)).max(10000).optional().describe('pull: the paths to fetch')
+      }
+    }, (args, parts) => {
+      let { room, doc, branch, fdoc, files, blobs, activity } = parts
+      // The folder's git branch, when the session has it: the agent works there from now on (as quilt_git_branch).
+      const want = args.step === 'plan' && typeof args.branch === 'string' ? args.branch.trim() : ''
+      if (want && ctx.setBranch && room.meta.layout === 2 && validBranchKey(want) && want !== DEFAULT_KEY && room.meta.branches[room.resolveKey(want)] && room.resolveKey(want) !== branchOf(room)) {
+        try {
+          ctx.setBranch(room, want, { by: me, editor: ctx.access(room)?.role !== 'viewer' })
+          branch = branchEntry(room)
+          fdoc = branch ? branch.doc : doc
+          files = fdoc.getMap('files')
+          blobs = fdoc.getMap('blobs')
+        } catch {}
+      }
+      const key = branch ? branch.key : DEFAULT_KEY
+      const a = ctx.access(room)
+      try {
+        const answer = turnSyncStep(args, {
+          room,
+          fdoc,
+          files,
+          blobs,
+          branchKey: branch ? branch.key : ROOM_KEY,
+          epoch: branch && room.branchEpoch ? room.branchEpoch(branch.key) : null,
+          account: ctx.who(room).id || me,
+          me,
+          origin: AGENT,
+          globalRefusal: () => waitRefusal(doc, 'quilt_sync', room) || writable(room) || branchWritable(room, branch),
+          pathRefusal: (rel) => {
+            if (a && a.role === 'viewer') return { kind: 'aside', why: 'you can only view this session' }
+            const scope = a && changeRefusal(a, rel)
+            if (scope) return { kind: 'aside', why: scope }
+            if (ctx.kind === 'agent' && room.meta.sync && heldForClash(room, key, rel)) return { kind: 'keep', why: `${rel} is held while a clash with GitHub is merged` }
+            const claim = claimsOf(room).find((c) => c.by !== me && globMatcher(c.pattern)(rel))
+            return claim ? { kind: 'claimed', why: heldRefusal(rel, claim), by: claim.by } : null
+          },
+          record: ({ rel, kind, before, after, detail }) => {
+            activity.push([{ by: me, path: rel, kind, detail: detail || '', ...(branch ? { branch: branch.key } : {}), ts: Date.now() }])
+            if (activity.length > ACTIVITY_CAP) activity.delete(0, activity.length - ACTIVITY_CAP)
+            historyOf(room).record({ by: me, path: rel, kind, before, after, detail, task: currentTask(readTasks(taskMap(doc)), me) })
+          },
+          lastEditor: (rel) => activity.toArray().reverse().find((e) => e && e.path === rel && (!branch || !e.branch || e.branch === branch.key))?.by || null,
+          // Others' boxes: their unfinished work stays out of this folder (relay-turn-sync.js).
+          ghosts: new Set(claimsOf(room).filter((c) => c.box && c.by !== me).map((c) => c.pattern))
+        })
+        return text(JSON.stringify({ ...answer, branch: key === DEFAULT_KEY ? room.defaultKey : key }))
+      } catch (e) { return fail(e.message) }
+    })
+  }
+}
+
+const SYNC_DESCRIPTION = 'For `quilt sync` (npx heyquilt sync), which syncs a sandboxed agent\'s folder with the session in one go: run that command rather than calling this yourself. ' +
+  'Steps: plan (the folder\'s files and their sha1s: what to upload, pull, remove and keep aside), push (their contents), pull (the session\'s versions), done (the folder\'s files after writing: the relay keeps them as this slot\'s checkpoint). Answers are JSON.'
+
+// The workspace library for hosted agents (see workspace-tools.js), offered only while the
+// accounts API says workspaces are on.
+export const FEATURES_EVERY_MS = 10 * 60 * 1000
+const FEATURES_TIMEOUT_MS = 5000
+// One API call, and one upload or download (at most 2 MB from here), from the relay: under
+// the API's own 30 s wait for the relay, so a slow call is reported by the tool, not cut off.
+const WORKSPACE_CALL_TIMEOUT_MS = 20 * 1000
+const WORKSPACE_TRANSFER_TIMEOUT_MS = 20 * 1000
+
+/**
+ * Asks `<apiUrl>/v1/features` now and every `everyMs` whether workspaces are on. on() is
+ * false until the API first says true. A failed probe (unreachable, slow, a server error, an
+ * odd answer) keeps the last answer, so off when there was none; an API without the route
+ * (404) has no workspaces. Never throws; its timer never holds the process open; stop()
+ * ends it and any probe in flight. `ready` is the first probe's answer.
+ */
+export function watchFeatures ({ apiUrl, fetch: fetchImpl = globalThis.fetch, everyMs = FEATURES_EVERY_MS, retryMs = 30_000, timeoutMs = FEATURES_TIMEOUT_MS, log = () => {} }) {
+  const url = `${String(apiUrl).replace(/\/+$/, '')}/v1/features`
+  let known = false
+  let inflight = null
+  let current = null // the AbortController of the probe in flight
+  let stopped = false
+  let answered = false // until the API has answered once, ask again sooner
+  const set = (on) => {
+    answered = true
+    if (on !== known) log(`hosted agents: workspace tools ${on ? 'on' : 'off'}`)
+    known = on
+  }
+  async function ask () {
+    const ac = new AbortController()
+    current = ac
+    const timer = setTimeout(() => ac.abort(new Error('the features check took too long')), timeoutMs)
+    timer.unref?.()
+    try {
+      const res = await fetchImpl(url, { signal: ac.signal })
+      if (res.status === 404) { set(false); return }
+      if (!res.ok) return
+      const body = await res.json()
+      if (body && typeof body === 'object') set(body.workspaces === true)
+    } catch {
+      // Unreachable, slow or garbled: keep what we knew.
+    } finally {
+      clearTimeout(timer)
+      ac.abort()
+      current = null
+    }
+  }
+  function probe () {
+    if (stopped) return Promise.resolve(known)
+    if (!inflight) inflight = ask().catch(() => {}).finally(() => { inflight = null })
+    return inflight.then(() => known)
+  }
+  const ready = probe()
+  const timer = setInterval(() => { probe() }, everyMs)
+  timer.unref?.()
+  // The API may still be starting (both deployed together): until it answers, try every retryMs.
+  const early = setInterval(() => { if (answered) clearInterval(early); else probe() }, retryMs)
+  early.unref?.()
+  return {
+    ready,
+    on: () => !stopped && known,
+    probe,
+    stop () {
+      stopped = true
+      clearInterval(timer)
+      clearInterval(early)
+      current?.abort(new Error('stopped'))
+    }
+  }
+}
+
+/**
+ * How a hosted agent's library tools reach the accounts API: as the agent, with the pass
+ * the relay was handed (`Authorization: QuiltPass`, which only the workspace routes take).
+ * Errors carry the API's message and status. The pass never goes into an error or a log.
+ */
+export function hostedWorkspaceAccess ({ apiUrl, pass, fetch: fetchImpl = globalThis.fetch }) {
+  const api = String(apiUrl).replace(/\/+$/, '')
+  const call = async (method, route, body) => {
+    let res
+    try {
+      res = await fetchImpl(api + route, {
+        method,
+        headers: { authorization: `QuiltPass ${pass}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(WORKSPACE_CALL_TIMEOUT_MS)
+      })
+    } catch (err) {
+      throw new Error(`Couldn't reach Quilt (${err?.cause?.code || err?.name || 'no answer'}).`)
+    }
+    const data = await res.json().catch(() => null)
+    if (!res.ok) throw Object.assign(new Error(data?.error || `Quilt answered ${res.status}.`), { status: res.status })
+    if (!data || typeof data !== 'object') throw new Error('Quilt sent back something unexpected.')
+    return data
+  }
+  const put = async (url, bytes, headers) => {
+    try {
+      const res = await fetchImpl(url, { method: 'PUT', headers, body: bytes, signal: AbortSignal.timeout(WORKSPACE_TRANSFER_TIMEOUT_MS) })
+      await res.body?.cancel().catch(() => {}) // the status is all we need; let the socket go
+      return res.status
+    } catch (err) {
+      throw new Error(`The upload did not go through (${err?.cause?.code || err?.name || 'no answer'}).`)
+    }
+  }
+  return { call, fetchBytes: bytesFetcher(fetchImpl, { timeoutMs: WORKSPACE_TRANSFER_TIMEOUT_MS }), put, saveDir: null, readLocal: null }
+}
+
+async function serve (mcp, req, res, body) {
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
+  res.on('close', () => { transport.close().catch(() => {}); mcp.close().catch(() => {}) })
+  await mcp.connect(transport)
+  // `body`: read already (the relay on many machines looked at it to find the room's machine).
+  await transport.handleRequest(req, res, body)
+}
+
+/**
+ * Hosted agents: one MCP request (stateless) for the holder of `pass`, who is in whichever
+ * session `relay.hosted` remembers for them. `relay` is { getRoom, roomEnded, refused, hosted,
+ * saveHosted, log, endedMessage }. `workspaces`, given only while the API has them on and
+ * the holder is an agent, is { apiUrl, pass (as sent), fetch }: the library tools are added.
+ */
+export async function handleHostedMcp ({ req, res, pass, relay, workspaces = null, body = undefined }) {
+  const image = String(req.headers['x-quilt-image'] || '').trim()
+  // The library's guide is part of the instructions only when its tools are offered.
+  const mcp = new McpServer({ name: 'quilt', version: '0.2.0' }, { instructions: workspaces ? `${HOSTED_INSTRUCTIONS}\n\n${WORKSPACE_GUIDE_HOSTED}` : HOSTED_INSTRUCTIONS })
+  const me = pass.name
+  const account = `${pass.kind}:${pass.sub}`
+  const touched = new Set()
+  const done = () => { for (const room of touched) if (room && !room.conns.size && room.onEmpty) room.onEmpty() }
+  res.on('close', done)
+  // Which sessions the agent is in, for the accounts API (x-quilt-rooms), and which one this
+  // call acted on (x-quilt-room): its next pass is for that room, and so carries its grant there.
+  // On many relay machines (relay-cluster.js), the agent's sessions on other machines come from the
+  // accounts API's index (`relay.index`, read before this call); this machine holds the records
+  // of its own. Each call is sent to the machine of the session it names.
+  const index = relay.index || null
+  const allRooms = (h) => {
+    const mine = hostedRooms(h)
+    return index ? [...mine, ...index.rooms.filter((r) => !mine.includes(r))] : mine
+  }
+  const elsewhere = (h, name) => !!(index && !hostedIn(h, name) && index.rooms.includes(name))
+  const noteIndex = (o) => {
+    if (!index || !relay.noteHosted) return
+    if (o.add && !index.rooms.includes(o.add)) index.rooms.push(o.add)
+    if (o.remove) index.rooms = index.rooms.filter((r) => r !== o.remove)
+    relay.noteHosted(o)
+  }
+  const tellRoom = (acted = '') => {
+    if (res.headersSent) return
+    const rooms = allRooms(relay.hosted.get(account))
+    if (rooms.length) res.setHeader('x-quilt-rooms', rooms.join(',')); else res.removeHeader('x-quilt-rooms')
+    const one = acted || (rooms.length === 1 ? rooms[0] : '')
+    if (one) res.setHeader('x-quilt-room', one); else res.removeHeader('x-quilt-room')
+  }
+  tellRoom()
+  const listSessions = (rooms) => `You are in ${rooms.length} sessions (${rooms.join(', ')}): say which this is about with session: <id>.`
+  /** The agent's record for the session a call names (or its only one), or why there is none. */
+  const pick = (session) => {
+    const h = relay.hosted.get(account)
+    const rooms = allRooms(h)
+    if (!rooms.length) return { error: NOT_JOINED }
+    const name = session ? String(session).trim() : ''
+    if (name && elsewhere(h, name)) return { error: `Session ${name} is on another relay machine; call again with session: ${name} in a moment.` }
+    if (name && !hostedIn(h, name)) return { error: `You are not in session ${name}. ${rooms.length === 1 ? `You are in ${rooms[0]}.` : listSessions(rooms)}` }
+    if (!name && rooms.length > 1) return { error: listSessions(rooms) }
+    if (!name && elsewhere(h, rooms[0])) return { error: `Session ${rooms[0]} is on another relay machine; call again with session: ${rooms[0]}.` }
+    return { h, name: name || rooms[0] }
+  }
+  /** Forgets one session (ended, removed, denied); the entry, with its webhook, stays. */
+  const drop = (name, reason) => {
+    visitEnd(name, reason)
+    const h = relay.hosted.get(account)
+    if (h && h.rooms) delete h.rooms[name]
+    relay.saveHosted()
+    noteIndex({ remove: name })
+    tellRoom()
+  }
+
+  /** The session this call is about, with the agent's standing there, or why there is none: { room, access } | { error }. */
+  const current = (session) => {
+    const p = pick(session)
+    if (p.error) return p
+    const { h, name } = p
+    const r = h.rooms[name]
+    if (relay.roomEnded(name)) { drop(name, 'session_ended'); return { error: `${relay.endedMessage}. ${allRooms(h).length ? listSessions(allRooms(h)) : NOT_JOINED}` } }
+    const room = relay.getRoom(name)
+    if (!room) return { error: relay.refused(name)[1] }
+    touched.add(room)
+    if (!room.exists) { drop(name, 'session_ended'); return { error: REMOVED } }
+    if (r.denied) { drop(name, 'removed'); return { error: DENIED } }
+    const access = room.hostedAccess(pass)
+    if (access.needsRoomPass) {
+      if (!res.headersSent) { res.setHeader('x-quilt-retry', 'room-pass'); tellRoom(name) }
+      return { error: NEEDS_ROOM_PASS, room, access }
+    }
+    if (access.state !== 'approved') {
+      // Still waiting, but the relay restarted and forgot: back on the owner's list.
+      if (r.pending && ![...room.pending].some(([k, p]) => k.hosted && p.id === account)) room.hostedRequest(pass, r.invitedAs || 'viewer')
+      if (!r.pending) visitEnd(name, 'removed')
+      return { error: r.pending ? WAITING : REMOVED, room, access }
+    }
+    r.seenAt = h.seenAt = Date.now()
+    relay.saveHosted()
+    tellRoom(name)
+    room.hostedActive(account)
+    visitStart(room, access)
+    return { room, access }
+  }
+  // The audit trail (server.js keeps each visit with the agent's record for that session in relay.hosted).
+  const visitStart = (room, access) => { if (relay.visitStart) relay.visitStart(account, room, { name: me, tool: toolLabel(mcp.server.getClientVersion()?.name) || 'hosted', owner: !!(access && access.owner) }) }
+  const visitEnd = (roomName, reason) => { if (relay.visitEnd) relay.visitEnd(account, roomName, reason) }
+  // The agent's sessions that are loaded on this relay now (for a webhook taking stock).
+  const loadedRooms = () => hostedRooms(relay.hosted.get(account)).map((n) => (relay.roomEnded(n) ? null : relay.getRoom(n))).filter((r) => r && r.exists)
+  const ctx = {
+    me,
+    multi: true, // every tool takes `session`
+    who: () => ({ name: me, id: account }),
+    kind: pass.kind === 'agent' ? 'agent' : 'human',
+    access: (room) => room.hostedAccess(pass),
+    branch: (room) => room.hostedBranch(account),
+    setBranch: (room, key, opts) => room.setHostedBranch(account, key, opts),
+    pin: (room) => room.pinHostedBranch(account),
+    tool: () => toolLabel(mcp.server.getClientVersion()?.name) || 'hosted',
+    warn: () => '',
+    inbox: (room) => {
+      const r = hostedIn(relay.hosted.get(account), room.name)
+      if (!r) return { state: null }
+      if (!r.inbox) r.inbox = { state: null }
+      return r.inbox
+    },
+    saveInbox: () => relay.saveHosted(),
+    webhook: relay.webhooks ? {
+      get: () => relay.hosted.get(account)?.webhook || null,
+      subscribe: (given) => {
+        const sub = relay.webhooks.subscribe(account, { name: me, rooms: loadedRooms() }, given)
+        if (relay.shareWebhook) relay.shareWebhook(relay.hosted.get(account).webhook)
+        return sub
+      },
+      // A workspace agent's one webhook also gets session.started from the accounts API: the same URL and secret go there.
+      tellApi: async (sub) => {
+        if (!workspaces || pass.kind !== 'agent') return ''
+        try {
+          await hostedWorkspaceAccess(workspaces).call('PUT', '/v1/agents/me/webhook', { url: sub.url, secret: sub.secret })
+          return 'Your workspaces send session.started there too (a session starting in a workspace that invites you, with its join link).'
+        } catch (e) { return `Your workspaces could not be told (${e.message}); session.started events will not reach it until quilt_webhook_subscribe succeeds.` }
+      },
+      unsubscribe: async () => {
+        const had = relay.webhooks.unsubscribe(account)
+        if (relay.shareWebhook) relay.shareWebhook(null)
+        if (had && workspaces && pass.kind === 'agent') await hostedWorkspaceAccess(workspaces).call('DELETE', '/v1/agents/me/webhook').catch(() => {})
+        return had
+      }
+    } : null,
+    updates: relay.updates || null,
+    image: () => image,
+    withSession: (fn, session) => {
+      const c = current(session)
+      return c.error ? fail(c.error) : fn(c.room)
+    }
+  }
+
+  mcp.registerTool('quilt_join_session', {
+    description: 'Join a live quilt session from an invite link (https://join.heyquilt.com/<room>#<secret>). The session owner may have to let you in; call quilt_session_info to see when they have.',
+    inputSchema: { invite: z.string().min(1).max(600).describe('The invite link, or the full "quilt join <link>" command') }
+  }, ({ invite }) => {
+    let inv
+    try { inv = parseInvite(invite, { allowRelay: () => true }) } catch (err) { return fail(err.message) }
+    if (relay.roomEnded(inv.room)) return fail(`${relay.endedMessage}. Ask for a new invite.`)
+    const room = relay.getRoom(inv.room)
+    if (!room) return fail(relay.refused(inv.room)[1])
+    touched.add(room)
+    if (!room.exists) return fail("That session isn't running on the relay (yet). Ask the person who invited you to start it, then try again.")
+    const auth = room.authorize(inv.secret, '')
+    if (auth !== 'editor' && auth !== 'viewer') return fail('Wrong room secret: copy the whole invite link, including the part after #.')
+    const a = room.hostedRequest(pass, auth)
+    // One more session for the agent (it stays in the others); joining again in the same session carries its visit and inbox on.
+    const h = relay.hosted.get(account) || newHosted()
+    const was = hostedIn(h, inv.room)
+    h.rooms[inv.room] = { since: was ? was.since : Date.now(), seenAt: Date.now(), pending: a.state === 'pending', ...(a.state === 'pending' ? { invitedAs: auth, name: me, kind: pass.kind } : {}), inbox: was && was.inbox ? was.inbox : takeStock(room.doc, me), ...(was && was.visit ? { visit: was.visit } : {}) }
+    h.seenAt = Date.now()
+    relay.hosted.set(account, h)
+    // Its webhook (one for every session) takes stock of this one: what is there already is not news.
+    if (relay.webhooks) relay.webhooks.takeStock(account, room)
+    relay.saveHosted()
+    noteIndex({ add: inv.room })
+    tellRoom(inv.room)
+    const all = allRooms(h)
+    const also = all.length > 1 ? ` You are in ${all.length} sessions now (${all.join(', ')}): name this one with session: ${inv.room} in your calls.` : ''
+    if (a.state === 'pending') return text(`Asked to join room ${inv.room} as ${auth === 'viewer' ? 'a viewer' : 'an editor'}. ${WAITING}${also}`)
+    room.hostedActive(account)
+    visitStart(room, a)
+    return text(`Joined room ${inv.room} as ${me} (${a.owner ? 'owner' : a.role}${a.scopes && a.scopes.length ? `, folders ${a.scopes.join(', ')}` : ''}). Call quilt_status to see who is here.${also}`)
+  })
+
+  mcp.registerTool('quilt_session_info', {
+    description: 'The sessions you are in (their ids, for `session` in every other tool) and your access in each: waiting for the owner, or let in as an editor or viewer. With session, just that one.',
+    inputSchema: { session: SESSION_ARG }
+  }, ({ session } = {}) => {
+    const h = relay.hosted.get(account)
+    const rooms = allRooms(h)
+    if (!rooms.length) return text(NOT_JOINED)
+    const lines = []
+    const one = session ? String(session).trim() : ''
+    if (one && !rooms.includes(one)) return fail(`You are not in session ${one}. ${listSessions(rooms)}`)
+    for (const name of one ? [one] : rooms) {
+      // A session on another relay machine is described there: this call names it to ask.
+      if (elsewhere(h, name)) { lines.push(`Room ${name}: call quilt_session_info with session: ${name} for your access there.`); continue }
+      const c = current(name)
+      if (c.error) { lines.push(`Room ${name}: ${c.error}`); continue }
+      const a = c.access
+      const room = c.room
+      lines.push(`Room ${name}${room.meta.name ? ` (${room.meta.name})` : ''}${room.meta.workspace ? `, workspace ${room.meta.workspace}` : ''}: you are ${me}, ${a.owner ? 'the owner' : a.role === 'viewer' ? 'a viewer (no file changes)' : 'an editor'}${a.scopes && a.scopes.length ? `, limited to ${a.scopes.join(', ')}` : ''}${a.scopesExcept && a.scopesExcept.length ? `, not in ${a.scopesExcept.join(', ')}` : ''}${a.talk === false ? ', and you may not post' : ''}.`)
+    }
+    if (rooms.length > 1) lines.push('Name the session in every call (session: <id>); a webhook event or inbox entry says which it is from.')
+    return text(lines.join('\n'))
+  })
+
+  mcp.registerTool('quilt_leave_session', {
+    description: 'Leave a session you are in (the others, and your webhook, stay).',
+    inputSchema: { session: SESSION_ARG }
+  }, ({ session }) => {
+    const p = pick(session)
+    if (p.error) return p.error === NOT_JOINED ? text('You are not in a session.') : fail(p.error)
+    const { h, name } = p
+    visitEnd(name, 'left')
+    delete h.rooms[name]
+    relay.saveHosted()
+    noteIndex({ remove: name })
+    tellRoom()
+    const room = relay.getRoom(name)
+    if (room) {
+      touched.add(room)
+      room.hostedSeen.delete(account)
+      room.forgetHostedBranch(account)
+      for (const [k, p] of room.pending) if (k.hosted && p.id === account) room.pending.delete(k)
+      // Leaving lets go of its claims: nobody else could.
+      room.dropRequests((r) => r.byId === account)
+      room.dropClaims((c) => c.byId === account, (c) => `${c.by} left the session.`)
+      room.broadcastClaims()
+      room.broadcastMembers()
+    }
+    const left = allRooms(h)
+    return text(`Left room ${name}.${left.length ? ` You are still in ${left.join(', ')}.` : ''}`)
+  })
+
+  mcp.registerTool('quilt_git_branch', {
+    description: 'Work on another branch of the session: your file tools, claims and history then read and write that branch. quilt_status lists the branches and who is on each. create: true adds a branch that isn\'t in the session yet: one that is on GitHub is loaded at its latest commit (and the relay brings later commits on it in); any other starts from a copy of the files on the one you are on.',
+    inputSchema: {
+      branch: z.string().min(1).max(200).optional().describe('The branch to work on, e.g. quilt/<you>/<topic> or feature/login; without it, the session\'s branches are listed'),
+      create: z.boolean().optional().describe('Add it to the session: from GitHub when it is there, otherwise a copy of your current branch\'s files'),
+      session: SESSION_ARG
+    }
+  }, async ({ branch, create, session }) => {
+    const c = current(session)
+    if (c.error) return fail(c.error)
+    const room = c.room
+    if (!branch) {
+      const members = []
+      for (const st of room.awareness.getStates().values()) if (st && st.name && st.git) members.push({ name: st.name, git: cleanGit(st.git) })
+      const br = branchBoard(members, room.branchList ? room.branchList() : [])
+      return text(br.length ? `${branchesMarkdown(br, { limit: 20, mine: room.hostedBranch(account) })}\nSwitch with quilt_git_branch and a branch name; create: true adds one.` : 'This session has one branch, and you are on it.')
+    }
+    const key = String(branch).trim()
+    const editor = ctx.access(room)?.role !== 'viewer'
+    let gh = null
+    try {
+      if (create && validBranchKey(key) && key !== DEFAULT_KEY && !room.meta.branches[room.resolveKey(key)]) {
+        room.assertMigrated()
+        room.assertBranchRoom(editor, 0) // refused before asking GitHub anything
+        gh = await room.branchFromGitHub(account, key)
+      }
+      const r = room.setHostedBranch(account, key, { create: !!create, by: me, editor, github: gh && gh.state === 'loaded' ? gh : null })
+      if (r.created && gh && gh.state === 'loaded') {
+        const n = gh.texts.size + gh.blobs.size
+        const left = gh.skipped.length ? ` ${gh.skipped.length} file${gh.skipped.length === 1 ? ' was' : 's were'} too large for the relay and left out (${gh.skipped.slice(0, 5).join(', ')}${gh.skipped.length > 5 ? ', …' : ''}): a member's folder on it brings ${gh.skipped.length === 1 ? 'it' : 'them'} in.` : ''
+        return text(`Loaded ${r.branch} from GitHub (${gh.repo} at ${gh.head.slice(0, 7)}, ${n} file${n === 1 ? '' : 's'}).${left} Your file tools, claims and history use ${r.branch} now. People work on it with \`git checkout ${r.branch}\`, and their folder follows. The relay brings new commits on ${gh.upstream.name} in while no folder on it can; quilt_sync_branch asks for them now.`)
+      }
+      if (r.created) {
+        const why = !gh ? '' : {
+          'not-github': `The session's repository (${gh.repo}) isn't on GitHub, so the relay can't load ${r.branch} from it: `,
+          'no-branch': `${r.branch} isn't a branch on GitHub (${gh.repo}), so `,
+          private: `The relay can't read ${gh.repo} on GitHub (a private repository needs a read-only token: ask the session owner to add one), so `,
+          'token-refused': `The relay's GitHub token can't read ${gh.repo} (ask the session owner to give it read access), so `,
+          'too-many': `${r.branch} on GitHub has more files than the relay loads at once (${LOAD_FILES}), so `,
+          backoff: 'GitHub asked the relay to slow down, so ',
+          error: `The relay couldn't read ${r.branch} from GitHub (${gh.message || 'no answer'}), so `
+        }[gh.state] || ''
+        const said = `Started ${r.branch} from ${r.from}, with a copy of its files. Your file tools, claims and history use ${r.branch} now. It isn't in git yet: people work on it with \`git checkout -b ${r.branch}\` (or \`git checkout ${r.branch}\` once it is pushed), and their folder follows.`
+        return text(why ? `${why}${said[0].toLowerCase()}${said.slice(1)}` : said)
+      }
+      return text(`You are on ${r.branch} now: your file tools, claims and history use it.`)
+    } catch (e) { return fail(e.message) }
+  })
+
+  mcp.registerTool('quilt_sync_branch', {
+    description: 'Bring commits made outside the session (a PR merged on GitHub, a push) into your branch now. A member\'s folder on the branch that can fetch does this about once a minute; otherwise the relay asks GitHub itself, about every 10 minutes, and this asks it now (at most once a minute per branch). It never merges git history: files that clash with the session\'s work become one task on the board for one agent to merge.',
+    inputSchema: { session: SESSION_ARG }
+  }, async ({ session }) => {
+    const c = current(session)
+    if (c.error) return fail(c.error)
+    const room = c.room
+    if (room.meta.layout !== 2 || !room.syncUpstreamNow) return fail('This session has no branches on the relay.')
+    try {
+      const key = room.hostedBranch(account)
+      const r = await room.syncUpstreamNow(key)
+      return text(r.said)
+    } catch (e) { return fail(e.message) }
+  })
+
+  mcp.registerTool('quilt_github_token', {
+    description: 'Session owner only: set (or clear, with an empty token) the GitHub token the relay uses to bring commits in from a private repository while no folder can, to load branches from it, and, when it can write, to commit members\' work (quilt_commit). A fine-grained token for the repository with "Contents: Read" brings commits in; "Contents: Read and write" and "Pull requests: Read and write" let agents commit and open pull requests, within what quilt_agent_commits allows. It stays on the relay: it is never shown again, in any answer, status or log.',
+    inputSchema: { token: z.string().max(300).describe('The token (github_pat_… or ghp_…), or "" to remove it'), session: SESSION_ARG }
+  }, ({ token, session }) => {
+    const c = current(session)
+    if (c.error) return fail(c.error)
+    if (!c.access || !c.access.owner) return fail('Only the session owner can set the GitHub token: ask them.')
+    try {
+      const r = c.room.setGithubToken(token)
+      return text(r.githubToken ? 'Saved the GitHub token on the relay. It looks at the session\'s branches again now.' : 'Removed the GitHub token.')
+    } catch (e) { return fail(e.message) }
+  })
+
+  sessionTools(mcp, ctx)
+  // The library works whether or not the agent is in a session (it never touches relay.hosted).
+  if (workspaces) registerWorkspaceTools(mcp, { ...hostedWorkspaceAccess(workspaces), webhook: false })
+  await serve(mcp, req, res, body)
+}
+
+/**
+ * Handles one MCP request (stateless: a fresh server per request) for the older
+ * link-based flow: a browser's token tied to a room by /agent/link.
+ * @param {object} o
+ * @param {object} o.room   the relay Room (doc, awareness, full)
+ * @param {object} o.link   { name, tool, tabSeenAt }
+ * @param {string} [o.toolHint] tool name from the URL (?tool=Cursor)
+ */
+export async function handleAgentMcp ({ req, res, room, link, toolHint, updates = null }) {
+  const mcp = new McpServer({ name: 'quilt', version: '0.1.0' }, { instructions: INSTRUCTIONS })
+  const me = link ? link.name : ''
+  const image = String(req.headers['x-quilt-image'] || '').trim()
+  const ctx = {
+    me,
+    updates,
+    image: () => image,
+    who: () => ({ name: me }),
+    access: () => null,
+    tool: () => toolHint || toolLabel(mcp.server.getClientVersion()?.name),
+    warn: () => Date.now() - (link.tabSeenAt || 0) > TAB_STALE_MS
+      ? `\n\n⚠️ ${me}'s quilt browser tab doesn't seem to be open, so file changes aren't syncing. Ask your user to reopen quilt in their browser.`
+      : '',
+    withSession: (fn) => (room && link) ? fn(room) : fail(NOT_LINKED),
+    inbox: () => {
+      let box = link ? linkInboxes.get(link) : null
+      if (!box) {
+        box = room && link ? takeStock(room.doc, me) : { state: null }
+        if (link) linkInboxes.set(link, box)
+      }
+      return box
+    }
+  }
+  sessionTools(mcp, ctx)
+  await serve(mcp, req, res)
+}