@capagents/forgeqe 1.1.2 → 1.1.3

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,21 +17,25 @@ 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]
@@ -52,6 +56,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 +109,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

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 || "")
 }
@@ -212,7 +217,7 @@ export async function main(argv: string[]): Promise<number> {
         const cfg = loadConfig(configOpts(flags))
         const trends = positionals[1] === "trends"
         const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
-        const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
         const out = (await TOOLS.find((t) => t.name === (trends ? "quality_trends" : "quality_report"))!.run(trends ? { page: positionals[2] } : { run_dir: positionals[1] }, ctx)) as { budget_exceeded?: unknown[]; pages?: { slower: unknown[]; newly_failing_rules: unknown[] }[] }
         return out.budget_exceeded?.length || out.pages?.some((p) => p.slower.length || p.newly_failing_rules.length) ? 1 : 0
       }
@@ -377,7 +382,7 @@ async function cmdApi(args: string[], flags: Flags): Promise<number> {
   const cfg = loadConfig(configOpts(flags))
   const action = args[0] || "list"
   const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
-  const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
   const tool = (name: string) => TOOLS.find((t) => t.name === name)!
   const csv = (name: string) => (strFlag(flags, name) || "").split(",").map((s) => s.trim()).filter(Boolean)
   switch (action) {
@@ -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") },
@@ -913,6 +928,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 +989,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 +1014,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 +1156,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 +1228,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 +1267,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. */
@@ -59,6 +63,20 @@ export type MemoryConfig = {
   replay: ReplayMode
 }
 
+export type CacheConfig = {
+  enabled: boolean
+  /** Redis connection string, e.g. redis://127.0.0.1:6379. */
+  redisUrl: string
+  /** Prefix for every Redis key this ForgeQE workspace writes. */
+  keyPrefix: string
+  /** Default TTL for cached JSON payloads, in seconds. */
+  defaultTtlSeconds: number
+  /** TTL for BI external dataset exports, in seconds. */
+  biTtlSeconds: number
+  /** Socket connect timeout for Redis, in milliseconds. */
+  connectTimeoutMs: number
+}
+
 function runtimeBin(value: unknown, base: string): string | undefined {
   if (!value) return undefined
   const s = String(value)
@@ -330,6 +348,8 @@ export type AppConfig = {
   configPath?: string
   /** `mcp:` in forgeqe.yaml: more MCP servers for ForgeQE's agent, by name. */
   mcp?: Record<string, ExtraMcpServer>
+  /** Optional Redis-backed cache for deterministic external data fetches. */
+  cache?: CacheConfig
   activeProfile: string
   profiles: Record<string, LlmProfile>
   llm: LlmProfile
@@ -390,6 +410,22 @@ function domainConfig(raw: unknown): DomainConfig | undefined {
   return { industry, regulations, ...(d.notes ? { notes: String(d.notes).trim() } : {}) }
 }
 
+function cacheConfig(raw: unknown): CacheConfig | undefined {
+  const c = asRecord(raw)
+  const asked = raw !== undefined || Boolean(process.env.FORGEQE_REDIS_URL)
+  if (!asked || c.enabled === false) return undefined
+  const redisUrl = String(c.redis_url || c.url || process.env.FORGEQE_REDIS_URL || "").trim()
+  if (!redisUrl) throw new Error('cache.redis_url is required when cache is enabled. Example: cache: { redis_url: "redis://127.0.0.1:6379" }')
+  return {
+    enabled: true,
+    redisUrl,
+    keyPrefix: String(c.key_prefix || "forgeqe").trim() || "forgeqe",
+    defaultTtlSeconds: positiveInt(c.default_ttl_seconds, 3600, "cache.default_ttl_seconds"),
+    biTtlSeconds: positiveInt(c.bi_ttl_seconds, 900, "cache.bi_ttl_seconds"),
+    connectTimeoutMs: positiveInt(c.connect_timeout_ms, 3000, "cache.connect_timeout_ms"),
+  }
+}
+
 export function replayMode(raw: unknown): ReplayMode {
   const mode = String(raw || "verify").toLowerCase()
   if (mode === "trust" || mode === "off") return mode
@@ -444,29 +480,82 @@ const REMOTE_BROWSER_DEFAULTS: Record<RemoteBrowserProvider, Pick<BrowserRemoteC
   },
 }
 
+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}.`)
   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 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),
@@ -485,6 +574,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,14 +774,17 @@ 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),
+    cache: cacheConfig(yaml.cache),
     activeProfile,
     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 +793,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,
     },

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),

package/src/monitor/run.ts

@@ -3,7 +3,7 @@ import path from "node:path"
 
 import type { Card } from "../card.ts"
 import { loadCases, type TestCase } from "../cases/index.ts"
-import type { AppConfig } from "../config.ts"
+import type { AppConfig, BrowserProvider } from "../config.ts"
 import { counts, suiteUsage } from "../suite/report.ts"
 import { runSuite, type SuiteEvent, type SuiteOptions, type SuiteResult } from "../suite/run.ts"
 import { formatDuration, formatTokens } from "../tui/theme.ts"
@@ -28,6 +28,7 @@ export type MonitorOptions = {
   config: AppConfig
   /** Test case sources; default monitor.checks. */
   checks: string[]
+  browserProvider?: BrowserProvider
   headed?: boolean
   url?: string
   /** Browser skills for every check (empty: none); unset: the engine picks once per check for the monitor's lifetime. */
@@ -67,6 +68,7 @@ export async function monitorRound(opts: MonitorOptions): Promise<RoundResult> {
     suite = await runSuite({
       config: { ...config, suite: { ...config.suite, outDir: m.outDir, code: false } },
       cases,
+      browserProvider: opts.browserProvider,
       parallel: Math.min(m.parallel, cases.length),
       writeBack: m.writeBack,
       replay: m.replay,

package/src/run.ts

@@ -5,7 +5,7 @@ import path from "node:path"
 import { assertGoalUrlsAllowed, hostAllowed, normalizeHttpUrl } from "./guard.ts"
 import { missingKey } from "./llm.ts"
 import type { AgentEvent, ReplayMode, RunResult } from "./types.ts"
-import type { AppConfig } from "./config.ts"
+import { browserConfigFor, type AppConfig, type BrowserProvider } from "./config.ts"
 import { runEngine } from "./engine/bridge.ts"
 import { MOCK_ENGINE } from "./engine/mock.ts"
 import { ensureEngine } from "./engine/setup.ts"
@@ -23,6 +23,7 @@ import { knowledgeBlock, readKnowledge, relevantKnowledge } from "./knowledge.ts
 export type ExecuteOptions = {
   config: AppConfig
   goal: string
+  browserProvider?: BrowserProvider
   url?: string
   headed?: boolean
   maxSteps?: number
@@ -148,6 +149,7 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
 
   const dir = opts.outDir || runDirectory(opts.config.export.outDir)
   const maxSteps = opts.maxSteps || opts.config.browser.maxSteps
+  const browser = browserConfigFor(opts.config, opts.browserProvider)
   const t0 = Date.now()
   const withReport = (out: { result: RunResult; files: string[] }) => {
     out.result.cost = costOf(out.result.usage, opts.config.llm.price)
@@ -216,7 +218,7 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
       headed: Boolean(opts.headed) || !opts.config.browser.headless,
       maxSteps,
       allowedHosts: allowed,
-      browser: { provider: opts.config.browser.provider, remote: opts.config.browser.remote },
+      browser,
       extendSystemMessage: extend || undefined,
       memory,
       env,