@capagents/forgeqe 1.1.2 → 1.1.4

package/src/capabilities/registry.ts

@@ -61,11 +61,11 @@ export const CAPABILITIES: Capability[] = [
     area: "Browser",
     title: "Run any goal in a real browser",
     summary:
-      "Carries out a plain-language goal in Chrome one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper.",
+      "Carries out a plain-language goal in a real browser one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when configured. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper.",
     tools: ["browser_run", "run_details", "page_memory"],
     examples: ["Go to booking.com and search hotels in Mumbai for next weekend", "What does ForgeQE know about the checkout page?"],
     requires: [{ kind: "live_model" }],
-    limits: ["Web applications in Chrome or Chromium only: not native mobile or desktop applications."],
+    limits: ["Web applications only: local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest; not native mobile or desktop applications."],
     docs: [
       { doc: "HOW_TO_USE.md", heading: "4. Without the shell" },
       { doc: "HOW_TO_USE.md", heading: "5. Page memory" },
@@ -345,7 +345,7 @@ export const CAPABILITIES: Capability[] = [
  * Only add what is certain.
  */
 export const OUT_OF_SCOPE: { what: string; instead?: string }[] = [
-  { what: "Native mobile apps (iOS, Android) and desktop applications", instead: "web applications in Chrome or Chromium" },
+  { what: "Native mobile apps (iOS, Android) and desktop applications", instead: "web applications in local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest" },
   { what: "Load, stress, or soak testing with many simultaneous users", instead: "per-page Core Web Vitals with budgets" },
   { what: "Penetration testing or dynamic security scanning", instead: "security findings in pull request reviews" },
 ]

package/src/cli/help.ts

@@ -17,26 +17,32 @@ Usage:
                  [--repo DIR] [--no-code]
   forgeqe run "<request>" [--profile name] [--url URL] [--headed] [--plain] [--max-steps N]
                [--repo DIR] [--no-code] [--replay MODE] [--no-memory] [--attempts N] [--code-model provider/model]
+               [--browser-provider local|browserstack|testmu]
                                                ForgeQE's agent works out what the request needs: a browser goal,
                                                test cases from Jira, Azure DevOps, Xray or files, a test, a pipeline
-  forgeqe run --direct "<goal>" [--out DIR] [--skill NAME] ...  one browser goal, no agent
+  forgeqe run --direct "<goal>" [--out DIR] [--skill NAME] [--browser-provider local|browserstack|testmu] ...  one browser goal, no agent
   forgeqe suite <source...> [--parallel N] [--repo DIR] [--no-code] [--no-write-back] [--out DIR]
                  [--profile name] [--url URL] [--headed] [--plain] [--attempts N] [--skill NAME]
+                 [--browser-provider local|browserstack|testmu]
                                                run test cases the same way every time (what pipelines call)
   forgeqe cases <source...> [--goal]          list the test cases a source gives (--goal: the goal each runs)
   forgeqe code [run-dir] [--repo DIR] [--attempts N] [--code-model provider/model]
                                                write a test for a run (default: the latest) with Scribe
   forgeqe heal ["<test command>"] [--repo DIR] [--attempts N] [--code-model provider/model] [--headed] [--plain]
+                [--browser-provider local|browserstack|testmu]
                                                run the repo's tests and heal the ones the app has outgrown
   forgeqe monitor [source...] [--every 15m] [--once] [--replay MODE] [--parallel N] [--out DIR] [--verbose] [--skill NAME]
+                  [--browser-provider local|browserstack|testmu]
                                                check flows on a schedule and alert Teams or email when one breaks
   forgeqe monitor --test-alerts               send a sample alert to check the Teams and email settings
-  forgeqe mcp [--repo DIR] [--profile name] [--url URL] [--headed]
+  forgeqe mcp [--repo DIR] [--profile name] [--url URL] [--headed] [--browser-provider local|browserstack|testmu]
                                                ForgeQE's tools as an MCP server on stdio, for other agents
   forgeqe mcp list                            the Azure DevOps, Jira and other MCP servers ForgeQE's agent gets
-  forgeqe bi [build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR]
-                                               export ForgeQE + ADO/Jira datasets into an Evidence project and build static BI HTML
-  forgeqe bi init                             scaffold or refresh the managed Evidence project files
+  forgeqe bi [build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR] [--static | --evidence]
+                                               export ForgeQE + ADO/Jira datasets into an Evidence project and build a static
+                                               site; without Node.js or when Evidence fails, ForgeQE's own page (--static: always,
+                                               --evidence: fail instead)
+  forgeqe bi init                             scaffold the Evidence project and install its packages
   forgeqe bi sync                             refresh the CSV datasets and generated Evidence pages, without building
   forgeqe pr-tests [pr] [--base BRANCH] [--agent] [--run] [--post]
                                                the tests a pull request (or the commits since BRANCH) can break; --run runs
@@ -52,6 +58,7 @@ Usage:
   forgeqe visual approve [run-dir] [--page a,b] [--yes]
                                                make the run's screenshots the new baselines (an intended change)
   forgeqe explore <story> [--url URL] [--charters N] [--roles a,b] [--focus TEXT] [--yes] [--file-bugs]
+                         [--browser-provider local|browserstack|testmu]
                                                exploratory testing of a story (ado:123, SHOP-12, a link, or its text):
                                                charters beyond the scripted cases, defects confirmed by a second run,
                                                proposed test cases, bugs for confirmed defects; exits 1 on a defect
@@ -104,6 +111,7 @@ page with ranked locators and a confidence %, plus the steps of each goal's last
 --replay verify   replay a known goal without the LLM, then one LLM step checks the result (default)
 --replay trust    replay and finish without the LLM when every step works
 --replay off      never replay; still record pages
+--browser-provider  pick which configured browser provider runs this command's browser work
 
 ForgeQE's agent (forgeqe start, forgeqe run) runs on the agent runtime with the active profile's model (or code.model) and
 calls ForgeQE's tools: browser runs, reading and running test cases, writing tests and running them, page memory, pushing
@@ -132,8 +140,9 @@ The report is report.html (step verdicts, timeline with screenshots, timings, en
 out/suites/<time>/; every run folder also has its own report.html.
 
 Static BI (bi: in forgeqe.yaml): \`forgeqe bi\` writes curated CSV datasets from ForgeQE's own suite and readiness
-reports plus optional Azure DevOps WIQL and Jira JQL datasets, scaffolds an Evidence project, and runs
-\`evidence build\` to produce static HTML in the build directory. No server stays up between runs.
+reports plus optional Azure DevOps WIQL and Jira JQL datasets, scaffolds an Evidence project (@evidence-dev/evidence
+40.x, needs Node.js), and runs \`evidence sources\` and \`evidence build\` to produce a static site in the build directory;
+when that cannot run, it writes ForgeQE's own self-contained page instead. No server stays up between runs.
 
 Healing (forgeqe heal): ForgeQE runs the tests (the command given, code.test_command, or one the agent finds).
 For each failing test, Scribe re-runs its flow in the real browser: when the flow still works, the test is out

package/src/cli/index.ts

@@ -10,7 +10,7 @@ import { goalFor, loadCases } from "../cases/index.ts"
 import { codeSkipReason, latestRunDir, runCodeAgent } from "../code/index.ts"
 import { detailFrom } from "../detail.ts"
 import { ensureOpencode, INSTALL_HINT } from "../code/runtime.ts"
-import { loadConfig, parseDuration, replayMode, selectProfile, userConfigDir, type AppConfig } from "../config.ts"
+import { browserProvider, loadConfig, parseDuration, replayMode, selectProfile, userConfigDir, type AppConfig, type BrowserProvider } from "../config.ts"
 import { runHeal } from "../heal/loop.ts"
 import { formatHeal } from "../heal/report.ts"
 import { backgroundMonitors, stopBackgroundMonitors } from "../monitor/background.ts"
@@ -62,6 +62,11 @@ const LOGGED_COMMANDS = new Set([...AGENT_COMMANDS, "mcp", "login", "setup", "bi
 /** How much of the agents' work to print: brief unless --verbose. */
 const detailOf = (flags: Flags) => detailFrom(boolFlag(flags, "verbose"))
 
+function browserProviderFlag(flags: Flags): BrowserProvider | undefined {
+  const value = strFlag(flags, "browser-provider")
+  return value ? browserProvider(value) : undefined
+}
+
 function debugRequested(flags: Flags): boolean {
   return boolFlag(flags, "debug") || /^(1|true|yes|on)$/i.test(process.env.FORGEQE_DEBUG || "")
 }
@@ -454,7 +459,17 @@ async function cmdExplore(args: string[], flags: Flags): Promise<number> {
   process.once("SIGINT", onSigint)
   try {
     const ask = process.stdin.isTTY && !boolFlag(flags, "yes") ? terminalAsk(controller.signal) : undefined
-    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", signal: controller.signal, headed: boolFlag(flags, "headed"), maxSteps: maxStepsFlag(flags), emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)), ...(ask ? { ask } : {}) }
+    const ctx: ToolContext = {
+      config: cfg,
+      cwd: process.cwd(),
+      session: "once",
+      signal: controller.signal,
+      headed: boolFlag(flags, "headed"),
+      browserProvider: browserProviderFlag(flags),
+      maxSteps: maxStepsFlag(flags),
+      emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)),
+      ...(ask ? { ask } : {}),
+    }
     const roles = (strFlag(flags, "roles") || "").split(",").map((s) => s.trim()).filter(Boolean)
     const out = (await TOOLS.find((t) => t.name === "explore_story")!.run(
       { story, url: strFlag(flags, "url"), charters: Number(strFlag(flags, "charters")) || undefined, ...(roles.length ? { roles } : {}), focus: strFlag(flags, "focus"), file_bugs: boolFlag(flags, "file-bugs") },
@@ -474,11 +489,16 @@ async function cmdBi(args: string[], flags: Flags): Promise<number> {
     dataDir: strFlag(flags, "data-dir"),
     buildDir: strFlag(flags, "build-dir") || strFlag(flags, "out"),
   }
+  const shown = (file: string) => path.relative(process.cwd(), file) || file
+  const printNotes = (notes: string[]) => {
+    for (const note of notes) console.log(`note              ${note}`)
+  }
   switch (action) {
     case "init": {
       const out = await initBiProject(cfg, overrides)
       console.log(`Evidence project  ${out.evidenceDir}`)
-      for (const file of out.files) console.log(`generated         ${path.relative(process.cwd(), file) || file}`)
+      for (const file of out.files) console.log(`generated         ${shown(file)}`)
+      printNotes(out.notes)
       return 0
     }
     case "sync": {
@@ -490,23 +510,30 @@ async function cmdBi(args: string[], flags: Flags): Promise<number> {
       console.log(`Case results      ${out.caseResults}`)
       console.log(`Readiness reports ${out.readinessReports}`)
       console.log(`External datasets ${out.externalDatasets}`)
-      console.log(`Summary           ${path.relative(process.cwd(), out.summaryFile) || out.summaryFile}`)
+      console.log(`Summary           ${shown(out.summaryFile)}`)
+      printNotes(out.notes)
       return 0
     }
     case "build": {
-      const out = await buildBi(cfg, overrides)
+      const out = await buildBi(cfg, overrides, boolFlag(flags, "static") ? "static" : boolFlag(flags, "evidence") ? "evidence" : "auto")
       console.log(`Evidence project  ${out.evidenceDir}`)
       console.log(`Static site       ${out.buildDir}`)
-      console.log(`Index             ${path.relative(process.cwd(), out.indexFile) || out.indexFile}`)
-      console.log(`Summary           ${path.relative(process.cwd(), out.summaryFile) || out.summaryFile}`)
+      console.log(`Index             ${shown(out.indexFile)}`)
+      console.log(`Summary           ${shown(out.summaryFile)}`)
       console.log(`Suite runs        ${out.suites}`)
       console.log(`Case results      ${out.caseResults}`)
       console.log(`Readiness reports ${out.readinessReports}`)
       console.log(`External datasets ${out.externalDatasets}`)
+      if (out.engine === "evidence") {
+        console.log("Built with        Evidence. Serve the folder to view it (npx serve, or evidence preview): opened from disk it cannot load its data.")
+      } else {
+        console.log(`Built with        ForgeQE's own page, without Evidence (${out.fallbackReason}). It opens straight from disk.`)
+      }
+      printNotes(out.notes)
       return 0
     }
     default:
-      throw new Error("Usage: forgeqe bi [init|sync|build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR]")
+      throw new Error("Usage: forgeqe bi [init|sync|build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR] [--static | --evidence]")
   }
 }
 
@@ -913,6 +940,7 @@ async function runAgent(cfg: AppConfig, flags: Flags, text: string, maxSteps: nu
       signal: controller.signal,
       context: () => ({
         headed: boolFlag(flags, "headed"),
+        browserProvider: browserProviderFlag(flags),
         maxSteps,
         url: strFlag(flags, "url"),
         ...memoryFlags(flags),
@@ -973,7 +1001,17 @@ async function cmdMcp(args: string[], flags: Flags): Promise<number> {
   const repo = repoFlag(flags)
   const cwd = repo || process.cwd()
   const log = toolPrinter(false, (line) => process.stderr.write(`${line}\n`), detailOf(flags))
-  const context = (): ToolContext => ({ config: cfg, cwd, headed: boolFlag(flags, "headed"), maxSteps: maxStepsFlag(flags), url: strFlag(flags, "url"), ...memoryFlags(flags), emit: log, session: "server" })
+  const context = (): ToolContext => ({
+    config: cfg,
+    cwd,
+    headed: boolFlag(flags, "headed"),
+    browserProvider: browserProviderFlag(flags),
+    maxSteps: maxStepsFlag(flags),
+    url: strFlag(flags, "url"),
+    ...memoryFlags(flags),
+    emit: log,
+    session: "server",
+  })
   const server = createMcpServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), version: packageVersion() })
   process.stderr.write(`ForgeQE MCP server on stdio (${TOOLS.length} tools, working in ${cwd})\n`)
   await serveStdio(server)
@@ -988,6 +1026,7 @@ async function runGoal(cfg: AppConfig, flags: Flags, goal: string, maxSteps: num
   const { result, files } = await executeRun({
     config: cfg,
     goal,
+    browserProvider: browserProviderFlag(flags),
     url: strFlag(flags, "url"),
     headed: boolFlag(flags, "headed"),
     maxSteps,
@@ -1129,6 +1168,7 @@ async function cmdHeal(args: string[], flags: Flags): Promise<number> {
       repo,
       command,
       outDir: strFlag(flags, "out"),
+      browserProvider: browserProviderFlag(flags),
       headed: boolFlag(flags, "headed"),
       maxSteps: maxStepsFlag(flags),
       url: strFlag(flags, "url"),
@@ -1200,6 +1240,7 @@ async function cmdMonitor(refs: string[], flags: Flags): Promise<number> {
       config: cfg,
       checks,
       once,
+      browserProvider: browserProviderFlag(flags),
       headed: boolFlag(flags, "headed"),
       url: strFlag(flags, "url"),
       skills: skillFlags(flags),
@@ -1238,6 +1279,7 @@ async function cmdSuite(refs: string[], flags: Flags): Promise<number> {
       config: cfg,
       cases,
       repo,
+      browserProvider: browserProviderFlag(flags),
       parallel,
       outDir: strFlag(flags, "out"),
       writeBack: boolFlag(flags, "no-write-back") ? false : undefined,

package/src/config.ts

@@ -18,6 +18,8 @@ import { ragConfig, type RagConfig } from "./cases/rag.ts"
 
 export type BrowserProvider = "local" | "browserstack" | "testmu"
 export type RemoteBrowserProvider = Exclude<BrowserProvider, "local">
+export type BrowserRemoteConfigs = Partial<Record<RemoteBrowserProvider, BrowserRemoteConfig>>
+export type BrowserProviderFiles = Partial<Record<RemoteBrowserProvider, string>>
 
 export type BrowserRemoteConfig = {
   provider: RemoteBrowserProvider
@@ -47,6 +49,8 @@ export type BrowserConfig = {
   allowedHosts: string[]
   startUrl?: string
   remote?: BrowserRemoteConfig
+  remotes: BrowserRemoteConfigs
+  providerFiles: BrowserProviderFiles
   /** 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. */
@@ -435,43 +439,104 @@ const REMOTE_BROWSER_DEFAULTS: Record<RemoteBrowserProvider, Pick<BrowserRemoteC
   browserstack: {
     usernameEnv: "BROWSERSTACK_USERNAME",
     accessKeyEnv: "BROWSERSTACK_ACCESS_KEY",
-    endpoint: "wss://cdp.browserstack.com/playwright",
+    endpoint: "wss://cdp.browserstack.com/puppeteer",
   },
   testmu: {
     usernameEnv: "LT_USERNAME",
     accessKeyEnv: "LT_ACCESS_KEY",
-    endpoint: "wss://cdp.lambdatest.com/playwright",
+    endpoint: "wss://cdp.lambdatest.com/puppeteer",
   },
 }
 
+const REMOTE_BROWSER_PROVIDERS = Object.keys(REMOTE_BROWSER_DEFAULTS) as RemoteBrowserProvider[]
+const REMOTE_BROWSER_KEYS = new Set([
+  "browser",
+  "browser_version",
+  "browserVersion",
+  "os",
+  "os_version",
+  "osVersion",
+  "platform",
+  "username_env",
+  "usernameEnv",
+  "access_key_env",
+  "accessKeyEnv",
+  "endpoint",
+  "project",
+  "build",
+  "name",
+  "local",
+  "local_testing",
+  "extra",
+  "capabilities",
+])
+
 function objectMap(raw: unknown, where: string): Record<string, unknown> | undefined {
   if (raw === undefined || raw === null) return undefined
   if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must be a map of names to values.`)
   return { ...(raw as Record<string, unknown>) }
 }
 
-function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProvider): BrowserRemoteConfig | undefined {
+function browserProviderFiles(raw: Record<string, unknown>, base: string): BrowserProviderFiles {
+  const files = objectMap(raw.providers, "browser.providers")
+  const out: BrowserProviderFiles = {}
+  for (const provider of REMOTE_BROWSER_PROVIDERS) {
+    const file = files?.[provider]
+    if (file === undefined || file === null || file === false || String(file).trim() === "") continue
+    out[provider] = path.resolve(base, String(file))
+  }
+  return out
+}
+
+function browserProviderFileSection(file: string, provider: RemoteBrowserProvider): Record<string, unknown> {
+  if (!existsSync(file)) throw new Error(`browser.providers.${provider} not found: ${file}`)
+  const doc = readYaml(file)
+  const section = Object.keys(asRecord(doc.browser)).length ? { ...asRecord(doc.browser) } : { ...doc }
+  if (!section.provider && doc.provider !== undefined) section.provider = doc.provider
+  if (!Object.keys(asRecord(section.remote)).length) {
+    const rootRemote = asRecord(doc.remote)
+    if (Object.keys(rootRemote).length) section.remote = rootRemote
+    else {
+      const directRemote = Object.fromEntries(Object.entries(section).filter(([k]) => REMOTE_BROWSER_KEYS.has(k)))
+      if (Object.keys(directRemote).length) section.remote = directRemote
+    }
+  }
+  if (section.provider !== undefined && browserProvider(section.provider) !== provider) {
+    throw new Error(`browser.providers.${provider} points to ${file}, but that file declares provider ${String(section.provider)}.`)
+  }
+  return section
+}
+
+function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProvider, where = "browser"): BrowserRemoteConfig | undefined {
   if (provider === "local") return undefined
   const remote = asRecord(raw.remote)
   const defaults = REMOTE_BROWSER_DEFAULTS[provider]
   const browser = String(remote.browser || "").trim()
-  if (!browser) throw new Error(`browser.remote.browser is required when browser.provider is ${provider}.`)
+  if (!browser) throw new Error(`${where}.remote.browser is required when browser.provider is ${provider}.`)
+  // The engine drives the browser over the Chrome DevTools Protocol, so the grid must hand back a Chromium browser.
+  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.`)
+  }
   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 platform = String(remote.platform || "").trim() || undefined
   if (provider === "browserstack" && (!os || !osVersion)) {
-    throw new Error("browser.remote.os and browser.remote.os_version are required when browser.provider is browserstack.")
+    throw new Error(`${where}.remote.os and ${where}.remote.os_version are required when browser.provider is browserstack.`)
   }
   if (provider === "testmu" && !platform && !os) {
-    throw new Error("browser.remote.platform is required when browser.provider is testmu, or set browser.remote.os (and optionally os_version).")
+    throw new Error(`${where}.remote.platform is required when browser.provider is testmu, or set ${where}.remote.os (and optionally os_version).`)
+  }
+  const endpoint = String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, "")
+  if (/\/playwright$/i.test(endpoint)) {
+    throw new Error(`${where}.remote.endpoint ${endpoint} speaks Playwright's own protocol; ForgeQE needs the CDP endpoint (${defaults.endpoint}).`)
   }
-  const extra = objectMap(remote.extra ?? remote.capabilities, "browser.remote.extra")
+  const extra = objectMap(remote.extra ?? remote.capabilities, `${where}.remote.extra`)
   return {
     provider,
     usernameEnv: String(remote.username_env || remote.usernameEnv || defaults.usernameEnv),
     accessKeyEnv: String(remote.access_key_env || remote.accessKeyEnv || defaults.accessKeyEnv),
-    endpoint: String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, ""),
+    endpoint,
     browser,
     browserVersion,
     ...(os ? { os } : {}),
@@ -485,6 +550,35 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   }
 }
 
+function browserRemoteConfigs(browser: Record<string, unknown>, provider: BrowserProvider, base: string): { remotes: BrowserRemoteConfigs; providerFiles: BrowserProviderFiles } {
+  const providerFiles = browserProviderFiles(browser, base)
+  const remotes: BrowserRemoteConfigs = {}
+  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,
+    )
+  }
+  return { remotes, providerFiles }
+}
+
+export function browserConfigFor(config: Pick<AppConfig, "browser">, provider = config.browser.provider): Pick<BrowserConfig, "provider" | "remote"> {
+  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)
+  if (remote) return { provider: chosen, remote }
+  throw new Error(`Browser provider ${chosen} is not configured. Add browser.providers.${chosen} to forgeqe.yaml, or set browser.provider: ${chosen} with browser.remote.`)
+}
+
 function profileFromRaw(name: string, raw: Record<string, unknown>): LlmProfile {
   const provider = String(raw.provider || "openai") as LlmProfile["provider"]
   return {
@@ -656,6 +750,8 @@ 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 config: AppConfig = {
     configPath,
     mcp: extraMcpServers(yaml.mcp, base),
@@ -663,7 +759,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
     profiles,
     llm: profiles[activeProfile] || { ...NO_PROFILE },
     browser: {
-      provider: browserProvider(browser.provider),
+      provider,
       headless: browser.headless !== false,
       width: Number(viewport.width || 1280),
       height: Number(viewport.height || 800),
@@ -672,7 +768,9 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       visionDetail: visionDetail(browser.vision_detail),
       allowedHosts: hosts,
       startUrl: browser.start_url ? String(browser.start_url) : undefined,
-      remote: browserRemoteConfig(browser, browserProvider(browser.provider)),
+      remote: provider === "local" ? undefined : remotes[provider],
+      remotes,
+      providerFiles,
       overlay: browser.overlay !== false,
       judge: browser.judge === true,
     },
@@ -953,9 +1051,12 @@ function apiConfig(a: Record<string, unknown>): ApiConfig {
   }
 }
 
+/** The tables forgeqe bi always exports; a dataset id may not reuse one. */
+export const BI_BUILTIN_TABLES = ["suites", "case_results", "step_results", "writebacks", "readiness", "readiness_stories", "readiness_cases", "external_datasets"]
+
 function biConfig(b: Record<string, unknown>, base: string, outDir: string, configPath: string | undefined): BiConfig {
   const evidenceDir = path.resolve(base, String(b.evidence_dir || path.join(".", "evidence")))
-  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe", "data")
+  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe")
   const title = String(b.title || "ForgeQE BI").trim() || "ForgeQE BI"
   const datasets = Object.entries(asRecord(b.datasets)).map(([id, value]) => biDataset(id, asRecord(value)))
   return {
@@ -968,7 +1069,9 @@ function biConfig(b: Record<string, unknown>, base: string, outDir: string, conf
 }
 
 function biDataset(id: string, raw: Record<string, unknown>): BiDatasetConfig {
-  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits, - and _.`)
+  // The id is the dataset's table name in Evidence's SQL (forgeqe.<id>), so it must be a plain identifier.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits and _, and must not start with a digit.`)
+  if (BI_BUILTIN_TABLES.includes(id)) throw new Error(`bi.datasets.${id}: ${id} is one of ForgeQE's own BI tables; choose another id.`)
   const title = String(raw.title || id.replace(/[-_]+/g, " ").trim()).trim()
   const kind = String(raw.kind || "").trim().toLowerCase()
   if (kind === "ado_wiql") {

package/src/heal/loop.ts

@@ -7,7 +7,7 @@ import { addUsage, costOf, meterSince, meterSnapshot, type Cost } from "../usage
 import { openSession, type OpencodeSession } from "../code/runtime.ts"
 import { runTestCommand, type TestRun } from "../code/testrun.ts"
 import { changedFiles, ownPaths, protectPatterns, restoreRemoved, snapshot } from "../code/worktree.ts"
-import type { AppConfig } from "../config.ts"
+import type { AppConfig, BrowserProvider } from "../config.ts"
 import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
 import { TOOLS, environmentNotes, type ToolContext, type ToolEvent } from "../mcp/tools.ts"
 import { runDirectory } from "../run.ts"
@@ -79,6 +79,7 @@ export type HealOptions = {
   /** The repo's test command; default code.test_command, else the agent finds it. */
   command?: string
   outDir?: string
+  browserProvider?: BrowserProvider
   headed?: boolean
   maxSteps?: number
   url?: string
@@ -149,6 +150,7 @@ export async function runHeal(opts: HealOptions): Promise<HealResult> {
     config: runsConfig,
     cwd: repo,
     headed: opts.headed,
+    browserProvider: opts.browserProvider,
     maxSteps: opts.maxSteps,
     url: opts.url,
     signal: opts.signal,

package/src/init.ts

@@ -64,6 +64,24 @@ export function initWorkspace(
   // Prompts, skills, and product knowledge templates, to read and change: .forgeqe/ in a project, ~/.forgeqe for the user.
   const root = home ? forgeqeHome() : projectDir(directory)
   const shown = (p: string) => (home ? p : path.relative(directory, p) || p)
+  for (const [srcName, destName] of [
+    ["browserstack.example.yaml", "browserstack.yaml"],
+    ["testmu.example.yaml", "testmu.yaml"],
+  ] as const) {
+    const src = path.join(ROOT, srcName)
+    const dest = path.join(root, destName)
+    if (!existsSync(src)) {
+      notes.push(`Template missing: ${src}`)
+      continue
+    }
+    if (existsSync(dest) && !opts.force) {
+      notes.push(`Kept existing ${shown(dest)}`)
+      continue
+    }
+    mkdirSync(path.dirname(dest), { recursive: true })
+    writeFileSync(dest, readFileSync(src, "utf8"), "utf8")
+    created.push(dest)
+  }
   for (const { what, src, dest, keys } of [
     { what: "prompts", src: PROMPTS_DIR, dest: path.join(root, "prompts"), keys: entries(PROMPTS_DIR, (e) => e.endsWith(".md")) },
     { what: "skills", src: PREBUILT_DIR, dest: path.join(root, "skills"), keys: entries(PREBUILT_DIR, (e) => existsSync(path.join(PREBUILT_DIR, e, "SKILL.md"))) },

package/src/mcp/tools.ts

@@ -15,7 +15,7 @@ import { buildHandoff } from "../code/handoff.ts"
 import { latestRunDir, runCodeAgent } from "../code/index.ts"
 import type { OpencodeSession } from "../code/runtime.ts"
 import { runTestCommand } from "../code/testrun.ts"
-import type { AppConfig } from "../config.ts"
+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"
@@ -123,6 +123,7 @@ export type ToolContext = {
   /** The repository or folder the agent works in. */
   cwd: string
   headed?: boolean
+  browserProvider?: AppConfig["browser"]["provider"]
   maxSteps?: number
   replay?: ReplayMode
   memory?: boolean
@@ -256,7 +257,7 @@ export const TOOLS: McpTool[] = [
   {
     name: "browser_run",
     description:
-      "Carry out a goal in a real browser with ForgeQE's browser agent and verify the outcome. The agent picks the site from the goal unless start_url is given. Returns pass/fail, the agent's summary, the steps, and the run folder (run.json, workflow.yaml with ranked locators, trace.md, steps and screenshots, report.html). Takes minutes.",
+      "Carry out a goal in a real browser with ForgeQE's browser agent and verify the outcome. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when browser.provider selects one. The agent picks the site from the goal unless start_url is given. Returns pass/fail, the agent's summary, the steps, and the run folder (run.json, workflow.yaml with ranked locators, trace.md, steps and screenshots, report.html). Takes minutes.",
     inputSchema: {
       type: "object",
       properties: {
@@ -266,6 +267,12 @@ export const TOOLS: McpTool[] = [
             "The final instructions for the browser agent: what to do and what to check, in plain language, with every value it needs. Only the decided task; never your own questions, alternatives, or reasoning about it.",
         },
         start_url: { type: "string", description: "Page to open first, only when the user named one" },
+        browser_provider: {
+          type: "string",
+          enum: ["local", "browserstack", "testmu"],
+          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.",
+        },
         resume_from: {
           type: "string",
           description:
@@ -287,6 +294,7 @@ export const TOOLS: McpTool[] = [
       const from = args.resume_from ? String(args.resume_from) : ""
       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
       const runDir = runDirectory(ctx.config.export.outDir)
       const emit = ctx.emit || (() => {})
       const t0 = Date.now()
@@ -295,6 +303,7 @@ export const TOOLS: McpTool[] = [
         const { result, files } = await (ctx.execute || executeRun)({
           config: ctx.config,
           goal,
+          browserProvider: selectedBrowser,
           url,
           headed: ctx.headed,
           maxSteps: ctx.maxSteps,
@@ -410,13 +419,19 @@ export const TOOLS: McpTool[] = [
   {
     name: "run_test_cases",
     description:
-      "Run test cases in real browsers: each case is one browser goal whose steps are done in order and whose expected results are checked, with a verdict for every step. Writes report.html (steps, screenshots, timings) and junit.xml, posts results back to Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, or qTest unless write_back is false, and files or updates bugs for failures when bugs are set up. In a session that writes tests, each passed case is handed to ForgeQE's coding agent as soon as its browser run ends, and its test is written and run before the next case starts. Returns each case's result, step verdicts, run folder, and test (file, command, status, or why none was written). Takes minutes.",
+      "Run test cases in real browsers: each case is one browser goal whose steps are done in order and whose expected results are checked, with a verdict for every step. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when browser.provider selects one. Writes report.html (steps, screenshots, timings) and junit.xml, posts results back to Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, or qTest unless write_back is false, and files or updates bugs for failures when bugs are set up. In a session that writes tests, each passed case is handed to ForgeQE's coding agent as soon as its browser run ends, and its test is written and run before the next case starts. Returns each case's result, step verdicts, run folder, and test (file, command, status, or why none was written). Takes minutes.",
     inputSchema: {
       type: "object",
       properties: {
         sources: SOURCES_SCHEMA,
         parallel: { type: "integer", minimum: 1, maximum: 8, description: "Browsers at once (default from config)" },
         write_back: { type: "boolean", description: "Post results to the source system (default from config)" },
+        browser_provider: {
+          type: "string",
+          enum: ["local", "browserstack", "testmu"],
+          description:
+            "Override the browser provider for every case in this suite when the user asked for one specifically.",
+        },
         skills: SKILLS_SCHEMA,
       },
       required: ["sources"],
@@ -429,6 +444,7 @@ export const TOOLS: McpTool[] = [
       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 emit = ctx.emit || (() => {})
       emit({ type: "suite-start", cases, parallel })
       // In a session that writes tests, each passed case goes to the coding agent right after its own browser run,
@@ -455,6 +471,7 @@ export const TOOLS: McpTool[] = [
         config: ctx.writeTests ? { ...ctx.config, suite: { ...ctx.config.suite, code: true } } : ctx.config,
         cases,
         ...(ctx.writeTests ? { repo: ctx.cwd, coder } : {}),
+        browserProvider: selectedBrowser,
         parallel,
         writeBack: typeof args.write_back === "boolean" ? args.write_back : undefined,
         headed: ctx.headed,
@@ -765,7 +782,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">): string {
+export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url" | "browserProvider">): string {
   const { config: cfg } = ctx
   const s = cfg.sources
   const systems = [
@@ -802,13 +819,17 @@ export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url"
   const monitor = m.checks.length || channels.length
     ? `Monitoring (monitor: in forgeqe.yaml): ${m.checks.length ? `checks ${m.checks.join(" ")}` : "no checks yet"}, every ${Math.round(m.everyMs / 60_000)} min, alerts to ${channels.length ? channels.join(" and ") : "nobody yet"}.`
     : ""
+  const browser = cfg.browser || {}
   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 skills = browserSkills.length
     ? [`Browser skills (pass the ones a goal needs as skills to browser_run or run_test_cases):`, ...catalogLines(browserSkills)].join("\n")
     : ""
   return [
     `Working directory: ${ctx.cwd}`,
     `Browser runs are saved under ${cfg.export.outDir}; page memory is in ${cfg.memory.dir}.`,
+    `Browser provider default: ${browserProvider}.${remoteProviders.length ? ` Also configured: ${remoteProviders.join(", ")}. Pass browser_provider to browser_run or run_test_cases when the user asks for one of them.` : ""}`,
     `Test case systems configured: ${systems.length ? systems.join("; ") : "none (files and text still work)"}.`,
     s.confluence ? `Confluence: ${s.confluence.url}${s.confluence.space ? `, space ${s.confluence.space}` : ""} (read_confluence).` : "",
     `Sprints (list_sprints, find_tests sprint): ${[s.ado ? "Azure DevOps iterations" : "", s.jira ? "Jira scrum boards" : ""].filter(Boolean).join(" and ") || "none configured; ask the user for dates"}.`,
@@ -831,6 +852,7 @@ export function environmentNotes(ctx: Pick<ToolContext, "config" | "cwd" | "url"
     `Browser model profile: ${cfg.activeProfile} (${cfg.llm.provider}/${cfg.llm.deployment || cfg.llm.model}).`,
     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}.` : "",
     skills,
     domainNotes(cfg),
     knowledgeNotes(cfg),