@hasna/testers 0.0.11 → 0.0.13

package/dist/mcp/index.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env bun
 // @bun
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -4902,6 +4906,22 @@ function updateScenario(id, input, version) {
   }
   return getScenario(existing.id);
 }
+function findStaleScenarios(days) {
+  const db2 = getDatabase();
+  const rows = db2.query(`
+    SELECT s.*, MAX(r.created_at) AS last_run_at
+    FROM scenarios s
+    LEFT JOIN results r ON r.scenario_id = s.id
+    GROUP BY s.id
+    HAVING last_run_at IS NULL
+       OR last_run_at < datetime('now', ? || ' days')
+    ORDER BY last_run_at ASC NULLS FIRST
+  `).all(`-${days}`);
+  return rows.map((row) => ({
+    ...scenarioFromRow(row),
+    lastRunAt: row.last_run_at
+  }));
+}
 function deleteScenario(id) {
   const db2 = getDatabase();
   const scenario = getScenario(id);
@@ -5106,6 +5126,9 @@ function updateResult(id, updates) {
   db2.query(`UPDATE results SET ${sets.join(", ")} WHERE id = ?`).run(...params);
   return getResult(existing.id);
 }
+function getResultsByRun(runId) {
+  return listResults(runId);
+}
 
 // src/db/screenshots.ts
 init_types();
@@ -5193,6 +5216,22 @@ function listAgents() {
   const rows = db2.query("SELECT * FROM agents ORDER BY created_at DESC").all();
   return rows.map(agentFromRow);
 }
+function heartbeatAgent(id) {
+  const db2 = getDatabase();
+  const affected = db2.query("UPDATE agents SET last_seen_at = ? WHERE id = ?").run(now(), id);
+  if (affected.changes === 0)
+    return null;
+  return getAgent(id);
+}
+function setAgentFocus(id, scenarioId) {
+  const db2 = getDatabase();
+  const agent = getAgent(id);
+  if (!agent)
+    return null;
+  const metadata = { ...agent.metadata ?? {}, focus: scenarioId };
+  db2.query("UPDATE agents SET metadata = ?, last_seen_at = ? WHERE id = ?").run(JSON.stringify(metadata), now(), id);
+  return getAgent(id);
+}
 
 // src/lib/browser.ts
 import { chromium as chromium2 } from "playwright";
@@ -6310,6 +6349,199 @@ async function pushFailedRunToLogs(run, failedResults, scenarios) {
   } catch {}
 }
 
+// src/lib/todos-connector.ts
+import { Database as Database2 } from "bun:sqlite";
+import { existsSync as existsSync4 } from "fs";
+import { join as join4 } from "path";
+import { homedir as homedir4 } from "os";
+init_types();
+function resolveTodosDbPath() {
+  const envPath = process.env["TODOS_DB_PATH"];
+  if (envPath)
+    return envPath;
+  return join4(homedir4(), ".todos", "todos.db");
+}
+function connectToTodos() {
+  const dbPath = resolveTodosDbPath();
+  if (!existsSync4(dbPath)) {
+    throw new TodosConnectionError(`Todos database not found at ${dbPath}. Install @hasna/todos or set TODOS_DB_PATH.`);
+  }
+  const db2 = new Database2(dbPath, { readonly: true });
+  db2.exec("PRAGMA foreign_keys = ON");
+  return db2;
+}
+function pullTasks(options = {}) {
+  const db2 = connectToTodos();
+  try {
+    let query = "SELECT id, short_id, title, description, status, priority, tags, project_id FROM tasks WHERE 1=1";
+    const params = [];
+    if (options.status) {
+      query += " AND status = ?";
+      params.push(options.status);
+    } else {
+      query += " AND status IN ('pending', 'in_progress')";
+    }
+    if (options.priority) {
+      query += " AND priority = ?";
+      params.push(options.priority);
+    }
+    if (options.projectName) {
+      const project = db2.query("SELECT id FROM projects WHERE name = ?").get(options.projectName);
+      if (project) {
+        query += " AND project_id = ?";
+        params.push(project.id);
+      }
+    }
+    query += " ORDER BY CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END";
+    const tasks = db2.query(query).all(...params);
+    if (options.tags && options.tags.length > 0) {
+      return tasks.filter((task) => {
+        const taskTags = JSON.parse(task.tags || "[]");
+        return options.tags.some((tag) => taskTags.includes(tag));
+      });
+    }
+    return tasks;
+  } finally {
+    db2.close();
+  }
+}
+function taskToScenarioInput(task, projectId) {
+  const tags = JSON.parse(task.tags || "[]");
+  const priority = ["low", "medium", "high", "critical"].includes(task.priority) ? task.priority : "medium";
+  const steps = [];
+  if (task.description) {
+    const lines = task.description.split(`
+`);
+    for (const line of lines) {
+      const match = line.match(/^\s*\d+[\.\)]\s*(.+)/);
+      if (match?.[1]) {
+        steps.push(match[1].trim());
+      }
+    }
+  }
+  return {
+    name: task.title.replace(/^(OPE\d+-\d+|[A-Z]+-\d+):\s*/, ""),
+    description: task.description || task.title,
+    steps,
+    tags,
+    priority,
+    projectId,
+    metadata: { todosTaskId: task.id, todosShortId: task.short_id }
+  };
+}
+function importFromTodos(options = {}) {
+  const tasks = pullTasks({
+    projectName: options.projectName,
+    tags: options.tags ?? ["qa", "test", "testing"],
+    priority: options.priority
+  });
+  const existing = listScenarios({ projectId: options.projectId });
+  const existingTodoIds = new Set(existing.filter((s) => s.metadata?.todosTaskId).map((s) => s.metadata.todosTaskId));
+  let imported = 0;
+  let skipped = 0;
+  for (const task of tasks) {
+    if (existingTodoIds.has(task.id)) {
+      skipped++;
+      continue;
+    }
+    const input = taskToScenarioInput(task, options.projectId);
+    createScenario(input);
+    imported++;
+  }
+  return { imported, skipped };
+}
+
+// src/lib/failure-pipeline.ts
+async function createFailureTasks(run, failedResults, scenarios) {
+  if (failedResults.length === 0)
+    return { created: 0, skipped: 0 };
+  const projectId = process.env["TESTERS_TODOS_PROJECT_ID"];
+  if (!projectId)
+    return { created: 0, skipped: 0 };
+  let db2 = null;
+  try {
+    db2 = connectToTodos();
+  } catch {
+    return { created: 0, skipped: 0 };
+  }
+  const scenarioMap = new Map(scenarios.map((s) => [s.id, s]));
+  let created = 0;
+  let skipped = 0;
+  try {
+    for (const result of failedResults) {
+      const scenario = scenarioMap.get(result.scenarioId);
+      const title = `BUG: [testers] ${scenario?.name ?? result.scenarioId} failed`;
+      const existing = db2.query("SELECT id FROM tasks WHERE title = ? AND status NOT IN ('completed', 'cancelled') LIMIT 1").get(title);
+      if (existing) {
+        skipped++;
+        continue;
+      }
+      const id = crypto.randomUUID();
+      const now2 = new Date().toISOString();
+      const description = [
+        `Test failure detected by open-testers.`,
+        ``,
+        `**Run:** ${run.id}`,
+        `**URL:** ${run.url}`,
+        `**Scenario:** ${scenario?.name ?? result.scenarioId}`,
+        `**Status:** ${result.status}`,
+        result.error ? `**Error:** ${result.error}` : null,
+        result.reasoning ? `**Reasoning:** ${result.reasoning.slice(0, 500)}` : null,
+        `**Duration:** ${result.durationMs ? `${(result.durationMs / 1000).toFixed(1)}s` : "N/A"}`,
+        `**Tokens:** ${result.tokensUsed ?? 0}`
+      ].filter(Boolean).join(`
+`);
+      try {
+        db2.query(`
+          INSERT INTO tasks (id, short_id, title, description, status, priority, tags, project_id, version, created_at, updated_at)
+          VALUES (?, ?, ?, ?, 'pending', 'high', ?, ?, 1, ?, ?)
+        `).run(id, `BUG-${id.slice(0, 6)}`, title, description, JSON.stringify(["bug", "testers", "auto-created"]), projectId, now2, now2);
+        created++;
+      } catch {
+        skipped++;
+      }
+    }
+  } finally {
+    db2.close();
+  }
+  return { created, skipped };
+}
+async function notifyFailureToConversations(run, failedResults, scenarios) {
+  const baseUrl = process.env["TESTERS_CONVERSATIONS_URL"];
+  const space = process.env["TESTERS_CONVERSATIONS_SPACE"];
+  if (!baseUrl || !space)
+    return;
+  const scenarioMap = new Map(scenarios.map((s) => [s.id, s]));
+  const total = run.total;
+  const failedCount = failedResults.length;
+  const passedCount = run.passed;
+  const failureLines = failedResults.slice(0, 5).map((r) => {
+    const name = scenarioMap.get(r.scenarioId)?.name ?? r.scenarioId;
+    const err = r.error ? ` \u2014 ${r.error.slice(0, 120)}` : "";
+    return `  \u274C ${name}${err}`;
+  });
+  const extra = failedResults.length > 5 ? `  \u2026 and ${failedResults.length - 5} more` : "";
+  const message = [
+    `\uD83D\uDEA8 **Testers run failed** \u2014 ${failedCount}/${total} scenarios failed`,
+    ``,
+    `**URL:** ${run.url}`,
+    `**Run ID:** \`${run.id}\``,
+    `**Pass rate:** ${passedCount}/${total}`,
+    ``,
+    `**Failures:**`,
+    ...failureLines,
+    extra
+  ].filter((l) => l !== "").join(`
+`);
+  try {
+    await fetch(`${baseUrl.replace(/\/$/, "")}/api/spaces/${encodeURIComponent(space)}/messages`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ content: message, from: "testers" })
+    });
+  } catch {}
+}
+
 // src/lib/runner.ts
 var eventHandler = null;
 function emit(event) {
@@ -6543,6 +6775,8 @@ async function runBatch(scenarios, options) {
   if (finalRun.status === "failed") {
     const failedResults = results.filter((r) => r.status === "failed" || r.status === "error");
     pushFailedRunToLogs(finalRun, failedResults, scenarios).catch(() => {});
+    createFailureTasks(finalRun, failedResults, scenarios).catch(() => {});
+    notifyFailureToConversations(finalRun, failedResults, scenarios).catch(() => {});
   }
   return { run: finalRun, results };
 }
@@ -6656,106 +6890,54 @@ function estimateCost(model, tokens) {
   return tokens / 1e6 * costPer1M * 100;
 }
 
-// src/lib/todos-connector.ts
-import { Database as Database2 } from "bun:sqlite";
-import { existsSync as existsSync4 } from "fs";
-import { join as join4 } from "path";
-import { homedir as homedir4 } from "os";
-init_types();
-function resolveTodosDbPath() {
-  const envPath = process.env["TODOS_DB_PATH"];
-  if (envPath)
-    return envPath;
-  return join4(homedir4(), ".todos", "todos.db");
-}
-function connectToTodos() {
-  const dbPath = resolveTodosDbPath();
-  if (!existsSync4(dbPath)) {
-    throw new TodosConnectionError(`Todos database not found at ${dbPath}. Install @hasna/todos or set TODOS_DB_PATH.`);
-  }
-  const db2 = new Database2(dbPath, { readonly: true });
-  db2.exec("PRAGMA foreign_keys = ON");
-  return db2;
-}
-function pullTasks(options = {}) {
-  const db2 = connectToTodos();
-  try {
-    let query = "SELECT id, short_id, title, description, status, priority, tags, project_id FROM tasks WHERE 1=1";
-    const params = [];
-    if (options.status) {
-      query += " AND status = ?";
-      params.push(options.status);
-    } else {
-      query += " AND status IN ('pending', 'in_progress')";
-    }
-    if (options.priority) {
-      query += " AND priority = ?";
-      params.push(options.priority);
-    }
-    if (options.projectName) {
-      const project = db2.query("SELECT id FROM projects WHERE name = ?").get(options.projectName);
-      if (project) {
-        query += " AND project_id = ?";
-        params.push(project.id);
+// src/lib/affected.ts
+function globToRegex(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\x00DS\x00").replace(/\*/g, "[^/]*").replace(/\x00DS\x00/g, ".*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+function matchFilesToScenarios(filePaths, scenarios, mappings = []) {
+  if (filePaths.length === 0)
+    return scenarios;
+  const compiledMappings = mappings.map((m) => ({
+    regex: globToRegex(m.glob),
+    tags: m.tags
+  }));
+  const normPaths = filePaths.map((p) => p.replace(/\\/g, "/").toLowerCase());
+  const matchedIds = new Set;
+  for (const scenario of scenarios) {
+    let matched = false;
+    if (!matched) {
+      for (const { regex, tags } of compiledMappings) {
+        if (normPaths.some((fp) => regex.test(fp)) && tags.some((tag) => scenario.tags.includes(tag))) {
+          matched = true;
+          break;
+        }
       }
     }
-    query += " ORDER BY CASE priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 WHEN 'low' THEN 3 END";
-    const tasks = db2.query(query).all(...params);
-    if (options.tags && options.tags.length > 0) {
-      return tasks.filter((task) => {
-        const taskTags = JSON.parse(task.tags || "[]");
-        return options.tags.some((tag) => taskTags.includes(tag));
-      });
+    if (!matched && scenario.targetPath) {
+      const segments = scenario.targetPath.replace(/^\//, "").split("/").filter((s) => s.length > 2);
+      if (segments.some((seg) => normPaths.some((fp) => fp.includes(seg.toLowerCase())))) {
+        matched = true;
+      }
     }
-    return tasks;
-  } finally {
-    db2.close();
-  }
-}
-function taskToScenarioInput(task, projectId) {
-  const tags = JSON.parse(task.tags || "[]");
-  const priority = ["low", "medium", "high", "critical"].includes(task.priority) ? task.priority : "medium";
-  const steps = [];
-  if (task.description) {
-    const lines = task.description.split(`
-`);
-    for (const line of lines) {
-      const match = line.match(/^\s*\d+[\.\)]\s*(.+)/);
-      if (match?.[1]) {
-        steps.push(match[1].trim());
+    if (!matched) {
+      for (const tag of scenario.tags) {
+        if (tag.length > 2 && normPaths.some((fp) => fp.includes(tag.toLowerCase()))) {
+          matched = true;
+          break;
+        }
       }
     }
-  }
-  return {
-    name: task.title.replace(/^(OPE\d+-\d+|[A-Z]+-\d+):\s*/, ""),
-    description: task.description || task.title,
-    steps,
-    tags,
-    priority,
-    projectId,
-    metadata: { todosTaskId: task.id, todosShortId: task.short_id }
-  };
-}
-function importFromTodos(options = {}) {
-  const tasks = pullTasks({
-    projectName: options.projectName,
-    tags: options.tags ?? ["qa", "test", "testing"],
-    priority: options.priority
-  });
-  const existing = listScenarios({ projectId: options.projectId });
-  const existingTodoIds = new Set(existing.filter((s) => s.metadata?.todosTaskId).map((s) => s.metadata.todosTaskId));
-  let imported = 0;
-  let skipped = 0;
-  for (const task of tasks) {
-    if (existingTodoIds.has(task.id)) {
-      skipped++;
-      continue;
+    if (!matched) {
+      const nameWords = scenario.name.toLowerCase().split(/[\s\-_/]+/).filter((w) => w.length > 3);
+      if (nameWords.some((word) => normPaths.some((fp) => fp.includes(word)))) {
+        matched = true;
+      }
     }
-    const input = taskToScenarioInput(task, options.projectId);
-    createScenario(input);
-    imported++;
+    if (matched)
+      matchedIds.add(scenario.id);
   }
-  return { imported, skipped };
+  return scenarios.filter((s) => matchedIds.has(s.id));
 }
 
 // src/db/schedules.ts
@@ -7103,6 +7285,63 @@ class Scheduler {
 
 // src/mcp/index.ts
 init_database();
+init_types();
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function notFoundErr(id, label = "Resource") {
+  return Object.assign(new Error(`${label} not found: ${id}`), { name: "NotFoundError" });
+}
+function errorResponse(e, context) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  if (e instanceof VersionConflictError) {
+    const payload2 = {
+      error: {
+        code: "VERSION_CONFLICT",
+        message: err.message,
+        retryable: true,
+        hint: "Fetch the scenario with get_scenario to get the current version, then retry.",
+        currentVersion: null
+      }
+    };
+    if (context?.fetchCurrent) {
+      try {
+        const current = context.fetchCurrent();
+        if (current && typeof current.version === "number") {
+          payload2.error.currentVersion = current.version;
+          payload2.error.hint = `Retry with version: ${current.version}`;
+        }
+      } catch {}
+    }
+    return { content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }], isError: true };
+  }
+  const name = err.name ?? "Error";
+  const msg = err.message ?? String(e);
+  let code = "INTERNAL_ERROR";
+  let retryable = false;
+  let hint;
+  if (name === "NotFoundError" || name === "ScenarioNotFoundError" || msg.toLowerCase().includes("not found")) {
+    code = "NOT_FOUND";
+    retryable = false;
+    hint = "Check the ID or short ID and try again.";
+  } else if (msg.toLowerCase().includes("timeout")) {
+    code = "TIMEOUT";
+    retryable = true;
+    hint = "The operation timed out. Try again.";
+  } else if (msg.toLowerCase().includes("unique") || msg.toLowerCase().includes("already exists")) {
+    code = "CONFLICT";
+    retryable = false;
+    hint = "A resource with this identifier already exists.";
+  }
+  const payload = {
+    error: { code, message: msg, retryable }
+  };
+  if (hint)
+    payload.error.hint = hint;
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], isError: true };
+}
+var ID_DESC = "Accepts either the full UUID (e.g. 'abc123...') or the short ID (e.g. 'sc-1').";
+var MODEL_DESC = "Model to use. Values: 'quick' (claude-haiku-4-5, cheapest), 'thorough' (claude-sonnet-4-6, balanced), 'deep' (claude-opus-4-6, most capable). Default: 'quick'.";
 var server = new McpServer({
   name: "testers",
   version: "0.0.1"
@@ -7113,47 +7352,27 @@ server.tool("create_scenario", "Create a new test scenario", {
   steps: exports_external.array(exports_external.string()).optional().describe("Ordered test steps"),
   tags: exports_external.array(exports_external.string()).optional().describe("Tags for filtering"),
   priority: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Scenario priority"),
-  model: exports_external.string().optional().describe("AI model to use"),
+  model: exports_external.string().optional().describe(MODEL_DESC),
   targetPath: exports_external.string().optional().describe("URL path to navigate to"),
   requiresAuth: exports_external.boolean().optional().describe("Whether scenario requires authentication")
 }, async ({ name, description, steps, tags, priority, model, targetPath, requiresAuth }) => {
   try {
     const scenario = createScenario({ name, description, steps, tags, priority, model, targetPath, requiresAuth });
-    return { content: [{ type: "text", text: `Created scenario ${scenario.shortId}: "${scenario.name}" (id: ${scenario.id})` }] };
+    return json(scenario);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
-server.tool("get_scenario", "Get a scenario by ID or short ID", {
-  id: exports_external.string().describe("Scenario ID or short ID")
+server.tool("get_scenario", `Get a scenario by ID or short ID. ${ID_DESC}`, {
+  id: exports_external.string().describe(`Scenario ID or short ID. ${ID_DESC}`)
 }, async ({ id }) => {
   try {
     const scenario = getScenario(id) ?? getScenarioByShortId(id);
-    if (!scenario) {
-      return { content: [{ type: "text", text: `ScenarioNotFoundError: Scenario not found: ${id}` }], isError: true };
-    }
-    const text = [
-      `Scenario: ${scenario.name} (${scenario.shortId})`,
-      `ID: ${scenario.id}`,
-      `Description: ${scenario.description}`,
-      `Priority: ${scenario.priority}`,
-      `Tags: ${scenario.tags.join(", ") || "none"}`,
-      `Steps: ${scenario.steps.length > 0 ? `
-  ` + scenario.steps.map((s, i) => `${i + 1}. ${s}`).join(`
-  `) : "none"}`,
-      `Model: ${scenario.model ?? "default"}`,
-      `Target path: ${scenario.targetPath ?? "none"}`,
-      `Requires auth: ${scenario.requiresAuth}`,
-      `Version: ${scenario.version}`,
-      `Created: ${scenario.createdAt}`,
-      `Updated: ${scenario.updatedAt}`
-    ].join(`
-`);
-    return { content: [{ type: "text", text }] };
+    if (!scenario)
+      return errorResponse(notFoundErr(id, "Scenario"));
+    return json(scenario);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("list_scenarios", "List test scenarios with optional filters", {
@@ -7164,20 +7383,13 @@ server.tool("list_scenarios", "List test scenarios with optional filters", {
 }, async ({ projectId, tags, priority, limit }) => {
   try {
     const scenarios = listScenarios({ projectId, tags, priority, limit });
-    if (scenarios.length === 0) {
-      return { content: [{ type: "text", text: "No scenarios found." }] };
-    }
-    const lines = scenarios.map((s) => `[${s.shortId}] ${s.name} \u2014 ${s.priority} \u2014 tags: ${s.tags.join(", ") || "none"}`);
-    return { content: [{ type: "text", text: `${scenarios.length} scenario(s):
-${lines.join(`
-`)}` }] };
+    return json({ items: scenarios, total: scenarios.length });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
-server.tool("update_scenario", "Update an existing scenario (requires version for optimistic locking)", {
-  id: exports_external.string().describe("Scenario ID or short ID"),
+server.tool("update_scenario", `Update an existing scenario (requires version for optimistic locking). ${ID_DESC}`, {
+  id: exports_external.string().describe(`Scenario ID or short ID. ${ID_DESC}`),
   name: exports_external.string().optional().describe("New name"),
   description: exports_external.string().optional().describe("New description"),
   steps: exports_external.array(exports_external.string()).optional().describe("New steps"),
@@ -7188,24 +7400,23 @@ server.tool("update_scenario", "Update an existing scenario (requires version fo
 }, async ({ id, name, description, steps, tags, priority, model, version }) => {
   try {
     const scenario = updateScenario(id, { name, description, steps, tags, priority, model }, version);
-    return { content: [{ type: "text", text: `Updated scenario ${scenario.shortId}: "${scenario.name}" (version: ${scenario.version})` }] };
+    return json(scenario);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error, {
+      fetchCurrent: () => getScenario(id) ?? getScenarioByShortId(id)
+    });
   }
 });
-server.tool("delete_scenario", "Delete a scenario by ID", {
-  id: exports_external.string().describe("Scenario ID or short ID")
+server.tool("delete_scenario", `Delete a scenario by ID. ${ID_DESC}`, {
+  id: exports_external.string().describe(`Scenario ID or short ID. ${ID_DESC}`)
 }, async ({ id }) => {
   try {
     const deleted = deleteScenario(id);
-    if (!deleted) {
-      return { content: [{ type: "text", text: `ScenarioNotFoundError: Scenario not found: ${id}` }], isError: true };
-    }
-    return { content: [{ type: "text", text: `Deleted scenario: ${id}` }] };
+    if (!deleted)
+      return errorResponse(notFoundErr(id, "Scenario"));
+    return json({ deleted: true, id });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("run_scenarios", "Run test scenarios against a URL", {
@@ -7213,50 +7424,27 @@ server.tool("run_scenarios", "Run test scenarios against a URL", {
   tags: exports_external.array(exports_external.string()).optional().describe("Filter scenarios by tags"),
   scenarioIds: exports_external.array(exports_external.string()).optional().describe("Run specific scenario IDs"),
   priority: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Filter by priority"),
-  model: exports_external.string().optional().describe("AI model to use"),
+  model: exports_external.string().optional().describe(MODEL_DESC),
   headed: exports_external.boolean().optional().describe("Run browser in headed mode"),
   parallel: exports_external.number().optional().describe("Number of parallel workers")
 }, async ({ url, tags, scenarioIds, priority, model, headed, parallel }) => {
   try {
     const { runId, scenarioCount } = startRunAsync({ url, tags, scenarioIds, priority, model, headed, parallel });
-    const text = [
-      `Run started: ${runId}`,
-      `Scenarios: ${scenarioCount}`,
-      `URL: ${url}`,
-      `Status: running (async)`,
-      ``,
-      `Poll with get_run to check progress.`
-    ].join(`
-`);
-    return { content: [{ type: "text", text }] };
+    return json({ runId, scenarioCount, url, status: "running", message: "Poll with get_run to check progress." });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
-server.tool("get_run", "Get details of a test run", {
-  id: exports_external.string().describe("Run ID")
+server.tool("get_run", `Get details of a test run. ${ID_DESC}`, {
+  id: exports_external.string().describe(`Run ID. ${ID_DESC}`)
 }, async ({ id }) => {
   try {
     const run = getRun(id);
-    if (!run) {
-      return { content: [{ type: "text", text: `RunNotFoundError: Run not found: ${id}` }], isError: true };
-    }
-    const text = [
-      `Run: ${run.id}`,
-      `Status: ${run.status}`,
-      `URL: ${run.url}`,
-      `Model: ${run.model}`,
-      `Total: ${run.total} | Passed: ${run.passed} | Failed: ${run.failed}`,
-      `Parallel: ${run.parallel} | Headed: ${run.headed}`,
-      `Started: ${run.startedAt}`,
-      run.finishedAt ? `Finished: ${run.finishedAt}` : "Finished: in progress"
-    ].join(`
-`);
-    return { content: [{ type: "text", text }] };
+    if (!run)
+      return errorResponse(notFoundErr(id, "Run"));
+    return json(run);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("list_runs", "List test runs with optional filters", {
@@ -7265,50 +7453,61 @@ server.tool("list_runs", "List test runs with optional filters", {
 }, async ({ status, limit }) => {
   try {
     const runs = listRuns({ status, limit });
-    if (runs.length === 0) {
-      return { content: [{ type: "text", text: "No runs found." }] };
-    }
-    const lines = runs.map((r) => `[${r.id.slice(0, 8)}] ${r.status} \u2014 ${r.total} scenarios \u2014 ${r.passed} passed, ${r.failed} failed \u2014 ${r.startedAt}`);
-    return { content: [{ type: "text", text: `${runs.length} run(s):
-${lines.join(`
-`)}` }] };
+    return json({ items: runs, total: runs.length });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
-server.tool("get_results", "Get test results for a run", {
-  runId: exports_external.string().describe("Run ID")
-}, async ({ runId }) => {
+server.tool("get_results", `Get test results for a run. Optionally filter by status and/or scenarioId. Each result includes AI reasoning when available. ${ID_DESC}`, {
+  runId: exports_external.string().describe(`Run ID. ${ID_DESC}`),
+  status: exports_external.enum(["passed", "failed", "error", "running"]).optional().describe("Filter by result status"),
+  scenarioId: exports_external.string().optional().describe("Filter by scenario ID (full or partial)")
+}, async ({ runId, status, scenarioId }) => {
   try {
-    const results = listResults(runId);
-    if (results.length === 0) {
-      return { content: [{ type: "text", text: `No results found for run: ${runId}` }] };
-    }
-    const lines = results.map((r) => `[${r.status}] scenario:${r.scenarioId.slice(0, 8)} \u2014 ${r.stepsCompleted}/${r.stepsTotal} steps \u2014 ${r.durationMs}ms \u2014 ${r.model}${r.error ? ` \u2014 error: ${r.error}` : ""}`);
-    return { content: [{ type: "text", text: `${results.length} result(s) for run ${runId.slice(0, 8)}:
-${lines.join(`
-`)}` }] };
+    let results = listResults(runId);
+    if (status) {
+      results = results.filter((r) => r.status === status);
+    }
+    if (scenarioId) {
+      results = results.filter((r) => r.scenarioId === scenarioId || r.scenarioId.startsWith(scenarioId));
+    }
+    return json({ items: results, total: results.length });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
-server.tool("get_screenshots", "Get screenshots for a test result", {
-  resultId: exports_external.string().describe("Result ID")
+var MAX_BASE64_SCREENSHOTS = 5;
+server.tool("get_screenshots", `Get screenshots for a test result. Returns base64-encoded image data for up to 5 screenshots. If more than 5 exist, only metadata is returned with truncated:true. ${ID_DESC}`, {
+  resultId: exports_external.string().describe(`Result ID. ${ID_DESC}`)
 }, async ({ resultId }) => {
   try {
     const screenshots = listScreenshots(resultId);
     if (screenshots.length === 0) {
-      return { content: [{ type: "text", text: `No screenshots found for result: ${resultId}` }] };
+      return json({ items: [], total: 0 });
     }
-    const lines = screenshots.map((s) => `Step ${s.stepNumber}: ${s.action} \u2014 ${s.width}x${s.height} \u2014 ${s.filePath}`);
-    return { content: [{ type: "text", text: `${screenshots.length} screenshot(s):
-${lines.join(`
-`)}` }] };
+    const truncated = screenshots.length > MAX_BASE64_SCREENSHOTS;
+    const withBase64 = await Promise.all(screenshots.map(async (s, index) => {
+      let base64 = null;
+      let note;
+      if (!truncated || index < MAX_BASE64_SCREENSHOTS) {
+        try {
+          const file = Bun.file(s.filePath);
+          const exists = await file.exists();
+          if (exists) {
+            const buffer = await file.arrayBuffer();
+            base64 = `data:image/png;base64,${Buffer.from(buffer).toString("base64")}`;
+          } else {
+            note = `File not found on disk: ${s.filePath}`;
+          }
+        } catch {
+          note = `Failed to read file: ${s.filePath}`;
+        }
+      }
+      return { id: s.id, stepNumber: s.stepNumber, description: s.description, pageUrl: s.pageUrl, filePath: s.filePath, base64, note, width: s.width, height: s.height, createdAt: s.timestamp };
+    }));
+    return json({ truncated, total: screenshots.length, items: withBase64 });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("register_project", "Register or ensure a project exists", {
@@ -7318,25 +7517,17 @@ server.tool("register_project", "Register or ensure a project exists", {
 }, async ({ name, path, description }) => {
   try {
     const project = description ? createProject({ name, path, description }) : ensureProject(name, path);
-    return { content: [{ type: "text", text: `Project "${project.name}" registered (id: ${project.id})` }] };
+    return json(project);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("list_projects", "List all registered projects", {}, async () => {
   try {
     const projects = listProjects();
-    if (projects.length === 0) {
-      return { content: [{ type: "text", text: "No projects registered." }] };
-    }
-    const lines = projects.map((p) => `[${p.id.slice(0, 8)}] ${p.name}${p.path ? ` \u2014 ${p.path}` : ""}${p.description ? ` \u2014 ${p.description}` : ""}`);
-    return { content: [{ type: "text", text: `${projects.length} project(s):
-${lines.join(`
-`)}` }] };
+    return json({ items: projects, total: projects.length });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("register_agent", "Register an agent (idempotent \u2014 returns existing if name matches)", {
@@ -7346,25 +7537,17 @@ server.tool("register_agent", "Register an agent (idempotent \u2014 returns exis
 }, async ({ name, description, role }) => {
   try {
     const agent = registerAgent({ name, description, role });
-    return { content: [{ type: "text", text: `Agent "${agent.name}" registered (id: ${agent.id})` }] };
+    return json(agent);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("list_agents", "List all registered agents", {}, async () => {
   try {
     const agents = listAgents();
-    if (agents.length === 0) {
-      return { content: [{ type: "text", text: "No agents registered." }] };
-    }
-    const lines = agents.map((a) => `[${a.id.slice(0, 8)}] ${a.name}${a.role ? ` (${a.role})` : ""} \u2014 last seen: ${a.lastSeenAt}`);
-    return { content: [{ type: "text", text: `${agents.length} agent(s):
-${lines.join(`
-`)}` }] };
+    return json({ items: agents, total: agents.length });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("import_from_todos", "Import test scenarios from the todos database", {
@@ -7374,10 +7557,9 @@ server.tool("import_from_todos", "Import test scenarios from the todos database"
 }, async ({ projectName, tags, projectId }) => {
   try {
     const result = importFromTodos({ projectName, tags, projectId });
-    return { content: [{ type: "text", text: `Imported ${result.imported} scenario(s), skipped ${result.skipped} duplicate(s)` }] };
+    return json(result);
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("get_status", "Get system status: DB path, API key, scenario and run counts", {}, async () => {
@@ -7387,18 +7569,27 @@ server.tool("get_status", "Get system status: DB path, API key, scenario and run
     const scenarioCount = db2.query("SELECT COUNT(*) as count FROM scenarios").get().count;
     const runCount = db2.query("SELECT COUNT(*) as count FROM runs").get().count;
     const hasApiKey = !!(config.anthropicApiKey || process.env["ANTHROPIC_API_KEY"]);
-    const text = [
-      `DB: ${process.env["TESTERS_DB_PATH"] || "~/.testers/testers.db"}`,
-      `API key: ${hasApiKey ? "configured" : "not set"}`,
-      `Scenarios: ${scenarioCount}`,
-      `Runs: ${runCount}`,
-      `Default model: ${config.defaultModel}`
-    ].join(`
-`);
-    return { content: [{ type: "text", text }] };
+    return json({
+      dbPath: process.env["TESTERS_DB_PATH"] || "~/.testers/testers.db",
+      apiKey: hasApiKey ? "configured" : "not set",
+      scenarioCount,
+      runCount,
+      defaultModel: config.defaultModel
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("scenario_exists", "Check whether a scenario with the given name exists (exact match). Returns { exists, scenario }.", {
+  name: exports_external.string().describe("Scenario name to look up (exact match)"),
+  projectId: exports_external.string().optional().describe("Restrict search to a specific project ID")
+}, async ({ name, projectId }) => {
+  try {
+    const scenarios = listScenarios({ projectId });
+    const scenario = scenarios.find((s) => s.name === name) ?? null;
+    return json({ exists: scenario !== null, scenario });
   } catch (error) {
-    const e = error instanceof Error ? error : new Error(String(error));
-    return { content: [{ type: "text", text: `${e.name}: ${e.message}` }], isError: true };
+    return errorResponse(error);
   }
 });
 server.tool("create_schedule", {
@@ -7407,7 +7598,7 @@ server.tool("create_schedule", {
   url: exports_external.string().describe("Target URL to test"),
   tags: exports_external.array(exports_external.string()).optional().describe("Filter scenarios by tags"),
   priority: exports_external.string().optional().describe("Filter scenarios by priority"),
-  model: exports_external.string().optional().describe("AI model"),
+  model: exports_external.string().optional().describe(MODEL_DESC),
   headed: exports_external.boolean().optional().describe("Run headed"),
   parallel: exports_external.number().optional().describe("Parallel count"),
   projectId: exports_external.string().optional().describe("Project ID")
@@ -7424,9 +7615,9 @@ server.tool("create_schedule", {
       projectId: params.projectId
     });
     const nextRun = getNextRunTime(schedule.cronExpression);
-    return { content: [{ type: "text", text: `Schedule created: ${schedule.id.slice(0, 8)} | ${schedule.name} | cron: ${schedule.cronExpression} | next: ${nextRun.toISOString()}` }] };
+    return json({ ...schedule, nextRunAt: nextRun.toISOString() });
   } catch (e) {
-    return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    return errorResponse(e);
   }
 });
 server.tool("list_schedules", {
@@ -7434,35 +7625,239 @@ server.tool("list_schedules", {
   enabled: exports_external.boolean().optional(),
   limit: exports_external.number().optional()
 }, async (params) => {
-  const schedules = listSchedules({ projectId: params.projectId, enabled: params.enabled, limit: params.limit });
-  if (schedules.length === 0)
-    return { content: [{ type: "text", text: "No schedules found." }] };
-  const lines = schedules.map((s) => `${s.id.slice(0, 8)} | ${s.name} | ${s.cronExpression} | ${s.url} | ${s.enabled ? "enabled" : "disabled"} | next: ${s.nextRunAt ?? "N/A"}`);
-  return { content: [{ type: "text", text: lines.join(`
-`) }] };
+  try {
+    const schedules = listSchedules({ projectId: params.projectId, enabled: params.enabled, limit: params.limit });
+    return json({ items: schedules, total: schedules.length });
+  } catch (e) {
+    return errorResponse(e);
+  }
 });
 server.tool("enable_schedule", { id: exports_external.string().describe("Schedule ID") }, async (params) => {
   try {
     const schedule = updateSchedule(params.id, { enabled: true });
-    return { content: [{ type: "text", text: `Schedule ${schedule.name} enabled.` }] };
+    return json(schedule);
   } catch (e) {
-    return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    return errorResponse(e);
   }
 });
 server.tool("disable_schedule", { id: exports_external.string().describe("Schedule ID") }, async (params) => {
   try {
     const schedule = updateSchedule(params.id, { enabled: false });
-    return { content: [{ type: "text", text: `Schedule ${schedule.name} disabled.` }] };
+    return json(schedule);
   } catch (e) {
-    return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    return errorResponse(e);
   }
 });
 server.tool("delete_schedule", { id: exports_external.string().describe("Schedule ID") }, async (params) => {
   try {
     const deleted = deleteSchedule(params.id);
-    return { content: [{ type: "text", text: deleted ? "Schedule deleted." : "Schedule not found." }] };
+    if (!deleted)
+      return errorResponse(notFoundErr(params.id, "Schedule"));
+    return json({ deleted: true, id: params.id });
   } catch (e) {
-    return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    return errorResponse(e);
+  }
+});
+server.tool("wait_for_run", "Poll a run until it reaches a terminal status (passed, failed, error, or cancelled). Blocks until done or timeout.", {
+  runId: exports_external.string().describe("Run ID to wait for"),
+  timeoutMs: exports_external.number().optional().describe("Max wait time in ms (default 300000)"),
+  pollIntervalMs: exports_external.number().optional().describe("Poll interval in ms (default 3000)")
+}, async ({ runId, timeoutMs = 300000, pollIntervalMs = 3000 }) => {
+  try {
+    const terminalStatuses = new Set(["passed", "failed", "error", "cancelled"]);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const run = getRun(runId);
+      if (!run)
+        return errorResponse(notFoundErr(runId, "Run"));
+      if (terminalStatuses.has(run.status)) {
+        const results = getResultsByRun(runId);
+        const passed = results.filter((r) => r.status === "passed").length;
+        const failed = results.filter((r) => r.status === "failed" || r.status === "error").length;
+        return json({ ...run, passedCount: passed, failedCount: failed });
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    return errorResponse(Object.assign(new Error(`Run ${runId} did not complete within ${timeoutMs}ms`), { name: "TimeoutError" }));
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("get_run_stats", "Get aggregate statistics for a run: pass rate, cost, token usage, duration", {
+  runId: exports_external.string().describe("Run ID")
+}, async ({ runId }) => {
+  try {
+    const run = getRun(runId);
+    if (!run)
+      return errorResponse(notFoundErr(runId, "Run"));
+    const results = getResultsByRun(runId);
+    const total = results.length;
+    const passed = results.filter((r) => r.status === "passed").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    const errors2 = results.filter((r) => r.status === "error").length;
+    const passRate = total > 0 ? Math.round(passed / total * 100) : 0;
+    const totalCostCents = results.reduce((sum, r) => sum + (r.costCents ?? 0), 0);
+    const totalTokens = results.reduce((sum, r) => sum + (r.tokensUsed ?? 0), 0);
+    const durations = results.filter((r) => r.durationMs != null && r.durationMs > 0).map((r) => r.durationMs);
+    const avgDurationMs = durations.length > 0 ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length) : 0;
+    return json({ runId, status: run.status, total, passed, failed, errors: errors2, passRate, totalCostCents, totalTokens, avgDurationMs, startedAt: run.startedAt, completedAt: run.finishedAt ?? null });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("get_run_costs", "Get cost breakdown for a run, with per-scenario detail", {
+  runId: exports_external.string().describe("Run ID")
+}, async ({ runId }) => {
+  try {
+    const run = getRun(runId);
+    if (!run)
+      return errorResponse(notFoundErr(runId, "Run"));
+    const results = getResultsByRun(runId);
+    const totalCostCents = results.reduce((sum, r) => sum + (r.costCents ?? 0), 0);
+    const totalTokens = results.reduce((sum, r) => sum + (r.tokensUsed ?? 0), 0);
+    const byScenario = results.map((r) => {
+      const scenario = getScenario(r.scenarioId);
+      return { scenarioId: r.scenarioId, scenarioName: scenario?.name ?? r.scenarioId, costCents: r.costCents ?? 0, tokens: r.tokensUsed ?? 0, status: r.status };
+    });
+    return json({ runId, totalCostCents, totalTokens, byScenario });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("batch_create_scenarios", "Create multiple scenarios in a single call. Returns created scenarios and any failures.", {
+  scenarios: exports_external.array(exports_external.object({
+    name: exports_external.string().describe("Scenario name"),
+    url: exports_external.string().optional().describe("Target URL (stored as targetPath)"),
+    description: exports_external.string().optional().describe("What this scenario tests"),
+    steps: exports_external.array(exports_external.string()).optional().describe("Ordered test steps"),
+    tags: exports_external.array(exports_external.string()).optional().describe("Tags for filtering"),
+    priority: exports_external.enum(["low", "medium", "high", "critical"]).optional().describe("Scenario priority")
+  })).describe("Array of scenarios to create")
+}, async ({ scenarios }) => {
+  const created = [];
+  const failed = [];
+  for (let i = 0;i < scenarios.length; i++) {
+    const input = scenarios[i];
+    try {
+      const scenario = createScenario({
+        name: input.name,
+        description: input.description ?? input.name,
+        steps: input.steps,
+        tags: input.tags,
+        priority: input.priority,
+        targetPath: input.url
+      });
+      created.push(scenario);
+    } catch (error) {
+      const e = error instanceof Error ? error : new Error(String(error));
+      failed.push({ index: i, name: input.name, error: e.message });
+    }
+  }
+  const lines = [
+    `Created: ${created.length} scenario(s)`,
+    ...created.map((s) => `  [${s.shortId}] ${s.name}`)
+  ];
+  return json({ created, failed });
+});
+server.tool("cancel_run", "Mark a run as cancelled in the database. In-flight browser processes may still complete but results will be ignored.", {
+  runId: exports_external.string().describe("Run ID to cancel")
+}, async ({ runId }) => {
+  try {
+    const run = getRun(runId);
+    if (!run)
+      return errorResponse(notFoundErr(runId, "Run"));
+    updateRun(runId, { status: "cancelled", finished_at: new Date().toISOString() });
+    return json({ cancelled: true, runId });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("get_tags", "List all unique tags across scenarios, optionally filtered by project", {
+  projectId: exports_external.string().optional().describe("Filter by project ID")
+}, async ({ projectId }) => {
+  try {
+    const scenarios = listScenarios({ projectId });
+    const tagSet = new Set;
+    for (const s of scenarios) {
+      for (const tag of s.tags) {
+        tagSet.add(tag);
+      }
+    }
+    const tags = Array.from(tagSet).sort();
+    return json({ tags, total: tags.length });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("get_stale_scenarios", "List scenarios that have not been run recently (or never run)", {
+  days: exports_external.number().optional().describe("Scenarios not run in this many days are considered stale (default 7)"),
+  projectId: exports_external.string().optional().describe("Filter by project ID")
+}, async ({ days = 7, projectId }) => {
+  try {
+    let scenarios = findStaleScenarios(days);
+    if (projectId) {
+      scenarios = scenarios.filter((s) => s.projectId === projectId);
+    }
+    return json({ items: scenarios, total: scenarios.length });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("run_affected_scenarios", "Run only the scenarios relevant to a set of changed files. Matches files to scenarios via explicit glob\u2192tag rules, targetPath keywords, and name/tag inference. Returns immediately \u2014 poll with get_run.", {
+  url: exports_external.string().describe("Target URL to test against"),
+  filePaths: exports_external.array(exports_external.string()).describe("Changed file paths (relative or absolute)"),
+  mappings: exports_external.array(exports_external.object({
+    glob: exports_external.string().describe("File glob pattern (supports * and **)"),
+    tags: exports_external.array(exports_external.string()).describe("Run scenarios tagged with these if glob matches")
+  })).optional().describe("Explicit file glob \u2192 scenario tag mappings"),
+  projectId: exports_external.string().optional().describe("Restrict to scenarios in this project"),
+  model: exports_external.string().optional().describe(MODEL_DESC),
+  headed: exports_external.boolean().optional().describe("Run browser in headed mode"),
+  parallel: exports_external.number().optional().describe("Number of parallel workers")
+}, async ({ url, filePaths, mappings, projectId, model, headed, parallel }) => {
+  try {
+    const allScenarios = listScenarios({ projectId });
+    const matched = matchFilesToScenarios(filePaths, allScenarios, mappings ?? []);
+    if (matched.length === 0) {
+      return json({ runId: null, scenarioCount: 0, matchedScenarios: [], message: "No scenarios matched the provided file paths." });
+    }
+    const scenarioIds = matched.map((s) => s.id);
+    const { runId, scenarioCount } = startRunAsync({ url, scenarioIds, model, headed, parallel, projectId });
+    return json({
+      runId,
+      scenarioCount,
+      url,
+      status: "running",
+      matchedScenarios: matched.map((s) => ({ id: s.id, shortId: s.shortId, name: s.name, tags: s.tags })),
+      message: "Poll with get_run to check progress."
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("heartbeat", "Update an agent's last_seen_at timestamp. Call regularly to signal the agent is alive.", {
+  agentId: exports_external.string().describe("Agent ID to heartbeat")
+}, async ({ agentId }) => {
+  try {
+    const agent = heartbeatAgent(agentId);
+    if (!agent)
+      return errorResponse(notFoundErr(agentId, "Agent"));
+    return json({ ok: true, agentId: agent.id, lastSeenAt: agent.lastSeenAt });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+server.tool("set_focus", "Set (or clear) an agent's current focus scenario. Stored in agent metadata.", {
+  agentId: exports_external.string().describe("Agent ID"),
+  scenarioId: exports_external.string().nullable().describe("Scenario ID the agent is working on, or null to clear")
+}, async ({ agentId, scenarioId }) => {
+  try {
+    const agent = setAgentFocus(agentId, scenarioId);
+    if (!agent)
+      return errorResponse(notFoundErr(agentId, "Agent"));
+    return json({ ok: true, agentId: agent.id, focus: agent.metadata?.focus ?? null });
+  } catch (error) {
+    return errorResponse(error);
   }
 });
 async function main() {