@mmerterden/multi-agent-toolkit-mcp 3.14.0 → 3.15.0

package/index.js

@@ -21,7 +21,6 @@ import { join, dirname, basename, isAbsolute, resolve, sep } from "path";
 import { homedir, tmpdir } from "os";
 import { createHash } from "crypto";
 import { createRequire } from "node:module";
-import * as ctxIndex from "./tools/context/index.js";
 
 // This file is ESM ("type": "module"), so `require` does not exist here. The
 // optional readability helpers are resolved through createRequire: absent, the
@@ -52,6 +51,9 @@ import { parseLeaksOutput, parseMeminfoOutput, diffMeminfo } from "./tools/memor
 import { auditIosTree, auditAndroidDump, parseAuditResults } from "./tools/a11y/index.js";
 import { interactiveElements } from "./tools/ui-inspect/index.js";
 import { selectCrashReports } from "./tools/crash-logs/index.js";
+import { urlPolicy, urlPolicyError, urlAllowList, indexDenyList, indexDenied as pathDenied, strictLaunchOptions } from "./tools/policy/index.js";
+import { startEgressProxy } from "./tools/policy/egress-proxy.js";
+import { spawnCollect, killAllSpawned } from "./tools/spawn-collect/index.js";
 import {
   offloadLargeText,
   queryOffloadedOutput,
@@ -67,6 +69,14 @@ if (!existsSync(SCREENSHOT_DIR)) mkdirSync(SCREENSHOT_DIR, { recursive: true });
 // ever removed them.
 pruneWorkDir(SCREENSHOT_DIR);
 
+// Read once at startup; see tools/policy for what strict refuses. Unset, both
+// checks return early and nothing is refused.
+const URL_POLICY = urlPolicy();
+const URL_ALLOW = URL_POLICY === "strict" ? urlAllowList() : [];
+const INDEX_DENY = indexDenyList({ policy: URL_POLICY });
+const checkUrl = (url) => urlPolicyError(url, { policy: URL_POLICY, allow: URL_ALLOW });
+const indexDenied = (path) => pathDenied(path, INDEX_DENY);
+
 // ── Helpers ──
 
 // Marker prefix for command failures. The CallTool dispatch turns any result
@@ -157,67 +167,6 @@ function runAsync(cmd, opts = {}) {
   });
 }
 
-// spawn-based collector for the long-runners that also want incremental output
-// (progress heartbeats read the last line). Interleaves stdout+stderr the way a
-// terminal would, honors an AbortSignal, and never rejects.
-//
-// Output is capped at the 64MB the execSync it replaced enforced via maxBuffer:
-// unbounded `output += chunk` on a verbose xcodebuild can exceed V8's max
-// string length, and that throw fires inside a stream 'data' handler - outside
-// the CallTool try/catch - killing the whole stdio server. The oldest chunks
-// are dropped; errors and test verdicts land at the tail of a build log.
-const SPAWN_OUTPUT_CAP = 64 * 1024 * 1024;
-
-function spawnCollect(cmd, { timeout = 600000, signal, env, onLine } = {}) {
-  return new Promise((resolve) => {
-    const child = spawn("/bin/sh", ["-c", cmd], { env });
-    const chunks = [];
-    let size = 0;
-    let truncated = false;
-    let timedOut = false;
-    let aborted = false;
-    const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, timeout);
-    const onAbort = () => { aborted = true; child.kill("SIGTERM"); };
-    if (signal) {
-      if (signal.aborted) onAbort();
-      else signal.addEventListener("abort", onAbort, { once: true });
-    }
-    const collect = (chunk) => {
-      const s = String(chunk);
-      chunks.push(s);
-      size += s.length;
-      while (size > SPAWN_OUTPUT_CAP && chunks.length > 1) {
-        size -= chunks[0].length;
-        chunks.shift();
-        truncated = true;
-      }
-      if (size > SPAWN_OUTPUT_CAP) {
-        chunks[0] = chunks[0].slice(size - SPAWN_OUTPUT_CAP);
-        size = SPAWN_OUTPUT_CAP;
-        truncated = true;
-      }
-      if (onLine) {
-        const lines = s.split("\n");
-        for (let i = lines.length - 1; i >= 0; i--) {
-          const line = lines[i].trim();
-          if (line) { onLine(line); break; }
-        }
-      }
-    };
-    child.stdout.on("data", collect);
-    child.stderr.on("data", collect);
-    child.on("error", (e) => {
-      clearTimeout(timer);
-      resolve({ code: 127, output: `${chunks.join("")}\n${e.message}`, truncated, timedOut, aborted });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (signal) signal.removeEventListener("abort", onAbort);
-      resolve({ code: code ?? 1, output: chunks.join(""), truncated, timedOut, aborted });
-    });
-  });
-}
-
 function startHeartbeat(ctx, label, detail) {
   if (!ctx?.progress) return () => {};
   const started = Date.now();
@@ -245,11 +194,31 @@ function safeRelOutput(name, baseDir) {
   return full;
 }
 
+// Bundle IDs / package names: reverse-DNS characters only (alphanumeric, dots,
+// underscores, hyphens). Absent (undefined/null) passes through for the callers
+// that treat it as optional, but a PRESENT value must name something: an empty
+// string makes `simctl privacy <d> reset all <id>` reset every app on the
+// device, and a leading dash reaches the CLI as an option instead of an
+// operand. A slash is refused because `defaults write <id>` reads a value
+// containing one as a plist path, so a bundle id of /tmp/x writes a file. The
+// one place a slash is legitimate, an Android package/activity component, has
+// its own validator.
 function sanitizeId(id) {
-  // Bundle IDs / package names: only allow alphanumeric, dots, underscores, hyphens
-  if (!id) return id;
-  if (!/^[a-zA-Z0-9._\-/]+$/.test(id)) throw new Error(`Invalid identifier: ${id}`);
-  return id;
+  if (id === undefined || id === null) return id;
+  const s = String(id);
+  if (!/^[a-zA-Z0-9._][a-zA-Z0-9._-]*$/.test(s)) throw new Error(`Invalid bundle id or package name: ${JSON.stringify(s)}`);
+  return s;
+}
+
+// An Android activity: a class name, relative (.Main) or qualified, optionally
+// prefixed with its package as package/activity. At most one slash, never at
+// either end.
+function androidActivity(activity) {
+  const s = String(activity ?? "");
+  if (!/^[a-zA-Z0-9._][a-zA-Z0-9._-]*(\/[a-zA-Z0-9._][a-zA-Z0-9._-]*)?$/.test(s)) {
+    throw new Error(`Invalid activity: ${JSON.stringify(s)}`);
+  }
+  return s;
 }
 
 // Single-quote a value for POSIX sh. Every command here is built as a string and
@@ -432,6 +401,17 @@ const HAS_ADB = hasCommand("adb");
 // two simctl recorders on one simulator fight over the io channel.
 const RECORDINGS = new Map();
 
+// Resolves once the child has either started or failed to. A spawn failure
+// (the binary is gone, not executable) arrives as an 'error' event, and an
+// 'error' nobody listens for is thrown as an uncaught exception - which takes
+// the whole stdio server down one tick after the start call answered "started".
+function spawnStarted(child) {
+  return new Promise((resolve) => {
+    child.once("spawn", () => resolve(null));
+    child.once("error", (e) => resolve(e));
+  });
+}
+
 function fileResult(text, ...paths) {
   return {
     type: "file",
@@ -660,6 +640,8 @@ async function handleIOS(name, args, ctx = {}) {
       const recParent = dirname(f);
       if (!existsSync(recParent)) return `${ERROR_PREFIX}directory does not exist: ${recParent}`;
       const child = spawn("xcrun", ["simctl", "io", d, "recordVideo", `--codec=${args.codec || "hevc"}`, "--force", f], { stdio: "ignore" });
+      const spawnError = await spawnStarted(child);
+      if (spawnError) return `${ERROR_PREFIX}could not start xcrun simctl io recordVideo: ${spawnError.message}`;
       child.once("close", () => { if (RECORDINGS.get(key)?.child === child) RECORDINGS.delete(key); });
       RECORDINGS.set(key, { child, path: f });
       return `Recording started on ${d} (pid ${child.pid}) -> ${f}\nCall ios_record_video with action:"stop" to finish.`;
@@ -1122,7 +1104,7 @@ function adbFlag(id) { return id ? `-s ${deviceSerial(id)}` : ""; }
 // carries the package (com.x/.Main) is used as it is.
 function androidComponent(packageName, activity) {
   const pkg = sanitizeId(packageName);
-  const act = sanitizeId(activity);
+  const act = androidActivity(activity);
   return act.includes("/") ? act : `${pkg}/${act}`;
 }
 
@@ -1204,7 +1186,14 @@ async function handleAndroid(name, args, ctx = {}) {
     case "android_key_event": return run(`adb ${df} shell input keyevent ${token(args.keycode, "keycode")}`) || `Key ${args.keycode}`;
     case "android_launch_app": return args.activity ? run(`adb ${df} shell am start -n ${androidComponent(args.package_name, args.activity)}`) : run(`adb ${df} shell monkey -p ${sanitizeId(args.package_name)} -c android.intent.category.LAUNCHER 1`) || `Launched`;
     case "android_stop_app": return run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`) || "Stopped";
-    case "android_list_packages": { const out = run(`adb ${df} shell pm list packages`); return args.filter ? out.split("\n").filter(l => l.toLowerCase().includes(args.filter.toLowerCase())).join("\n") : out; }
+    case "android_list_packages": {
+      const out = run(`adb ${df} shell pm list packages`);
+      // The filter applies to package lines, not to a failure: filtering the
+      // ERROR text by a package name would answer with an empty success.
+      if (isFailure(out) || !args.filter) return out;
+      const wanted = String(args.filter).toLowerCase();
+      return out.split("\n").filter((l) => l.toLowerCase().includes(wanted)).join("\n");
+    }
     case "android_go_home": return run(`adb ${df} shell input keyevent 3`) || "Home";
     case "android_go_back": return run(`adb ${df} shell input keyevent 4`) || "Back";
     case "android_get_ui_tree": {
@@ -1315,6 +1304,8 @@ async function handleAndroid(name, args, ctx = {}) {
       if (!existsSync(parent)) return `${ERROR_PREFIX}directory does not exist: ${parent}`;
       const argv = [...(args.device_id ? ["-s", deviceSerial(args.device_id)] : []), "shell", "screenrecord", "--time-limit", String(dur), remotePath];
       const child = spawn("adb", argv, { stdio: "ignore" });
+      const spawnError = await spawnStarted(child);
+      if (spawnError) return `${ERROR_PREFIX}could not start adb screenrecord: ${spawnError.message}`;
       const entry = { child, remotePath, path: localPath, exited: false };
       child.once("close", () => { if (RECORDINGS.get(key) === entry) entry.exited = true; });
       RECORDINGS.set(key, entry);
@@ -1486,13 +1477,121 @@ async function handleAndroid(name, args, ctx = {}) {
 let _browser = null;
 let _page = null;
 let _engine = null;
+let _userAgent = null;
 
 // A request for a different engine closes the current browser and relaunches;
 // a partial launch (newContext/newPage threw) is closed rather than left as a
 // browser with no page that the next call would launch beside.
-async function ensureBrowser(browserType) {
+//
+// The user agent belongs to the browser context: set there, it reaches every
+// request and navigator.userAgent alike. A header override would change only
+// the former. So a web_goto naming a DIFFERENT user_agent starts a fresh
+// context, and with it drops the previous one's cookies, storage and tabs; one
+// that omits it keeps whatever context is open.
+// ── Strict URL policy inside the browser ─────────────────────────────
+//
+// Checking the URL handed to web_goto is not enough: a script, a click, a
+// redirect, a popup, a fetch or an <img> reaches a host without passing
+// through it. Under the strict policy every context gets a route that runs the
+// same check on every request the context makes - navigations, subresources,
+// popups, WebSockets - and aborts the refused ones before they leave the
+// browser. Service workers are blocked, because their requests bypass routing.
+// Routing disables the HTTP cache, which is why it is not installed by default.
+const REFUSAL_CAP = 50;
+let _refusals = [];
+let _refusalSeq = 0;
+
+function recordRefusal(url, reason, navigation) {
+  _refusals.push({ seq: ++_refusalSeq, url: String(url).slice(0, 300), reason, navigation });
+  if (_refusals.length > REFUSAL_CAP) _refusals.shift();
+}
+
+const refusalsSince = (seq) => _refusals.filter((r) => r.seq > seq);
+
+// data:, blob: and about: never reach the network.
+const LOCAL_SCHEME = /^(data|blob|about):/i;
+
+async function guardContext(ctx) {
+  await ctx.route("**/*", async (route) => {
+    const req = route.request();
+    const url = req.url();
+    const refused = LOCAL_SCHEME.test(url) ? null : await checkUrl(url);
+    if (refused) {
+      recordRefusal(url, refused, req.isNavigationRequest());
+      return route.abort("blockedbyclient").catch(() => {});
+    }
+    return route.fallback().catch(() => {});
+  });
+  await ctx.routeWebSocket(/.*/, async (ws) => {
+    const url = ws.url();
+    const refused = await checkUrl(url.replace(/^ws(s?):/i, "http$1:"));
+    if (refused) {
+      recordRefusal(url, refused, false);
+      await ws.close({ code: 1008, reason: "refused by the URL policy" }).catch(() => {});
+      return;
+    }
+    ws.connectToServer();
+  });
+}
+
+// The route above never sees the hops of a redirect chain; the proxy does.
+// Started with the first strict browser and kept for the life of the process
+// (it is unref'd and listens on 127.0.0.1 only).
+let _egressProxy = null;
+async function egressProxy() {
+  _egressProxy ??= startEgressProxy({
+    check: (url, lookup) => urlPolicyError(url, { policy: URL_POLICY, allow: URL_ALLOW, lookup }),
+    onRefuse: (url, reason) => recordRefusal(url, reason, null),
+  }).catch((e) => { _egressProxy = null; throw e; });
+  return _egressProxy;
+}
+
+async function launchOptions(engineName) {
+  if (URL_POLICY !== "strict") return { headless: true };
+  const proxy = await egressProxy();
+  return strictLaunchOptions(engineName, proxy.url);
+}
+
+// WebKit has no launch switch for WebRTC, so under the strict policy its pages
+// get no peer-connection constructors at all.
+const NO_PEER_CONNECTION = `for (const k of ["RTCPeerConnection", "webkitRTCPeerConnection", "RTCDataChannel"]) { try { delete window[k]; } catch {} }`;
+
+async function newContext(agent) {
+  const strict = URL_POLICY === "strict";
+  const ctx = await _browser.newContext({
+    ...(agent ? { userAgent: agent } : {}),
+    ...(strict ? { serviceWorkers: "block" } : {}),
+  });
+  if (strict) {
+    try {
+      if (_browser.browserType().name() === "webkit") await ctx.addInitScript(NO_PEER_CONNECTION);
+      await guardContext(ctx);
+    } catch (e) {
+      await ctx.close().catch(() => {});
+      throw e;
+    }
+  }
+  return ctx;
+}
+
+async function ensureBrowser(browserType, userAgent) {
   const wanted = browserType || _engine || "chromium";
-  if (_browser && _page && _engine === wanted) return _page;
+  const agent = userAgent === undefined || userAgent === null || userAgent === "" ? _userAgent : String(userAgent);
+  if (_browser && _page && _engine === wanted && agent === _userAgent) return _page;
+  if (_browser && _page && _engine === wanted) {
+    try { await _page.context().close(); } catch {}
+    _page = null;
+    try {
+      const ctx = await newContext(agent);
+      _page = await ctx.newPage();
+      observePage(_page);
+    } catch (e) {
+      await closeBrowser();
+      throw e;
+    }
+    _userAgent = agent;
+    return _page;
+  }
   if (_browser || _page) await closeBrowser();
   let pw;
   try {
@@ -1503,9 +1602,9 @@ async function ensureBrowser(browserType) {
   const engines = { chromium: pw.chromium, webkit: pw.webkit, firefox: pw.firefox };
   const engine = engines[wanted];
   if (!engine) throw new Error(`unknown browser engine: ${wanted}`);
-  _browser = await engine.launch({ headless: true });
+  _browser = await engine.launch(await launchOptions(wanted));
   try {
-    const ctx = await _browser.newContext();
+    const ctx = await newContext(agent);
     _page = await ctx.newPage();
     observePage(_page);
   } catch (e) {
@@ -1513,6 +1612,7 @@ async function ensureBrowser(browserType) {
     throw e;
   }
   _engine = wanted;
+  _userAgent = agent;
   return _page;
 }
 
@@ -1522,6 +1622,7 @@ async function closeBrowser() {
   _page = null;
   _browser = null;
   _engine = null;
+  _userAgent = null;
 }
 
 // ── Page observation ─────────────────────────────────────────────────
@@ -1767,6 +1868,10 @@ function turndownBundlePath(resolved) {
 function blankPageError(page, tool) {
   const url = page.url();
   if (url && url !== "about:blank" && !url.startsWith("chrome-error://")) return null;
+  // Under strict, a navigation the policy aborted leaves the browser's error
+  // page behind; naming the refusal says why better than "nothing opened".
+  const refused = url.startsWith("chrome-error://") ? [..._refusals].reverse().find((r) => r.navigation) : null;
+  if (refused) return `ERROR: ${tool} has no page to read: the last navigation, to ${refused.url}, was refused. ${refused.reason}`;
   return `ERROR: ${tool} reads the page that is currently open, and nothing has been opened yet (${url || "no url"}). Call web_goto first.`;
 }
 
@@ -1868,7 +1973,7 @@ function locate(page, args) {
 }
 
 const WEB_TOOLS = [
-  { name: "web_goto", description: "Open a URL in a headless browser (Playwright). Reuses a single browser instance across calls.", inputSchema: { type: "object", properties: { url: { type: "string" }, browser: { type: "string", enum: ["chromium", "webkit", "firefox"], description: "Default chromium; use webkit for Safari-like behavior" }, wait_until: { type: "string", enum: ["load", "domcontentloaded", "networkidle"] }, timeout_ms: { type: "number", description: "Navigation timeout. Default 30000." }, viewport: { type: "string", description: "WIDTHxHEIGHT, e.g. 390x844 for a phone-sized layout." }, locale: { type: "string", description: "Accept-Language for this navigation, e.g. tr-TR." }, user_agent: { type: "string" } }, required: ["url"] } },
+  { name: "web_goto", description: "Open a URL in a headless browser (Playwright). Reuses a single browser instance across calls.", inputSchema: { type: "object", properties: { url: { type: "string" }, browser: { type: "string", enum: ["chromium", "webkit", "firefox"], description: "Default chromium; use webkit for Safari-like behavior" }, wait_until: { type: "string", enum: ["load", "domcontentloaded", "networkidle"] }, timeout_ms: { type: "number", description: "Navigation timeout. Default 30000." }, viewport: { type: "string", description: "WIDTHxHEIGHT, e.g. 390x844 for a phone-sized layout." }, locale: { type: "string", description: "Accept-Language for this navigation, e.g. tr-TR." }, user_agent: { type: "string", description: "User-Agent for the browser context, seen by requests and navigator.userAgent alike. A value different from the current one starts a fresh context, discarding its cookies, storage and tabs; omit it to keep the current context." } }, required: ["url"] } },
   { name: "web_screenshot", description: "Capture a screenshot of the current page. Returns a base64 PNG by default; pass `path` to write the file and return only its location.", inputSchema: { type: "object", properties: { full_page: { type: "boolean" }, path: { type: "string", description: "Absolute file path to write the PNG to. The parent directory must already exist. Returns the path instead of the image." } } } },
   { name: "web_click", description: "Click an element by CSS selector, text, or a [ref=eN] from web_snapshot. Auto-waits for the element.", inputSchema: { type: "object", properties: { selector: { type: "string", description: "CSS selector, or 'text=...' / 'role=...'" }, ref: { type: "string", description: "A ref from the most recent web_snapshot, e.g. e7. Use this instead of selector." }, timeout_ms: { type: "number" } } } },
   { name: "web_type", description: "Type text into an input matched by a selector or a [ref=eN] from web_snapshot.", inputSchema: { type: "object", properties: { selector: { type: "string" }, ref: { type: "string", description: "A ref from the most recent web_snapshot." }, text: { type: "string" }, clear_first: { type: "boolean" } }, required: ["text"] } },
@@ -1889,9 +1994,121 @@ const WEB_TOOLS = [
   { name: "web_select_option", description: "Choose an option in a <select>, by value or by visible label.", inputSchema: { type: "object", properties: { selector: { type: "string" }, ref: { type: "string" }, value: { type: "string" }, label: { type: "string" } } } },
 ];
 
+// The policy verdict on where the page is now. Only a network or file URL is
+// judged: about:blank and the browser's own error page hold nothing a refused
+// host served.
+async function landedRefusal(page) {
+  const url = page.url();
+  if (!/^(https?|wss?|ftp|file):/i.test(url)) return null;
+  return checkUrl(url);
+}
+
+// The crawl loop proper. handleWeb routes the crawl's User-Agent around it and
+// removes the route afterwards, whatever this returns or throws.
+async function crawlFrom(page, { start, origin, maxPages, maxDepth, delay, respectRobots, wantIndex, indexDb, crawlDir, ctxIndex }) {
+  let indexed = 0;
+  const disallowed = respectRobots ? await robotsDisallow(page, origin) : [];
+  const seen = new Set([start]);
+  const queue = [{ url: start, depth: 0 }];
+  const out = [];
+  while (queue.length && out.length < maxPages) {
+    const { url, depth } = queue.shift();
+    if (disallowed.some((rule) => url.startsWith(origin + rule))) continue;
+    const refused = await checkUrl(url);
+    if (refused) {
+      out.push(`--- ${url}\nERROR: ${refused}`);
+      continue;
+    }
+    let gotoError = null;
+    try {
+      await page.goto(url, { waitUntil: "load", timeout: 15000 });
+    } catch (e) {
+      gotoError = e;
+    }
+    // A redirect can land somewhere the queued URL did not name. Such a page is
+    // neither read, indexed nor followed.
+    const landed = await landedRefusal(page);
+    if (landed) {
+      out.push(`--- ${url}\nERROR: redirected to a refused address. ${landed}`);
+      await page.goto("about:blank").catch(() => {});
+      continue;
+    }
+    if (gotoError) {
+      out.push(`--- ${url}\nERROR: ${gotoError.message}`);
+      continue;
+    }
+    const doc = await extractReadable(page);
+    out.push(`--- ${url}\n${doc.markdown}`);
+    // A crawl that cannot be searched afterwards is a wall of text: twenty
+    // pages arrive at once and the caller has no way to ask which of them
+    // answers the question. Each page is written beside the index and
+    // indexed under its URL, so context_search ranks the crawl the same way
+    // it ranks an offloaded payload. Failure here never fails the crawl -
+    // the pages are already in the reply.
+    if (wantIndex && indexDb) {
+      try {
+        const slug = url.replace(/[^a-z0-9]+/gi, "-").slice(0, 120);
+        const file = join(crawlDir, `${slug || "page"}.md`);
+        writeFileSync(file, `# ${url}\n\n${doc.markdown}\n`);
+        ctxIndex.indexFile(indexDb, file);
+        indexed += 1;
+      } catch {
+        /* the page is in the reply; the index is the bonus */
+      }
+    }
+    if (depth < maxDepth) {
+      for (const link of await sameOriginLinks(page)) {
+        if (seen.has(link) || seen.size >= maxPages * 4) continue;
+        seen.add(link);
+        queue.push({ url: link, depth: depth + 1 });
+      }
+    }
+    // One request at a time, with a pause. A crawler that opens a site in
+    // parallel is a load test nobody asked for.
+    if (queue.length && out.length < maxPages) await page.waitForTimeout(delay);
+  }
+  resetRefs();
+  const indexNote = indexed
+    ? ` - ${indexed} indexed, searchable with context_search`
+    : wantIndex && indexDb === null
+      ? " - the index could not be opened, so these pages are not searchable"
+      : "";
+  return `${out.length} page(s)${indexNote}\n\n${fenceUntrusted(`${out.length} page(s) from ${origin && origin !== "null" ? origin : start}`, out.join("\n\n"))}`;
+}
+
+// web_crawl announces itself on every request it makes, so a site operator
+// reading the access log can tell the crawl from a visitor and find its owner.
+const crawlUserAgent = () => `multi-agent-toolkit-mcp/${PKG.version} (+https://github.com/mmerterden/multi-agent-toolkit-mcp)`;
+
+// Non-negative integer when given, the default when absent. An explicit 0 is a
+// value (max_depth 0 means the start page only, delay_ms 0 means no pause), so
+// it cannot be read as "not given".
+function countOr(value, fallback) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Math.trunc(Number(value));
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+const PAGE_READING_TOOLS = new Set([
+  "web_get_text", "web_extract", "web_snapshot", "web_screenshot", "web_eval",
+  "web_map", "web_storage_state", "web_select_option", "web_type", "web_click", "web_press_key", "web_wait_for",
+]);
+
 async function handleWeb(name, args) {
   if (name === "web_close") { await closeBrowser(); resetRefs(); return "Browser closed"; }
-  const page = await ensureBrowser(args.browser);
+  // Before the browser launches: a refused URL costs nothing.
+  if (name === "web_goto") {
+    const refused = await checkUrl(args.url);
+    if (refused) return `${ERROR_PREFIX}${refused}`;
+  }
+  const page = await ensureBrowser(args.browser, name === "web_goto" ? args.user_agent : undefined);
+  // The route guard stops a refused page from loading; this is the second
+  // line, for a page that got there anyway (a DNS answer that changed between
+  // two lookups): nothing is read from a page whose address is refused now.
+  if (URL_POLICY === "strict" && PAGE_READING_TOOLS.has(name)) {
+    const refused = await landedRefusal(page);
+    if (refused) return `${ERROR_PREFIX}the current page is at a refused address. ${refused}`;
+  }
   switch (name) {
     case "web_goto": {
       if (args.viewport) {
@@ -1911,10 +2128,33 @@ async function handleWeb(name, args) {
       // Every ref from before this navigation points at a page that is gone,
       // so they are dropped rather than left to resolve by accident.
       resetRefs();
-      await page.goto(args.url, {
-        waitUntil: args.wait_until || "load",
-        timeout: args.timeout_ms || 30000,
-      });
+      const seq = _refusalSeq;
+      let gotoError = null;
+      try {
+        await page.goto(args.url, {
+          waitUntil: args.wait_until || "load",
+          timeout: args.timeout_ms || 30000,
+        });
+      } catch (e) {
+        gotoError = e;
+      }
+      // A redirect can land somewhere the requested URL did not name, and a
+      // goto that threw (a timeout after the redirect) may still have landed.
+      const landed = await landedRefusal(page);
+      if (landed) {
+        await page.goto("about:blank").catch(() => {});
+        resetRefs();
+        return `${ERROR_PREFIX}${args.url} redirected to a refused address. ${landed}`;
+      }
+      if (gotoError) {
+        const refused = refusalsSince(seq).find((r) => r.navigation);
+        if (refused) {
+          await page.goto("about:blank").catch(() => {});
+          resetRefs();
+          return `${ERROR_PREFIX}${args.url} was refused on the way to ${refused.url}. ${refused.reason}`;
+        }
+        throw gotoError;
+      }
       return `Opened ${args.url} (title: "${await page.title()}")`;
     }
     case "web_screenshot": {
@@ -2064,74 +2304,44 @@ async function handleWeb(name, args) {
       const blank = blankPageError(page, "web_crawl");
       if (blank) return blank;
       const maxPages = Math.min(Number(args.max_pages) || 20, 200);
-      const maxDepth = Number(args.max_depth) || 2;
-      const delay = Number(args.delay_ms) || 250;
+      const maxDepth = countOr(args.max_depth, 2);
+      const delay = countOr(args.delay_ms, 250);
       const respectRobots = args.respect_robots !== false;
       const start = page.url();
+      // The start page can be reached without web_goto (a click, a script),
+      // so it is checked here as well as every page the crawl opens.
+      const refusedStart = await checkUrl(start);
+      if (refusedStart) return `${ERROR_PREFIX}${refusedStart}`;
       const origin = new URL(start).origin;
       const wantIndex = args.index !== false;
-      let indexed = 0;
       let indexDb = null;
       let crawlDir = null;
+      let ctxIndex = null;
       if (wantIndex) {
-        try {
-          indexDb = ctxIndex.openIndex();
-          crawlDir = join(ctxIndex.INDEX_DIR, "crawl");
-          if (!existsSync(crawlDir)) mkdirSync(crawlDir, { recursive: true });
-        } catch {
-          indexDb = null;
-        }
-      }
-      const disallowed = respectRobots ? await robotsDisallow(page, origin) : [];
-      const seen = new Set([start]);
-      const queue = [{ url: start, depth: 0 }];
-      const out = [];
-      while (queue.length && out.length < maxPages) {
-        const { url, depth } = queue.shift();
-        if (disallowed.some((rule) => url.startsWith(origin + rule))) continue;
-        try {
-          await page.goto(url, { waitUntil: "load", timeout: 15000 });
-        } catch (e) {
-          out.push(`--- ${url}\nERROR: ${e.message}`);
-          continue;
-        }
-        const doc = await extractReadable(page);
-        out.push(`--- ${url}\n${doc.markdown}`);
-        // A crawl that cannot be searched afterwards is a wall of text: twenty
-        // pages arrive at once and the caller has no way to ask which of them
-        // answers the question. Each page is written beside the index and
-        // indexed under its URL, so context_search ranks the crawl the same way
-        // it ranks an offloaded payload. Failure here never fails the crawl -
-        // the pages are already in the reply.
-        if (wantIndex && indexDb) {
+        const opened = await openContextDb();
+        if (!opened.error) {
           try {
-            const slug = url.replace(/[^a-z0-9]+/gi, "-").slice(0, 120);
-            const file = join(crawlDir, `${slug || "page"}.md`);
-            writeFileSync(file, `# ${url}\n\n${doc.markdown}\n`);
-            ctxIndex.indexFile(indexDb, file);
-            indexed += 1;
+            ctxIndex = opened.ctx;
+            crawlDir = join(ctxIndex.INDEX_DIR, "crawl");
+            if (!existsSync(crawlDir)) mkdirSync(crawlDir, { recursive: true });
+            indexDb = opened.db;
           } catch {
-            /* the page is in the reply; the index is the bonus */
+            indexDb = null;
           }
         }
-        if (depth < maxDepth) {
-          for (const link of await sameOriginLinks(page)) {
-            if (seen.has(link) || seen.size >= maxPages * 4) continue;
-            seen.add(link);
-            queue.push({ url: link, depth: depth + 1 });
-          }
-        }
-        // One request at a time, with a pause. A crawler that opens a site in
-        // parallel is a load test nobody asked for.
-        if (queue.length && out.length < maxPages) await page.waitForTimeout(delay);
       }
-      resetRefs();
-      const indexNote = indexed
-        ? ` - ${indexed} indexed, searchable with context_search`
-        : wantIndex && indexDb === null
-          ? " - the index could not be opened, so these pages are not searchable"
-          : "";
-      return `${out.length} page(s)${indexNote}\n\n${fenceUntrusted(`${out.length} page(s) from ${origin && origin !== "null" ? origin : start}`, out.join("\n\n"))}`;
+      // A route rather than a header override: a context created with a
+      // user_agent wins over extra headers, and the crawl has to identify
+      // itself whatever the session was set to.
+      // fallback, not continue: continue would send the request straight to the
+      // network and skip the context's URL-policy route behind it.
+      const identify = (route) => route.fallback({ headers: { ...route.request().headers(), "user-agent": crawlUserAgent() } }).catch(() => {});
+      await page.route("**/*", identify);
+      try {
+        return await crawlFrom(page, { start, origin, maxPages, maxDepth, delay, respectRobots, wantIndex, indexDb, crawlDir, ctxIndex });
+      } finally {
+        await page.unroute("**/*", identify).catch(() => {});
+      }
     }
 
     case "web_press_key": {
@@ -2319,33 +2529,66 @@ const CONTEXT_TOOLS = [
   },
 ];
 
-async function handleContext(name, args) {
-  let db;
+// node:sqlite is unflagged from Node 22.13, and a static import of it fails the
+// whole module graph, so every tool would go down with the three that need it.
+// The context module is imported on first use instead; when it cannot load,
+// context_* and crawl indexing answer with the reason and nothing else changes.
+let contextModule = null;
+function loadContext() {
+  contextModule ??= import("./tools/context/index.js").then(
+    (mod) => ({ mod }),
+    (e) => ({ error: `the context index needs node:sqlite, available unflagged from Node 22.13 (this is ${process.version}): ${e.message}` }),
+  );
+  return contextModule;
+}
+
+// One handle for the life of the server. A DatabaseSync per call keeps every
+// earlier handle open until the garbage collector happens to run.
+let contextDb = null;
+async function openContextDb() {
+  const ctx = await loadContext();
+  if (ctx.error) return { error: ctx.error };
   try {
-    db = ctxIndex.openIndex();
+    contextDb ??= ctx.mod.openIndex();
   } catch (e) {
-    return `${ERROR_PREFIX}could not open the index: ${e.message}`;
+    return { error: `could not open the index: ${e.message}` };
   }
+  return { ctx: ctx.mod, db: contextDb };
+}
+
+function closeContextDb() {
+  try { contextDb?.close(); } catch {}
+  contextDb = null;
+}
+
+async function handleContext(name, args) {
+  const opened = await openContextDb();
+  if (opened.error) return `${ERROR_PREFIX}${opened.error}`;
+  const { ctx, db } = opened;
   switch (name) {
     case "context_index": {
-      const out = ctxIndex.indexFile(db, String(args.path));
+      const denied = indexDenied(String(args.path));
+      if (denied) return `${ERROR_PREFIX}${denied}`;
+      const out = ctx.indexFile(db, String(args.path));
       if (out.reason === "no such file") return `${ERROR_PREFIX}no such file: ${args.path}`;
       if (!out.indexed) return `Already indexed and unchanged: ${out.chunks} passage(s)`;
       return `Indexed ${args.path}: ${out.chunks} passage(s)`;
     }
     case "context_search": {
-      const hits = ctxIndex.search(db, String(args.query), {
+      const hits = ctx.search(db, String(args.query), {
         limit: Number(args.limit) || 5,
         path: args.path ? String(args.path) : null,
-      });
+      }).filter((h) => !indexDenied(h.path));
       if (!hits.length) return "(no match in the index; run context_index on the file first)";
       return hits
         .map((h) => `[id ${h.id}] ${h.path}:${h.firstLine}-${h.lastLine}\n${h.snippet}`)
         .join("\n\n");
     }
     case "context_get": {
-      const row = ctxIndex.getChunk(db, args.id);
+      const row = ctx.getChunk(db, args.id);
       if (!row) return `${ERROR_PREFIX}no passage with id ${args.id}`;
+      const denied = indexDenied(row.path);
+      if (denied) return `${ERROR_PREFIX}${denied}`;
       return `${row.path} lines ${row.first_line}-${row.last_line}\n\n${row.body}`;
     }
     default:
@@ -2376,21 +2619,51 @@ const RESEARCH_TOOLS = [
   },
 ];
 
+const RESEARCH_PROVIDERS = ["brave", "perplexity"];
+const RESEARCH_KEYS = { brave: "BRAVE_API_KEY", perplexity: "PERPLEXITY_API_KEY" };
+// Brave's web search answers at most 20 results per request.
+const RESEARCH_MAX_RESULTS = 20;
+
+// The provider decides both the endpoint and the key, so it is resolved once,
+// normalized, and checked against the same list the schema declares. A value
+// from RESEARCH_PROVIDER never passes through the schema, and deriving the key
+// and the endpoint separately lets a near miss ("Brave") send one provider's
+// key to the other.
+function researchProvider(args) {
+  const raw = args.provider || process.env.RESEARCH_PROVIDER || "brave";
+  const provider = String(raw).trim().toLowerCase();
+  if (RESEARCH_PROVIDERS.includes(provider)) return { provider };
+  return { error: `${ERROR_PREFIX}unknown research provider "${String(raw).trim()}"; expected one of ${RESEARCH_PROVIDERS.join(", ")}` };
+}
+
 function researchKey(provider) {
-  const name = provider === "perplexity" ? "PERPLEXITY_API_KEY" : "BRAVE_API_KEY";
-  const value = process.env[name];
+  const name = RESEARCH_KEYS[provider];
+  const value = name ? process.env[name] : undefined;
   // The NAME is safe to say; the value never is. A caller who has not set it
   // needs to know which variable to set.
   return value ? { value, name } : { error: `${ERROR_PREFIX}${name} is not set in this environment` };
 }
 
+function researchLimit(value) {
+  const n = Math.trunc(Number(value));
+  return Number.isFinite(n) && n > 0 ? Math.min(n, RESEARCH_MAX_RESULTS) : 5;
+}
+
+// One shape for every provider: title, url and snippet, one block per result.
+function researchRows(rows) {
+  if (!rows.length) return "(no results)";
+  return rows.map((r) => `${r.title ?? ""}\n${r.url ?? ""}\n${r.snippet ?? ""}`).join("\n\n");
+}
+
 async function handleResearch(name, args) {
   const timeout = AbortSignal.timeout(20000);
   if (name === "research_search") {
-    const provider = args.provider || process.env.RESEARCH_PROVIDER || "brave";
+    const chosen = researchProvider(args);
+    if (chosen.error) return chosen.error;
+    const { provider } = chosen;
     const key = researchKey(provider);
     if (key.error) return key.error;
-    const limit = Number(args.limit) || 5;
+    const limit = researchLimit(args.limit);
     try {
       if (provider === "brave") {
         const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(args.query)}&count=${limit}`;
@@ -2401,8 +2674,7 @@ async function handleResearch(name, args) {
         if (!res.ok) return `${ERROR_PREFIX}brave returned ${res.status}`;
         const body = await res.json();
         const rows = (body?.web?.results || []).slice(0, limit);
-        if (!rows.length) return "(no results)";
-        return rows.map((r) => `${r.title}\n${r.url}\n${r.description ?? ""}`).join("\n\n");
+        return researchRows(rows.map((r) => ({ title: r.title, url: r.url, snippet: r.description })));
       }
       const res = await fetch("https://api.perplexity.ai/chat/completions", {
         method: "POST",
@@ -2415,10 +2687,14 @@ async function handleResearch(name, args) {
       });
       if (!res.ok) return `${ERROR_PREFIX}perplexity returned ${res.status}`;
       const body = await res.json();
-      const cites = body?.citations || [];
-      return cites.length ? cites.slice(0, limit).join("\n") : "(no citations returned)";
+      // search_results carries titles and snippets; an older response has only
+      // the citation URLs, which still fill the url line.
+      const rows = Array.isArray(body?.search_results) && body.search_results.length
+        ? body.search_results.map((r) => ({ title: r.title, url: r.url, snippet: r.snippet ?? "" }))
+        : (body?.citations || []).map((c) => ({ title: "", url: c, snippet: "" }));
+      return researchRows(rows.slice(0, limit));
     } catch (e) {
-      return `${ERROR_PREFIX}${String(e.message || e).slice(0, 200)}`;
+      return `${ERROR_PREFIX}${provider}: ${String(e.message || e).slice(0, 200)}`;
     }
   }
   if (name === "research_ask") {
@@ -2460,6 +2736,8 @@ const MEDIA_TOOLS = [
   },
 ];
 
+const FRAME_NAME = /^frame-\d{3,}\.png$/;
+
 async function handleMedia(name, args) {
   if (name !== "media_frames") return null;
   if (!existsSync(String(args.path))) return `${ERROR_PREFIX}no such file: ${args.path}`;
@@ -2472,11 +2750,17 @@ async function handleMedia(name, args) {
   const threshold = Number(args.threshold) > 0 ? Number(args.threshold) : 0.25;
   const outDir = args.out_dir ? String(args.out_dir) : join(dirname(String(args.path)), `${basename(String(args.path), ".mp4")}-frames`);
   if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  // Frames from an earlier run into the same directory would be counted as
+  // this run's, and ffmpeg refuses to overwrite them without -y. Only the
+  // names this tool writes are removed.
+  for (const f of readdirSync(outDir)) {
+    if (FRAME_NAME.test(f)) unlinkSync(join(outDir, f));
+  }
   // The scene filter is what drops near-duplicates: it emits a frame only when
   // enough of the picture changed, which is the difference between twelve
   // useful screens and six hundred copies of the same one.
   const args2 = [
-    "-hide_banner", "-loglevel", "error",
+    "-y", "-hide_banner", "-loglevel", "error",
     "-i", String(args.path),
     "-vf", `select='gt(scene,${threshold})',showinfo`,
     "-vsync", "vfr",
@@ -2485,7 +2769,7 @@ async function handleMedia(name, args) {
   ];
   const r = spawnSync("ffmpeg", args2, { encoding: "utf8", timeout: 120000 });
   if (r.status !== 0) return `${ERROR_PREFIX}ffmpeg failed: ${String(r.stderr || "").slice(0, 200)}`;
-  const frames = readdirSync(outDir).filter((f) => f.startsWith("frame-") && f.endsWith(".png")).sort();
+  const frames = readdirSync(outDir).filter((f) => FRAME_NAME.test(f)).sort();
   if (!frames.length) {
     return `No scene changes above ${threshold} in ${args.path}. A lower threshold keeps more frames.`;
   }
@@ -2556,7 +2840,7 @@ const TOOL_SCHEMAS = new Map(ALL_TOOLS.map((t) => [t.name, t.inputSchema || {}])
 // number, which is the root cause of the shell-injection class. This enforces
 // the declared contract at the one boundary every tool passes through. Zero
 // dependencies (no ajv): supports type (string/number/integer/boolean/array/
-// object), required, and enum - the only constructs the tool schemas use.
+// object), required, enum and additionalProperties:false at any depth.
 function schemaTypeOk(value, type) {
   switch (type) {
     // A scalar is a fine string (paths/schemes have always arrived as strings,
@@ -2613,6 +2897,25 @@ function checkConstraints(key, value, spec) {
       return `argument '${key}' must be <= ${spec.maximum}`;
     }
   }
+  // Declared object fields are enforced at every depth, not only at the top
+  // level: a target list whose items declare additionalProperties:false must
+  // refuse a misspelt field inside an item the same way a tool refuses a
+  // misspelt argument.
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && (spec.properties || spec.required)) {
+    for (const req of spec.required || []) {
+      if (value[req] === undefined || value[req] === null) return `argument '${key}' is missing required field: ${req}`;
+    }
+    const props = spec.properties || {};
+    if (spec.additionalProperties === false) {
+      const extra = Object.keys(value).find((k) => !Object.hasOwn(props, k));
+      if (extra) return `argument '${key}' has unexpected field: ${extra}`;
+    }
+    for (const [k, sub] of Object.entries(props)) {
+      if (value[k] === undefined || value[k] === null) continue;
+      const subErr = checkConstraints(`${key}.${k}`, value[k], sub);
+      if (subErr) return subErr;
+    }
+  }
   if (Array.isArray(value)) {
     if (Number.isFinite(spec.minItems) && value.length < spec.minItems) {
       return `argument '${key}' must have at least ${spec.minItems} item(s)`;
@@ -2652,6 +2955,12 @@ function validateArgs(name, args) {
       return `missing required argument: ${req}`;
     }
   }
+  // Only where a schema says so. Most tools declare no additionalProperties and
+  // keep accepting extras, as they always have.
+  if (schema.additionalProperties === false) {
+    const extra = Object.keys(args).find((k) => !Object.hasOwn(props, k));
+    if (extra) return `unexpected argument: ${extra}`;
+  }
   for (const [key, spec] of Object.entries(props)) {
     if (args[key] === undefined || args[key] === null) continue;
     const err = checkConstraints(key, args[key], spec);
@@ -2673,6 +2982,7 @@ const READ_ONLY_TOOLS = new Set([
   "android_list_crashes",
   "web_screenshot", "web_get_text",
   "design_mock_detect", "design_scenario_inventory", "design_ui_geometry", "design_visual_compare",
+  "design_component_variants",
   // Seven of the eight. Every code_* tool reads source and answers; the one
   // that is not here stops a cached server.
   ...CODE_READ_ONLY,
@@ -2980,7 +3290,13 @@ if (SERVED_TOOLS.length !== ANNOTATED_TOOLS.length) {
 }
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: SERVED_TOOLS }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+// Never written to the offload directory. The query tool reads that directory,
+// and web_storage_state returns session cookies and localStorage: a file on
+// disk would outlive the session it authenticates, and the reply is JSON the
+// caller restores from, which a head+tail window would break.
+const OFFLOAD_EXEMPT = new Set(["agent_query_output", "web_storage_state"]);
+
+async function handleCallTool(request, extra) {
   const { name, arguments: args } = request.params;
   // Long-running tools (xcodebuild, export, validate, install) report progress
   // when the client sent a progressToken, and abandon their child process when
@@ -3068,9 +3384,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       return { content: [{ type: "text", text: String(result) }], isError: true };
     }
     // Prose payloads only: a tool with an outputSchema answers with JSON the
-    // caller parses, and a head+tail summary would break that parse. The query
-    // tool is exempt for the obvious reason.
-    if (!OUTPUT_SCHEMAS[name] && name !== "agent_query_output") {
+    // caller parses, and a head+tail summary would break that parse.
+    if (!OUTPUT_SCHEMAS[name] && !OFFLOAD_EXEMPT.has(name)) {
       const { text, offloaded } = offloadLargeText(name, String(result));
       if (offloaded) return { content: [{ type: "text", text }] };
       return withStructured(name, text);
@@ -3082,6 +3397,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       isError: true,
     };
   }
+}
+
+// Counted so a host that closes stdin still gets the answers it is owed before
+// the server exits.
+let inFlight = 0;
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  inFlight += 1;
+  try {
+    return await handleCallTool(request, extra);
+  } finally {
+    inFlight -= 1;
+  }
 });
 
 // Recorder children must not outlive the server: `simctl io recordVideo` has no
@@ -3093,8 +3420,41 @@ function stopRecorders() {
   }
 }
 
-process.on("SIGTERM", async () => { stopRecorders(); shutdownAllLsp(); await closeBrowser(); process.exit(0); });
-process.on("SIGINT", async () => { stopRecorders(); shutdownAllLsp(); await closeBrowser(); process.exit(0); });
+// One path for every way the server is told to go: children first, then the
+// browser (bounded, a wedged browser must not keep the process alive), then
+// the index handle.
+const BROWSER_CLOSE_BUDGET_MS = 3000;
+let shuttingDown = null;
+function shutdown() {
+  shuttingDown ??= (async () => {
+    stopRecorders();
+    shutdownAllLsp();
+    killAllSpawned("SIGTERM");
+    await Promise.race([closeBrowser(), new Promise((r) => setTimeout(r, BROWSER_CLOSE_BUDGET_MS).unref())]);
+    closeContextDb();
+    process.exit(0);
+  })();
+  return shuttingDown;
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+// A host that closes stdin is gone, and nobody is left to send action:"stop"
+// or close the browser. An open browser, an LSP server or a recorder would keep
+// this process alive indefinitely. Recorders stop at once so their files are
+// finalised; calls already in flight get up to STDIN_END_GRACE_MS to answer,
+// and then the same shutdown as SIGTERM runs.
+const STDIN_END_GRACE_MS = 5000;
+process.stdin.once("end", async () => {
+  stopRecorders();
+  const deadline = Date.now() + STDIN_END_GRACE_MS;
+  while (inFlight > 0 && Date.now() < deadline) await new Promise((r) => setTimeout(r, 50));
+  // The SDK writes a response after its handler settles; let that write reach
+  // stdout before exiting.
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => process.stdout.write("", () => r()));
+  await shutdown();
+});
 
 const transport = new StdioServerTransport();
 await server.connect(transport);