@hasna/testers 0.0.11 → 0.0.12

package/dist/cli/index.js

@@ -3413,7 +3413,7 @@ import chalk5 from "chalk";
 // package.json
 var package_default = {
   name: "@hasna/testers",
-  version: "0.0.11",
+  version: "0.0.12",
   description: "AI-powered QA testing CLI \u2014 spawns cheap AI agents to test web apps with headless browsers",
   type: "module",
   main: "dist/index.js",

package/dist/mcp/index.js

@@ -4902,6 +4902,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 +5122,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();
@@ -7103,6 +7122,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 +7189,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 +7220,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 +7237,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 +7261,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 +7290,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 +7354,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 +7374,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 +7394,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 +7406,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 +7435,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 +7452,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 +7462,182 @@ 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);
   }
 });
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/testers",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "AI-powered QA testing CLI — spawns cheap AI agents to test web apps with headless browsers",
   "type": "module",
   "main": "dist/index.js",