@capagents/forgeqe 1.1.4 → 1.1.6

package/src/config.ts

@@ -38,6 +38,13 @@ export type BrowserRemoteConfig = {
   extra?: Record<string, unknown>
 }
 
+/** A named remote browser (devices: in a provider file): the provider's shared remote settings with its own on top. */
+export type BrowserDevice = {
+  name: string
+  provider: RemoteBrowserProvider
+  remote: BrowserRemoteConfig
+}
+
 export type BrowserConfig = {
   provider: BrowserProvider
   headless: boolean
@@ -51,6 +58,8 @@ export type BrowserConfig = {
   remote?: BrowserRemoteConfig
   remotes: BrowserRemoteConfigs
   providerFiles: BrowserProviderFiles
+  /** Named devices from the provider files, by name; names are unique across providers. */
+  devices: Record<string, BrowserDevice>
   /** ForgeQE overlay in a visible browser: edge glow, a bar with the current step, the person's input locked. */
   overlay: boolean
   /** A second model call checks the finished run against the goal, and its verdict can fail a run the agent completed. */
@@ -78,6 +87,8 @@ export type CodeConfig = {
   stallAfter?: number
   /** Give Scribe a Playwright-driven browser, set up like the run's, switched on once a step fails. */
   liveBrowser?: boolean
+  /** Give Scribe the code graph of the repository (code_find, code_outline, code_element, …) and link the handoff's elements to the page objects that locate them (code.graph, default true). */
+  graph?: boolean
   /** Before Scribe starts, replay the run's steps as a Playwright script and hand over what worked and where it failed. */
   replay?: boolean
   /** Model for ForgeQE's agent and Scribe as provider/model, instead of the run's llms.json profile. */
@@ -122,11 +133,16 @@ export type SourcesConfig = {
   qtest?: { url: string; tokenEnv: string; projectId: number; statuses: { passed: string; failed: string; error: string } }
   /** File a bug for each failed case, or comment on the open one ForgeQE filed before. */
   bugs?: BugsConfig
+  /**
+   * GitHub: issues as test cases and bugs, and GitHub's MCP server for ForgeQE's agent. `repo` (owner/name) is the default
+   * for issue references; the token is `tokenEnv`, else the GitHub CLI's sign-in. `toolsets`: the MCP server's tool groups.
+   */
+  github?: { repo?: string; apiUrl: string; tokenEnv: string; mcp: boolean; toolsets: string[] }
 }
 
 export type BugsConfig = {
-  system: "jira" | "azure_devops"
-  /** Jira project key. Azure DevOps uses this, or sources.azure_devops.project. */
+  system: "jira" | "azure_devops" | "github"
+  /** Jira project key; GitHub owner/repo (default sources.github.repo). Azure DevOps uses this, or sources.azure_devops.project. */
   project?: string
   /** Jira issue type or Azure DevOps work item type. */
   type: string
@@ -135,6 +151,11 @@ export type BugsConfig = {
   areaPath?: string
   /** Also file bugs for cases that could not run (status error). */
   onError: boolean
+  /**
+   * "defect" (the default): one bug per defect, so cases failing the same way (the same failed request, the same
+   * uncaught error) share a bug, each added to it. "case": one bug per failing case.
+   */
+  groupBy?: "defect" | "case"
 }
 
 /** A site the browser agent can sign in to. Values come from the environment; the agent only sees placeholders. */
@@ -307,6 +328,9 @@ function notifyConfig(raw: unknown): NotifyConfig | undefined {
     if (unknown.length) throw new Error(`${where}.on: ${unknown.join(", ")} is not an event. Events: ${NOTIFY_EVENTS.join(", ")}.`)
     return { name, ...alerts, on: on as NotifyEvent[] }
   })
+  // No channels set up, but a Teams webhook in the environment: a "teams" channel for messages the user asks for. It
+  // takes no events (on: []), so runs nobody watches never start posting to it unasked.
+  if (!channels.length && process.env.TEAMS_WEBHOOK_URL?.trim()) channels.push({ name: "teams", teams: { webhookEnv: "TEAMS_WEBHOOK_URL" }, on: [] })
   if (!channels.length) return undefined
   return { channels, ...(n.report_url ? { reportUrl: trimUrl(n.report_url) } : {}) }
 }
@@ -345,6 +369,8 @@ export type AppConfig = {
   prompts: { stepInstruction: string; guiderails: string; dirs?: { dir: string; source: string }[] }
   /** Product knowledge (.forgeqe/knowledge): see src/knowledge.ts. */
   knowledge?: { dir: string; browserMaxChars: number }
+  /** Defect intelligence (defects: in forgeqe.yaml): see src/cases/defects.ts, repro.ts, rca.ts. */
+  defects: DefectsConfig
   export: { outDir: string; format: string }
   memory: MemoryConfig
   code: CodeConfig
@@ -517,9 +543,16 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   if (!/chrome|edge|chromium/i.test(browser) || /^(playwright|pw)-/i.test(browser)) {
     throw new Error(`${where}.remote.browser is "${browser}": ForgeQE drives remote browsers over the Chrome DevTools Protocol, so use chrome or edge.`)
   }
+  // Checked live: TestMu AI's CDP endpoint opens Chrome sessions only; an Edge session never opens and times out.
+  if (provider === "testmu" && !/chrome/i.test(browser)) {
+    throw new Error(`${where}.remote.browser is "${browser}": TestMu AI's CDP endpoint only serves Chrome, so use Chrome there (Edge works on BrowserStack).`)
+  }
   const browserVersion = String(remote.browser_version || remote.browserVersion || "latest").trim() || "latest"
-  const os = String(remote.os || "").trim() || undefined
-  const osVersion = String(remote.os_version || remote.osVersion || "").trim() || undefined
+  const rawOs = String(remote.os || "").trim() || undefined
+  const rawOsVersion = String(remote.os_version || remote.osVersion || "").trim() || undefined
+  // BrowserStack documents "Windows" and "OS X" with versions like 11 or Sequoia: what people write maps onto those.
+  const os = provider === "browserstack" && rawOs ? browserstackOs(rawOs) : rawOs
+  const osVersion = provider === "browserstack" && rawOsVersion && os === "OS X" ? titleCase(rawOsVersion) : rawOsVersion
   const platform = String(remote.platform || "").trim() || undefined
   if (provider === "browserstack" && (!os || !osVersion)) {
     throw new Error(`${where}.remote.os and ${where}.remote.os_version are required when browser.provider is browserstack.`)
@@ -550,28 +583,68 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   }
 }
 
-function browserRemoteConfigs(browser: Record<string, unknown>, provider: BrowserProvider, base: string): { remotes: BrowserRemoteConfigs; providerFiles: BrowserProviderFiles } {
+function browserstackOs(os: string): string {
+  if (/^(os ?x|macos|mac( ?os)?)$/i.test(os)) return "OS X"
+  if (/^win(dows)?$/i.test(os)) return "Windows"
+  return os
+}
+
+const titleCase = (s: string) => s.toLowerCase().replace(/\b[a-z]/g, (c) => c.toUpperCase())
+
+/** A device name: what the user and the agent call it ("win11-chrome"), also used in folder names. */
+export const DEVICE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+function browserRemoteConfigs(
+  browser: Record<string, unknown>,
+  provider: BrowserProvider,
+  base: string,
+): { remotes: BrowserRemoteConfigs; providerFiles: BrowserProviderFiles; devices: Record<string, BrowserDevice> } {
   const providerFiles = browserProviderFiles(browser, base)
   const remotes: BrowserRemoteConfigs = {}
+  const devices: Record<string, BrowserDevice> = {}
   for (const remoteProvider of REMOTE_BROWSER_PROVIDERS) {
     const fromFile = providerFiles[remoteProvider] ? browserProviderFileSection(providerFiles[remoteProvider]!, remoteProvider) : undefined
     const inline = provider === remoteProvider ? browser : undefined
     if (!fromFile && !inline) continue
     const where = fromFile ? `browser.providers.${remoteProvider}` : "browser"
-    remotes[remoteProvider] = browserRemoteConfig(
-      {
-        ...(fromFile || {}),
-        ...(inline || {}),
-        remote: { ...asRecord(fromFile?.remote), ...asRecord(inline?.remote) },
-      },
-      remoteProvider,
-      where,
-    )
+    const shared = { ...asRecord(fromFile?.remote), ...asRecord(inline?.remote) }
+    const named = objectMap(fromFile?.devices, `${where}.devices`) || {}
+    for (const [name, raw] of Object.entries(named)) {
+      if (!DEVICE_NAME.test(name)) throw new Error(`${where}.devices.${name}: a device name uses letters, digits, ".", "_" and "-".`)
+      const other = devices[name]
+      if (other) throw new Error(`Device ${name} is in both ${other.provider} and ${remoteProvider}; device names must be unique.`)
+      const remote = browserRemoteConfig({ remote: { ...shared, ...asRecord(raw) } }, remoteProvider, `${where}.devices.${name}`)!
+      devices[name] = { name, provider: remoteProvider, remote }
+    }
+    // A provider file that only lists devices: its first device is the provider's default browser.
+    const first = Object.values(devices).find((d) => d.provider === remoteProvider)
+    remotes[remoteProvider] =
+      !String(shared.browser || "").trim() && first
+        ? first.remote
+        : browserRemoteConfig({ ...(fromFile || {}), ...(inline || {}), remote: shared }, remoteProvider, where)
   }
-  return { remotes, providerFiles }
+  return { remotes, providerFiles, devices }
 }
 
-export function browserConfigFor(config: Pick<AppConfig, "browser">, provider = config.browser.provider): Pick<BrowserConfig, "provider" | "remote"> {
+/**
+ * The browser a run uses: a named device (which also picks its provider), else the provider's default remote,
+ * else the local browser. A device on another provider than the one asked for is an error, not a silent switch.
+ */
+export function browserConfigFor(
+  config: Pick<AppConfig, "browser">,
+  provider?: BrowserProvider,
+  device?: string,
+): Pick<BrowserConfig, "provider" | "remote"> & { device?: string } {
+  if (device) {
+    const d = config.browser.devices?.[device]
+    if (!d) {
+      const known = Object.keys(config.browser.devices || {})
+      throw new Error(`No browser device named ${device}. ${known.length ? `Configured: ${known.join(", ")}.` : "None is configured yet."} Add one with browser_devices, or under devices: in the provider's YAML file.`)
+    }
+    if (provider && provider !== d.provider) throw new Error(`Device ${device} is on ${d.provider}, not ${provider}.`)
+    // The session name shows the device in the provider's dashboard.
+    return { provider: d.provider, remote: { ...d.remote, name: [d.remote.name, device].filter(Boolean).join(" · ") }, device }
+  }
   const chosen = provider || config.browser.provider || "local"
   if (chosen === "local") return { provider: chosen }
   const remote = config.browser.remotes?.[chosen] || ((config.browser.provider === chosen || !config.browser.provider) ? config.browser.remote : undefined)
@@ -751,7 +824,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
 
   const sessionsDir = configPath ? path.join(projectDir(base), "sessions") : path.join(forgeqeHome(), "sessions")
   const provider = browserProvider(browser.provider)
-  const { remotes, providerFiles } = browserRemoteConfigs(browser, provider, base)
+  const { remotes, providerFiles, devices } = browserRemoteConfigs(browser, provider, base)
   const config: AppConfig = {
     configPath,
     mcp: extraMcpServers(yaml.mcp, base),
@@ -771,6 +844,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       remote: provider === "local" ? undefined : remotes[provider],
       remotes,
       providerFiles,
+      devices,
       overlay: browser.overlay !== false,
       judge: browser.judge === true,
     },
@@ -780,6 +854,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       dirs: promptDirsFor(prompts, base, configPath),
     },
     knowledge: knowledgeConfig(asRecord(yaml.knowledge), base, configPath),
+    defects: defectsConfig(asRecord(yaml.defects), base),
     export: {
       outDir,
       format: String(exp.format || "playwright"),
@@ -799,6 +874,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       testTimeoutSeconds: Number(code.test_timeout_seconds || 600),
       stallAfter: Math.max(2, Number(code.stall_after || 5)),
       liveBrowser: code.live_browser !== false,
+      graph: code.graph !== false,
       replay: code.replay !== false,
       model: code.model ? String(code.model) : undefined,
       ...(code.review_profile ? { reviewProfile: String(code.review_profile) } : {}),
@@ -1001,6 +1077,26 @@ function sourcesConfig(raw: Record<string, unknown>): SourcesConfig {
     ...optional("zephyr", zephyrConfig(raw.zephyr)),
     ...optional("qtest", qtestConfig(asRecord(raw.qtest))),
     ...optional("bugs", bugsConfig(raw.bugs)),
+    ...optional("github", githubConfig(raw.github)),
+  }
+}
+
+/** The GitHub MCP server's tool groups ForgeQE loads unless sources.github.toolsets says otherwise. */
+export const GITHUB_TOOLSETS = ["repos", "issues", "pull_requests", "actions"]
+
+function githubConfig(raw: unknown): SourcesConfig["github"] {
+  if (raw === undefined || raw === null) return undefined
+  if (raw === false) return { apiUrl: "https://api.github.com", tokenEnv: "GITHUB_TOKEN", mcp: false, toolsets: [] }
+  const g = asRecord(raw)
+  const repo = String(g.repo || "").trim()
+  if (repo && !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new Error(`sources.github.repo is owner/name; got "${repo}".`)
+  const toolsets = Array.isArray(g.toolsets) ? g.toolsets.map(String).filter(Boolean) : GITHUB_TOOLSETS
+  return {
+    ...(repo ? { repo } : {}),
+    apiUrl: String(g.api_url || "https://api.github.com").replace(/\/+$/, ""),
+    tokenEnv: String(g.token_env || "GITHUB_TOKEN"),
+    mcp: g.mcp !== false,
+    toolsets,
   }
 }
 
@@ -1024,6 +1120,27 @@ function promptDirsFor(p: Record<string, unknown>, base: string, configPath: str
   return dirs.filter((d, i) => dirs.findIndex((x) => path.resolve(x.dir) === path.resolve(d.dir)) === i)
 }
 
+export type DefectsConfig = {
+  /** The application's own repository: suspect commits, and the code the root-cause analysis reads. */
+  productRepo?: string
+  /** Run the first case of each new defect once more, to see whether it repeats. */
+  reproduce: boolean
+  /** A model writes a root-cause hypothesis for new defects and regressions. */
+  analyze: boolean
+  /** Most defects analysed by the model in one suite. */
+  maxAnalyses: number
+}
+
+export function defectsConfig(d: Record<string, unknown>, base: string): DefectsConfig {
+  const max = Number(d.max_analyses)
+  return {
+    ...(d.product_repo ? { productRepo: path.resolve(base, String(d.product_repo)) } : {}),
+    reproduce: d.reproduce !== false,
+    analyze: d.analyze !== false,
+    maxAnalyses: Number.isInteger(max) && max >= 0 && d.max_analyses !== undefined ? max : 3,
+  }
+}
+
 function knowledgeConfig(k: Record<string, unknown>, base: string, configPath: string | undefined): NonNullable<AppConfig["knowledge"]> {
   const dir = k.dir ? path.resolve(base, String(k.dir)) : configPath ? path.join(projectDir(base), "knowledge") : path.join(forgeqeHome(), "knowledge")
   const max = Number(k.browser_max_chars)
@@ -1163,7 +1280,7 @@ function bugsConfig(raw: unknown): BugsConfig | undefined {
   if (raw === undefined || raw === null || raw === false) return undefined
   const b = asRecord(raw)
   const system = String(b.system || "").toLowerCase().replace(/[\s-]/g, "_")
-  if (system !== "jira" && system !== "azure_devops") throw new Error(`sources.bugs.system must be jira or azure_devops; got "${String(b.system ?? "")}".`)
+  if (system !== "jira" && system !== "azure_devops" && system !== "github") throw new Error(`sources.bugs.system must be jira, azure_devops, or github; got "${String(b.system ?? "")}".`)
   if (system === "jira" && !b.project) throw new Error("sources.bugs.project is required for Jira: the project key bugs are filed in.")
   return {
     system,
@@ -1172,9 +1289,16 @@ function bugsConfig(raw: unknown): BugsConfig | undefined {
     labels: Array.isArray(b.labels) ? b.labels.map(String).filter(Boolean) : ["forgeqe"],
     ...(b.area_path ? { areaPath: String(b.area_path) } : {}),
     onError: b.on_error === true,
+    ...(groupBy(b.group_by) === "case" ? { groupBy: "case" as const } : {}),
   }
 }
 
+function groupBy(raw: unknown): "defect" | "case" {
+  if (raw === undefined || raw === null || raw === "defect") return "defect"
+  if (raw === "case") return "case"
+  throw new Error(`sources.bugs.group_by must be defect or case; got "${String(raw)}".`)
+}
+
 function jiraMcp(raw: unknown): JiraMcp | false {
   if (raw === false || raw === "false" || raw === "off") return false
   if (raw === undefined || raw === null || raw === true || raw === "mcp-atlassian") return "mcp-atlassian"

package/src/mcp/attachtools.ts

@@ -0,0 +1,223 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import path from "node:path"
+
+import { adoSettings } from "../cases/ado.ts"
+import { http, textToAdf } from "../cases/http.ts"
+import { jiraApi } from "../cases/jira.ts"
+import type { AppConfig } from "../config.ts"
+import type { McpTool } from "./tools.ts"
+
+/**
+ * Evidence onto an existing work item or issue: files from a run (screenshots, the report, JUnit, the trace) uploaded
+ * as attachments, posted in a comment (images inline, text as text), or both. Only files inside the working folder or
+ * the reports folders can go, so a request can never send anything else from the machine.
+ */
+
+const MAX_FILE = 25 * 1024 * 1024
+/** Text read into a comment; longer text is attached instead. */
+const MAX_COMMENT_TEXT = 20_000
+const IMAGE = /\.(png|jpe?g|gif|webp)$/i
+const TEXT = /\.(md|txt|log|json|xml|csv|ya?ml)$/i
+const MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".html": "text/html",
+  ".json": "application/json",
+  ".xml": "application/xml",
+}
+
+export type Pick = "last_screenshot" | "failure_screenshot" | "report" | "junit" | "trace"
+const PICKS: Pick[] = ["last_screenshot", "failure_screenshot", "report", "junit", "trace"]
+
+type File = { path: string; name: string; data: Buffer; type: string }
+
+/** Files a run folder holds, by what they are. A suite folder's last screenshot is its last case's. */
+export function pickFiles(runDir: string, picks: Pick[]): string[] {
+  const out: string[] = []
+  const lastShot = (dir: string): string | undefined => {
+    const steps = path.join(dir, "steps")
+    const shots = existsSync(steps) ? readdirSync(steps).filter((f) => IMAGE.test(f)).sort() : []
+    if (shots.length) return path.join(steps, shots[shots.length - 1])
+    if (existsSync(path.join(dir, "failure.png"))) return path.join(dir, "failure.png")
+    // A suite folder: its case folders, last one first.
+    const cases = readdirSync(dir).filter((d) => statSync(path.join(dir, d)).isDirectory() && d !== "steps").sort().reverse()
+    for (const c of cases) {
+      const shot = lastShot(path.join(dir, c))
+      if (shot) return shot
+    }
+    return undefined
+  }
+  for (const pick of picks) {
+    const file =
+      pick === "last_screenshot"
+        ? lastShot(runDir)
+        : pick === "failure_screenshot"
+          ? [path.join(runDir, "failure.png")].find(existsSync)
+          : pick === "report"
+            ? path.join(runDir, "report.html")
+            : pick === "junit"
+              ? path.join(runDir, "junit.xml")
+              : path.join(runDir, "trace.md")
+    if (!file || !existsSync(file)) throw new Error(`${runDir} has no ${pick.replace("_", " ")}.`)
+    out.push(file)
+  }
+  return out
+}
+
+/** A file to send: inside the working folder or a reports folder, and not too big. */
+function readAllowed(file: string, config: AppConfig, cwd: string): File {
+  if (!existsSync(file)) throw new Error(`No such file: ${file}`)
+  const real = realpathSync(file)
+  const roots = [cwd, config.export?.outDir, config.suite?.outDir, config.monitor?.outDir].filter(Boolean).map((r) => (existsSync(r!) ? realpathSync(r!) : path.resolve(r!)))
+  if (!roots.some((r) => real === r || real.startsWith(`${r}${path.sep}`))) {
+    throw new Error(`${file} is outside the working folder and the reports folders, so it is not sent.`)
+  }
+  const size = statSync(real).size
+  if (size > MAX_FILE) throw new Error(`${file} is ${(size / 1024 / 1024).toFixed(1)} MB; the limit is ${MAX_FILE / 1024 / 1024} MB.`)
+  return { path: real, name: path.basename(real), data: readFileSync(real), type: MIME[path.extname(real).toLowerCase()] || "application/octet-stream" }
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+type Outcome = { item: string; url?: string; attached: string[]; commented: boolean; inline: string[] }
+
+async function toAdo(config: AppConfig, id: string, files: File[], mode: string, comment: string): Promise<Outcome> {
+  const { auth, org } = adoSettings(config.sources)
+  if (!/^\d+$/.test(id)) throw new Error(`An Azure DevOps work item id is a number; got "${id}".`)
+  // Comments and attachments live in the work item's own project.
+  const { data: wi } = await http<{ fields?: Record<string, unknown>; _links?: { html?: { href?: string } } }>(`${org}/_apis/wit/workitems/${id}?fields=System.TeamProject&api-version=7.1`, { auth })
+  const project = encodeURIComponent(String(wi.fields?.["System.TeamProject"] || ""))
+  const scoped = `${org}/${project}`
+  const upload = async (f: File) => {
+    const res = await fetch(`${scoped}/_apis/wit/attachments?fileName=${encodeURIComponent(f.name)}&api-version=7.1`, {
+      method: "POST",
+      headers: { Authorization: auth, "Content-Type": "application/octet-stream", Accept: "application/json" },
+      body: new Uint8Array(f.data),
+    })
+    if (!res.ok) throw new Error(`Uploading ${f.name} to work item ${id} failed: ${res.status} ${res.statusText}.`)
+    return ((await res.json()) as { url: string }).url
+  }
+  const out: Outcome = { item: `#${id}`, url: wi._links?.html?.href, attached: [], commented: false, inline: [] }
+  const urls = new Map<string, string>()
+  if (mode === "attach" || mode === "both") {
+    const ops = []
+    for (const f of files) {
+      const url = await upload(f)
+      urls.set(f.path, url)
+      ops.push({ op: "add", path: "/relations/-", value: { rel: "AttachedFile", url, attributes: { comment: comment ? comment.slice(0, 250) : "Added by ForgeQE" } } })
+      out.attached.push(f.name)
+    }
+    await http(`${org}/_apis/wit/workitems/${id}?api-version=7.1`, { method: "PATCH", auth, body: ops, contentType: "application/json-patch+json" })
+  }
+  if (mode === "comment" || mode === "both") {
+    const parts = comment ? [`<p>${esc(comment).replace(/\n/g, "<br>")}</p>`] : []
+    for (const f of files) {
+      if (IMAGE.test(f.name)) {
+        const url = urls.get(f.path) || (await upload(f))
+        parts.push(`<p><b>${esc(f.name)}</b><br><img src="${url}" alt="${esc(f.name)}"></p>`)
+        out.inline.push(f.name)
+      } else if (TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT) {
+        parts.push(`<p><b>${esc(f.name)}</b></p><pre>${esc(f.data.toString("utf8"))}</pre>`)
+        out.inline.push(f.name)
+      } else {
+        // An HTML report or a big file cannot go in a comment: it is attached, and the comment names it.
+        const url = urls.get(f.path) || (await upload(f))
+        if (!urls.has(f.path)) {
+          await http(`${org}/_apis/wit/workitems/${id}?api-version=7.1`, {
+            method: "PATCH",
+            auth,
+            body: [{ op: "add", path: "/relations/-", value: { rel: "AttachedFile", url, attributes: { comment: "Added by ForgeQE" } } }],
+            contentType: "application/json-patch+json",
+          })
+          out.attached.push(f.name)
+        }
+        parts.push(`<p>Attached: <a href="${url}">${esc(f.name)}</a></p>`)
+      }
+    }
+    await http(`${scoped}/_apis/wit/workItems/${id}/comments?api-version=7.1-preview.4`, { auth, body: { text: parts.join("\n") } })
+    out.commented = true
+  }
+  return out
+}
+
+async function toJira(config: AppConfig, key: string, files: File[], mode: string, comment: string): Promise<Outcome> {
+  const j = jiraApi(config.sources, "Attaching to Jira")
+  const issue = key.trim().toUpperCase()
+  if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(issue)) throw new Error(`A Jira issue key looks like SHOP-12; got "${key}".`)
+  const out: Outcome = { item: issue, url: `${j.url}/browse/${issue}`, attached: [], commented: false, inline: [] }
+  // Jira shows images from the issue's attachments, so files go up as attachments in either mode.
+  const send = files.filter((f) => mode !== "comment" || !(TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT))
+  for (const f of send) {
+    const form = new FormData()
+    form.append("file", new Blob([new Uint8Array(f.data)], { type: f.type }), f.name)
+    const res = await fetch(`${j.api}/issue/${encodeURIComponent(issue)}/attachments`, {
+      method: "POST",
+      headers: { Authorization: j.auth, "X-Atlassian-Token": "no-check", Accept: "application/json" },
+      body: form,
+    })
+    if (!res.ok) throw new Error(`Attaching ${f.name} to ${issue} failed: ${res.status} ${res.statusText}.`)
+    out.attached.push(f.name)
+  }
+  if (mode === "comment" || mode === "both") {
+    const lines = comment ? [comment, ""] : []
+    for (const f of files) {
+      if (TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT) {
+        lines.push(`${f.name}:`, f.data.toString("utf8"), "")
+        out.inline.push(f.name)
+      } else if (IMAGE.test(f.name) && !j.cloud) {
+        // Jira Server/Data Center wiki markup shows an attached image in the comment.
+        lines.push(`!${f.name}|thumbnail!`)
+        out.inline.push(f.name)
+      } else lines.push(`Attached: ${f.name}`)
+    }
+    const text = lines.join("\n").trim()
+    await http(`${j.api}/issue/${encodeURIComponent(issue)}/comment`, { auth: j.auth, body: { body: j.cloud ? textToAdf(text) : text } })
+    out.commented = true
+  }
+  return out
+}
+
+export const ATTACH_TOOLS: McpTool[] = [
+  {
+    name: "attach_to_work_item",
+    description:
+      "Put evidence on an existing Azure DevOps work item or Jira issue, when the user asks (\"add the screenshot to ADO 256\", \"attach the report to SHOP-12\", \"comment the results on the bug\"). mode attach uploads the files as attachments; comment posts a comment with images shown inline and text files as text (an HTML report cannot be shown in a comment, so it is attached and named); both does both. Files come from a run folder by what they are (pick), or by path; only files in the working folder or the reports folders can be sent. Returns the item's link and what went where.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"] },
+        item: { type: "string", description: "Work item id (azure_devops), e.g. 256, or issue key (jira), e.g. SHOP-12" },
+        mode: { type: "string", enum: ["attach", "comment", "both"], description: "attach: upload as attachments. comment: one comment with the files in it. both: attachments and a comment (default when the user did not say)" },
+        run_dir: { type: "string", description: "A run or suite folder from browser_run or run_test_cases, to pick files from" },
+        pick: { type: "array", items: { type: "string", enum: PICKS }, description: "What to take from run_dir: last_screenshot, failure_screenshot, report, junit, trace" },
+        files: { type: "array", items: { type: "string" }, description: "Other files by path, relative to the working folder" },
+        comment: { type: "string", description: "Text for the comment (comment/both), and the attachment note: what ran, where, the result" },
+      },
+      required: ["system", "item"],
+    },
+    async run(args, ctx) {
+      const mode = String(args.mode || "both")
+      if (!["attach", "comment", "both"].includes(mode)) throw new Error(`mode is attach, comment, or both; got "${mode}".`)
+      const picks = (Array.isArray(args.pick) ? args.pick.map(String) : []) as Pick[]
+      const bad = picks.filter((p) => !PICKS.includes(p))
+      if (bad.length) throw new Error(`pick takes ${PICKS.join(", ")}; got ${bad.join(", ")}.`)
+      if (picks.length && !args.run_dir) throw new Error("pick needs run_dir: the run folder to take the files from.")
+      const runDir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : ""
+      const paths = [...(runDir ? pickFiles(runDir, picks.length ? picks : ["last_screenshot"]) : []), ...(Array.isArray(args.files) ? args.files.map((f) => path.resolve(ctx.cwd, String(f))) : [])]
+      const comment = String(args.comment || "").trim()
+      if (!paths.length && !comment) throw new Error("Nothing to add: give run_dir (and pick), files, or a comment.")
+      if (!paths.length && mode === "attach") throw new Error("Nothing to attach: give run_dir (and pick) or files.")
+      const files = [...new Set(paths)].map((p) => readAllowed(p, ctx.config, ctx.cwd))
+      const out = args.system === "jira" ? await toJira(ctx.config, String(args.item), files, mode, comment) : await toAdo(ctx.config, String(args.item), files, mode, comment)
+      return {
+        item: out.item,
+        ...(out.url ? { link: out.url } : {}),
+        ...(out.attached.length ? { attached: out.attached } : {}),
+        ...(out.commented ? { comment: out.inline.length ? `posted, with ${out.inline.join(", ")} in it` : "posted" } : {}),
+      }
+    },
+  },
+]

package/src/mcp/commands.ts

@@ -361,7 +361,7 @@ export const COMMAND_TOOLS: McpTool[] = [
             note: "The user switches profiles with Tab or /profile in the shell, or --profile.",
           }
         case "mcp_servers": {
-          const { servers, skipped } = externalMcp(cfg)
+          const { servers, skipped } = externalMcp(cfg, Bun.which, process.env, { cwd: ctx.cwd })
           return {
             servers: servers.map((s) => {
               const c = s.config as { type: string; command?: string[]; url?: string }

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,
+      }
+    },
+  },
+]