@capagents/forgeqe 1.1.3 → 1.1.5

package/src/mcp/defecttools.ts

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process"
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { areaFacts, changeOf, defectTrends, predict, predictionLines, savePrediction, trendsMarkdown, type Prediction } from "../cases/predict.ts"
+import type { McpTool } from "./tools.ts"
+
+/** The branch a change is compared with when none is named: the remote's default branch, else main, else master. */
+export function defaultBase(repo: string): string {
+  const ok = (ref: string) => spawnSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", ref], { encoding: "utf8" }).status === 0
+  const head = spawnSync("git", ["-C", repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], { encoding: "utf8" })
+  if (head.status === 0 && head.stdout.trim()) return head.stdout.trim()
+  for (const ref of ["origin/main", "main", "origin/master", "master"]) if (ok(ref)) return ref
+  throw new Error("No base branch found (origin/HEAD, main, or master): name one with base.")
+}
+
+const pct = (a: number, b: number) => (b ? `${Math.round((a / b) * 100)}%` : "—")
+
+export const DEFECT_TOOLS: McpTool[] = [
+  {
+    name: "defect_trends",
+    description:
+      "How the defects of the saved suite runs went over time, from defect-history.json next to the suite folders: how many are still there, gone, or came back after a fix, the time they took to go away, the most seen ones with their bugs, defects by area (page or API route), defects per suite, and how often defect predictions were right. Writes defect-trends.md next to the suites. Shows a card. Nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        folder: { type: "string", description: "Folder of saved suites (default: suite.out_dir in forgeqe.yaml)" },
+      },
+    },
+    async run(args, ctx) {
+      const folder = args.folder ? path.resolve(ctx.cwd, String(args.folder)) : ctx.config.suite.outDir
+      const t = defectTrends(folder)
+      const md = trendsMarkdown(t)
+      mkdirSync(folder, { recursive: true })
+      const file = path.join(folder, "defect-trends.md")
+      writeFileSync(file, md)
+      const p = t.predictions
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: t.defects ? (t.open ? "fail" : "ok") : "info",
+          title: t.defects ? `${t.defects} defect${t.defects === 1 ? "" : "s"}: ${t.open} still there, ${t.gone} gone, ${t.regressions} came back` : "No defect history yet",
+          stats: `${t.suites} suite run${t.suites === 1 ? "" : "s"}`,
+          body: t.defects
+            ? [
+                ...(t.daysToFix ? [`Time to go away: median ${t.daysToFix.median} days over ${t.daysToFix.count}`] : []),
+                ...(p ? [`Predictions (${p.scored} scored): ${p.inPredicted} of ${p.defects} defects (${pct(p.inPredicted, p.defects)}) were in a predicted area; ${p.highWithDefect} of ${p.high} high-risk areas (${pct(p.highWithDefect, p.high)}) had one`] : []),
+                "",
+                "Most seen:",
+                ...t.recurring.slice(0, 5).map((d) => `  ${d.seen}× ${d.title}${d.open ? "" : " (gone)"}${d.returns ? `, came back ${d.returns}×` : ""}${d.bug ? `  ${d.bug.label}` : ""}`),
+                ...(t.areas.length ? ["", "By area:", ...t.areas.slice(0, 5).map((a) => `  ${a.area}: ${a.defects} defect${a.defects === 1 ? "" : "s"}${a.runs ? `, ${a.failed} of ${a.runs} case runs failed` : ""}`)] : []),
+                "",
+                `Report: ${path.relative(ctx.cwd, file) || file}`,
+              ]
+            : ["Run suites into this folder first: each one adds its defects to defect-history.json."],
+        },
+      })
+      return { ...t, report: file }
+    },
+  },
+  {
+    name: "predict_defects",
+    description:
+      "Where a change is likely to cause defects. Compares a git range of the product's repository (base...head; default: the default branch to HEAD, in defects.product_repo or the working directory) with what the saved suites know about each area (page or API route): the change touches an area when it changes a file named after it or its diff mentions the route; the area's earlier defects, defects that came back, defects still open, and case failures raise its risk. Gives each area high, medium, or low with every reason, the cases to run first, and changed code no case reaches. Saves the prediction; the next suite scores it, and defect_trends says how often predictions were right. A heuristic, not a model. Shows a card. Nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: { type: "string", description: "The product's repository (default: defects.product_repo, else the working directory)" },
+        base: { type: "string", description: "Base ref of the change (default: origin/HEAD, main, or master)" },
+        head: { type: "string", description: "Head ref of the change (default: HEAD)" },
+        folder: { type: "string", description: "Folder of saved suites (default: suite.out_dir in forgeqe.yaml)" },
+      },
+    },
+    async run(args, ctx) {
+      const repo = args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.config.defects?.productRepo || ctx.cwd
+      const folder = args.folder ? path.resolve(ctx.cwd, String(args.folder)) : ctx.config.suite.outDir
+      const base = args.base ? String(args.base) : defaultBase(repo)
+      const head = args.head ? String(args.head) : "HEAD"
+      const change = changeOf(repo, base, head)
+      const facts = areaFacts(folder)
+      const at = new Date().toISOString()
+      const p: Prediction = { id: at.replace(/[:.]/g, "-"), at, repo, base, head, changed: change.files, ...predict(facts, change) }
+      mkdirSync(folder, { recursive: true })
+      savePrediction(folder, p)
+      const high = p.areas.filter((a) => a.level === "high").length
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: high ? "fail" : p.areas.length ? "info" : "ok",
+          title: p.areas.length ? `${high} high-risk area${high === 1 ? "" : "s"} in ${base}...${head}` : `No known area touched by ${base}...${head}`,
+          stats: `${p.changed.length} changed file${p.changed.length === 1 ? "" : "s"} · ${facts.size} known area${facts.size === 1 ? "" : "s"}`,
+          body: [...predictionLines(p), ...(facts.size ? [] : ["", "ForgeQE knows no areas yet: run suites into this folder first."])],
+        },
+      })
+      return {
+        base,
+        head,
+        changed: p.changed,
+        areas: p.areas,
+        run_first: p.runFirst,
+        untested: p.untested,
+        next_step: p.runFirst.length ? "Offer to run the run_first cases before the others (run_test_cases)." : undefined,
+      }
+    },
+  },
+]

package/src/mcp/devicetools.ts

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import YAML from "yaml"
+
+import { browserProvider, DEVICE_NAME, loadConfig, type AppConfig, type BrowserDevice, type RemoteBrowserProvider } from "../config.ts"
+import { projectDir } from "../tools.ts"
+import type { McpTool } from "./tools.ts"
+
+/**
+ * Named remote browsers ("devices") the user describes in conversation: kept under devices: in the provider's YAML
+ * file (browser.providers.<provider> in forgeqe.yaml, created when missing), so runs and CI see the same list.
+ */
+
+/** A device as the agent reads it. */
+export function deviceView(d: BrowserDevice) {
+  const r = d.remote
+  return {
+    name: d.name,
+    provider: d.provider,
+    browser: r.browser,
+    browser_version: r.browserVersion,
+    ...(r.platform ? { platform: r.platform } : {}),
+    ...(r.os ? { os: r.os } : {}),
+    ...(r.osVersion ? { os_version: r.osVersion } : {}),
+  }
+}
+
+/** The provider's YAML file, from forgeqe.yaml; when there is none, .forgeqe/<provider>.yaml, added to forgeqe.yaml. */
+function providerFile(config: AppConfig, provider: RemoteBrowserProvider): { file: string; added: boolean } {
+  const known = config.browser.providerFiles[provider]
+  if (known) return { file: known, added: false }
+  const configPath = config.configPath
+  if (!configPath) throw new Error("There is no forgeqe.yaml here to add a device to: run forgeqe init first.")
+  const file = path.join(projectDir(path.dirname(configPath)), `${provider}.yaml`)
+  const doc = YAML.parseDocument(readFileSync(configPath, "utf8"))
+  if (!YAML.isMap(doc.get("browser"))) doc.set("browser", doc.createNode({}))
+  doc.setIn(["browser", "providers", provider], `./${path.relative(path.dirname(configPath), file).split(path.sep).join("/")}`)
+  writeFileSync(configPath, doc.toString())
+  return { file, added: true }
+}
+
+/**
+ * Write a change to a provider file and forgeqe.yaml, then load the whole configuration again: a device that does not
+ * load (a missing platform, a browser the engine cannot drive) puts both files back and fails, so a bad device never
+ * breaks the configuration. The session's configuration takes the new browser settings.
+ */
+function applyChange(config: AppConfig, provider: RemoteBrowserProvider, change: (doc: YAML.Document) => void): { file: string } {
+  const configPath = config.configPath
+  const before = configPath && existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined
+  const { file, added } = providerFile(config, provider)
+  const old = existsSync(file) ? readFileSync(file, "utf8") : undefined
+  const doc = YAML.parseDocument(old ?? `provider: ${provider}\n`)
+  change(doc)
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, doc.toString())
+  try {
+    const fresh = loadConfig({ configPath, profile: config.activeProfile })
+    Object.assign(config.browser, fresh.browser)
+  } catch (err) {
+    if (old === undefined) rmSync(file, { force: true })
+    else writeFileSync(file, old)
+    if (added && configPath && before !== undefined) writeFileSync(configPath, before)
+    throw err
+  }
+  return { file }
+}
+
+const str = (v: unknown) => (v === undefined || v === null ? "" : String(v).trim())
+
+export const DEVICE_TOOLS: McpTool[] = [
+  {
+    name: "browser_devices",
+    description:
+      "List, add or change, and remove named remote browsers (devices) on BrowserStack or TestMu AI/LambdaTest, kept in the provider's YAML file so every later run and CI sees them. When the user describes the devices or browsers to test on, save each one here, then run on them by passing their names as devices to browser_run or run_test_cases. ForgeQE drives remote browsers over the Chrome DevTools Protocol, so a device is Chrome (TestMu AI: Chrome only) or Edge (BrowserStack) on a Windows or macOS version; Safari, Firefox, and real mobile devices are not supported, so say so instead of saving them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list", "save", "remove"], description: "list the devices; save adds a device or changes one; remove deletes one" },
+        name: { type: "string", description: "Short device name for save/remove, e.g. win11-chrome, mac-sequoia-edge" },
+        provider: { type: "string", enum: ["browserstack", "testmu"], description: "For save: the grid the device is on (testmu is TestMu AI / LambdaTest). Needed for a new device." },
+        browser: { type: "string", description: "For save: TestMu: Chrome; BrowserStack: chrome or edge" },
+        browser_version: { type: "string", description: "For save: a version such as 128, or latest, latest-1 (default latest)" },
+        platform: { type: "string", description: "For save on TestMu: the platform, e.g. Windows 11, Windows 10, macOS Sequoia" },
+        os: { type: "string", description: "For save on BrowserStack: Windows or OS X" },
+        os_version: { type: "string", description: "For save on BrowserStack: 11, 10, Sequoia, Sonoma, ..." },
+      },
+      required: ["action"],
+    },
+    async run(args, ctx) {
+      const config = ctx.config
+      const action = str(args.action) || "list"
+      const list = () => ({
+        devices: Object.values(config.browser.devices || {}).map(deviceView),
+        providers: Object.fromEntries(Object.entries(config.browser.providerFiles).map(([p, f]) => [p, f])),
+      })
+      if (action === "list") return list()
+      const name = str(args.name)
+      if (!DEVICE_NAME.test(name)) throw new Error('name is required: a short name such as "win11-chrome" (letters, digits, ".", "_", "-").')
+      const existing = config.browser.devices?.[name]
+      if (action === "remove") {
+        if (!existing) throw new Error(`No device named ${name}.`)
+        const { file } = applyChange(config, existing.provider, (doc) => {
+          doc.deleteIn(["devices", name])
+          const left = doc.get("devices")
+          if (YAML.isMap(left) && !left.items.length) doc.delete("devices")
+        })
+        return { removed: name, file, ...list() }
+      }
+      if (action !== "save") throw new Error(`Unknown action ${action}: use list, save, or remove.`)
+      const asked = str(args.provider)
+      const provider = (asked ? browserProvider(asked) : existing?.provider) as RemoteBrowserProvider | "local" | undefined
+      if (!provider || provider === "local") throw new Error("provider is required for a new device: browserstack or testmu.")
+      if (existing && existing.provider !== provider) throw new Error(`Device ${name} is on ${existing.provider}; remove it first to move it to ${provider}.`)
+      const fields: Record<string, string> = {}
+      for (const key of ["browser", "browser_version", "platform", "os", "os_version"]) if (str(args[key])) fields[key] = str(args[key])
+      if (!existing && !fields.browser) throw new Error("browser is required for a new device: Chrome or Edge.")
+      const { file } = applyChange(config, provider, (doc) => {
+        if (!doc.get("provider")) doc.set("provider", provider)
+        for (const [key, value] of Object.entries(fields)) doc.setIn(["devices", name, key], value)
+      })
+      const saved = config.browser.devices[name]
+      return { saved: deviceView(saved), file, ...list() }
+    },
+  },
+]

package/src/mcp/external.ts

@@ -1,3 +1,6 @@
+import { spawnSync } from "node:child_process"
+
+import { ghAuthToken } from "../cases/github.ts"
 import type { AppConfig } from "../config.ts"
 
 /**
@@ -22,6 +25,15 @@ const ADO_DOMAIN_WORDS: Record<string, string> = {
   "advanced-security": "security alerts",
 }
 export const ROVO_URL = "https://mcp.atlassian.com/v2/mcp"
+export const GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
+
+/** The GitHub repository (owner/name) the folder's git remotes point at, or null. */
+export function githubRemote(cwd: string): string | null {
+  const res = spawnSync("git", ["config", "--get-regexp", "^remote\\..*\\.url$"], { cwd, encoding: "utf8", timeout: 5000 })
+  if (res.status !== 0) return null
+  const m = /github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\s*$/m.exec(res.stdout)
+  return m ? `${m[1]}/${m[2]}` : null
+}
 /** Also the time allowed for the first start, when npx or uvx downloads the server. */
 const TIMEOUT_MS = 120_000
 
@@ -61,7 +73,12 @@ export function adoOrganization(orgUrl: string): string | null {
  * server for Jira, and anything under `mcp:`. Credentials stay in the environment: configs refer to them as {env:NAME}.
  * A system whose server cannot start here is listed in `skipped`; ForgeQE's own API tools still cover it.
  */
-export function externalMcp(cfg: AppConfig, which: Which = Bun.which, env: NodeJS.ProcessEnv = process.env): ExternalPlan {
+export function externalMcp(
+  cfg: AppConfig,
+  which: Which = Bun.which,
+  env: NodeJS.ProcessEnv = process.env,
+  opts: { cwd?: string; ghToken?: () => string | null; remote?: (cwd: string) => string | null } = {},
+): ExternalPlan {
   const servers: ExternalServer[] = []
   const skipped: ExternalPlan["skipped"] = []
   const { ado, jira, confluence: conf } = cfg.sources
@@ -175,6 +192,30 @@ export function externalMcp(cfg: AppConfig, which: Which = Bun.which, env: NodeJ
     }
   }
 
+  // GitHub's hosted MCP server, when the project is on GitHub: sources.github in forgeqe.yaml, or a GitHub remote in the
+  // folder. Its tools cost tokens on every request, so a project that is not on GitHub does not get them.
+  const gh = cfg.sources.github
+  // The folder the agent works in, when the caller names it: a GitHub remote there turns the server on.
+  const remote = gh?.mcp === false || cfg.mcp?.github || !opts.cwd ? null : (opts.remote || githubRemote)(opts.cwd)
+  if (gh?.mcp !== false && !cfg.mcp?.github && (gh || remote)) {
+    const label = "GitHub MCP"
+    const token = env[gh?.tokenEnv || "GITHUB_TOKEN"]?.trim() || (opts.ghToken || ghAuthToken)()
+    if (gh && gh.apiUrl !== "https://api.github.com") skipped.push({ label, why: "GitHub's hosted server is for github.com; add your Enterprise server's MCP under mcp:" })
+    else if (!token) skipped.push({ label, why: `sign in with forgeqe auth login github, or set ${gh?.tokenEnv || "GITHUB_TOKEN"}` })
+    else {
+      const toolsets = gh?.toolsets?.length ? gh.toolsets : ["repos", "issues", "pull_requests", "actions"]
+      const repo = gh?.repo || remote
+      servers.push({
+        name: "github",
+        label,
+        about: `GitHub's MCP server (${toolsets.join(", ")})${repo ? `; this project is ${repo}, so use it unless the user names another repository` : ""}. It cannot upload files to issues; ForgeQE's own tools write test results and bugs to GitHub issues.`,
+        config: { type: "remote", url: GITHUB_MCP_URL, headers: { Authorization: "Bearer {env:FORGEQE_GITHUB_MCP_TOKEN}", "X-MCP-Toolsets": toolsets.join(",") }, oauth: false, enabled: true, timeout: TIMEOUT_MS },
+        secrets: { FORGEQE_GITHUB_MCP_TOKEN: token },
+        signIn: env[gh?.tokenEnv || "GITHUB_TOKEN"]?.trim() ? `token in ${gh?.tokenEnv || "GITHUB_TOKEN"}` : "GitHub CLI sign-in",
+      })
+    }
+  }
+
   for (const [name, server] of Object.entries(cfg.mcp || {})) {
     const at = servers.findIndex((s) => s.name === name)
     if (at >= 0) servers.splice(at, 1)

package/src/mcp/tools.ts

@@ -19,17 +19,20 @@ import { browserProvider, type AppConfig } from "../config.ts"
 import { clearMemory, memoryFilesFor, memoryFlows, memoryOverview, memoryShow } from "../memory.ts"
 import { executeRun, runDirectory } from "../run.ts"
 import { counts } from "../suite/report.ts"
-import { runSuite, type SuiteEvent, type SuiteResult } from "../suite/run.ts"
+import { deviceCases, runSuite, suiteParallel, type SuiteEvent, type SuiteResult } from "../suite/run.ts"
 import { COMMAND_TOOLS, TASK_FILE } from "./commands.ts"
 import { PR_TOOLS } from "./prtools.ts"
 import { CASE_TOOLS, checkResult, precheck } from "./casetools.ts"
 import { REPO_TEST_TOOLS } from "./repotests.ts"
+import { DEFECT_TOOLS } from "./defecttools.ts"
 import { API_TOOLS } from "./apitools.ts"
 import { EXPLORE_TOOLS } from "./exploretools.ts"
 import { QUALITY_TOOLS } from "./qualitytools.ts"
 import { CAPABILITY_TOOLS } from "./captools.ts"
 import { NOTIFY_TOOLS } from "./notifytools.ts"
 import { REPORT_TOOLS } from "./reporttools.ts"
+import { DEVICE_TOOLS } from "./devicetools.ts"
+import { ATTACH_TOOLS } from "./attachtools.ts"
 import { capabilityIndex } from "../capabilities/render.ts"
 import { domainNotes } from "../domain.ts"
 import { readNetwork } from "../api/traffic.ts"
@@ -124,6 +127,8 @@ export type ToolContext = {
   cwd: string
   headed?: boolean
   browserProvider?: AppConfig["browser"]["provider"]
+  /** Named devices the user pinned for this session (--devices): runs go to each of them. */
+  devices?: string[]
   maxSteps?: number
   replay?: ReplayMode
   memory?: boolean
@@ -190,14 +195,14 @@ const SOURCES_SCHEMA = {
     properties: {
       source: {
         type: "string",
-        enum: ["azure_devops", "jira", "xray", "testrail", "zephyr", "qtest", "file", "text"],
+        enum: ["azure_devops", "jira", "xray", "testrail", "zephyr", "qtest", "github", "file", "text"],
         description:
-          "azure_devops: Test Case work items or a Test Plan. jira: issues. xray: Xray Test issues or a Test Plan. testrail: cases, a run, a plan, or a suite. zephyr: Zephyr Scale test cases, a test cycle, or a folder. qtest: qTest test cases, a test cycle, or a suite. file: .txt/.md/.csv/.yaml/.json/.feature files. text: test case text the user wrote (also cases you wrote from requirements).",
+          "azure_devops: Test Case work items or a Test Plan. github: GitHub issues (by number, labels, or an issue search). jira: issues. xray: Xray Test issues or a Test Plan. testrail: cases, a run, a plan, or a suite. zephyr: Zephyr Scale test cases, a test cycle, or a folder. qtest: qTest test cases, a test cycle, or a suite. file: .txt/.md/.csv/.yaml/.json/.feature files. text: test case text the user wrote (also cases you wrote from requirements).",
       },
       ids: {
         type: "array",
         items: { type: "string" },
-        description: "Work item ids (azure_devops), issue keys (jira, xray), case ids like C12 (testrail), keys like SHOP-T3 (zephyr), or test case ids (qtest)",
+        description: "Work item ids (azure_devops), issue keys (jira, xray), case ids like C12 (testrail), keys like SHOP-T3 (zephyr), test case ids (qtest), or issue numbers (github: 12, or owner/repo#12)",
       },
       plan: { type: "string", description: "Test plan id (azure_devops, testrail) or Test Plan issue key (xray)" },
       suite: { type: "string", description: "Suite id: inside the Azure DevOps plan (omit for every suite), a TestRail suite, or a qTest test suite" },
@@ -205,6 +210,9 @@ const SOURCES_SCHEMA = {
       cycle: { type: "string", description: "zephyr: test cycle key like SHOP-R5. qtest: test cycle id" },
       folder: { type: "string", description: "zephyr: folder id" },
       jql: { type: "string", description: "JQL query (jira, xray)" },
+      repo: { type: "string", description: "github: owner/repo (default: sources.github.repo); ids may also be owner/repo#12" },
+      labels: { type: "array", items: { type: "string" }, description: "github: open issues with all these labels" },
+      query: { type: "string", description: 'github: a GitHub issue search, e.g. "login in:title is:open label:test-case"' },
       paths: { type: "array", items: { type: "string" }, description: "Files, relative to the working directory" },
       text: { type: "string", description: "The test case itself: title on the first line, then steps and expected results" },
     },
@@ -253,6 +261,61 @@ function summarizeRun(result: RunResult, runDir: string, files: string[]) {
   }
 }
 
+const DEVICES_SCHEMA = {
+  type: "array",
+  items: { type: "string" },
+  description:
+    "Names of saved devices (browser_devices) to run on, when the user asked for specific devices or browsers: each runs in parallel on its own remote browser and is reported separately. A device's name also picks its provider.",
+}
+
+/** One goal on several devices at once: a one-off case through the suite, so each device runs and reports on its own. */
+async function runGoalOnDevices(goal: string, url: string | undefined, devices: string[], args: Record<string, unknown>, ctx: ToolContext) {
+  const tc: TestCase = { id: "goal", title: clip(goal.split("\n")[0], 80) || "Goal", source: "text", description: goal, steps: [], ...(url ? { startUrl: url } : {}) }
+  const shown = deviceCases([tc], devices)
+  const parallel = suiteParallel(undefined, ctx.config.suite.parallel, devices.length, shown.length)
+  const emit = ctx.emit || (() => {})
+  emit({ type: "suite-start", cases: shown, parallel })
+  const suite = await runSuite({
+    config: ctx.config,
+    cases: [tc],
+    devices,
+    parallel,
+    writeBack: false,
+    headed: ctx.headed,
+    url,
+    maxSteps: ctx.maxSteps,
+    replay: ctx.replay,
+    memory: ctx.memory,
+    skills: skillNames(args.skills),
+    skillsRepo: ctx.cwd,
+    signal: ctx.signal,
+    execute: ctx.execute,
+    onEvent: (event) => emit({ type: "suite-event", event }),
+  })
+  emit({ type: "suite-done", suite })
+  const c = counts(suite.results)
+  return {
+    devices: suite.results.map((r) => ({ device: r.device, status: r.status, summary: clip(r.summary, 600), run_dir: r.runDir, final_url: r.finalUrl })),
+    passed: c.passed,
+    failed: c.failed + c.errors,
+    report: suite.files.html,
+    note: "Each device ran the goal on its own remote browser. To turn it into a test, run write_test with one device's run_dir.",
+  }
+}
+
+/** Devices a tool call asked for, else the session's pinned ones; names checked against the configuration. */
+function devicesFor(args: Record<string, unknown>, ctx: ToolContext): string[] {
+  const asked = Array.isArray(args.devices) ? args.devices.map((d) => String(d).trim()).filter(Boolean) : []
+  const devices = asked.length ? asked : ctx.devices || []
+  if (!devices.length) return []
+  const known = ctx.config.browser?.devices || {}
+  const missing = devices.filter((d) => !known[d])
+  if (missing.length) {
+    throw new Error(`No device named ${missing.join(", ")}. ${Object.keys(known).length ? `Saved devices: ${Object.keys(known).join(", ")}.` : "No device is saved yet."} Save it with browser_devices first.`)
+  }
+  return [...new Set(devices)]
+}
+
 export const TOOLS: McpTool[] = [
   {
     name: "browser_run",
@@ -273,6 +336,7 @@ export const TOOLS: McpTool[] = [
           description:
             "Override the browser provider for this run when the user asked for one specifically. local uses the machine's own browser; browserstack and testmu use their configured YAML or browser.remote settings.",
         },
+        devices: DEVICES_SCHEMA,
         resume_from: {
           type: "string",
           description:
@@ -295,6 +359,10 @@ export const TOOLS: McpTool[] = [
       const resumeFrom = from ? (existsSync(path.resolve(ctx.cwd, from)) ? path.resolve(ctx.cwd, from) : from) : undefined
       const url = args.start_url ? String(args.start_url) : ctx.url
       const selectedBrowser = args.browser_provider ? browserProvider(args.browser_provider) : ctx.browserProvider
+      // Pinned devices are for testing the app: a task (reading a work item, looking something up) runs once, here.
+      const devices = args.purpose === "task" && !Array.isArray(args.devices) ? [] : devicesFor(args, ctx)
+      // Several devices: the goal runs as a one-off case on each, in parallel, through the suite (no write-back).
+      if (devices.length > 1) return runGoalOnDevices(goal, url, devices, args, ctx)
       const runDir = runDirectory(ctx.config.export.outDir)
       const emit = ctx.emit || (() => {})
       const t0 = Date.now()
@@ -303,7 +371,8 @@ export const TOOLS: McpTool[] = [
         const { result, files } = await (ctx.execute || executeRun)({
           config: ctx.config,
           goal,
-          browserProvider: selectedBrowser,
+          browserProvider: devices.length ? undefined : selectedBrowser,
+          browserDevice: devices[0],
           url,
           headed: ctx.headed,
           maxSteps: ctx.maxSteps,
@@ -432,6 +501,7 @@ export const TOOLS: McpTool[] = [
           description:
             "Override the browser provider for every case in this suite when the user asked for one specifically.",
         },
+        devices: DEVICES_SCHEMA,
         skills: SKILLS_SCHEMA,
       },
       required: ["sources"],
@@ -443,10 +513,12 @@ export const TOOLS: McpTool[] = [
       const cases = all.filter((c) => !skip.has(c.id))
       if (!cases.length) return { ran: false, reason: "No case can run as written (suite.case_check: block).", check: checkResult(checks) }
       if (!cases.length) throw new Error("No test cases found.")
-      const parallel = Math.min(Number(args.parallel) || ctx.config.suite.parallel, cases.length)
-      const selectedBrowser = args.browser_provider ? browserProvider(args.browser_provider) : ctx.browserProvider
+      const devices = devicesFor(args, ctx)
+      const shown = deviceCases(cases, devices)
+      const parallel = suiteParallel(Number(args.parallel) || undefined, ctx.config.suite.parallel, devices.length, shown.length)
+      const selectedBrowser = devices.length ? undefined : args.browser_provider ? browserProvider(args.browser_provider) : ctx.browserProvider
       const emit = ctx.emit || (() => {})
-      emit({ type: "suite-start", cases, parallel })
+      emit({ type: "suite-start", cases: shown, parallel })
       // In a session that writes tests, each passed case goes to the coding agent right after its own browser run,
       // inside the suite, rather than every case being explored first and handed over at the end.
       const coder: typeof runCodeAgent = async (o) => {
@@ -472,6 +544,7 @@ export const TOOLS: McpTool[] = [
         cases,
         ...(ctx.writeTests ? { repo: ctx.cwd, coder } : {}),
         browserProvider: selectedBrowser,
+        devices,
         parallel,
         writeBack: typeof args.write_back === "boolean" ? args.write_back : undefined,
         headed: ctx.headed,
@@ -498,8 +571,10 @@ export const TOOLS: McpTool[] = [
         stopped: suite.stopped,
         report: suite.files.html,
         junit: suite.files.junit,
+        ...(devices.length > 1 ? { devices, posted_back: "one combined result per case: it fails when any device fails" } : {}),
         results: suite.results.map((r) => ({
           id: r.case.id,
+          ...(r.device ? { device: r.device } : {}),
           title: r.case.title,
           status: r.status,
           summary: clip(r.summary, 600),
@@ -762,6 +837,7 @@ export const TOOLS: McpTool[] = [
   },
   ...COMMAND_TOOLS,
   ...REPO_TEST_TOOLS,
+  ...DEFECT_TOOLS,
   ...PR_TOOLS,
   ...CASE_TOOLS,
   ...API_TOOLS,
@@ -770,6 +846,8 @@ export const TOOLS: McpTool[] = [
   ...CAPABILITY_TOOLS,
   ...NOTIFY_TOOLS,
   ...REPORT_TOOLS,
+  ...DEVICE_TOOLS,
+  ...ATTACH_TOOLS,
 ]
 
 /** The setup the agent should know about: where it works, which systems are configured, and the defaults. */
@@ -782,7 +860,7 @@ function knowledgeNotes(cfg: AppConfig): string {
     : `No product knowledge yet: the team can describe the product, roles, rules, and test data in ${cfg.knowledge.dir} (forgeqe init adds templates).`
 }
 
-export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url" | "browserProvider">): string {
+export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url" | "browserProvider" | "devices">): string {
   const { config: cfg } = ctx
   const s = cfg.sources
   const systems = [
@@ -823,6 +901,7 @@ export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url"
   const browserSkills = skillsFor(loadSkills(cfg.skills, ctx.cwd), "browser")
   const browserProvider = browser.provider || "local"
   const remoteProviders = (["browserstack", "testmu"] as const).filter((name) => browser.remotes?.[name])
+  const devices = Object.values(browser.devices || {}).map((d) => `${d.name} (${d.provider}: ${d.remote.browser} ${d.remote.browserVersion} on ${d.remote.platform || [d.remote.os, d.remote.osVersion].filter(Boolean).join(" ")})`)
   const skills = browserSkills.length
     ? [`Browser skills (pass the ones a goal needs as skills to browser_run or run_test_cases):`, ...catalogLines(browserSkills)].join("\n")
     : ""
@@ -853,6 +932,10 @@ export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url"
     keys.length ? `Set in ForgeQE's environment (names only, usable with set_ci_secret): ${keys.join(", ")}.` : "",
     ctx.url ? `The user pinned this start URL for browser runs: ${ctx.url}` : "",
     ctx.browserProvider ? `The user pinned this browser provider for runs in this session: ${ctx.browserProvider}.` : "",
+    devices.length
+      ? `Saved devices (pass names as devices to browser_run or run_test_cases; browser_devices adds, changes, or removes them): ${devices.join("; ")}.`
+      : "No devices are saved yet: when the user names devices or browsers to test on, save them with browser_devices.",
+    ctx.devices?.length ? `The user pinned these devices for runs in this session: ${ctx.devices.join(", ")}.` : "",
     skills,
     domainNotes(cfg),
     knowledgeNotes(cfg),

package/src/monitor/run.ts

@@ -234,7 +234,7 @@ export function formatRound(r: RoundResult, nextAt?: Date, cwd = process.cwd()):
   if (ok.length) lines.push(`    ↑ Alert sent: ${ok.join(", ")}`)
   for (const s of r.sent.filter((s) => !s.ok)) lines.push(`    ✗ ${CHANNEL[s.channel]} alert not sent: ${s.error}`)
   if (r.suite) {
-    const total = suiteUsage(r.suite.results)
+    const total = suiteUsage(r.suite.results, r.suite.analysis)
     if (total.usage.input || total.usage.output) lines.push(`    Usage   ${usageLine(total.usage, total.cost)}`)
     lines.push(`    Report  ${path.relative(cwd, r.suite.files.html) || r.suite.files.html}`)
   }

package/src/report/data.ts

@@ -3,6 +3,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
 import path from "node:path"
 
 import type { CaseResult, CaseStatus, Cost, WriteBack } from "../cases/types.ts"
+import type { DefectCluster } from "../cases/defects.ts"
+import { DEFECT_HISTORY } from "../cases/defectHistory.ts"
+import { defectTrends, type DefectTrends } from "../cases/predict.ts"
 import type { ReportEnv } from "./html.ts"
 import { addCost } from "../usage.ts"
 import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
@@ -106,6 +109,10 @@ export type ReportData = {
   cases: ReportCase[]
   posted: WriteBack[]
   history: HistoryRun[]
+  /** Failures grouped by cause, from the suite; unset for a single run and for reports written before defects. */
+  defects?: DefectCluster[]
+  /** How the defects of the suites in this folder went over time, when they have a history. */
+  defectTrends?: DefectTrends
 }
 
 export type ReportCase = {
@@ -183,6 +190,7 @@ export type DataInput = {
   results: CaseResult[]
   posted: WriteBack[]
   env?: ReportEnv
+  defects?: DefectCluster[]
 }
 
 export type DataOptions = {
@@ -243,6 +251,12 @@ export function buildReportData(p: DataInput, opts: DataOptions = {}): ReportDat
     cases,
     posted: p.posted.filter((w) => !w.caseId),
     history: [],
+    ...(p.defects ? { defects: p.defects } : {}),
+  }
+  if (p.kind === "suite" && existsSync(path.join(path.dirname(p.dir), DEFECT_HISTORY))) {
+    try {
+      data.defectTrends = defectTrends(path.dirname(p.dir))
+    } catch {}
   }
   if (p.kind === "suite") {
     data.history = [

package/src/report/html.ts

@@ -4,7 +4,8 @@ import path from "node:path"
 
 import type { RunResult } from "../types.ts"
 import { costOf, type CaseResult, type WriteBack } from "../cases/types.ts"
-import type { AppConfig } from "../config.ts"
+import type { AppConfig, BrowserConfig } from "../config.ts"
+import type { DefectCluster } from "../cases/defects.ts"
 import { packageVersion } from "../tui/theme.ts"
 import { buildReportData, type DataOptions } from "./data.ts"
 
@@ -38,11 +39,21 @@ export function ciInfo(env = process.env): Pick<ReportEnv, "ci" | "commit" | "br
   return {}
 }
 
-export function reportEnv(config: AppConfig, opts: { url?: string; headed?: boolean } = {}): ReportEnv {
+export function reportEnv(
+  config: AppConfig,
+  opts: { url?: string; headed?: boolean; browser?: Pick<BrowserConfig, "provider" | "remote"> & { device?: string } } = {},
+): ReportEnv {
   const llm = config.llm
+  const remote = opts.browser?.remote
+  const where = remote
+    ? `${remote.browser} ${remote.browserVersion} on ${remote.platform || [remote.os, remote.osVersion].filter(Boolean).join(" ")} (${opts.browser!.provider}${opts.browser!.device ? `, device ${opts.browser!.device}` : ""})`
+    : undefined
   return {
     model: `${config.activeProfile} (${llm.provider}/${llm.deployment || llm.model})`,
-    browser: llm.provider === "mock" ? "synthetic page (mock profile)" : `Chrome, ${opts.headed || !config.browser.headless ? "visible" : "headless"}, ${config.browser.width}×${config.browser.height}`,
+    browser:
+      llm.provider === "mock"
+        ? "synthetic page (mock profile)"
+        : where || `Chrome, ${opts.headed || !config.browser.headless ? "visible" : "headless"}, ${config.browser.width}×${config.browser.height}`,
     startUrl: opts.url || config.browser.startUrl,
     version: packageVersion(),
     machine: `${os.hostname()} · ${process.platform}`,
@@ -68,6 +79,7 @@ export type ReportInput = {
   env?: ReportEnv
   /** "run" opens on the case itself; "suite" (the default) on the overview. */
   kind?: "suite" | "run"
+  defects?: DefectCluster[]
 }
 
 /** Built from report-ui/ by `bun run build:report`: one HTML file with the whole React app inlined. */