@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/code/history.ts

@@ -0,0 +1,170 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { projectDir } from "../tools.ts"
+
+/**
+ * Each automated test's recent results in a repository, to tell a flaky test from a broken one, and the tests in
+ * quarantine. Kept in .forgeqe/test-history.json in the repository (commit it to share the history; CI can keep it
+ * between runs as a cache). Quarantine changes no test code: a quarantined test still runs, so its history goes on,
+ * but its failure does not fail the run.
+ */
+
+export const HISTORY_FILE = path.join(".forgeqe", "test-history.json")
+const KEEP = 30
+const WINDOW = 20
+/** Consecutive clean passes after which a quarantined test is offered for release. */
+export const RELEASE_AFTER = 5
+
+export type Result = { at: string; status: "passed" | "failed" | "skipped"; /** Failed, then passed when run again. */ retried?: boolean; message?: string; seconds?: number }
+export type Quarantine = { at: string; reason: string; by: "auto" | "user" }
+export type TestHistory = { runs: Result[]; quarantined?: Quarantine }
+type HistoryFile = { version: 1; tests: Record<string, TestHistory> }
+
+export type Cause = "timing" | "overlay" | "data" | "network" | "environment" | "unknown"
+
+export const CAUSE_TEXT: Record<Cause, string> = {
+  timing: "timing: waits that are too short or race the page (timeouts, elements not ready, detached)",
+  overlay: "something covers the element now and then (a banner, a dialog, a spinner intercepts the click)",
+  data: "data that changes between runs (other values, other counts, data left by another test)",
+  network: "network or backend errors now and then (failed requests, 5xx, resets)",
+  environment: "the environment (the browser crashed or closed, the server was not ready)",
+  unknown: "no pattern in the failure messages",
+}
+
+export type Flakiness = {
+  name: string
+  runs: number
+  passRate: number
+  /** Runs where it failed, then passed when run again, in the last WINDOW runs. */
+  retryPasses: number
+  /** Pass/fail changes in the last WINDOW runs. */
+  flips: number
+  score: number
+  flaky: boolean
+  cause: Cause
+  example?: string
+  /** The last results, oldest first: ✓ passed, ✗ failed, ↻ passed on retry, – skipped. */
+  trail: string
+  quarantined?: Quarantine
+  /** Quarantined and clean for RELEASE_AFTER runs in a row. */
+  releasable: boolean
+}
+
+const file = (repo: string) => path.join(projectDir(repo), path.basename(HISTORY_FILE))
+
+export function readHistory(repo: string): HistoryFile {
+  try {
+    const data = JSON.parse(readFileSync(file(repo), "utf8")) as HistoryFile
+    return { version: 1, tests: data?.tests && typeof data.tests === "object" ? data.tests : {} }
+  } catch {
+    return { version: 1, tests: {} }
+  }
+}
+
+function save(repo: string, h: HistoryFile) {
+  mkdirSync(path.dirname(file(repo)), { recursive: true })
+  writeFileSync(file(repo), `${JSON.stringify(h, null, 1)}\n`)
+}
+
+/** Add one run's results. */
+export function recordResults(repo: string, results: { name: string; status: Result["status"]; retried?: boolean; message?: string; seconds?: number }[], at = new Date().toISOString()): void {
+  if (!results.length) return
+  const h = readHistory(repo)
+  for (const r of results) {
+    const t = h.tests[r.name] || { runs: [] }
+    t.runs.push({ at, status: r.status, ...(r.retried ? { retried: true } : {}), ...(r.message ? { message: r.message.slice(0, 300) } : {}), ...(r.seconds !== undefined ? { seconds: r.seconds } : {}) })
+    t.runs = t.runs.slice(-KEEP)
+    h.tests[r.name] = t
+  }
+  save(repo, h)
+}
+
+/** The likely cause behind a test's failure messages. */
+export function likelyCause(messages: string[]): { cause: Cause; example?: string } {
+  const rules: [Cause, RegExp][] = [
+    ["overlay", /intercepts pointer events|element is not visible|is covered|obscured|not clickable at point|other element would receive the click|ElementClickInterceptedException/i],
+    ["network", /net::ERR_|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|\b5\d\d\b.*(error|status|response)|request failed|fetch failed/i],
+    ["environment", /browser has been closed|Target (page, context or browser )?closed|browser crashed|Protocol error|WebDriverException|session not created|server (is )?not (ready|running)/i],
+    ["timing", /timeout|timed out|exceeded|waiting for|detached from (the )?DOM|stale element|not attached|toBeVisible|toHaveText.*\bTimeout\b/i],
+    ["data", /expected[\s\S]{0,80}(received|but (was|got)|actual)|toEqual|toBe\(|AssertionError|assert .* ==|Expected: .*\n?\s*Received:/i],
+  ]
+  const counts = new Map<Cause, { n: number; example: string }>()
+  for (const m of messages.filter(Boolean)) {
+    const hit = rules.find(([, r]) => r.test(m))
+    if (!hit) continue
+    const c = counts.get(hit[0]) || { n: 0, example: m }
+    c.n++
+    counts.set(hit[0], c)
+  }
+  const best = [...counts].sort((a, b) => b[1].n - a[1].n)[0]
+  return best ? { cause: best[0], example: best[1].example.slice(0, 200) } : { cause: "unknown" }
+}
+
+/** How flaky a test is from its history: passes on retry and flip-flops, but a test that only fails is broken, not flaky. */
+export function flakiness(name: string, t: TestHistory, flakyAfter = 2): Flakiness {
+  const ran = t.runs.filter((r) => r.status !== "skipped")
+  const recent = ran.slice(-WINDOW)
+  let flips = 0
+  for (let i = 1; i < recent.length; i++) if (recent[i].status !== recent[i - 1].status) flips++
+  const retryPasses = recent.filter((r) => r.retried).length
+  const passes = recent.filter((r) => r.status === "passed").length
+  const failures = recent.filter((r) => r.status === "failed").length + retryPasses
+  const score = retryPasses + Math.floor(flips / 2)
+  const tail = ran.slice(-RELEASE_AFTER)
+  const { cause, example } = likelyCause(t.runs.slice(-WINDOW).filter((r) => r.message).map((r) => r.message!))
+  return {
+    name,
+    runs: ran.length,
+    passRate: recent.length ? Math.round((passes / recent.length) * 100) / 100 : 0,
+    retryPasses,
+    flips,
+    score,
+    flaky: score >= flakyAfter && passes > 0 && failures > 0,
+    cause,
+    ...(example ? { example } : {}),
+    trail: t.runs.slice(-WINDOW).map((r) => (r.status === "skipped" ? "–" : r.retried ? "↻" : r.status === "passed" ? "✓" : "✗")).join(""),
+    ...(t.quarantined ? { quarantined: t.quarantined } : {}),
+    releasable: Boolean(t.quarantined) && tail.length === RELEASE_AFTER && tail.every((r) => r.status === "passed" && !r.retried),
+  }
+}
+
+/** Every test's flakiness, flakiest first. */
+export function flakyReport(repo: string, flakyAfter = 2): Flakiness[] {
+  return Object.entries(readHistory(repo).tests)
+    .map(([name, t]) => flakiness(name, t, flakyAfter))
+    .sort((a, b) => Number(Boolean(b.quarantined)) - Number(Boolean(a.quarantined)) || b.score - a.score || a.passRate - b.passRate)
+}
+
+export function quarantined(repo: string): Map<string, Quarantine> {
+  return new Map(Object.entries(readHistory(repo).tests).flatMap(([n, t]) => (t.quarantined ? [[n, t.quarantined] as [string, Quarantine]] : [])))
+}
+
+/** Put tests in quarantine, or take them out (reason null). Returns the names changed. */
+export function setQuarantine(repo: string, names: string[], reason: string | null, by: Quarantine["by"] = "user"): string[] {
+  const h = readHistory(repo)
+  const changed: string[] = []
+  for (const n of names) {
+    const t = h.tests[n] || { runs: [] }
+    if (reason === null) {
+      if (!t.quarantined) continue
+      delete t.quarantined
+    } else {
+      if (t.quarantined) continue
+      t.quarantined = { at: new Date().toISOString(), reason, by }
+    }
+    h.tests[n] = t
+    changed.push(n)
+  }
+  if (changed.length) save(repo, h)
+  return changed
+}
+
+/** A test name ForgeQE knows, from a name the user gave: exact, else the one that contains it. */
+export function matchTest(repo: string, given: string): string | null {
+  const names = Object.keys(readHistory(repo).tests)
+  if (names.includes(given)) return given
+  const low = given.toLowerCase()
+  const hits = names.filter((n) => n.toLowerCase().includes(low))
+  return hits.length === 1 ? hits[0] : null
+}

package/src/code/impact.ts

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { adoSettings } from "../cases/ado.ts"
+import { http } from "../cases/http.ts"
+import { runDirectory } from "../run.ts"
+import type { TestSelection } from "./find.ts"
+import { readMappings } from "./traceability.ts"
+
+/**
+ * Which of a repository's tests a change affects, without a model: the test files it changes, the tests that import
+ * a changed file (following imports through page objects and helpers), the tests that name a changed class or page
+ * object, and the tests mapped (.forgeqe/test-cases.json) to the test cases of the work items the change is linked
+ * to. Each test comes with its reasons, so a person, or the find-tests agent, can see why it was picked.
+ */
+
+export type ImpactedTest = { file: string; reasons: string[] }
+export type Impact = { changed: string[]; tests: ImpactedTest[]; untested: string[] }
+
+// By name, as the frameworks find them: a helper in a tests/ folder is not a test, and imports go on through it.
+const TEST_FILE = /\.(spec|test|e2e|cy)\.[cm]?[jt]sx?$|(^|\/)test_[^/]*\.py$|_test\.py$|Tests?\.(cs|java|kt)$|Spec\.(cs|java|kt)$/i
+const CODE = /\.([cm]?[jt]sx?|py|cs|java|kt)$/i
+const SKIP = /(^|\/)(node_modules|dist|build|out|bin|obj|\.forgeqe|\.venv|venv|__pycache__|coverage|test-results|playwright-report|needs-attention)\//
+const MAX_FILES = 6000
+const MAX_READ = 300_000
+
+const posix = (p: string) => p.split(path.sep).join("/")
+const git = (repo: string, args: string[]) => spawnSync("git", ["-c", "core.quotepath=false", ...args], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+
+export const isTestFile = (rel: string) => TEST_FILE.test(rel) && CODE.test(rel)
+
+/** Files changed between the merge base of `base` and `head`, existing in the working tree or not. */
+export function changedBetween(repo: string, base: string, head = "HEAD"): string[] {
+  const mb = git(repo, ["merge-base", base, head])
+  if (mb.status !== 0) throw new Error(`No common history between ${base} and ${head}: ${mb.stderr.trim().slice(0, 300)}`)
+  const out = git(repo, ["diff", "--name-only", "-M", mb.stdout.trim(), head])
+  if (out.status !== 0) throw new Error(`git diff failed: ${out.stderr.trim().slice(0, 300)}`)
+  return out.stdout.split("\n").map((l) => l.trim()).filter(Boolean)
+}
+
+function trackedCode(repo: string): string[] {
+  const out = git(repo, ["ls-files", "--cached", "--others", "--exclude-standard"])
+  return out.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((f) => f && CODE.test(f) && !SKIP.test(f))
+    .slice(0, MAX_FILES)
+}
+
+function read(repo: string, rel: string): string {
+  try {
+    const file = path.join(repo, rel)
+    return statSync(file).size <= MAX_READ ? readFileSync(file, "utf8") : ""
+  } catch {
+    return ""
+  }
+}
+
+/** The files a JS/TS or Python file imports, as repository paths (only those that exist). */
+export function importsOf(rel: string, text: string, files: Set<string>): string[] {
+  const dir = path.posix.dirname(rel)
+  const out: string[] = []
+  if (/\.[cm]?[jt]sx?$/i.test(rel)) {
+    for (const m of text.matchAll(/(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)['"](\.{1,2}\/[^'"]+)['"]/gm)) {
+      const base = path.posix.normalize(path.posix.join(dir, m[1]))
+      const hit = [base, ...[".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].map((e) => base.replace(/\.(js|mjs|cjs)$/, "") + e), ...["ts", "tsx", "js"].map((e) => `${base}/index.${e}`)].find((c) => files.has(c))
+      if (hit) out.push(hit)
+    }
+  } else if (/\.py$/i.test(rel)) {
+    for (const m of text.matchAll(/^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))/gm)) {
+      const mod = (m[1] || m[2]).replace(/^\.+/, "")
+      if (!mod) continue
+      const tail = mod.split(".").join("/")
+      const hit = [...files].find((f) => f.endsWith(`${tail}.py`) || f.endsWith(`${tail}/__init__.py`))
+      if (hit) out.push(hit)
+    }
+  }
+  return out
+}
+
+/** A changed file's names a test can mention: its class or module name (LoginPage from pages/LoginPage.ts). */
+function namesOf(rel: string): string[] {
+  const stem = path.posix.basename(rel).replace(/\.(spec|test)?\.?[cm]?[jt]sx?$|\.(py|cs|java|kt)$/i, "")
+  return stem.length >= 5 && /[A-Z_]/.test(stem) ? [stem] : []
+}
+
+/** The tests a change affects, each with why. `mapped` adds tests found from linked test cases. */
+export function analyzeImpact(repo: string, changed: string[], mapped: ImpactedTest[] = []): Impact {
+  const files = trackedCode(repo)
+  const set = new Set(files)
+  const tests = new Map<string, Set<string>>()
+  const add = (file: string, why: string) => {
+    if (!existsSync(path.join(repo, file))) return
+    if (!tests.has(file)) tests.set(file, new Set())
+    tests.get(file)!.add(why)
+  }
+  for (const f of changed) if (isTestFile(f)) add(f, "changed in this pull request")
+
+  // Who imports whom, reversed, so a changed module leads to every test that reaches it.
+  const importers = new Map<string, string[]>()
+  const texts = new Map<string, string>()
+  for (const f of files) {
+    const text = read(repo, f)
+    texts.set(f, text)
+    for (const dep of importsOf(f, text, set)) importers.set(dep, [...(importers.get(dep) || []), f])
+  }
+  const source = changed.filter((f) => CODE.test(f) && !isTestFile(f))
+  const reached = new Set<string>()
+  for (const f of source) {
+    const queue = [{ file: f, depth: 0 }]
+    const seen = new Set([f])
+    while (queue.length) {
+      const { file, depth } = queue.shift()!
+      for (const imp of importers.get(file) || []) {
+        if (seen.has(imp) || depth >= 6) continue
+        seen.add(imp)
+        if (isTestFile(imp)) {
+          add(imp, `imports ${f}${depth ? " (through other modules)" : ""}`)
+          reached.add(f)
+        } else queue.push({ file: imp, depth: depth + 1 })
+      }
+    }
+  }
+  // C#, Java, and anything imports cannot show: tests that name a changed class or page object.
+  const testFiles = files.filter(isTestFile)
+  for (const f of source) {
+    for (const name of namesOf(f)) {
+      const word = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`)
+      for (const t of testFiles) {
+        if (word.test(texts.get(t) || "")) {
+          add(t, `uses ${name} (${f})`)
+          reached.add(f)
+        }
+      }
+    }
+  }
+  for (const m of mapped) for (const why of m.reasons) add(m.file, why)
+  return {
+    changed,
+    tests: [...tests].map(([file, reasons]) => ({ file, reasons: [...reasons] })).sort((a, b) => a.file.localeCompare(b.file)),
+    untested: source.filter((f) => !reached.has(f)),
+  }
+}
+
+/**
+ * Tests mapped to the test cases that test the given Azure DevOps work items (a story or bug linked to the pull
+ * request, "Tested By" its test cases): from .forgeqe/test-cases.json.
+ */
+export async function testsForWorkItems(cfg: AppConfig, repo: string, ids: number[]): Promise<ImpactedTest[]> {
+  if (!ids.length || !cfg.sources.ado) return []
+  const map = readMappings(repo).cases
+  const { org, auth } = adoSettings(cfg.sources)
+  const out: ImpactedTest[] = []
+  for (const id of ids.slice(0, 20)) {
+    try {
+      const { data } = await http<{ relations?: { rel: string; url: string }[] }>(`${org}/_apis/wit/workitems/${id}?$expand=relations&api-version=7.1`, { auth })
+      for (const r of data?.relations || []) {
+        if (r.rel !== "Microsoft.VSTS.Common.TestedBy-Forward") continue
+        const caseId = `ADO-${r.url.split("/").pop()}`
+        const m = map[caseId]
+        if (m?.testFile && m.status !== "needs_attention") out.push({ file: m.testFile, reasons: [`automates ${caseId}, which tests work item ${id} linked to the pull request`] })
+      }
+    } catch {
+      // A work item the token cannot read: the other signals still count.
+    }
+  }
+  return out
+}
+
+/** The nearest folder above `file` (inside the repo) that holds one of `names`. */
+function nearest(repo: string, file: string, names: string[]): string | null {
+  let dir = path.dirname(path.join(repo, file))
+  while (!path.relative(repo, dir).startsWith("..")) {
+    if (names.some((n) => existsSync(path.join(dir, n)))) return dir
+    const up = path.dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  return null
+}
+
+const quote = (s: string) => (/^[\w./@:-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+/**
+ * A run command for the impacted test files, without a model, writing JUnit XML to `junit`: Playwright and pytest.
+ * Null for other frameworks (the find-tests agent works those out).
+ */
+export function impactCommand(repo: string, files: string[], junit: string): { command: string; framework: string } | null {
+  if (!files.length) return null
+  const js = files.filter((f) => /\.[cm]?[jt]sx?$/i.test(f))
+  const py = files.filter((f) => /\.py$/i.test(f))
+  const env = (name: string, value: string) => (process.platform === "win32" ? `set ${name}=${value}&& ` : `${name}=${quote(value)} `)
+  if (js.length === files.length) {
+    const dir = nearest(repo, js[0], ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"])
+    if (!dir || js.some((f) => nearest(repo, f, ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"]) !== dir)) return null
+    const rel = js.map((f) => quote(posix(path.relative(dir, path.join(repo, f)))))
+    const cd = posix(path.relative(repo, dir))
+    return { framework: "Playwright", command: `${cd ? `cd ${quote(cd)} && ` : ""}${env("PLAYWRIGHT_JUNIT_OUTPUT_NAME", junit)}npx playwright test ${rel.join(" ")} --reporter=line,junit` }
+  }
+  if (py.length === files.length) return { framework: "pytest", command: `python -m pytest ${py.map(quote).join(" ")} --junitxml=${quote(junit)}` }
+  return null
+}
+
+/** A test selection run_tests can run (after the user confirms), from the impact analysis alone. */
+export function impactSelection(cfg: AppConfig, repo: string, request: string, impact: Impact): TestSelection | null {
+  const dir = runDirectory(path.join(cfg.export.outDir, "tests"))
+  const junit = path.join(dir, "results.xml")
+  const cmd = impactCommand(repo, impact.tests.map((t) => t.file), junit)
+  if (!cmd) return null
+  const sel: TestSelection = {
+    id: path.basename(dir),
+    dir,
+    repo,
+    request,
+    framework: cmd.framework,
+    tests: impact.tests.map((t) => ({ name: t.file, file: t.file, reason: t.reasons.join("; ") })),
+    related: [],
+    listCommand: "",
+    listed: false,
+    runCommand: cmd.command,
+    results: [junit],
+    notes: impact.untested.length ? `No test reaches: ${impact.untested.join(", ")}.` : "",
+    model: "",
+    usage: { input: 0, output: 0 },
+    createdAt: new Date().toISOString(),
+  }
+  writeFileSync(path.join(dir, "selection.json"), JSON.stringify(sel, null, 2))
+  return sel
+}

package/src/code/index.ts

@@ -0,0 +1,34 @@
+import { existsSync, readdirSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { RunResult } from "../types.ts"
+import type { AppConfig } from "../config.ts"
+import { FAILURE_ACTION, FAILURE_LABEL, type Failure } from "../cases/failure.ts"
+
+export { runCodeAgent } from "./loop.ts"
+
+/** Newest run directory under the export folder that has a run.json. */
+export function latestRunDir(outRoot: string): string | undefined {
+  if (!existsSync(outRoot)) return undefined
+  return readdirSync(outRoot)
+    .map((name) => path.join(outRoot, name))
+    .filter((dir) => existsSync(path.join(dir, "run.json")))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0]
+}
+
+/**
+ * Why the coding step should not follow this run, or null when it should. A run that found a functional defect goes
+ * to the coding agent too: the test asserts the correct behaviour and is marked as an expected failure.
+ */
+export function codeSkipReason(cfg: AppConfig, result: Pick<RunResult, "status" | "driver" | "outcome" | "failedChecks">, failure?: Failure): string | null {
+  if (failure && failure.type !== "functional_defect") return `${FAILURE_LABEL[failure.type]}: ${FAILURE_ACTION[failure.type]}`
+  if (!failure && result.outcome === "assertion_failed") {
+    const what = (result.failedChecks || []).map((c) => `expected ${c.expected}, the page shows ${c.actual}`).join("; ")
+    return `the test case failed: an expected result does not hold (${what || "see the run"}); a test is written from a passing run`
+  }
+  if (!failure && result.status !== "complete") return "the browser run did not pass"
+  if (result.driver === "synthetic") return "mock runs have no real page to test"
+  if (cfg.llm.provider === "mock" && !cfg.code.model) return "the mock profile has no model; pick a live profile or set code.model"
+  if (cfg.llm.provider === "none" && !cfg.code.model) return "no model is set up; add a profile to llms.json or set code.model"
+  return null
+}

package/src/code/livebrowser.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+/** The agent runtime names this server's tools `live_<tool>`, e.g. `live_browser_snapshot`. */
+export const LIVE_BROWSER_SERVER = "live"
+export const PLAYWRIGHT_MCP = "@playwright/mcp@0.0.83"
+/** Also the time allowed for the first start, when npx downloads the server. */
+const TIMEOUT_MS = 120_000
+
+type BrowserProfile = {
+  channel?: string
+  executable?: string
+  headless?: boolean
+  user_agent?: string
+  language?: string
+  timezone?: string
+  viewport?: number[]
+}
+
+export type LiveBrowser = {
+  /** MCP server config for the agent runtime. */
+  config: Record<string, unknown>
+  /** Where the server saves screenshots and snapshots; the coding agent may read it. */
+  dir: string
+}
+
+function runBrowser(runDir: string): BrowserProfile {
+  try {
+    return (JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8")).browser || {}) as BrowserProfile
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Microsoft's Playwright MCP server on a browser set up like the one the run used (channel, headless, user agent,
+ * language, time zone, viewport), so the coding agent can open pages, read their elements, try locators, and act in
+ * seconds, through the same library the repository's tests use, instead of building and running a test to look.
+ * Null without Node.js (npx).
+ */
+export function liveBrowser(runDir: string, which: (bin: string) => string | null = Bun.which): LiveBrowser | null {
+  if (!which("npx")) return null
+  const b = runBrowser(runDir)
+  const dir = path.join(runDir, "live-browser")
+  mkdirSync(dir, { recursive: true })
+  const launch: Record<string, unknown> = { headless: Boolean(b.headless) }
+  if (b.channel) launch.channel = b.channel
+  else if (b.executable && existsSync(b.executable)) launch.executablePath = b.executable
+  else launch.channel = "chrome"
+  const context: Record<string, unknown> = {}
+  if (b.viewport?.length === 2) context.viewport = { width: b.viewport[0], height: b.viewport[1] }
+  if (b.language) context.locale = b.language
+  if (b.timezone) context.timezoneId = b.timezone
+  if (b.user_agent) context.userAgent = b.user_agent
+  const file = path.join(dir, "config.json")
+  writeFileSync(
+    file,
+    `${JSON.stringify({ browser: { browserName: "chromium", isolated: true, launchOptions: launch, contextOptions: context }, outputDir: dir }, null, 2)}\n`,
+  )
+  return {
+    dir,
+    // --snapshot-mode none: clicks, typing, and navigation do not return a full page snapshot each. Every tool result
+    // stays in the coding agent's conversation and is sent again with each later call, so on a heavy page those
+    // snapshots made up most of a job's tokens. The agent takes a snapshot (or finds one element) when it needs one.
+    config: { type: "local", command: ["npx", "-y", PLAYWRIGHT_MCP, "--config", file, "--snapshot-mode", "none"], enabled: true, timeout: TIMEOUT_MS },
+  }
+}