scanruler-mcp 0.2.0 → 0.4.0

package/src/mcp.js

@@ -1,290 +1,1155 @@
-// SPDX-License-Identifier: AGPL-3.0-only
-// The MCP side: the tools an agent lists and calls. Each of the page's
-// commands is a tool (tools.js); four more are this server's own —
-// scanruler_status, to see whether a ScanRuler page is connected and how to
-// connect one; scanruler_open, to open one in the user's browser, paired;
-// scanruler_wait, to wait for it or for it to be idle; and scanruler_batch,
-// to run several of the page's tools in one call.
-
-import { readFileSync } from 'node:fs'
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import { agentJson, imageContent, inputFor, saveFileResult, toolFor, toolName } from './tools.js'
-
-/** The app's own commands as of this release, so the tools are there before
- *  a page connects — unless a page has connected before, whose list was
- *  kept (`remembered`); a connected page's own list replaces either, its
- *  plugins' commands included. Kept in step by the app's tests
- *  (tests/mcpCommands.test.ts). */
-export const SNAPSHOT = JSON.parse(readFileSync(new URL('./commands.json', import.meta.url), 'utf8'))
-
-const INSTRUCTIONS = [
-  'These tools drive ScanRuler, a measuring app for 3D scans, in the browser tab the user has open: the user watches every step in the viewport and can undo it there.',
-  'Start with scanruler_status. If no ScanRuler page is connected, call scanruler_open: it opens ScanRuler in the user’s browser, paired with this server, and waits for it. If that leaves it unconnected, tell the user what howToConnect says, then call scanruler_wait.',
-  'Read session_state before acting and after: the scan’s bounding box says where the part lies, the elements and dimensions what is measured. Lengths are millimetres, angles degrees; answers give numbers to six significant digits.',
-  'A place on the scan is { point: [x, y, z] } (the nearest scan vertex is taken) or { vertex: n }. To fit a feature, aim at its middle, not at an edge.',
-  'Every tool that changes the session is one step of the undo history; history_undo takes the last back. report_get gives the report as JSON (format "json") or as the text the panel copies (format "text").',
-  'view_render shows you the 3D view as a picture; view_set turns it to a standard view or fits it.',
-  'scanruler_batch runs several tools in one call, in order — many scan_nearest or element_fit calls, say — and stops at the first that is refused unless told to go on.',
-].join(' ')
-
-const text = (value, exact = false) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : agentJson(value, exact) }] })
-const failure = (e) => {
-  const code = e?.code ?? 'failed'
-  const message = e?.message ?? String(e)
-  return { ...text(`${code}: ${message}`), isError: true }
-}
-
-/**
- * @param {{
- *   link: import('./relay.js').SharedLink | import('./link.js').PageLink,
- *   version: string,
- *   cwd: string,
- *   outDir: string,
- *   connectHelp: () => string,
- *   serverInfo: () => Record<string, unknown>,
- *   pageTimeoutMs?: number,
- *   remembered?: { load(): unknown[] | null, save(commands: unknown[]): void } | null,
- *   openPage?: () => Promise<boolean>,
- *   openGraceMs?: number,
- *   openWaitMs?: number,
- * }} options — `openPage` opens the pairing link in the user's browser
- *   (browser.js), true when it could; scanruler_open first gives a tab that
- *   is already paired `openGraceMs` to connect by itself — the page tries
- *   again at most ten seconds apart — and then waits `openWaitMs` for the
- *   one it opened, the user's answer to the browser's question included.
- *   Both together stay under the minute some clients give a tool call.
- */
-export function createMcpServer({
-  link,
-  version,
-  cwd,
-  outDir,
-  connectHelp,
-  serverInfo,
-  pageTimeoutMs = 15_000,
-  remembered = null,
-  openPage = async () => false,
-  openGraceMs = 11_000,
-  openWaitMs = 40_000,
-}) {
-  const server = new Server(
-    { name: 'scanruler', title: 'ScanRuler', version },
-    { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS },
-  )
-
-  // The last connected page's commands, for listing before a page is back:
-  // a client that lists the tools once — at its start, before the tab has
-  // reconnected — and does not list them again when told they changed
-  // still sees every tool the tab offers.
-  let lastPage = remembered?.load() ?? null
-  const commands = () => (link.page?.commands?.length ? link.page.commands : lastPage ?? SNAPSHOT)
-  const remember = () => {
-    const list = link.page?.commands
-    if (!list?.length) return
-    lastPage = list
-    try {
-      remembered?.save(list)
-    } catch {
-      // Not kept: the next run lists the app's own until the page is back.
-    }
-  }
-
-  const status = () => ({
-    connected: link.connected,
-    page: link.page
-      ? {
-          app: link.page.app,
-          version: link.page.version,
-          origin: link.page.origin,
-          plugins: link.page.plugins ?? [],
-          viewport: link.page.viewport ?? null,
-          commands: link.page.commands.length,
-        }
-      : null,
-    server: serverInfo(),
-    ...(link.connected ? {} : { howToConnect: connectHelp() }),
-  })
-
-  const own = [
-    {
-      name: 'scanruler_status',
-      title: 'ScanRuler connection status',
-      description: 'Whether a ScanRuler page is connected to this agent, which version and plugins it has, and — when none is — how the user connects one.',
-      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-      annotations: { readOnlyHint: true, openWorldHint: false },
-      call: async () => text(status()),
-    },
-    {
-      name: 'scanruler_open',
-      title: 'Open ScanRuler',
-      description: 'Open ScanRuler in the user’s default browser, paired with this server, and wait for the page to connect — for when scanruler_status says none is. The first time, the browser asks the user whether the site may reach apps on this computer; they must allow it. Returns the status, with opened: whether the browser was asked to open it. If connected is still false, tell the user what howToConnect says.',
-      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-      annotations: { readOnlyHint: false, openWorldHint: false },
-      call: async () => {
-        // A tab that was paired before is likely open and on its way back.
-        if (link.connected || (await link.waitForPage(openGraceMs))) return text({ ...status(), opened: false })
-        const opened = await openPage().catch(() => false)
-        if (opened) await link.waitForPage(openWaitMs)
-        return text({ ...status(), opened })
-      },
-    },
-    {
-      name: 'scanruler_wait',
-      title: 'Wait for ScanRuler',
-      description: 'Wait until a ScanRuler page is connected (for: "page", the default), or until it is also done with what it is busy with (for: "idle"). Returns the status; connected is false if the time ran out.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          for: { type: 'string', enum: ['page', 'idle'], description: 'page (the default) or idle.' },
-          timeoutSeconds: { type: 'number', exclusiveMinimum: 0, maximum: 600, description: 'How long to wait at most, seconds — 120 by default.' },
-        },
-        additionalProperties: false,
-      },
-      annotations: { readOnlyHint: true, openWorldHint: false },
-      call: async (args) => {
-        const until = Date.now() + 1000 * (args?.timeoutSeconds ?? 120)
-        if (!(await link.waitForPage(Math.max(0, until - Date.now())))) return text(status())
-        if (args?.for === 'idle') {
-          while (Date.now() < until) {
-            const state = await link.run('session.state', {}).catch(() => null)
-            if (state && state.busy === null && state.running === null) break
-            await new Promise((r) => setTimeout(r, 500))
-          }
-        }
-        return text(status())
-      },
-    },
-  ]
-
-  let listed = ''
-  const listNow = () => [...own.map(({ call: _call, ...tool }) => tool), ...commands().map((c) => toolFor(c, { outDir }))]
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    const tools = listNow()
-    listed = JSON.stringify(tools)
-    return { tools }
-  })
-
-  // A page with other commands than were listed — plugins, another version,
-  // a command whose input or description changed — has the client list them
-  // again.
-  const relist = () => {
-    if (!listed) return
-    if (JSON.stringify(listNow()) !== listed) server.sendToolListChanged().catch(() => {})
-  }
-  for (const event of ['connected', 'commands']) {
-    link.on(event, () => {
-      remember()
-      relist()
-    })
-  }
-
-  /** One of the page's tools run on the page: the result as MCP content,
-   *  or a failure. */
-  const runPageTool = async (name, args, onProgress) => {
-    const command = commands().find((c) => toolName(c) === name)
-    if (!command) return failure({ code: 'unknown_command', message: `There is no tool ${name}.` })
-    if (!link.connected && !(await link.waitForPage(pageTimeoutMs))) {
-      return failure({ code: 'unavailable', message: `No ScanRuler page is connected; scanruler_open opens one. ${connectHelp()}` })
-    }
-    try {
-      const { input, binaryKey } = await inputFor(command, args, { cwd })
-      const result = await link.run(command.name, input, binaryKey, onProgress)
-      const image = command.returnsImage ? await imageContent(result, args, { cwd, outDir }) : null
-      if (image) return { content: image }
-      return text(await saveFileResult(result, args, { cwd, outDir }), Boolean(command.exact))
-    } catch (e) {
-      return failure(e)
-    }
-  }
-
-  // Several of the page's tools in one call — what cuts a run of twenty
-  // scan_nearest calls to one round trip. Each answer is the tool's own; a
-  // picture comes back as the text beside it (where it was written, if a
-  // path was given), not as an image.
-  own.push({
-    name: 'scanruler_batch',
-    title: 'Run several ScanRuler tools',
-    description:
-      'Run several of the ScanRuler tools in one call, in order, each with its own arguments — a run of scan_nearest, element_fit or section_get calls, say. Returns results, one per call in order: { tool, ok, result } or { tool, ok: false, error: { code, message } }. The first refused stops the rest (stopped says which index) unless stopOnError is false. Each call that changes the session is still its own undo step. A tool that returns a picture gives its text here, the picture written to a file only if its call gave path. The server’s own tools (scanruler_status, _open, _wait, _batch) cannot be batched.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        calls: {
-          type: 'array',
-          minItems: 1,
-          maxItems: 200,
-          description: 'The calls, in order.',
-          items: {
-            type: 'object',
-            properties: {
-              tool: { type: 'string', minLength: 1, description: 'A tool’s name, as listed — scan_nearest, element_fit.' },
-              arguments: { type: 'object', description: 'Its arguments, as the tool takes them; {} for none.' },
-            },
-            required: ['tool'],
-            additionalProperties: false,
-          },
-        },
-        stopOnError: { type: 'boolean', description: 'Stop at the first refused call (the default), or run every call and report each.' },
-      },
-      required: ['calls'],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, openWorldHint: false },
-    call: async (args) => {
-      const calls = Array.isArray(args?.calls) ? args.calls : []
-      if (calls.length === 0) return failure({ code: 'invalid_input', message: 'calls: give at least one call.' })
-      const stopOnError = args?.stopOnError !== false
-      const results = []
-      let stopped
-      // A batch holding an exact answer (a plane's frame, say) keeps
-      // every answer exact: the rounding is one pass over the whole.
-      let exact = false
-      for (let i = 0; i < calls.length; i++) {
-        const c = calls[i] ?? {}
-        const tool = String(c.tool ?? '')
-        const one = own.some((t) => t.name === tool)
-          ? failure({ code: 'invalid_input', message: `${tool} is the server’s own and is not batched — call it on its own.` })
-          : await runPageTool(tool, c.arguments ?? {}, undefined)
-        if (!one.isError && commands().find((x) => toolName(x) === tool)?.exact) exact = true
-        const body = one.content.find((x) => x.type === 'text')?.text ?? ''
-        if (one.isError) {
-          const m = /^([a-z_]+): ([\s\S]*)$/.exec(body)
-          results.push({ tool, ok: false, error: m ? { code: m[1], message: m[2] } : { code: 'failed', message: body } })
-          if (stopOnError) {
-            stopped = i
-            break
-          }
-        } else {
-          let parsed
-          try {
-            parsed = JSON.parse(body)
-          } catch {
-            parsed = body
-          }
-          results.push({ tool, ok: true, result: parsed })
-        }
-      }
-      return text({ results, ran: results.length, of: calls.length, ...(stopped !== undefined ? { stopped } : {}) }, exact)
-    },
-  })
-
-  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-    const { name, arguments: args } = request.params
-    const mine = own.find((t) => t.name === name)
-    if (mine) return mine.call(args)
-    // Progress lines from the page, for a client that asked for them.
-    const token = request.params._meta?.progressToken
-    let step = 0
-    const onProgress =
-      token === undefined
-        ? undefined
-        : (line) => {
-            extra.sendNotification({ method: 'notifications/progress', params: { progressToken: token, progress: ++step, message: line } }).catch(() => {})
-          }
-    return runPageTool(name, args, onProgress)
-  })
-
-  return server
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// The MCP side: the tools an agent lists and calls. Each of the page's
+// commands is a tool (tools.js); six more are this server's own —
+// scanruler_status, to see whether a ScanRuler page is connected and how to
+// connect one; scanruler_open, to open one in the user's browser, paired;
+// scanruler_wait, to wait for it or for it to be idle; scanruler_batch, to
+// run several of the page's tools in one call; scanruler_write, to write a
+// text file — a report — next to the scan; and scanruler_files, to list
+// what is there. In compact mode, for a model with a small context window,
+// the page's tools are not listed but for those that return a picture,
+// which a batch cannot show — it writes the picture to a file and gives its
+// text: one more of the server's own, scanruler_tools, lists them a line
+// each and gives the definitions of those asked for, and scanruler_batch
+// runs them. Headless (engine.js), the tools are the commands ScanRuler
+// runs in this process with no page, listed in either mode.
+//
+// No call is held past the answer limit (`answerWithinMs`): a client, or a
+// bridge between it and this computer, may cut a call at a minute. A change
+// or a batch still running then answers with its job, and runs on.
+
+import { randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { absolute, agentJson, batchedPicture, fileKind, imageContent, inputFor, replacesSession, saveFileResult, toolFor, toolName, waitIn, withFiles } from './tools.js'
+import { jsonBytes, replyMeasure } from './trace.js'
+
+/** The app's own commands as of this release, so the tools are there before
+ *  a page connects — unless a page has connected before whose list was kept
+ *  (`remembered`) and is no older; a connected page's own list replaces
+ *  either, its plugins' commands included. Kept in step by the app's tests
+ *  (tests/mcpCommands.test.ts), with the app's version and when it was
+ *  written (SNAPSHOT_OF). */
+const SNAPSHOT_FILE = JSON.parse(readFileSync(new URL('./commands.json', import.meta.url), 'utf8'))
+export const SNAPSHOT = Array.isArray(SNAPSHOT_FILE) ? SNAPSHOT_FILE : SNAPSHOT_FILE.commands
+export const SNAPSHOT_OF = { version: SNAPSHOT_FILE.app ?? null, saved: SNAPSHOT_FILE.saved ?? null }
+
+/** -1, 0 or 1 as version `a` is older than, the same as or newer than `b`,
+ *  by their numbers in order — 0.6.10 after 0.6.9. */
+export function compareVersions(a, b) {
+  const pa = String(a).split(/[^0-9]+/).filter(Boolean).map(Number)
+  const pb = String(b).split(/[^0-9]+/).filter(Boolean).map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d) return Math.sign(d)
+  }
+  return 0
+}
+
+/** The list to give before a page connects, from the one kept from the
+ *  last page (`{ commands, version, plugins, saved }`, or a bare list) and
+ *  this server's own: the kept one when it is no older — a page's own,
+ *  plugins included — else this server's, with the kept page's plugins'
+ *  commands, which it lacks. A kept list with no version (a server before
+ *  0.4.0 kept it) is the older; the same version goes by when each was
+ *  written. `from` says which, for the status. */
+export function listBeforePage(kept, snapshot = SNAPSHOT, of = SNAPSHOT_OF) {
+  if (!kept) return null
+  const record = Array.isArray(kept) ? { commands: kept } : kept
+  if (!record.commands?.length) return null
+  const order = record.version && of.version ? compareVersions(record.version, of.version) : record.version ? 1 : -1
+  const keptNewer = order > 0 || (order === 0 && !(record.saved && of.saved && record.saved < of.saved))
+  const page = `ScanRuler ${record.version ?? 'of no version'}`
+  if (keptNewer) return { commands: record.commands, from: `the list kept from the last page that connected (${page})` }
+  // A plugin's commands are under its id (the app's registry); with no
+  // plugins kept, those under a name the app's own list has none of.
+  const namespace = (c) => String(c.name).split('.')[0]
+  const own = new Set(snapshot.map(namespace))
+  const plugin = record.plugins ? (c) => record.plugins.includes(namespace(c)) : (c) => !own.has(namespace(c))
+  const added = record.commands.filter(plugin)
+  const commands = [...snapshot, ...added].sort((a, b) => a.name.localeCompare(b.name))
+  return { commands, from: `this server’s own list (ScanRuler ${of.version ?? 'of no version'}), newer than the one kept from the last page (${page})${added.length ? `, and that page’s plugins’ commands (${added.length})` : ''}` }
+}
+
+/** How the page's commands are listed: `full`, each its own tool, or
+ *  `compact`, read through scanruler_tools. */
+export const TOOL_MODES = ['full', 'compact']
+
+/** The most definitions scanruler_tools gives in one answer: twenty are
+ *  some ten thousand tokens, a small window's fair share. */
+const MAX_DEFINITIONS = 20
+
+const ABOUT = [
+  'These tools drive ScanRuler, a measuring app for 3D scans, in the browser tab the user has open: the user watches every step in the viewport and can undo it there.',
+  'Start with scanruler_status. If no ScanRuler page is connected, call scanruler_open: it opens ScanRuler in the user’s browser, paired with this server, and waits for it. If that leaves it unconnected, tell the user what howToConnect says, then call scanruler_wait.',
+  'Before a task’s first step, read its guide with guide_read — how to measure a scan, model a part or turn a scan into CAD, written for the ScanRuler build connected: guide_read with no topic lists the guides and their sections.',
+]
+const WORKING = [
+  'Read session_state before acting and after: the scan’s bounding box says where the part lies, the elements and dimensions what is measured. Lengths are millimetres, angles degrees; answers give numbers to six significant digits.',
+  'A place on the scan is { point: [x, y, z] } (the nearest scan vertex is taken) or { vertex: n }. To fit a feature, aim at its middle, not at an edge.',
+  'Every tool that changes the session is one step of the undo history; history_undo takes the last back. report_get gives the report as JSON (format "json") or as the text the panel copies (format "text").',
+  'A change, a batch or a long read still running at the server’s answer limit (scanruler_status: server.answerWithin) answers { queued: true, job } and runs on: scanruler_wait { for: "job", job } gives its answer — call it again while it says running.',
+]
+const INSTRUCTIONS = {
+  full: [
+    ...ABOUT,
+    ...WORKING,
+    'view_render shows you the 3D view as a picture; view_set turns it to a standard view or fits it.',
+    'scanruler_batch runs several tools in one call, in order — many scan_nearest or element_fit calls, say — and stops at the first that is refused unless told to go on.',
+  ].join(' '),
+  compact: [
+    ...ABOUT,
+    'ScanRuler’s own tools are not listed one by one, but for those that return a picture. scanruler_tools lists them all, a name and a line each; scanruler_tools with names gives those tools’ full definitions. Read a tool’s definition before its first use, and give it the arguments its inputSchema asks for.',
+    'Run the tools through scanruler_batch — { "calls": [{ "tool": "session_state", "arguments": {} }] }; a single tool is a batch of one, and several run in order. Each result is { tool, ok, result } or { tool, ok: false, error: { code, message } }: the code is the page’s own (invalid_input, no_scan, busy, invalid_state, not_found …) and the message says what was wrong, so retry a refused call with its arguments corrected.',
+    ...WORKING,
+    'The tools that return a picture — view_render, which pictures the 3D view, among them — are listed as tools of their own: call them directly to see the picture. In a batch a picture is not shown: it is written to a file — the call’s path, or a new file in the server’s output folder — and its result says where (file.path). view_set turns the view.',
+  ].join(' '),
+}
+
+/** A command in a line, for scanruler_tools' list: its title, or the first
+ *  sentence of its description. */
+function summary(command) {
+  if (command.title) return command.title
+  const description = String(command.description ?? '').replace(/\s+/g, ' ').trim()
+  return /^.*?[.!?](?= |$)/.exec(description)?.[0] ?? description
+}
+
+/** What the server says it is when it runs ScanRuler itself, headless. */
+const HEADLESS_ABOUT = [
+  'These tools drive ScanRuler headless: the app runs inside this server, with no browser, no scan and no viewport — nobody watches it, and nothing is drawn. scanruler_status says so (backend: "headless").',
+  'Before a task’s first step, read its guide with guide_read — written for this build: guide_read with no topic lists the guides and their sections.',
+]
+const HEADLESS_WORKING = [
+  'Lengths are millimetres, angles degrees; answers give numbers to six significant digits. Every tool that changes the session is one step of the undo history; history_undo takes the last back. Read session_state before acting and after.',
+  'A change or a batch still running at the server’s answer limit (scanruler_status: server.answerWithin) answers { queued: true, job } and runs on: scanruler_wait { for: "job", job } gives its answer.',
+]
+const HEADLESS_INSTRUCTIONS = {
+  full: [
+    ...HEADLESS_ABOUT,
+    'The tools listed are those that run so: modelling solids feature by feature with parameters, describing and checking the bodies, notes, and STEP and STL files read and written on this computer. A tool that needs the page — a scan, a picture, the browser — is not listed, and answers unavailable if called; it needs this server started in page mode, paired with a ScanRuler tab.',
+    ...HEADLESS_WORKING,
+    'scanruler_batch runs several tools in one call, in order, and stops at the first that is refused unless told to go on.',
+  ].join(' '),
+  compact: [
+    ...HEADLESS_ABOUT,
+    'ScanRuler’s tools are those that run so — modelling solids feature by feature with parameters, describing and checking the bodies, notes, and STEP and STL files read and written on this computer — and are not listed one by one. scanruler_tools lists them, a name and a line each; scanruler_tools with names gives those tools’ full definitions. Read a tool’s definition before its first use, and give it the arguments its inputSchema asks for. A tool that needs the page — a scan, a picture, the browser — is not among them, and answers unavailable if called; it needs this server started in page mode, paired with a ScanRuler tab.',
+    'Run the tools through scanruler_batch — { "calls": [{ "tool": "session_state", "arguments": {} }] }; a single tool is a batch of one, and several run in order. Each result is { tool, ok, result } or { tool, ok: false, error: { code, message } }: the message says what was wrong, so retry a refused call with its arguments corrected.',
+    ...HEADLESS_WORKING,
+  ].join(' '),
+}
+
+/** How many jobs the server keeps answers of, the oldest finished let go
+ *  first. */
+const JOBS_KEPT = 50
+
+/** How long the status waits for the page to say what its session holds,
+ *  ms; past it the status goes without. */
+const SESSION_WITHIN_MS = 3_000
+
+/** The kinds of file scanruler_write writes: text, for a report. */
+const TEXT_KINDS = ['.md', '.txt', '.csv', '.json']
+
+/** A change answered directly that took longer than this has likely
+ *  outlived its client's wait (Claude Desktop's is a minute): its answer
+ *  counts as not yet seen, for scanruler_wait { for: "idle" } to give. */
+const SEEN_WITHIN_MS = 55_000
+
+/** How long a call is held before it answers with its job, by default: under
+ *  the minute a client or a bridge may cut it at. */
+export const ANSWER_WITHIN_MS = 45_000
+
+/** How long a batch waits for the page to be idle — before it retries a
+ *  call refused busy, and before it rolls back. */
+const IDLE_WAIT_MS = 60_000
+
+/** How long a listing of the tools waits for a page that connected before
+ *  and is not back yet, ms. */
+const LIST_WAIT_MS = 3_000
+
+/** The most characters an answer carries — some ten thousand tokens. A
+ *  longer one is written to a file in the output folder, and the answer
+ *  says where, how large and what it holds. */
+export const ANSWER_CAP = 40_000
+
+/** How many jobs the status lists besides those running, the newest. */
+const JOBS_LISTED = 5
+
+/** How many folders are kept, the latest first. */
+const FOLDERS_KEPT = 10
+
+/** How many entries scanruler_files lists at most. */
+const FILES_LISTED = 300
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)))
+
+const text = (value, exact = false) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : agentJson(value, exact) }] })
+const failure = (e) => {
+  const code = e?.code ?? 'failed'
+  const message = e?.message ?? String(e)
+  return { ...text(`${code}: ${message}`), isError: true }
+}
+
+/**
+ * @param {{
+ *   link: import('./relay.js').SharedLink | import('./link.js').PageLink,
+ *   version: string,
+ *   cwd: string,
+ *   outDir: string,
+ *   connectHelp: () => string,
+ *   serverInfo: () => Record<string, unknown>,
+ *   pageTimeoutMs?: number,
+ *   remembered?: { load(): unknown[] | null, save(commands: unknown[]): void } | null,
+ *   openPage?: () => Promise<boolean>,
+ *   openGraceMs?: number,
+ *   openWaitMs?: number,
+ *   tools?: 'full' | 'compact',
+ *   trace?: ReturnType<typeof import('./trace.js').createTrace>,
+ *   answerWithinMs?: number,
+ *   folderStore?: { load(): string[] | null, save(folders: string[]): void } | null,
+ *   listWaitMs?: number,
+ *   answerCap?: number,
+ * }} options — `tools` is how the page's commands are listed (TOOL_MODES).
+ *   `listWaitMs`: how long a listing waits for a page that connected before
+ *   and is not back yet. `answerCap`: the most characters an answer
+ *   carries; a longer one goes to a file in `outDir` (ANSWER_CAP).
+ *   `trace`, when given, gets a line per call (trace.js).
+ *   `answerWithinMs` is how long a job's call is held before it answers
+ *   with the job, and the most scanruler_wait waits; 0 holds it to the end.
+ *   `folderStore` keeps the folders scans came from between runs
+ *   (config.js).
+ *   `openPage` opens the pairing link in the user's browser
+ *   (browser.js), true when it could; scanruler_open first gives a tab that
+ *   is already paired `openGraceMs` to connect by itself — the page tries
+ *   again at most ten seconds apart — and then waits `openWaitMs` for the
+ *   one it opened, the user's answer to the browser's question included.
+ *   Both together stay under the minute some clients give a tool call.
+ */
+export function createMcpServer({
+  link,
+  version,
+  cwd,
+  outDir,
+  connectHelp,
+  serverInfo,
+  pageTimeoutMs = 15_000,
+  remembered = null,
+  openPage = async () => false,
+  openGraceMs = 11_000,
+  openWaitMs = 40_000,
+  tools: toolMode = 'full',
+  trace = null,
+  answerWithinMs = ANSWER_WITHIN_MS,
+  folderStore = null,
+  listWaitMs = LIST_WAIT_MS,
+  answerCap = ANSWER_CAP,
+}) {
+  // The most any call is held, ms — Infinity with no limit.
+  const holdMs = answerWithinMs > 0 ? answerWithinMs : Infinity
+  const holdS = answerWithinMs > 0 ? answerWithinMs / 1000 : null
+  const headless = link.backend === 'headless'
+  const compact = toolMode === 'compact'
+  const server = new Server(
+    { name: 'scanruler', title: 'ScanRuler', version },
+    { capabilities: { tools: { listChanged: true } }, instructions: (headless ? HEADLESS_INSTRUCTIONS : INSTRUCTIONS)[compact ? 'compact' : 'full'] },
+  )
+
+  // The last connected page's commands, for listing before a page is back:
+  // a client that lists the tools once — at its start, before the tab has
+  // reconnected — and does not list them again when told they changed
+  // still sees every tool the tab offers.
+  // A server shipped with a newer list than the one kept lists its own: the
+  // kept one may be days old (listBeforePage).
+  let lastPage = listBeforePage(remembered?.load() ?? null)
+  const commands = () => (link.page?.commands?.length ? link.page.commands : lastPage?.commands ?? SNAPSHOT)
+  const remember = () => {
+    const list = link.page?.commands
+    if (!list?.length) return
+    lastPage = { commands: list, from: 'the list kept from the last page that connected' }
+    try {
+      remembered?.save({ commands: list, version: link.page.version ?? null, plugins: link.page.plugins ?? null })
+    } catch {
+      // Not kept: the next run lists the app's own until the page is back.
+    }
+  }
+
+  // ---- jobs ---------------------------------------------------------------
+  // Every call that changes the session is a job, its answer kept: one
+  // started with wait: false answers at once with the job, and one the
+  // client gave up waiting for keeps running and keeps its reply — the
+  // status lists both, and scanruler_wait { for: "job" } gives the answer.
+  // The page keeps what each run under a job did (session.recent), so a
+  // copy of this server started later can still say: a job's name carries
+  // this copy's own mark, and is not taken again by the next.
+  const jobs = new Map()
+  let nextJob = 1
+  const copyMark = randomBytes(3).toString('hex').slice(0, 4)
+  // `ctx` is the call's own, for the trace: the job is named on the call's
+  // line, and one answered before it was done (queued) gets a line when it
+  // is. `run` is handed the job's name, for the page.
+  const startJob = (tool, run, ctx = null, queued = false) => {
+    const job = { job: `j${nextJob++}-${copyMark}`, tool, state: 'running', started: Date.now(), ms: null, reply: null, queued }
+    if (ctx) Object.assign(ctx.fields, { job: job.job, ...(queued ? { queued: true } : {}) })
+    const finished = (reply) => {
+      job.state = reply.isError ? 'failed' : 'done'
+      job.ms = Date.now() - job.started
+      job.reply = reply
+      // Answered to the client: seen, unless queued or likely timed out.
+      job.told = !job.queued && job.ms < SEEN_WITHIN_MS
+      if (job.queued && trace) trace.write({ ev: 'job', job: job.job, call: ctx?.call ?? null, tool, t: job.started, ms: job.ms, ...replyMeasure(reply) })
+      return reply
+    }
+    job.done = Promise.resolve()
+      .then(() => run(job.job))
+      .then(finished, (e) => finished(failure(e)))
+    jobs.set(job.job, job)
+    // The newest kept, but never one still running.
+    for (const [id, j] of jobs) {
+      if (jobs.size <= JOBS_KEPT) break
+      if (j.state !== 'running') jobs.delete(id)
+    }
+    return job
+  }
+  const jobBrief = (j) => ({ job: j.job, tool: j.tool, state: j.state, ...(j.ms !== null ? { ms: j.ms } : { runningMs: Date.now() - j.started }) })
+  /** A job's answer as scanruler_wait gives it: the tool's own answer
+   *  under result, or its refusal under error. */
+  const jobAnswer = (j) => {
+    if (!j.reply) return jobBrief(j)
+    const body = j.reply.content.find((x) => x.type === 'text')?.text ?? ''
+    if (j.reply.isError) {
+      const m = /^([a-z_]+): ([\s\S]*)$/.exec(body)
+      return { ...jobBrief(j), error: m ? { code: m[1], message: m[2] } : { code: 'failed', message: body } }
+    }
+    let result
+    try {
+      result = JSON.parse(body)
+    } catch {
+      result = body
+    }
+    return { ...jobBrief(j), result }
+  }
+
+  /** A job answered at once with its name: wait: false. */
+  const queuedReply = (job) => text({ queued: true, job: job.job, tool: job.tool })
+
+  /** A job's call answered: its reply once done, or — still running at
+   *  the answer limit — its name, as with wait: false. */
+  const answerFor = async (job, ctx) => {
+    if (holdMs === Infinity) return job.done
+    let timer
+    const reply = await Promise.race([job.done, new Promise((r) => (timer = setTimeout(() => r(null), holdMs)))])
+    clearTimeout(timer)
+    if (reply) return reply
+    job.queued = true
+    if (ctx) ctx.fields.queued = true
+    return text({
+      queued: true,
+      job: job.job,
+      tool: job.tool,
+      after: holdS,
+      note: `Still running after ${holdS} s, and running on. scanruler_wait { for: "job", job: "${job.job}" } gives its answer — call it again while it says running.`,
+    })
+  }
+
+  /** Whether the page is done with what it is busy with — polled until
+   *  `until` (ms since the epoch). A page that does not say is taken as
+   *  idle. */
+  const pageIdle = async (until) => {
+    for (;;) {
+      const state = await link.run('session.state', {}).catch(() => null)
+      if (!state || typeof state !== 'object' || (state.busy == null && state.running == null)) return true
+      if (Date.now() >= until) return false
+      await sleep(Math.min(500, until - Date.now()))
+    }
+  }
+
+  /** What the page says was run under a job this copy does not know — one
+   *  of a copy before it — waiting while a run under it goes on, until
+   *  `until`. Null when the page has nothing under it, or cannot say. */
+  const jobFromPage = async (job, until) => {
+    if (headless || !link.connected) return null
+    for (;;) {
+      let outcomes
+      try {
+        outcomes = (await link.run('session.recent', { job, limit: 100 }))?.outcomes
+      } catch {
+        return null
+      }
+      if (!Array.isArray(outcomes) || outcomes.length === 0) return null
+      const running = outcomes.some((o) => o.state === 'running')
+      if (!running || Date.now() >= until) return pageJobAnswer(job, outcomes.slice().reverse(), running)
+      await sleep(Math.min(1000, until - Date.now()))
+    }
+  }
+  /** The page's record of a job, in run order, as scanruler_wait gives it:
+   *  a single run as a job's answer, several — a batch — as calls. */
+  const pageJobAnswer = (job, runs, running) => {
+    const calls = runs.map((o) => ({
+      tool: toolName({ name: String(o.name) }),
+      state: o.state,
+      ms: o.ms,
+      ...(o.result !== undefined ? { result: o.result } : {}),
+      ...(o.resultOmitted ? { resultOmitted: o.resultOmitted } : {}),
+      ...(o.error ? { error: o.error } : {}),
+    }))
+    const from = `the page (session.recent): this server copy, started at ${startedAt}, did not start ${job}; the page kept what was run under it.`
+    if (calls.length === 1) return { job, ...calls[0], from }
+    return {
+      job,
+      state: running ? 'running' : 'ended',
+      calls,
+      from,
+      note: 'A batch’s own answer — its results in full, what it undid — belonged to the server copy that ran it. These are the page’s commands under the job, in order; a batch stopped part way shows only those it ran. Read session_state for where the session stands.',
+    }
+  }
+
+  /** Whether the tab is hidden now — null with no page, or headless. */
+  const hiddenNow = () => (link.connected && link.page && !headless ? (link.page.hidden ?? false) : null)
+  const runningJobs = () => [...jobs.values()].filter((j) => j.state === 'running').length
+
+  /** A finished job as scanruler_wait { for: "idle" } lists it: a failed
+   *  one with its error, a batch with the call it stopped at. */
+  const finishedOut = (j) => {
+    const answer = jobAnswer(j)
+    if (j.state === 'failed') return { ...jobBrief(j), error: answer.error }
+    const failed = j.tool === 'scanruler_batch' ? answer.result?.failed : undefined
+    return { ...jobBrief(j), ...(failed ? { failed } : {}) }
+  }
+
+  // Since when this copy of the server keeps jobs: one asked of a copy
+  // before it — another process, or this one restarted — is not known here.
+  const startedAt = new Date().toISOString()
+  const noJobs = `None asked of this server copy, which started at ${startedAt}. A change asked of an earlier copy is not known here: session_state says what the page holds.`
+
+  /** What the page's session holds, in brief, for the status: the scan,
+   *  the project's name, whether it has unsaved changes, and its work
+   *  counted — read off session.state, and left out when the page does not
+   *  answer soon. */
+  const sessionBrief = async () => {
+    if (!link.connected) return {}
+    let timer
+    const state = await Promise.race([
+      link.run('session.state', {}).catch(() => null),
+      new Promise((r) => (timer = setTimeout(() => r(null), SESSION_WITHIN_MS))),
+    ])
+    clearTimeout(timer)
+    if (!state || typeof state !== 'object') return {}
+    const project = state.project ?? {}
+    return {
+      session: {
+        scan: state.scan?.fileName ?? null,
+        ...(project.name ? { project: project.name } : {}),
+        unsaved: project.unsaved ?? null,
+        ...(project.holds ?? {}),
+      },
+      // The page's word that this server is older than its commands assume.
+      ...(typeof state.serverTooOld === 'string' ? { serverTooOld: state.serverTooOld } : {}),
+    }
+  }
+
+  // ---- answers that fit -----------------------------------------------------
+  // An answer past answerCap — a read with every point in it, a batch of
+  // many — would crowd out the agent's context: it is written whole to a
+  // file in outDir, and the answer says where, how large and what it holds.
+  /** `value` as an answer gives it: itself, or — its JSON past the cap —
+   *  `{ truncated, file, bytes, keys, brief }`, brief its short fields and
+   *  those named in `keep`. `tool` names the file. A file that cannot be
+   *  written leaves the answer whole. */
+  const fitted = async (value, tool, exact = false, keep = []) => {
+    const body = agentJson(value, exact)
+    if (body.length <= answerCap) return value
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    let file = join(outDir, `${tool}-${stamp}.json`)
+    try {
+      for (let n = 2; await stat(file).catch(() => null); n++) file = join(outDir, `${tool}-${stamp}-${n}.json`)
+      await mkdir(outDir, { recursive: true })
+      await writeFile(file, body, 'utf8')
+    } catch {
+      return value
+    }
+    const object = value !== null && typeof value === 'object' && !Array.isArray(value)
+    const short = (k, v) => keep.includes(k) || v === null || typeof v === 'number' || typeof v === 'boolean' || (typeof v === 'string' && v.length <= 200)
+    const brief = object ? Object.fromEntries(Object.entries(value).filter(([k, v]) => short(k, v))) : {}
+    return {
+      truncated: true,
+      file,
+      bytes: Buffer.byteLength(body, 'utf8'),
+      ...(object ? { keys: Object.keys(value) } : Array.isArray(value) ? { items: value.length } : {}),
+      ...(Object.keys(brief).length ? { brief } : {}),
+      note: `The answer is ${Math.round(body.length / 1000)} k characters, past the ${Math.round(answerCap / 1000)} k an answer carries, so it was written whole to file as JSON: read what you need from there, or ask for less next time (fields, limit).`,
+    }
+  }
+
+  // ---- folders -------------------------------------------------------------
+  // The folders this server opened a scan or a project from, or saved one
+  // into, the latest first: where scanruler_write may write and what
+  // scanruler_files lists. Kept beside the command list (folderStore), so a
+  // copy started afresh — or the other copy beside this one — has them too.
+  let folders = []
+  const knownFolders = () => {
+    try {
+      const kept = folderStore?.load()
+      if (kept) folders = kept
+    } catch {
+      // Not read: this copy's own list stands.
+    }
+    return folders
+  }
+  const rememberFolder = (file) => {
+    const folder = dirname(file)
+    folders = [folder, ...knownFolders().filter((f) => f !== folder)].slice(0, FOLDERS_KEPT)
+    try {
+      folderStore?.save(folders)
+    } catch {
+      // Not kept: this copy still has it.
+    }
+  }
+
+  /** The jobs as the status lists them, newest first: every one running
+   *  and the newest JOBS_LISTED others; jobsMore counts the rest kept. */
+  const jobsListed = () => {
+    const newest = [...jobs.values()].reverse()
+    let others = 0
+    const listed = newest.filter((j) => j.state === 'running' || others++ < JOBS_LISTED)
+    const more = newest.length - listed.length
+    return { jobs: listed.map(jobBrief), ...(more > 0 ? { jobsMore: more } : {}) }
+  }
+
+  const status = () => ({
+    backend: headless ? 'headless' : 'page',
+    connected: link.connected,
+    page: link.page
+      ? {
+          app: link.page.app,
+          version: link.page.version,
+          origin: link.page.origin,
+          plugins: link.page.plugins ?? [],
+          viewport: link.page.viewport ?? null,
+          hidden: link.page.hidden ?? null,
+          commands: link.page.commands.length,
+        }
+      : null,
+    server: { ...serverInfo(), answerWithin: holdS },
+    ...(link.connected || headless ? {} : { howToConnect: connectHelp() }),
+    ...(link.page?.hidden ? { hiddenNote: 'The ScanRuler tab is hidden — in the background, its window covered or minimised, or the screen locked. Changes still run; pictures and anything that waits on the screen are slower, and a browser that unloads background tabs (Chrome’s Memory Saver) may close it: add the site to "Always keep these sites active".' } : {}),
+    ...(jobs.size > 0 ? jobsListed() : { jobsNote: noJobs }),
+    ...(!headless && knownFolders().length ? { folders: knownFolders() } : {}),
+    ...staleTools(),
+  })
+
+  const own = [
+    {
+      name: 'scanruler_status',
+      title: 'ScanRuler connection status',
+      description: 'Whether a ScanRuler page is connected to this agent, which version and plugins it has, whether its tab is hidden (page.hidden), and — when none is — how the user connects one. session, with a page, says what it holds: the scan, the project’s name, whether it has changes not saved (unsaved), and its work counted — elements, features, notes … — so a session someone else left is seen before it is replaced (scan_open with saveTo keeps it). backend says whether ScanRuler runs in a tab (page) or in this server (headless). jobs lists the calls that change the session still running and the latest five others, newest first, each running, done or failed — a call whose answer you did not get is among them; scanruler_wait { for: "job", job } gives its answer, also for a job of an earlier copy of this server, which the page remembers; jobsMore counts the older ones kept. folders: where a scan or a project was opened from or saved into, the latest first — what scanruler_write writes into and scanruler_files lists; kept when the server restarts. server.answerWithin: the seconds a call is held at most before it answers with its job. server.version is this server’s, server.latest the newest on npm when known, server.handedOffFrom the older copy that started this one in its place. serverTooOld, when there, says this server is older than the page needs: tell the person once, in its words, and install nothing yourself. tools, when there, says the tools you were given are not the ones the page offers now (stale): which were added, removed or changed — named the first time, counted after — and which page they were listed from.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: async () => text({ ...status(), ...(await sessionBrief()) }),
+    },
+    {
+      name: 'scanruler_open',
+      title: 'Open ScanRuler',
+      description: 'Open ScanRuler in the user’s default browser, paired with this server, and wait for the page to connect — for when scanruler_status says none is. The first time, the browser asks the user whether the site may reach apps on this computer; they must allow it. Returns the status, with opened: whether the browser was asked to open it. If connected is still false, tell the user what howToConnect says.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: false, openWorldHint: false },
+      call: async () => {
+        if (headless) return text({ ...status(), opened: false, note: 'This server runs ScanRuler headless, in this process: there is no page to open.' })
+        // A tab that was paired before is likely open and on its way back.
+        if (link.connected || (await link.waitForPage(openGraceMs))) return text({ ...status(), opened: false })
+        const opened = await openPage().catch(() => false)
+        // Within the answer limit, with a little to spare for the answer.
+        if (opened) await link.waitForPage(Math.max(1_000, Math.min(openWaitMs, holdMs - openGraceMs - 2_000)))
+        return text({ ...status(), opened })
+      },
+    },
+    {
+      name: 'scanruler_wait',
+      title: 'Wait for ScanRuler',
+      description: `Wait until a ScanRuler page is connected (for: "page", the default), or until it is also done with what it is busy with and every change still running has finished (for: "idle" — then finished lists the changes done or failed since the last such answer, a failed one with its error, and state says idle or running), or until a job is done (for: "job" with job — a call started with wait: false, one answered queued, or one whose answer did not come; scanruler_status lists them). Returns the status — for idle only connected, state and finished — or for a job its answer: { job, tool, state, ms, result } or { …, error: { code, message } } — state running if the time ran out first: call it again. A job of an earlier copy of this server is read from the page's record of it (session.recent), from says so.${holdS ? ` It waits ${holdS} s at most, this server's answer limit, whatever timeoutSeconds says.` : ''} connected is false if the time ran out waiting for a page.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          for: { type: 'string', enum: ['page', 'idle', 'job'], description: 'page (the default), idle, or job.' },
+          job: { type: 'string', minLength: 1, description: 'The job to wait for, with for: "job" — as a call with wait: false, a queued answer or scanruler_status gave it.' },
+          timeoutSeconds: { type: 'number', exclusiveMinimum: 0, maximum: 600, description: `How long to wait at most, seconds — 120 by default${holdS ? `, and never past ${holdS}` : ''}.` },
+        },
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: async (args, ctx) => {
+        if (ctx) ctx.fields.wait = args?.for ?? (args?.job !== undefined ? 'job' : 'page')
+        // Never held past the answer limit: a cut call says nothing.
+        const until = Date.now() + Math.min(1000 * (args?.timeoutSeconds ?? 120), holdMs)
+        if (args?.for === 'job' || args?.job !== undefined) {
+          const id = String(args?.job ?? '')
+          const j = jobs.get(id)
+          if (!j) {
+            const kept = id ? await jobFromPage(id, until) : null
+            if (kept) return text(await fitted(kept, 'scanruler_wait'))
+            return failure({ code: 'not_found', message: `There is no job "${id}" — scanruler_status lists the latest. This server copy started at ${startedAt}; a job of an earlier one is not known here, nor did the page keep it (session_recent), so session_state says whether its change was made.` })
+          }
+          let timer
+          await Promise.race([j.done, new Promise((r) => (timer = setTimeout(r, Math.max(0, until - Date.now()))))])
+          clearTimeout(timer)
+          if (j.state !== 'running') j.told = true
+          return text(await fitted(jobAnswer(j), 'scanruler_wait'))
+        }
+        if (!(await link.waitForPage(Math.max(0, until - Date.now())))) return text(status())
+        if (args?.for === 'idle') {
+          // The changes still running first — their answers are what idle
+          // waits for — then the page's own work.
+          for (const j of [...jobs.values()].filter((x) => x.state === 'running')) {
+            let timer
+            await Promise.race([j.done, new Promise((r) => (timer = setTimeout(r, Math.max(0, until - Date.now()))))])
+            clearTimeout(timer)
+          }
+          const idle = (await pageIdle(until)) && runningJobs() === 0
+          // What finished since it was last said: each job once, a failed
+          // one with its error.
+          const finished = [...jobs.values()].filter((j) => j.state !== 'running' && !j.told)
+          for (const j of finished) j.told = true
+          // The state and what finished, not the whole status: an agent
+          // waits for idle many times in a run.
+          return text({ connected: link.connected, state: idle ? 'idle' : 'running', finished: finished.map(finishedOut), ...(hiddenNow() ? { hidden: true } : {}), ...staleTools() })
+        }
+        return text(status())
+      },
+    },
+  ]
+
+  // A report beside the scan, written by this server: no grant of the
+  // browser's to save a file, and nowhere but the scan's folder.
+  if (!headless) {
+    own.push({
+      name: 'scanruler_write',
+      title: 'Write a text file beside the scan',
+      description: `Write a text file — a report, notes, a table of readings — next to the scan, as UTF-8: ${TEXT_KINDS.join(', ')} only, and only inside the folder this server last opened a scan or a project from (scan_open, project_load) or saved one into (saveTo), or a folder under it. A relative path is taken in that folder; an absolute one must lie in one of those folders, and a path may not climb out with "..". A file already there is replaced. Returns its path and size in bytes. Refused while this server has opened no scan or project from a folder — then open the scan with scan_open first, or write the file yourself.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', minLength: 1, description: `The file: a name in the scan’s folder ("report.md"), a path under it ("report/sigma.md"), or an absolute path in it — ${TEXT_KINDS.join(', ')}.` },
+          text: { type: 'string', description: 'What the file holds, as text.' },
+        },
+        required: ['path', 'text'],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: false, openWorldHint: false },
+      call: async (args) => {
+        try {
+          return text(await writeText(args?.path, args?.text))
+        } catch (e) {
+          return failure(e)
+        }
+      },
+    })
+    own.push({
+      name: 'scanruler_files',
+      title: 'List the files beside the scan',
+      description: `The files in the folder this server last opened a scan or a project from, or saved one into — kept when the server restarts — or in a folder under it (path): each file's name, size in bytes and kind (mesh, project, step, picture, drawing, text or other), newest first, and the folders in it. Where scanruler_write's reports and the files saved beside the scan are; up to ${FILES_LISTED} entries. Refused while no scan or project has been opened from a folder.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', minLength: 1, description: 'A folder under the scan’s folder, relative to it or absolute; or one of the folders scanruler_status lists. Leave out for the scan’s folder.' },
+        },
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: async (args) => {
+        try {
+          return text(await listFiles(args?.path))
+        } catch (e) {
+          return failure(e)
+        }
+      },
+    })
+  }
+
+  /** scanruler_files' list — see its description. */
+  const listFiles = async (path) => {
+    const folders = knownFolders()
+    if (folders.length === 0) {
+      throw { code: 'invalid_state', message: 'This server has opened no scan or project from a folder, so it has none to list. Open the scan with scan_open (or a project with project_load) by its path first.' }
+    }
+    if (typeof path === 'string' && path.split(/[\\/]/).includes('..')) throw { code: 'invalid_input', message: 'path: ".." is not taken — give a folder in the scan’s folder or under it.' }
+    const folder = typeof path === 'string' && path ? (isAbsolute(path) ? resolve(path) : resolve(folders[0], path)) : folders[0]
+    const within = (f) => {
+      const r = relative(f, folder)
+      return r === '' || (!r.startsWith('..') && !isAbsolute(r))
+    }
+    if (!folders.some(within)) throw { code: 'invalid_input', message: `path: ${folder} is outside the folders a scan or a project was opened from — ${folders.join(', ')}.` }
+    let entries
+    try {
+      entries = await readdir(folder, { withFileTypes: true })
+    } catch (e) {
+      throw { code: 'not_found', message: `${folder} could not be read: ${e?.code === 'ENOENT' ? 'there is no such folder' : (e?.message ?? String(e))}.` }
+    }
+    const files = []
+    const subfolders = []
+    for (const entry of entries) {
+      if (entry.isDirectory()) subfolders.push(entry.name)
+      else if (entry.isFile()) {
+        const info = await stat(join(folder, entry.name)).catch(() => null)
+        if (info) files.push({ name: entry.name, size: info.size, kind: fileKind(entry.name), modified: info.mtime.toISOString() })
+      }
+    }
+    files.sort((a, b) => b.modified.localeCompare(a.modified))
+    const listed = files.slice(0, FILES_LISTED)
+    return {
+      folder,
+      files: listed,
+      folders: subfolders.slice(0, FILES_LISTED),
+      ...(files.length > listed.length ? { more: files.length - listed.length } : {}),
+    }
+  }
+
+  /** scanruler_write's file, kept to the folders a scan or a project came
+   *  from — see its description. */
+  const writeText = async (path, body) => {
+    if (typeof path !== 'string' || path.length === 0) throw { code: 'invalid_input', message: 'path: give the file to write.' }
+    if (typeof body !== 'string') throw { code: 'invalid_input', message: 'text: give what the file holds, as a string.' }
+    const kind = extname(path).toLowerCase()
+    if (!TEXT_KINDS.includes(kind)) throw { code: 'invalid_input', message: `path: only ${TEXT_KINDS.join(', ')} files are written — not "${kind || 'no extension'}".` }
+    if (path.split(/[\\/]/).includes('..')) throw { code: 'invalid_input', message: 'path: ".." is not taken — give a path in the scan’s folder or under it.' }
+    const folders = knownFolders()
+    if (folders.length === 0) {
+      throw { code: 'invalid_state', message: 'This server has opened no scan or project from a folder, so it has none to write into. Open the scan with scan_open (or a project with project_load) by its path first — its folder is where the file goes — or write the file yourself.' }
+    }
+    const target = isAbsolute(path) ? resolve(path) : resolve(folders[0], path)
+    const inside = (folder) => {
+      const r = relative(folder, target)
+      return r !== '' && !r.startsWith('..') && !isAbsolute(r)
+    }
+    if (!folders.some(inside)) {
+      throw { code: 'invalid_input', message: `path: ${target} is outside the folders a scan or a project was opened from — ${folders.join(', ')}. Give a path in one of them.` }
+    }
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, body, 'utf8')
+    return { path: target, size: Buffer.byteLength(body, 'utf8') }
+  }
+
+  // What the client was given at its last list: each tool's definition by
+  // name, and the page the list came from.
+  let listed = null
+  let listedFrom = null
+  const definition = ({ call: _call, ...tool }) => tool
+  // Compact, the list is the server's own tools and the page's that return
+  // a picture — a batch gives a picture as its text and a file, so those are called
+  // directly; scanruler_tools reads commands() when it is called.
+  const shown = (c) => !compact || Boolean(c.returnsImage)
+  const listNow = () => [...own.map(definition), ...commands().filter(shown).map((c) => toolFor(c, { outDir }))]
+  const listSource = () =>
+    link.page?.commands?.length ? `the page, ScanRuler ${link.page.version ?? 'of no version'}` : lastPage ? lastPage.from : `this server’s own list (scanruler-mcp ${version})`
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    // A tab that was paired before is likely open and on its way back: a
+    // client that lists once, at its start, gets its list if it comes soon.
+    if (!headless && !link.connected && lastPage && listWaitMs > 0) await link.waitForPage(listWaitMs)
+    const tools = listNow()
+    listed = new Map(tools.map((t) => [t.name, JSON.stringify(t)]))
+    listedFrom = listSource()
+    staleNamed = null
+    trace?.write({ ev: 'list', t: trace.now(), tools: tools.length, bytes: Buffer.byteLength(JSON.stringify(tools), 'utf8') })
+    return { tools }
+  })
+
+  /** How the tools now differ from those listed: added, removed, and
+   *  changed — the same name, another input or description. Null when
+   *  nothing was listed yet. */
+  const listDiff = () => {
+    if (!listed) return null
+    const now = new Map(listNow().map((t) => [t.name, JSON.stringify(t)]))
+    const added = [...now.keys()].filter((n) => !listed.has(n))
+    const removed = [...listed.keys()].filter((n) => !now.has(n))
+    const changed = [...now.keys()].filter((n) => listed.has(n) && listed.get(n) !== now.get(n))
+    return { now: now.size, added, removed, changed, any: added.length + removed.length + changed.length > 0 }
+  }
+
+  // A page with other commands than were listed — plugins, another version,
+  // a command whose input or description changed — has the client list them
+  // again.
+  const relist = () => {
+    if (listDiff()?.any) server.sendToolListChanged().catch(() => {})
+  }
+  // A client told the list changed may not list it again — Claude Desktop
+  // runs two copies of the server, and the chat's may keep the list it got
+  // at its start: the status says so, with what was added, taken away and
+  // changed, and which page the list came from — the names once for each
+  // difference, counted in every answer after it.
+  let staleNamed = null
+  function staleTools() {
+    const diff = listDiff()
+    if (!diff?.any) return {}
+    const key = JSON.stringify([diff.added, diff.removed, diff.changed])
+    const named = staleNamed !== key
+    staleNamed = key
+    const names = (list) => (named ? list : list.length)
+    return {
+      tools: {
+        stale: true,
+        listed: listed.size,
+        now: diff.now,
+        ...(diff.added.length ? { added: names(diff.added) } : {}),
+        ...(diff.removed.length ? { removed: names(diff.removed) } : {}),
+        ...(diff.changed.length ? { changed: names(diff.changed) } : {}),
+        listedFrom,
+        note: named
+          ? 'The tools this chat was given are not the ones the ScanRuler page offers now — it changed since they were listed, and the client did not list them again. A tool or field missing from them may be there now: start a new chat to get the current tools; meanwhile scanruler_batch runs any of the page’s tools by name, and a changed tool takes what the page’s command takes now.'
+          : 'Still stale, as an earlier answer named them: scanruler_batch runs any of the page’s tools by name.',
+      },
+    }
+  }
+  for (const event of ['connected', 'commands']) {
+    link.on(event, () => {
+      remember()
+      relist()
+    })
+  }
+
+  /** One of the page's tools run on the page: the result as MCP content,
+   *  or a failure. `batched`: a picture is written to a file — the call's
+   *  path or a new one in outDir — and given as its text, not shown. `job`:
+   *  the job the call is part of, which the page keeps its outcome under.
+   *  `deferred`: more changes follow straight after it (a batch with
+   *  build: "end"), and the page may leave their rebuild to the last.
+   *  A `{ "$file": path }` anywhere in the arguments is that file's JSON. */
+  const runPageTool = async (name, given, onProgress, { timings = false, ms = false, batched = false, job, deferred = false } = {}) => {
+    const command = commands().find((c) => toolName(c) === name)
+    const needsPage = !command && headless ? link.pageCommand(name) : null
+    if (needsPage) return failure({ code: 'unavailable', message: `${name} needs the ScanRuler page — a scan, the viewport or the browser — and this server runs ScanRuler headless, with none. Start scanruler-mcp in page mode (without --engine or --headless) and pair it with a ScanRuler tab for it.` })
+    if (!command) return failure({ code: 'unknown_command', message: `There is no tool ${name}.` })
+    if (!link.connected && !(await link.waitForPage(pageTimeoutMs))) {
+      return failure({ code: 'unavailable', message: `No ScanRuler page is connected; scanruler_open opens one. ${connectHelp()}` })
+    }
+    try {
+      const args = await withFiles(given ?? {}, cwd)
+      const { input, binaryKey, file } = await inputFor(command, args, { cwd })
+      // A session kept before it is replaced: saved, then let go.
+      const savedTo = replacesSession(command) && args?.saveTo !== undefined ? await saveSession(String(args.saveTo), job) : undefined
+      if (savedTo !== undefined) input.discard = true
+      const started = Date.now()
+      let result = await link.run(command.name, input, binaryKey, onProgress, job, deferred)
+      // The folder a scan or a project was opened from, for scanruler_write.
+      if (binaryKey && replacesSession(command) && file) rememberFolder(file)
+      if (savedTo !== undefined && result && typeof result === 'object' && !Array.isArray(result)) result = { ...result, savedTo }
+      if (ms && result && typeof result === 'object' && !Array.isArray(result)) result = { ...result, ms: Date.now() - started }
+      const image = command.returnsImage && !batched ? await imageContent(result, args, { cwd, outDir }) : null
+      if (image) return { content: image }
+      // Which steps a change's build played, and how long each took, only
+      // for a batch asked for its timings.
+      if (!timings && result?.steps?.played) {
+        const { played: _played, ...steps } = result.steps
+        result = { ...result, steps }
+      }
+      const saved = command.returnsImage && batched ? await batchedPicture(result, args, { cwd, outDir }) : await saveFileResult(result, args, { cwd, outDir })
+      return text(await fitted(saved, name, Boolean(command.exact)), Boolean(command.exact))
+    } catch (e) {
+      return failure(e)
+    }
+  }
+
+  /** The session saved as a project file at `path` (a file, or a folder
+   *  for its own name): where it went, or null when the session held
+   *  nothing to save. Throws, saving nothing, when the save fails. */
+  const saveSession = async (path, job) => {
+    let result
+    try {
+      result = await link.run('project.save', {}, undefined, undefined, job)
+    } catch (e) {
+      if (/nothing to save/i.test(e?.message ?? '')) return null
+      throw { code: e?.code ?? 'failed', message: `Nothing was replaced: the session could not be saved first — ${e?.message ?? String(e)}` }
+    }
+    const written = await saveFileResult(result, { path }, { cwd, outDir })
+    if (!written?.file?.path) throw { code: 'failed', message: 'Nothing was replaced: project.save gave no file to save.' }
+    rememberFolder(written.file.path)
+    return written.file.path
+  }
+
+  // Several of the page's tools in one call — what cuts a run of twenty
+  // scan_nearest calls to one round trip. Each answer is the tool's own; a
+  // picture comes back as the text beside it, not as an image, and is
+  // written to a file — the call's path, or a new one in outDir — which the
+  // text names.
+  own.push({
+    name: 'scanruler_batch',
+    title: 'Run several ScanRuler tools',
+    description:
+      `Run several of the ScanRuler tools in one call, in order, each with its own arguments — a run of scan_nearest, element_fit or section_get calls, say. Returns results, one per call in order: { tool, ok, result } or { tool, ok: false, error: { code, message } }. The first refused stops the rest (stopped says which index, failed: { index, tool, error } which call) unless stopOnError is false. When the refused call is a change, then with rollback (the default) every change the batch made before it is undone, so the batch stands or falls whole: undone names the steps taken back, newest first. A refused read — section_get, scan_query, any tool that changes nothing — undoes nothing: what came before it stands (kept says so). A call refused busy is run again once the page is idle (retried: "busy" on its result). Each call that changes the session is still its own undo step. build: "end" builds a modelled part once for a run of changes to it — sketches edited one after another, say — rather than after each: every call but the last is sent deferred, and a change so sent answers before its rebuild (build: "held", its result and bodies the part as last built; a pick by index names a face of that part); the last call builds them all, and so does a read of the part, or any other kind of tool, met on the way. timings: true gives each call its ms and the batch total_ms, and a change\'s build the steps it played with their ms (result.steps.played). wait: false answers at once with { queued, job }, and so does a batch still running at the server’s answer limit (with after, its seconds); scanruler_wait { for: "job", job } gives the batch\'s answer. A { "$file": path } anywhere in a call’s arguments is that JSON file’s contents. A tool that returns a picture is not shown here: the picture is written to a file — its call’s path, or a new file in ${outDir} — and its result gives that file.path; call the tool directly to see the picture. The server’s own tools (scanruler_status, _open, _wait, _batch, _write, _files, _tools) cannot be batched.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calls: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 200,
+          description: 'The calls, in order — or give file instead.',
+          items: {
+            type: 'object',
+            properties: {
+              tool: { type: 'string', minLength: 1, description: 'A tool’s name, as listed — scan_nearest, element_fit.' },
+              arguments: { type: 'object', description: 'Its arguments, as the tool takes them; {} for none.' },
+            },
+            required: ['tool'],
+            additionalProperties: false,
+          },
+        },
+        file: { type: 'string', minLength: 1, description: `A JSON file of the calls, read here in place of calls: [{ tool, arguments }], or [{ name, input }] by the command's own name (scan.open), or either under "calls" or "steps". For a long run a script wrote, which then need not pass through the conversation. A relative path is taken from ${cwd}.` },
+        stopOnError: { type: 'boolean', description: 'Stop at the first refused call (the default), or run every call and report each.' },
+        rollback: { type: 'boolean', description: 'When the batch stops at a refused change, undo what it changed before it (the default) — or leave those changes standing (false). A refused read undoes nothing either way.' },
+        build: { type: 'string', enum: ['each', 'end'], description: 'each (the default): a change rebuilds the part before it answers. end: the changes build once, at the last call.' },
+        timings: { type: 'boolean', description: 'Each call’s ms, the batch’s total_ms, and the steps a change’s build played with their ms.' },
+        wait: waitIn,
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: false },
+    call: async (args, ctx) => {
+      let calls = Array.isArray(args?.calls) ? args.calls : []
+      if (args?.file !== undefined) {
+        if (calls.length > 0) return failure({ code: 'invalid_input', message: 'Give calls or file, not both.' })
+        const read = await callsFromFile(String(args.file))
+        if (read.error) return failure({ code: 'invalid_input', message: read.error })
+        calls = read.calls
+      }
+      if (calls.length === 0) return failure({ code: 'invalid_input', message: 'calls: give at least one call (or a file of them).' })
+      if (ctx) ctx.fields.calls = calls.length
+      const job = startJob('scanruler_batch', (id) => runBatch(calls, args, ctx, id), ctx, args?.wait === false)
+      return args?.wait === false ? queuedReply(job) : answerFor(job, ctx)
+    },
+  })
+
+  /** A batch's calls read from a JSON file — { tool, arguments } as the
+   *  batch takes them, or { name, input } by the command's own name, a
+   *  list or one under "calls" or "steps". */
+  const callsFromFile = async (file) => {
+    const path = absolute(file, cwd)
+    let data
+    try {
+      data = JSON.parse(await readFile(path, 'utf8'))
+    } catch (e) {
+      return { error: `file: ${path} could not be read as JSON (${e instanceof Error ? e.message : String(e)}).` }
+    }
+    const list = Array.isArray(data) ? data : Array.isArray(data?.calls) ? data.calls : Array.isArray(data?.steps) ? data.steps : null
+    if (!list) return { error: `file: ${path} holds no list of calls — a list, or one under "calls" or "steps".` }
+    const calls = list.map((c) => (c && typeof c === 'object' && typeof c.name === 'string' && c.tool === undefined ? { tool: toolName({ name: c.name }), arguments: c.input ?? {} } : c))
+    if (calls.some((c) => !c || typeof c !== 'object' || typeof c.tool !== 'string')) return { error: `file: every call in ${path} needs a tool (or a name).` }
+    return { calls }
+  }
+
+  /** The batch's calls run in order — see scanruler_batch. `job` is the
+   *  batch's, sent with each of its calls for the page to keep. */
+  const runBatch = async (calls, args, ctx = null, job = undefined) => {
+    const stopOnError = args?.stopOnError !== false
+    const timings = args?.timings === true
+    // Built at the end: every call but the last sent deferred.
+    const atEnd = args?.build === 'end'
+    let lastDeferred = false
+    const commandOf = (tool) => commands().find((x) => toolName(x) === tool)
+    const changes = (tool) => Boolean(commandOf(tool)) && !commandOf(tool).readOnly
+    // Where the history stood, to go back to when a change is refused —
+    // only when a call may change something, and a page that cannot mark
+    // its history simply has its batch left as it went.
+    let checkpoint = null
+    if (args?.rollback !== false && stopOnError && calls.some((c) => changes(String(c?.tool ?? '')))) {
+      checkpoint = await link
+        .run('history.checkpoint', {}, undefined, undefined, job)
+        .then((r) => r?.checkpoint ?? null)
+        .catch(() => null)
+    }
+    const results = []
+    let stopped
+    let failed
+    // A batch holding an exact answer (a plane's frame, say) keeps
+    // every answer exact: the rounding is one pass over the whole.
+    let exact = false
+    const started = Date.now()
+    const errorOf = (reply) => {
+      const body = reply.content.find((x) => x.type === 'text')?.text ?? ''
+      const m = /^([a-z_]+): ([\s\S]*)$/.exec(body)
+      return m ? { code: m[1], message: m[2] } : { code: 'failed', message: body }
+    }
+    for (let i = 0; i < calls.length; i++) {
+      const c = calls[i] ?? {}
+      const tool = String(c.tool ?? '')
+      const at = Date.now()
+      const { wait: _wait, timings: _timings, ...callArgs } = c.arguments ?? {}
+      const hiddenAt = hiddenNow()
+      const deferred = atEnd && i < calls.length - 1
+      lastDeferred = deferred
+      const run = () => runPageTool(tool, callArgs, undefined, { timings, batched: true, job, deferred })
+      let one = own.some((t) => t.name === tool) ? failure({ code: 'invalid_input', message: `${tool} is the server’s own and is not batched — call it on its own.` }) : await run()
+      // Busy with something of the page's own — a map being worked out,
+      // say: once it is idle, the call is run again, once.
+      let retried
+      if (one.isError && errorOf(one).code === 'busy' && commandOf(tool)) {
+        await pageIdle(Date.now() + IDLE_WAIT_MS)
+        one = await run()
+        retried = 'busy'
+      }
+      if (ctx && trace) {
+        trace.write({ ev: 'entry', call: ctx.call, index: i, t: at, tool, ms: Date.now() - at, in: jsonBytes(callArgs), ...replyMeasure(one), hidden: [hiddenAt, hiddenNow()], ...(retried ? { retried } : {}), ...(trace.args ? { args: callArgs } : {}) })
+      }
+      const ms = timings ? { ms: Date.now() - at } : {}
+      const again = retried ? { retried } : {}
+      if (!one.isError && commandOf(tool)?.exact) exact = true
+      if (one.isError) {
+        const error = errorOf(one)
+        results.push({ tool, ok: false, error, ...again, ...ms })
+        if (stopOnError) {
+          stopped = i
+          failed = { index: i, tool, error }
+          break
+        }
+      } else {
+        const body = one.content.find((x) => x.type === 'text')?.text ?? ''
+        let parsed
+        try {
+          parsed = JSON.parse(body)
+        } catch {
+          parsed = body
+        }
+        results.push({ tool, ok: true, result: parsed, ...again, ...ms })
+      }
+    }
+    // A refused change: what the batch did before it taken back, newest
+    // first, once the page is idle — a rebuild still landing would refuse
+    // the undo. A refused read leaves it standing.
+    const rollback = Boolean(failed && checkpoint && changes(failed.tool))
+    let undone
+    let rollbackError
+    if (rollback) {
+      await pageIdle(Date.now() + IDLE_WAIT_MS)
+      try {
+        undone = (await link.run('history.restore', { checkpoint }, undefined, undefined, job))?.undone ?? []
+      } catch (e) {
+        rollbackError = `${e?.code ?? 'failed'}: ${e?.message ?? String(e)}`
+      }
+    }
+    // Stopped before its last call, a batch built at the end leaves no
+    // rebuild held: the page, read for idle, builds what is.
+    if (atEnd && lastDeferred && !rollback) await pageIdle(Date.now() + IDLE_WAIT_MS)
+    const kept = failed && checkpoint && !rollback ? { kept: `${failed.tool} changes nothing, so its refusal undid nothing: what the batch changed before it stands.` } : {}
+    const answer = {
+      results,
+      ran: results.length,
+      of: calls.length,
+      ...(stopped !== undefined ? { stopped } : {}),
+      ...(failed ? { failed, ...(rollback ? { undone: undone ?? [] } : {}), ...kept, ...(rollbackError ? { rollbackError } : {}) } : {}),
+      ...(timings ? { total_ms: Date.now() - started } : {}),
+    }
+    // Each call's result is capped already; many together may still be
+    // past it — then the whole goes to a file, and the answer keeps how
+    // the batch ended.
+    return text(await fitted(answer, 'scanruler_batch', exact, ['failed', 'undone']), exact)
+  }
+
+  // The page's tools for a client that does not list them: a line each,
+  // or the definitions of some — each as the full list would give it.
+  if (compact) {
+    own.push({
+      name: 'scanruler_tools',
+      title: 'List the ScanRuler tools',
+      description: `The ScanRuler tools, which this server lists one by one only when they return a picture. With no arguments: every tool’s name and what it does, a line each. With names: those tools’ full definitions — description and inputSchema — up to ${MAX_DEFINITIONS} at a time; read a tool’s before its first use. Run them with scanruler_batch, a single tool as a batch of one. Names it does not know come back in unknown. The list is the connected page’s, so it can change when a page connects.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          names: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+            maxItems: MAX_DEFINITIONS,
+            description: 'Tool names, as the list gives them — element_fit, scan_nearest. Leave out for the list.',
+          },
+        },
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      call: async (args) => {
+        const asked = typeof args?.names === 'string' ? args.names.split(/[\s,]+/) : Array.isArray(args?.names) ? args.names.map(String) : []
+        const names = [...new Set(asked.filter(Boolean))]
+        const list = commands()
+        if (names.length === 0) {
+          return text({
+            count: list.length,
+            tools: Object.fromEntries(list.map((c) => [toolName(c), summary(c)])),
+            next: 'scanruler_tools with names gives a tool’s definition; scanruler_batch runs it.',
+          })
+        }
+        if (names.length > MAX_DEFINITIONS) {
+          return failure({ code: 'invalid_input', message: `names: at most ${MAX_DEFINITIONS} at a time — ask for the rest in another call.` })
+        }
+        const found = []
+        const unknown = []
+        for (const name of names) {
+          const command = list.find((c) => toolName(c) === name)
+          const mine = own.find((t) => t.name === name)
+          if (command) found.push(toolFor(command, { outDir }))
+          else if (mine) found.push(definition(mine))
+          else unknown.push(name)
+        }
+        // Exact: a schema's numbers are limits and defaults, not readings.
+        return text({ tools: found, unknown }, true)
+      },
+    })
+  }
+
+  // Each call traced as one line when it is answered — what the client
+  // waited for — with the tab's hidden state at its start and end and the
+  // jobs running when it came; a batch's entries and a queued job's end get
+  // lines of their own.
+  let callNo = 0
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    if (!trace) return dispatch(request, extra, null)
+    const { name, arguments: args } = request.params
+    const ctx = { call: ++callNo, fields: {} }
+    const t = trace.now()
+    const hiddenAt = hiddenNow()
+    const running = runningJobs()
+    const reply = await dispatch(request, extra, ctx)
+    trace.write({
+      ev: 'call',
+      call: ctx.call,
+      t,
+      tool: name,
+      ms: trace.now() - t,
+      in: jsonBytes(args ?? {}),
+      ...replyMeasure(reply),
+      hidden: [hiddenAt, hiddenNow()],
+      ...(running ? { running } : {}),
+      ...ctx.fields,
+      ...(trace.args ? { args: args ?? {} } : {}),
+    })
+    return reply
+  })
+
+  /** A tool call answered — see the handler above. */
+  const dispatch = async (request, extra, ctx) => {
+    const { name, arguments: args } = request.params
+    const mine = own.find((t) => t.name === name)
+    if (mine) return mine.call(args, ctx)
+    // Progress lines from the page, for a client that asked for them.
+    const token = request.params._meta?.progressToken
+    let step = 0
+    const onProgress =
+      token === undefined
+        ? undefined
+        : (line) => {
+            extra.sendNotification({ method: 'notifications/progress', params: { progressToken: token, progress: ++step, message: line } }).catch(() => {})
+          }
+    // A change runs as a job, and so does a long read: answered when done —
+    // or with the job, at once for wait: false and at the answer limit
+    // otherwise — and kept either way, for a client that stops waiting
+    // before it is done.
+    const command = commands().find((c) => toolName(c) === name)
+    if (!command || (command.readOnly && !command.long)) return runPageTool(name, args, onProgress)
+    const { wait, timings, ...rest } = args ?? {}
+    const timed = timings === true && !command.readOnly
+    const job = startJob(name, (id) => runPageTool(name, rest, onProgress, { timings: timed, ms: timed, job: id }), ctx, wait === false)
+    return wait === false ? queuedReply(job) : answerFor(job, ctx)
+  }
+
+  trace?.write({ ev: 'start', t: trace.now(), version, backend: headless ? 'headless' : 'page', tools: toolMode, pid: process.pid, args: trace.args })
+  link.on?.('visibility', (hidden) => trace?.write({ ev: 'visibility', t: trace.now(), hidden }))
+
+  return server
+}