@capagents/forgeqe 1.1.1 → 1.1.3

package/src/config.ts

@@ -16,7 +16,30 @@ import { currencyCode, currencyForLocale } from "./money.ts"
 import { listPrice, pricesDate, type DeploymentType, type ListPrice } from "./prices.ts"
 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
+  usernameEnv: string
+  accessKeyEnv: string
+  endpoint: string
+  browser: string
+  browserVersion: string
+  os?: string
+  osVersion?: string
+  platform?: string
+  project?: string
+  build?: string
+  name?: string
+  local: boolean
+  extra?: Record<string, unknown>
+}
+
 export type BrowserConfig = {
+  provider: BrowserProvider
   headless: boolean
   width: number
   height: number
@@ -25,6 +48,9 @@ export type BrowserConfig = {
   visionDetail: "low" | "high"
   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. */
@@ -37,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)
@@ -176,6 +216,34 @@ export type ApiConfig = {
   timeoutSeconds: number
 }
 
+export type BiDatasetConfig =
+  | {
+      id: string
+      title: string
+      kind: "ado_wiql"
+      wiql: string
+      project?: string
+    }
+  | {
+      id: string
+      title: string
+      kind: "jira_jql"
+      jql: string
+    }
+
+export type BiConfig = {
+  /** Title of the generated Evidence project and its landing page. */
+  title: string
+  /** Evidence project root, generated and managed by ForgeQE. */
+  evidenceDir: string
+  /** Exported CSV datasets the Evidence project reads. */
+  dataDir: string
+  /** Static HTML output from `forgeqe bi build`. */
+  buildDir: string
+  /** Declarative external datasets to fetch on each sync/build. */
+  datasets: BiDatasetConfig[]
+}
+
 export type SuiteConfig = {
   /** Browser runs at the same time. Coding runs one at a time. */
   parallel: number
@@ -280,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
@@ -312,6 +382,8 @@ export type AppConfig = {
   release?: ReleaseThresholds
   /** API and contract tests (api: in forgeqe.yaml): see src/api/. */
   api?: ApiConfig
+  /** Offline BI export and the Evidence project that renders it (bi: in forgeqe.yaml). */
+  bi?: BiConfig
   /** Accessibility standard and accessibility/performance budgets (quality: in forgeqe.yaml): see src/quality/. */
   quality?: QualityConfig
   /** The product's industry and the regulations in scope (domain: in forgeqe.yaml): see src/domain.ts. */
@@ -338,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
@@ -371,6 +459,150 @@ function visionDetail(raw: unknown): BrowserConfig["visionDetail"] {
   return String(raw || "low").toLowerCase() === "high" ? "high" : "low"
 }
 
+export function browserProvider(raw: unknown): BrowserProvider {
+  const provider = String(raw || "local").trim().toLowerCase().replace(/[\s-]/g, "_")
+  if (!provider || provider === "local") return "local"
+  if (provider === "browserstack") return "browserstack"
+  if (provider === "testmu" || provider === "lambdatest" || provider === "lambda_test") return "testmu"
+  throw new Error(`browser.provider must be local, browserstack, or testmu; got "${String(raw)}".`)
+}
+
+const REMOTE_BROWSER_DEFAULTS: Record<RemoteBrowserProvider, Pick<BrowserRemoteConfig, "usernameEnv" | "accessKeyEnv" | "endpoint">> = {
+  browserstack: {
+    usernameEnv: "BROWSERSTACK_USERNAME",
+    accessKeyEnv: "BROWSERSTACK_ACCESS_KEY",
+    endpoint: "wss://cdp.browserstack.com/playwright",
+  },
+  testmu: {
+    usernameEnv: "LT_USERNAME",
+    accessKeyEnv: "LT_ACCESS_KEY",
+    endpoint: "wss://cdp.lambdatest.com/playwright",
+  },
+}
+
+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 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(`${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(`${where}.remote.os and ${where}.remote.os_version are required when browser.provider is browserstack.`)
+  }
+  if (provider === "testmu" && !platform && !os) {
+    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, `${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(/\/+$/, ""),
+    browser,
+    browserVersion,
+    ...(os ? { os } : {}),
+    ...(osVersion ? { osVersion } : {}),
+    ...(platform ? { platform } : {}),
+    ...(remote.project ? { project: String(remote.project).trim() } : {}),
+    ...(remote.build ? { build: String(remote.build).trim() } : {}),
+    ...(remote.name ? { name: String(remote.name).trim() } : {}),
+    local: remote.local === true || remote.local_testing === true,
+    ...(extra && Object.keys(extra).length ? { extra } : {}),
+  }
+}
+
+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 {
@@ -542,13 +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,
       headless: browser.headless !== false,
       width: Number(viewport.width || 1280),
       height: Number(viewport.height || 800),
@@ -557,6 +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: provider === "local" ? undefined : remotes[provider],
+      remotes,
+      providerFiles,
       overlay: browser.overlay !== false,
       judge: browser.judge === true,
     },
@@ -600,6 +839,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
     flaky: flakyConfig(asRecord(yaml.flaky)),
     release: releaseThresholds(yaml.release),
     api: apiConfig(asRecord(yaml.api)),
+    bi: biConfig(asRecord(yaml.bi), base, outDir, configPath),
     quality: withBaselineDir(qualityConfig(yaml.quality), base, configPath),
     domain: domainConfig(yaml.domain),
     notify: notifyConfig(yaml.notify),
@@ -836,6 +1076,38 @@ function apiConfig(a: Record<string, unknown>): ApiConfig {
   }
 }
 
+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 title = String(b.title || "ForgeQE BI").trim() || "ForgeQE BI"
+  const datasets = Object.entries(asRecord(b.datasets)).map(([id, value]) => biDataset(id, asRecord(value)))
+  return {
+    title,
+    evidenceDir,
+    dataDir: path.resolve(base, String(b.data_dir || defaultDataDir)),
+    buildDir: path.resolve(base, String(b.build_dir || path.join(outDir, "bi"))),
+    datasets,
+  }
+}
+
+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 _.`)
+  const title = String(raw.title || id.replace(/[-_]+/g, " ").trim()).trim()
+  const kind = String(raw.kind || "").trim().toLowerCase()
+  if (kind === "ado_wiql") {
+    const wiql = String(raw.wiql || "").trim()
+    if (!wiql) throw new Error(`bi.datasets.${id}.wiql is required for kind ado_wiql.`)
+    const project = String(raw.project || "").trim()
+    return { id, title: title || id, kind, wiql, ...(project ? { project } : {}) }
+  }
+  if (kind === "jira_jql") {
+    const jql = String(raw.jql || "").trim()
+    if (!jql) throw new Error(`bi.datasets.${id}.jql is required for kind jira_jql.`)
+    return { id, title: title || id, kind, jql }
+  }
+  throw new Error(`bi.datasets.${id}.kind must be ado_wiql or jira_jql; got "${String(raw.kind || "")}".`)
+}
+
 function optional<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
   return value === undefined ? {} : ({ [key]: value } as Record<K, V>)
 }

package/src/engine/bridge.ts

@@ -3,9 +3,9 @@ import { createInterface } from "node:readline"
 
 import type { LlmProfile } from "../llm.ts"
 import type { AgentEvent, CaseReport, MemoryInfo, ReplayMode, RunResult } from "../types.ts"
-import { loginEnvNames } from "../childEnv.ts"
+import { browserProviderEnvNames, loginEnvNames } from "../childEnv.ts"
 import { recordUsage } from "../usage.ts"
-import type { LoginConfig } from "../config.ts"
+import type { BrowserProvider, BrowserRemoteConfig, LoginConfig } from "../config.ts"
 import { debugLogging, logEvent } from "../sessionLog.ts"
 import { engineEnv } from "./setup.ts"
 import { AZURE_IDENTITY_ENV, entraPayload } from "../entra.ts"
@@ -18,6 +18,7 @@ export type EngineRequest = {
   headed: boolean
   maxSteps: number
   allowedHosts: string[]
+  browser?: { provider: BrowserProvider; remote?: BrowserRemoteConfig }
   extendSystemMessage?: string
   /** Page memory folder and replay mode; omit to run without memory. */
   memory?: { dir: string; replay: ReplayMode }
@@ -148,6 +149,33 @@ function llmPayload(p: LlmProfile): Record<string, unknown> {
   return out
 }
 
+function browserPayload(browser: EngineRequest["browser"]): Record<string, unknown> | null {
+  if (!browser) return null
+  return {
+    provider: browser.provider,
+    ...(browser.remote
+      ? {
+          remote: {
+            provider: browser.remote.provider,
+            username_env: browser.remote.usernameEnv,
+            access_key_env: browser.remote.accessKeyEnv,
+            endpoint: browser.remote.endpoint,
+            browser: browser.remote.browser,
+            browser_version: browser.remote.browserVersion,
+            ...(browser.remote.os ? { os: browser.remote.os } : {}),
+            ...(browser.remote.osVersion ? { os_version: browser.remote.osVersion } : {}),
+            ...(browser.remote.platform ? { platform: browser.remote.platform } : {}),
+            ...(browser.remote.project ? { project: browser.remote.project } : {}),
+            ...(browser.remote.build ? { build: browser.remote.build } : {}),
+            ...(browser.remote.name ? { name: browser.remote.name } : {}),
+            local: browser.remote.local,
+            ...(browser.remote.extra ? { extra: browser.remote.extra } : {}),
+          },
+        }
+      : {}),
+  }
+}
+
 export function toRunResult(goal: string, startUrl: string, r: EngineResult): RunResult {
   // The agent's evidence wins over its verdict: a check that does not hold, or a failed case step, fails the run even
   // when the agent called done with success (engines before this rule did not apply it themselves).
@@ -198,6 +226,7 @@ export async function runEngine(opts: {
   const child = spawn(bin!, args, {
     env: engineEnv(debugLogging() ? { ...req.env, BROWSER_USE_LOGGING_LEVEL: "debug" } : req.env, [
       ...(req.llm.auth === "entra" ? AZURE_IDENTITY_ENV : req.llm.apiKeyEnv ? [req.llm.apiKeyEnv] : []),
+      ...browserProviderEnvNames(req.browser || { provider: "local" }),
       ...loginEnvNames(req.logins || []),
     ]),
     stdio: ["pipe", "pipe", "pipe"],
@@ -222,6 +251,7 @@ export async function runEngine(opts: {
     headed: req.headed,
     max_steps: req.maxSteps,
     allowed_hosts: req.allowedHosts,
+    browser: browserPayload(req.browser),
     extend_system_message: req.extendSystemMessage || null,
     memory: req.memory || null,
     logins: loginPayload(req.logins),