@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/mcp/qualitytools.ts

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import type { Card } from "../card.ts"
+import { latestRunDir } from "../code/index.ts"
+import { DEFAULT_QUALITY, DISCLAIMER, evaluateQuality, fmtMetric, IMPACTS, METRIC_LABEL, METRICS, limitsFor, type QualityReport } from "../quality/budgets.ts"
+import { historyFile, qualityTrends, trendsCard } from "../quality/history.ts"
+import { approveVisual, readCaptures, visualLine, type VisualReport } from "../quality/visual.ts"
+import type { ToolContext } from "./tools.ts"
+import type { McpTool } from "./tools.ts"
+
+const VALUE = { lcp_ms: "lcp", cls: "cls", inp_ms: "inp", fcp_ms: "fcp", ttfb_ms: "ttfb", load_ms: "load" } as const
+
+/** A run's accessibility and timings as a card: each WCAG rule that failed, the rules that passed, and each page's vitals. */
+export function qualityCard(r: QualityReport, runDir: string, budgets: QualityReport["budgets"], perf: { budget?: Parameters<typeof limitsFor>[0] }): Card {
+  const body: string[] = []
+  if (r.accessibility.pages) {
+    body.push(`${r.standard} on ${r.accessibility.pages} page${r.accessibility.pages === 1 ? "" : "s"} (${r.engine}): ${r.accessibility.passed.length} rules passed, ${r.accessibility.failed.length} failed`)
+    for (const f of r.accessibility.failed.slice(0, 15)) body.push(`  ✗ ${f.rule}${f.wcag ? ` · WCAG ${f.wcag}${f.level ? ` (${f.level})` : ""}` : ""} · ${f.impact} · ${f.count} element${f.count === 1 ? "" : "s"} on ${f.pages} page${f.pages === 1 ? "" : "s"}: ${f.help}`)
+    if (r.accessibility.failed.length > 15) body.push(`  and ${r.accessibility.failed.length - 15} more`)
+    if (r.accessibility.passed.length) body.push(`  ✓ ${r.accessibility.passed.slice(0, 20).join(", ")}${r.accessibility.passed.length > 20 ? ", …" : ""}`)
+  }
+  if (r.performance.pages.length) {
+    body.push("", "Timings (Core Web Vitals):")
+    for (const p of r.performance.pages) {
+      const lim = perf.budget ? limitsFor(perf.budget, p.url) : {}
+      const shown = METRICS.filter((m) => typeof p[VALUE[m]] === "number").map((m) => `${METRIC_LABEL[m]} ${fmtMetric(m, p[VALUE[m]] as number)}${lim[m] !== undefined ? `/${fmtMetric(m, lim[m]!)}` : ""}`)
+      body.push(`  ${p.over.length ? "✗" : "•"} ${p.url}`, `      ${shown.join(" · ") || "not measured"}${p.requests ? ` · ${p.requests} requests, ${p.kb} KB` : ""}`)
+    }
+  }
+  if (r.breaches.length) body.push("", "Budgets exceeded:", ...r.breaches.map((b) => `  ✗ ${b.page}: ${b.text}`))
+  else if (budgets.accessibility || budgets.performance) body.push("", "Within budgets.")
+  else body.push("", "No budgets set: nothing fails on accessibility or timings. Set them under quality.budgets in forgeqe.yaml.")
+  body.push("", DISCLAIMER, `Run       ${runDir}`)
+  return { status: r.breaches.length ? "fail" : "ok", title: `Accessibility and performance: ${r.breaches.length ? `${r.breaches.length} budget${r.breaches.length === 1 ? "" : "s"} exceeded` : "within budgets"}`, stats: `${IMPACTS.filter((i) => r.accessibility.byImpact[i]).map((i) => `${r.accessibility.byImpact[i]} ${i}`).join(", ") || "no violations"}`, body }
+}
+
+function runFolder(args: Record<string, any>, ctx: ToolContext): string {
+  const dir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : latestRunDir(ctx.config.export.outDir)
+  if (!dir || !existsSync(dir)) throw new Error("No run found. Run a flow in the browser first.")
+  return dir
+}
+
+const baselineDir = (ctx: ToolContext) => (ctx.config.quality || DEFAULT_QUALITY).visual.baselineDir || path.join(path.dirname(ctx.config.memory?.dir || ctx.config.export.outDir), "visual-baselines")
+
+export function visualCard(v: VisualReport, runDir: string, cwd: string): Card {
+  const rel = (p: string) => {
+    const r = path.relative(cwd, p)
+    return r && !r.startsWith("..") ? r : p
+  }
+  const mark = { same: "✓", changed: "✗", new: "+", no_baseline: "?" } as const
+  const body: string[] = []
+  for (const p of v.pages) {
+    const what = p.status === "same" ? "same as its baseline" : p.status === "changed" ? `${p.diffPercent}% changed${p.limit !== undefined ? ` (budget ${p.limit}%)` : ""}${p.resized ? `, size ${p.resized}` : ""}` : p.status === "new" ? "first capture: now its baseline" : "no baseline (auto_baseline is off)"
+    body.push(`${p.status === "changed" && !p.over && p.limit !== undefined ? "~" : mark[p.status]} ${p.url}  · ${what}`)
+    if (p.diff) body.push(`    diff ${rel(p.diff)}`)
+  }
+  body.push("", `Baselines ${rel(v.baselineDir)}`, `Run       ${rel(runDir)}`)
+  const over = v.pages.filter((p) => p.over).length
+  const changed = v.pages.filter((p) => p.status === "changed").length
+  return { status: over ? "fail" : changed ? "info" : "ok", title: `Visual comparison: ${over ? `${over} page${over === 1 ? "" : "s"} over budget` : changed ? `${changed} page${changed === 1 ? "" : "s"} changed` : "no changes"}`, stats: visualLine(v), body }
+}
+
+/** Accessibility and performance: a run's WCAG and Core Web Vitals report, and the trend over runs. */
+export const QUALITY_TOOLS: McpTool[] = [
+  {
+    name: "quality_report",
+    description:
+      "A browser run's accessibility and performance: each WCAG rule that failed (success criterion, level, impact, elements, pages) and the rules that passed, from axe-core with the standard set in quality.accessibility.standard (default WCAG 2.1 AA); each page's Core Web Vitals and load timings (LCP, CLS, INP, FCP, TTFB, load); and the budgets in quality.budgets that were exceeded. Every run collects these; a run fails on them only when a budget is set and exceeded. Defaults to the latest run.",
+    inputSchema: { type: "object", properties: { run_dir: { type: "string", description: "Run folder (default: the latest run)" } } },
+    async run(args, ctx) {
+      const dir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : latestRunDir(ctx.config.export.outDir)
+      if (!dir || !existsSync(dir)) throw new Error("No run found. Run a flow in the browser first.")
+      const q = ctx.config.quality || DEFAULT_QUALITY
+      const r = evaluateQuality(dir, q)
+      if (!r) return { run_dir: dir, note: "This run has no accessibility or timing data (report.accessibility was off, or the run visited no page)." }
+      ctx.emit?.({ type: "card", card: qualityCard(r, dir, r.budgets, { budget: q.budgets.performance }) })
+      return {
+        run_dir: dir,
+        standard: r.standard,
+        engine: r.engine,
+        wcag: { passed_rules: r.accessibility.passed.length, failed_rules: r.accessibility.failed, violations_by_impact: r.accessibility.byImpact },
+        performance: r.performance.pages,
+        budgets_set: r.budgets,
+        budget_exceeded: r.breaches,
+        note: DISCLAIMER,
+      }
+    },
+  },
+  {
+    name: "quality_trends",
+    description:
+      "Accessibility and performance over time, per page, from every run's results: violations by impact and the rules that newly fail or were fixed since the previous run, and each Core Web Vital against its usual value over the last runs (slower or faster beyond noise). For 'is the site getting slower', 'did accessibility regress'.",
+    inputSchema: { type: "object", properties: { page: { type: "string", description: "Only pages whose URL contains this (a host or a path)" } } },
+    async run(args, ctx) {
+      const file = historyFile(ctx.config.export.outDir)
+      const trends = qualityTrends(file, args.page ? String(args.page) : undefined)
+      ctx.emit?.({ type: "card", card: trendsCard(trends, file, ctx.cwd) })
+      return {
+        pages: trends.map((t) => ({ page: t.page, runs: t.runs, accessibility: t.a11y.latest, accessibility_trend: t.a11y.trail, newly_failing_rules: t.a11y.newRules, fixed_rules: t.a11y.fixedRules, timings: t.perf.latest, usual: t.perf.usual, slower: t.perf.worse, faster: t.perf.better })),
+        history: file,
+      }
+    },
+  },
+  {
+    name: "visual_compare",
+    description:
+      "A browser run's visual comparison: each page it visited, captured with animations frozen and the masked regions (quality.visual.mask) hidden, against its approved baseline: same, changed (the share of pixels, with a diff image that marks them in red), or new (its first capture became the baseline). A run fails on it only when quality.budgets.visual sets the most a page may change. Defaults to the latest run.",
+    inputSchema: { type: "object", properties: { run_dir: { type: "string", description: "Run folder (default: the latest run)" } } },
+    async run(args, ctx) {
+      const dir = runFolder(args, ctx)
+      let v: VisualReport | null = null
+      try {
+        v = JSON.parse(readFileSync(path.join(dir, "visual-result.json"), "utf8")) as VisualReport
+      } catch {}
+      if (!v) return { run_dir: dir, note: readCaptures(dir).length ? "The run's pages were captured but not compared yet." : "This run has no visual captures (quality.visual.enabled was off, or the run visited no page)." }
+      ctx.emit?.({ type: "card", card: visualCard(v, dir, ctx.cwd) })
+      return { run_dir: dir, baselines: v.baselineDir, pages: v.pages.map((p) => ({ page: p.url, status: p.status, changed_percent: p.diffPercent, over_budget: p.over, resized: p.resized, current: p.current, baseline: p.baseline, diff: p.diff })), next_step: v.pages.some((p) => p.status === "changed") ? "Show the user what changed (the diff images). When the change is intended, offer visual_approve for those pages; when it is not, it is a visual defect." : undefined }
+    },
+  },
+  {
+    name: "visual_approve",
+    description: "Make a run's captures the new visual baselines, for all its pages or the pages whose URL contains one of pages: when a visual change is intended. Asks the user first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_dir: { type: "string", description: "Run folder (default: the latest run)" },
+        pages: { type: "array", items: { type: "string" }, description: "Only these pages (part of the URL); default: every page of the run" },
+        reason: { type: "string", description: "Why the change is intended, kept with the baseline" },
+      },
+    },
+    async run(args, ctx) {
+      const dir = runFolder(args, ctx)
+      const pages = Array.isArray(args.pages) ? args.pages.map(String) : []
+      const captures = readCaptures(dir).filter((c) => !pages.length || pages.some((p) => c.url.toLowerCase().includes(p.toLowerCase())))
+      if (!captures.length) throw new Error("No captured pages match.")
+      if (ctx.ask) {
+        const answer = await ctx.ask({
+          title: `Approve ${captures.length} page${captures.length === 1 ? "" : "s"} as the new visual baseline?`,
+          detail: "Later runs are compared with these captures.",
+          lines: captures.slice(0, 12).map((c) => `• ${c.url}`),
+          options: [
+            { id: "yes", label: "Approve" },
+            { id: "no", label: "Cancel" },
+          ],
+        })
+        if (answer !== "yes") return { cancelled: true }
+      }
+      const done = approveVisual(dir, baselineDir(ctx), pages, args.reason ? String(args.reason) : "approved")
+      ctx.emit?.({ type: "info", text: `${done.length} visual baseline${done.length === 1 ? "" : "s"} approved from ${path.basename(dir)}`, ok: true })
+      return { approved: done }
+    },
+  },
+]

package/src/mcp/repotests.ts

@@ -0,0 +1,286 @@
+import path from "node:path"
+
+import { noAgentModel } from "../llm.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { findSprint, listSprints, recentSprints, sprintLabel, type Sprint } from "../cases/sprints.ts"
+import { findTests, loadSelection, resultsCard, runSelection, selectionCard, type TestRange } from "../code/find.ts"
+import { CAUSE_TEXT, flakyReport, matchTest, RELEASE_AFTER, setQuarantine } from "../code/history.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `…${t.slice(-(n - 1))}`
+}
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+const sprintSummary = (s: Sprint) => ({ name: s.name, state: s.state, start: s.start || undefined, end: s.end || undefined, system: s.system, team_or_board: s.where })
+
+type SprintPick = { range: TestRange } | { stop: Record<string, unknown> }
+
+/** The date range of the sprint the user means: named, or picked from the recent sprints of Azure DevOps and Jira. */
+async function sprintRange(args: Record<string, any>, ctx: ToolContext): Promise<SprintPick> {
+  const { sprints, errors } = await listSprints(ctx.config.sources, { team: args.team, project: args.project, board: args.board })
+  if (!sprints.length) throw new Error(`No sprints found${errors.length ? `: ${errors.join("; ")}` : ""}. Ask the user for the dates and pass since and until.`)
+  const name = String(args.sprint).trim()
+  let picked: Sprint | undefined
+  if (name.toLowerCase() === "ask") {
+    const offer = recentSprints(sprints).slice(0, 8)
+    if (!ctx.ask) {
+      return {
+        stop: {
+          needs_choice: true,
+          sprints: offer.map(sprintSummary),
+          errors: errors.length ? errors : undefined,
+          next_step: "Ask the user which sprint, then call find_tests again with sprint set to its name.",
+        },
+      }
+    }
+    const choice = await ctx.ask({
+      title: "Which sprint?",
+      detail: "Tests added between the sprint's start and end dates are selected.",
+      lines: [...offer.map((s, i) => `${i + 1}. ${sprintLabel(s)}`), ...errors.map((e) => `Not available: ${e}`)],
+      options: [...offer.map((s, i) => ({ id: String(i), label: s.state === "current" ? `${s.name} (current)` : s.name })), { id: "cancel", label: "Cancel" }],
+    })
+    if (choice === null || choice === "cancel") return { stop: { cancelled: true, reason: "The user did not pick a sprint." } }
+    picked = offer[Number(choice)]
+  } else {
+    picked = findSprint(sprints, name)
+    if (!picked) throw new Error(`No sprint called "${name}". Recent sprints: ${recentSprints(sprints).map((s) => s.name).join(", ")}.`)
+  }
+  if (!picked?.start) throw new Error(`Sprint "${picked?.name}" has no start date; ask the user for the dates and pass since and until.`)
+  return { range: { since: picked.start, until: picked.end || undefined, label: sprintLabel(picked) } }
+}
+
+/** Find, confirm, and run a repository's existing automated tests. */
+export const REPO_TEST_TOOLS: McpTool[] = [
+  {
+    name: "list_sprints",
+    description:
+      "Recent sprints from the configured Azure DevOps (team iterations) and Jira (scrum board sprints): name, state (current, past, future), start and end dates, and the team or board. For requests like 'tests added this sprint'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        team: { type: "string", description: "Azure DevOps team (default: the project's default team)" },
+        project: { type: "string", description: "Jira project key whose boards to read (default: every scrum board, up to five)" },
+        board: { type: "string", description: "Jira board id or name" },
+        all: { type: "boolean", description: "Every sprint instead of the current, three most recent past, and next ones" },
+      },
+    },
+    async run(args, ctx) {
+      const { sprints, errors } = await listSprints(ctx.config.sources, { team: args.team, project: args.project, board: args.board })
+      return { sprints: (args.all ? sprints : recentSprints(sprints)).map(sprintSummary), errors: errors.length ? errors : undefined }
+    },
+  },
+  {
+    name: "find_tests",
+    description:
+      "Find the automated tests already in a repository that match a request, without running them: a feature or topic ('login'), test case ids or tags, a folder, or tests added in a date range or sprint. Scribe, the coding agent, reads the tests (and git history for a range) and decides each one from what it does; ForgeQE runs the framework's list command to confirm the selection. Shows the list to the user and returns selection_id for run_tests. Takes a minute or two.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        request: { type: "string", description: "What to find, in the user's words, e.g. 'tests related to login'" },
+        repo: { type: "string", description: "Repository, relative to the working directory (default: the working directory)" },
+        since: { type: "string", description: "Only tests added on or after this date, YYYY-MM-DD" },
+        until: { type: "string", description: "Only tests added on or before this date, YYYY-MM-DD" },
+        sprint: { type: "string", description: "Only tests added in a sprint: 'ask' lets the user pick from Azure DevOps and Jira sprints, or a sprint name" },
+        team: { type: "string", description: "Azure DevOps team for sprint" },
+        project: { type: "string", description: "Jira project key for sprint" },
+        board: { type: "string", description: "Jira board id or name for sprint" },
+      },
+      required: ["request"],
+    },
+    async run(args, ctx) {
+      const noModel = noAgentModel(ctx.config.llm, ctx.config.code.model, "Scribe")
+      if (noModel) throw new Error(noModel)
+      const request = String(args.request || "").trim()
+      if (!request) throw new Error("request is required.")
+      for (const k of ["since", "until"]) if (args[k] && !DATE.test(String(args[k]))) throw new Error(`${k} must be YYYY-MM-DD.`)
+      let range: TestRange | undefined
+      if (args.sprint) {
+        const pick = await sprintRange(args, ctx)
+        if ("stop" in pick) return pick.stop
+        range = pick.range
+      } else if (args.since || args.until) {
+        range = { since: args.since ? String(args.since) : undefined, until: args.until ? String(args.until) : undefined }
+      }
+      const sel = await findTests({
+        config: ctx.config,
+        repo: args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd,
+        request,
+        range,
+        signal: ctx.signal,
+        onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+        open: ctx.openSession as never,
+        runTest: ctx.runTest,
+      })
+      ctx.emit?.({ type: "card", card: selectionCard(sel, ctx.cwd) })
+      return {
+        selection_id: sel.id,
+        count: sel.tests.length,
+        framework: sel.framework,
+        range: range?.label || (range ? [range.since, range.until].filter(Boolean).join(" to ") : undefined),
+        tests: sel.tests,
+        left_out: sel.related.length ? sel.related : undefined,
+        list_command: sel.listCommand || undefined,
+        list_confirmed: sel.listed,
+        run_command: sel.runCommand,
+        notes: sel.notes || undefined,
+        next_step: sel.tests.length
+          ? ctx.ask
+            ? "The user sees the list. Call run_tests with this selection_id if they asked to run the tests: it asks them to confirm first."
+            : "Show the user the list and ask whether to run it; only after they say yes, call run_tests with this selection_id and confirmed: true."
+          : undefined,
+      }
+    },
+  },
+  {
+    name: "run_tests",
+    description:
+      "Run a selection from find_tests after the user confirms: ForgeQE asks the user (Run / Don't run), runs exactly those tests, and reads their JUnit or TRX results. Returns each test's pass or fail with the failure message, the output's end, and the result files. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to run this exact list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selection_id: { type: "string", description: "From find_tests" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to run this list" },
+        timeout_seconds: { type: "number", description: "Stop the run after this many seconds (default: code.test_timeout_seconds)" },
+      },
+      required: ["selection_id"],
+    },
+    async run(args, ctx) {
+      const sel = loadSelection(ctx.config, String(args.selection_id))
+      const n = sel.tests.length
+      if (!n) return { ran: false, reason: "The selection has no tests." }
+      const what = `${n} test${n === 1 ? "" : "s"}`
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Run ${what}?`,
+          detail: sel.runCommand,
+          lines: [`Selected for "${sel.request}":`, ...sel.tests.slice(0, 20).map((t) => `  • ${t.name}`), ...(n > 20 ? [`  and ${n - 20} more`] : [])],
+          options: [
+            { id: "run", label: `Run ${what}` },
+            { id: "no", label: "Don't run" },
+          ],
+        })
+        if (choice !== "run") return { ran: false, reason: "The user chose not to run them." }
+      } else if (args.confirmed !== true) {
+        return {
+          ran: false,
+          needs_confirmation: true,
+          tests: sel.tests.map((t) => t.name),
+          run_command: sel.runCommand,
+          next_step: "Show the user this list and ask whether to run it; call run_tests again with confirmed: true only after they say yes.",
+        }
+      }
+      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: `ForgeQE runs ${what}: ${sel.runCommand}` } })
+      const timeout = Number(args.timeout_seconds) > 0 ? Number(args.timeout_seconds) : ctx.config.code.testTimeoutSeconds
+      const r = await runSelection({ selection: sel, timeoutSeconds: timeout, signal: ctx.signal, runTest: ctx.runTest, hide: privateEnvNames(ctx.config), flaky: ctx.config.flaky })
+      ctx.emit?.({ type: "card", card: resultsCard(r, ctx.cwd) })
+      const failed = r.tests.filter((t) => t.status === "failed")
+      return {
+        ran: true,
+        status: r.status,
+        passed: r.counts.passed,
+        failed: r.counts.failed,
+        skipped: r.counts.skipped,
+        seconds: r.seconds,
+        exit_code: r.exitCode,
+        failures: failed.length ? failed.map((t) => ({ name: t.name, file: t.file, message: t.message })) : undefined,
+        per_test_results: r.tests.length > 0,
+        result_files: r.resultFiles,
+        output: r.status === "passed" ? undefined : clip(r.output, 4000),
+        folder: r.dir,
+        ...(r.flaky?.length ? { flaky: r.flaky } : {}),
+        ...(r.quarantinedFailures?.length ? { quarantined_failures: r.quarantinedFailures } : {}),
+        ...(r.suggestQuarantine?.length ? { flaky_by_history: r.suggestQuarantine.map((f) => ({ name: f.name, trail: f.trail, cause: CAUSE_TEXT[f.cause], example: f.example })) } : {}),
+        ...(r.quarantinedNow?.length ? { quarantined_now: r.quarantinedNow } : {}),
+        ...(r.releasable?.length ? { ready_to_leave_quarantine: r.releasable } : {}),
+        next_step: [
+          r.status === "failed" ? `Offer heal_tests with command: ${sel.runCommand}` : "",
+          r.flaky?.length ? "Say which tests passed only when run again: they are flaky, not failing." : "",
+          r.suggestQuarantine?.length ? "Offer quarantine_tests for the flaky ones (it asks the user), and heal_tests to fix their cause." : "",
+          r.releasable?.length ? "Offer quarantine_tests with action release for the tests ready to leave quarantine." : "",
+        ].filter(Boolean).join(" ") || undefined,
+      }
+    },
+  },
+  {
+    name: "flaky_tests",
+    description:
+      "The repository's flaky tests, from the history ForgeQE keeps of every run_tests run (.forgeqe/test-history.json): each test's recent results (✓ passed, ✗ failed, ↻ passed only when run again), its pass rate and flakiness score, the likely cause from its failure messages (timing, an overlay covering the element, data that changes, network, the environment), with an example message, and which tests are in quarantine or ready to leave it. Shows a card. Nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: { type: "string", description: "Repository, relative to the working directory (default: the working directory)" },
+        all: { type: "boolean", description: "Every test with history, not only flaky and quarantined ones" },
+      },
+    },
+    async run(args, ctx) {
+      const repo = args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd
+      const after = ctx.config.flaky?.flakyAfter ?? 2
+      const report = flakyReport(repo, after)
+      const shown = args.all ? report : report.filter((f) => f.flaky || f.quarantined)
+      const body = shown.slice(0, 30).flatMap((f) => [
+        `${f.quarantined ? "■" : "⚠"} ${f.name}  ${f.trail}  ${Math.round(f.passRate * 100)}% passed${f.quarantined ? `  quarantined ${f.quarantined.at.slice(0, 10)}${f.releasable ? ", ready to leave" : ""}` : ""}`,
+        `    likely ${CAUSE_TEXT[f.cause]}${f.example ? `: ${f.example}` : ""}`,
+      ])
+      const flaky = report.filter((f) => f.flaky && !f.quarantined).length
+      const q = report.filter((f) => f.quarantined).length
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: flaky ? "fail" : "info",
+          title: report.length ? `${flaky} flaky test${flaky === 1 ? "" : "s"}, ${q} in quarantine` : "No test history yet",
+          stats: `${report.length} tests with history`,
+          body: report.length ? body : ["ForgeQE keeps each test's results from run_tests and pr-tests runs; run the tests a few times first."],
+        },
+      })
+      return {
+        tests: shown.map((f) => ({ name: f.name, trail: f.trail, runs: f.runs, pass_rate: f.passRate, score: f.score, flaky: f.flaky, cause: CAUSE_TEXT[f.cause], example: f.example, quarantined: f.quarantined, ready_to_leave_quarantine: f.releasable || undefined })),
+        next_step: flaky ? "Offer quarantine_tests for the flaky tests (it asks the user), and heal_tests with their cause to fix them." : undefined,
+      }
+    },
+  },
+  {
+    name: "quarantine_tests",
+    description:
+      `Put flaky tests in quarantine, or take them out (action release), after the user confirms. A quarantined test keeps running, so its history goes on, but its failure no longer fails run_tests or pr-tests; no test code changes. A quarantined test that passes ${RELEASE_AFTER} runs in a row is offered for release. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        tests: { type: "array", items: { type: "string" }, description: "Test names as flaky_tests or run_tests give them (a unique part of the name is enough)" },
+        action: { type: "string", enum: ["quarantine", "release"] },
+        reason: { type: "string", description: "Why, for quarantine: the likely cause" },
+        repo: { type: "string" },
+        confirmed: { type: "boolean" },
+      },
+      required: ["tests", "action"],
+    },
+    async run(args, ctx) {
+      const repo = args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd
+      const given = (args.tests as string[]).map(String)
+      const names = given.map((g) => matchTest(repo, g))
+      const unknown = given.filter((_, i) => !names[i])
+      const known = names.filter((n): n is string => Boolean(n))
+      if (!known.length) throw new Error(`No test with history matches ${unknown.join(", ")}. flaky_tests lists them.`)
+      const release = args.action === "release"
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: release ? `Take ${known.length} test${known.length === 1 ? "" : "s"} out of quarantine?` : `Quarantine ${known.length} test${known.length === 1 ? "" : "s"}?`,
+          detail: release ? "Their failures will fail runs again." : "They keep running, but their failures stop failing runs and CI until they are released.",
+          lines: known.map((n) => `  • ${n}`),
+          options: [
+            { id: "yes", label: release ? "Release" : "Quarantine" },
+            { id: "no", label: "Cancel" },
+          ],
+        })
+        if (choice !== "yes") return { changed: [], reason: "The user cancelled." }
+      } else if (args.confirmed !== true) {
+        return { changed: [], needs_confirmation: true, tests: known, next_step: "Ask the user; call again with confirmed: true only after they agree." }
+      }
+      const changed = setQuarantine(repo, known, release ? null : String(args.reason || "flaky"), "user")
+      ctx.emit?.({ type: "info", text: `${release ? "Released from" : "Quarantined"}: ${changed.join(", ") || "nothing changed"}`, ok: true })
+      return { changed, ...(unknown.length ? { not_found: unknown } : {}) }
+    },
+  },
+]