@capagents/forgeqe 1.1.2 → 1.1.3

package/forgeqe.example.yaml

@@ -4,6 +4,10 @@ llm:
 
 browser:
   # provider: local          # local | browserstack | testmu
+  # providers:               # keep BrowserStack / TestMu AI details in separate YAML files
+  #   browserstack: ./.forgeqe/browserstack.yaml
+  #   testmu: ./.forgeqe/testmu.yaml
+  #                         # ForgeQE's agent can switch to one of these per request with browser_provider
   headless: true
   max_steps: 40 # a checkpoint: a run still making progress carries on, up to 3x
   timeout_seconds: 600 # whole run
@@ -15,7 +19,7 @@ browser:
   judge: false # true: a second model call checks each finished run against the goal and can fail it
   overlay: true # visible browser: ForgeQE start page, edge glow, a bar with the current step, your mouse and keyboard locked while the agent works
   # start_url: https://staging.example.com   # optional; omit to let the agent choose the site
-  # remote:                    # only when provider is browserstack or testmu
+  # remote:                    # inline settings for the selected remote provider; override the provider file when both are set
   #   browser: playwright-chromium   # BrowserStack: playwright-chromium / playwright-firefox / playwright-webkit
   #   browser_version: latest
   #   os: osx
@@ -71,6 +75,14 @@ memory:
   dir: ./.forgeqe/memory # pages, elements, locators, and recorded flows
   replay: verify # verify | trust | off
 
+# Redis cache for deterministic external data fetches, such as BI datasets. Live browser runs still execute.
+# cache:
+#   redis_url: redis://127.0.0.1:6379
+#   key_prefix: forgeqe
+#   default_ttl_seconds: 3600
+#   bi_ttl_seconds: 900
+#   connect_timeout_ms: 3000
+
 code:
   # repo: ../my-app          # where passed runs become tests (default: the current folder; --no-code turns it off)
   # test_command: npx playwright test   # the repo's test command, for forgeqe heal; default: the agent finds it

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.1.2",
-  "description": "ForgeQE: a browser agent CLI that runs goals and test cases in Chrome and turns passing runs into tests in your repo",
+  "version": "1.1.3",
+  "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -20,7 +20,9 @@
     "README.md",
     "HOW_TO_USE.md",
     "forgeqe-architecture.html",
+    "browserstack.example.yaml",
     "forgeqe.example.yaml",
+    "testmu.example.yaml",
     "llms.example.json"
   ],
   "engines": {
@@ -53,6 +55,7 @@
     "pixelmatch": "8.0.0",
     "pngjs": "7.0.0",
     "react": "^19.3.0",
+    "redis": "^4.7.1",
     "yaml": "^2.9.1"
   },
   "devDependencies": {

package/py/forgeqe_engine/service.py

@@ -46,6 +46,7 @@ from .llm import (
 from .browser import (
     browser_connection_label,
     browser_launch_kwargs,
+    local_browser_launch_kwargs,
     settle_page,
     _shutdown_browser_instance,
     _stop_agent_instance,

package/src/auth/signin.ts

@@ -58,8 +58,8 @@ export function envNames(cfg?: AppConfig) {
     zephyr: { url: "ZEPHYR_URL", token: s?.zephyr?.tokenEnv || "ZEPHYR_API_TOKEN" },
     qtest: { url: "QTEST_URL", project: "QTEST_PROJECT_ID", token: s?.qtest?.tokenEnv || "QTEST_TOKEN" },
     xray: { url: "XRAY_URL", id: s?.xray.clientIdEnv || "XRAY_CLIENT_ID", secret: s?.xray.clientSecretEnv || "XRAY_CLIENT_SECRET" },
-    browserstack: { user: b?.remote?.provider === "browserstack" ? b.remote.usernameEnv : "BROWSERSTACK_USERNAME", key: b?.remote?.provider === "browserstack" ? b.remote.accessKeyEnv : "BROWSERSTACK_ACCESS_KEY" },
-    testmu: { user: b?.remote?.provider === "testmu" ? b.remote.usernameEnv : "LT_USERNAME", key: b?.remote?.provider === "testmu" ? b.remote.accessKeyEnv : "LT_ACCESS_KEY" },
+    browserstack: { user: b?.remotes?.browserstack?.usernameEnv || "BROWSERSTACK_USERNAME", key: b?.remotes?.browserstack?.accessKeyEnv || "BROWSERSTACK_ACCESS_KEY" },
+    testmu: { user: b?.remotes?.testmu?.usernameEnv || "LT_USERNAME", key: b?.remotes?.testmu?.accessKeyEnv || "LT_ACCESS_KEY" },
   }
 }
 

package/src/bi.ts

@@ -7,6 +7,7 @@ import { adoSettings } from "./cases/ado.ts"
 import { FAILURE_ACTION } from "./cases/failure.ts"
 import { http } from "./cases/http.ts"
 import { jiraApi } from "./cases/jira.ts"
+import { cachedJson } from "./cache.ts"
 import type { CaseResult, WriteBack } from "./cases/types.ts"
 import type { AppConfig, BiConfig, BiDatasetConfig } from "./config.ts"
 import { counts as suiteCounts } from "./suite/report.ts"
@@ -643,57 +644,71 @@ async function exportExternalDatasets(cfg: AppConfig, paths: Paths): Promise<Ext
 async function fetchAdoRows(cfg: AppConfig, dataset: Extract<BiDatasetConfig, { kind: "ado_wiql" }>): Promise<Record<string, string | number>[]> {
   const { auth, org, project: configured } = adoSettings(cfg.sources)
   const project = dataset.project || configured
-  const base = project ? `${org}/${encodeURIComponent(project)}` : org
-  const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { source?: { id?: number } | null; target?: { id?: number } | null }[] }>(
-    `${base}/_apis/wit/wiql?api-version=7.1&$top=500`,
-    { auth, body: { query: dataset.wiql } },
-  )
-  const ids = [...new Set([...(data.workItems || []).map((w) => w.id), ...(data.workItemRelations || []).flatMap((r) => [r.source?.id, r.target?.id]).filter((id): id is number => typeof id === "number")])].slice(0, 500)
-  if (!ids.length) return []
-  const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.AssignedTo", "System.ChangedDate", "System.IterationPath", "System.TeamProject"]
-  const rows: Record<string, string | number>[] = []
-  for (let i = 0; i < ids.length; i += 200) {
-    const batch = await http<{ value?: { id: number; fields: Record<string, unknown> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids: ids.slice(i, i + 200), fields } })
-    for (const item of batch.data.value || []) {
-      rows.push({
-        id: item.id,
-        project: String(item.fields["System.TeamProject"] || project || ""),
-        type: String(item.fields["System.WorkItemType"] || ""),
-        title: String(item.fields["System.Title"] || ""),
-        state: String(item.fields["System.State"] || ""),
-        assigned_to: displayName(item.fields["System.AssignedTo"]),
-        changed_at: String(item.fields["System.ChangedDate"] || ""),
-        iteration: String(item.fields["System.IterationPath"] || ""),
-      })
-    }
-  }
-  return rows
+  return cachedJson(cfg.cache, {
+    namespace: "bi:ado_wiql",
+    keyParts: [org, project || "", dataset.wiql],
+    ttlSeconds: cfg.cache?.biTtlSeconds,
+    load: async () => {
+      const base = project ? `${org}/${encodeURIComponent(project)}` : org
+      const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { source?: { id?: number } | null; target?: { id?: number } | null }[] }>(
+        `${base}/_apis/wit/wiql?api-version=7.1&$top=500`,
+        { auth, body: { query: dataset.wiql } },
+      )
+      const ids = [...new Set([...(data.workItems || []).map((w) => w.id), ...(data.workItemRelations || []).flatMap((r) => [r.source?.id, r.target?.id]).filter((id): id is number => typeof id === "number")])].slice(0, 500)
+      if (!ids.length) return []
+      const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.AssignedTo", "System.ChangedDate", "System.IterationPath", "System.TeamProject"]
+      const rows: Record<string, string | number>[] = []
+      for (let i = 0; i < ids.length; i += 200) {
+        const batch = await http<{ value?: { id: number; fields: Record<string, unknown> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids: ids.slice(i, i + 200), fields } })
+        for (const item of batch.data.value || []) {
+          rows.push({
+            id: item.id,
+            project: String(item.fields["System.TeamProject"] || project || ""),
+            type: String(item.fields["System.WorkItemType"] || ""),
+            title: String(item.fields["System.Title"] || ""),
+            state: String(item.fields["System.State"] || ""),
+            assigned_to: displayName(item.fields["System.AssignedTo"]),
+            changed_at: String(item.fields["System.ChangedDate"] || ""),
+            iteration: String(item.fields["System.IterationPath"] || ""),
+          })
+        }
+      }
+      return rows
+    },
+  })
 }
 
 async function fetchJiraRows(cfg: AppConfig, dataset: Extract<BiDatasetConfig, { kind: "jira_jql" }>): Promise<Record<string, string>[]> {
   const jira = jiraApi(cfg.sources)
   const fields = "summary,status,statuscategory,issuetype,priority,assignee,reporter,labels,components,parent,created,updated"
-  const rows: Record<string, string>[] = []
-  if (jira.cloud) {
-    let next: string | undefined
-    do {
-      const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", ...(next ? { nextPageToken: next } : {}) })
-      const { data } = await http<{ issues?: any[]; nextPageToken?: string; isLast?: boolean }>(`${jira.api}/search/jql?${q}`, { auth: jira.auth })
-      for (const issue of data.issues || []) rows.push(jiraRow(jira.url, issue))
-      next = data.isLast === false || data.nextPageToken ? data.nextPageToken : undefined
-    } while (next)
-  } else {
-    let startAt = 0
-    for (;;) {
-      const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", startAt: String(startAt) })
-      const { data } = await http<{ issues?: any[]; total?: number }>(`${jira.api}/search?${q}`, { auth: jira.auth })
-      const page = data.issues || []
-      for (const issue of page) rows.push(jiraRow(jira.url, issue))
-      startAt += page.length
-      if (!page.length || startAt >= Number(data.total || 0)) break
-    }
-  }
-  return rows
+  return cachedJson(cfg.cache, {
+    namespace: "bi:jira_jql",
+    keyParts: [jira.url, jira.cloud, dataset.jql, fields],
+    ttlSeconds: cfg.cache?.biTtlSeconds,
+    load: async () => {
+      const rows: Record<string, string>[] = []
+      if (jira.cloud) {
+        let next: string | undefined
+        do {
+          const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", ...(next ? { nextPageToken: next } : {}) })
+          const { data } = await http<{ issues?: any[]; nextPageToken?: string; isLast?: boolean }>(`${jira.api}/search/jql?${q}`, { auth: jira.auth })
+          for (const issue of data.issues || []) rows.push(jiraRow(jira.url, issue))
+          next = data.isLast === false || data.nextPageToken ? data.nextPageToken : undefined
+        } while (next)
+      } else {
+        let startAt = 0
+        for (;;) {
+          const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", startAt: String(startAt) })
+          const { data } = await http<{ issues?: any[]; total?: number }>(`${jira.api}/search?${q}`, { auth: jira.auth })
+          const page = data.issues || []
+          for (const issue of page) rows.push(jiraRow(jira.url, issue))
+          startAt += page.length
+          if (!page.length || startAt >= Number(data.total || 0)) break
+        }
+      }
+      return rows
+    },
+  })
 }
 
 function jiraRow(baseUrl: string, issue: Record<string, any>): Record<string, string> {

package/src/cache.ts

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto"
+
+import { createClient } from "redis"
+
+import type { CacheConfig } from "./config.ts"
+
+type CacheAdapter = {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, ttlSeconds: number): Promise<void>
+}
+
+let factoryOverride: ((config: CacheConfig) => Promise<CacheAdapter | null>) | undefined
+const adapters = new Map<string, Promise<CacheAdapter | null>>()
+
+function keyFor(config: CacheConfig): string {
+  return `${config.redisUrl}\n${config.keyPrefix}\n${config.connectTimeoutMs}`
+}
+
+function fullKey(config: CacheConfig, namespace: string, parts: unknown[]): string {
+  const digest = createHash("sha256").update(JSON.stringify(parts)).digest("hex")
+  return `${config.keyPrefix}:${namespace}:${digest}`
+}
+
+async function connectRedis(config: CacheConfig): Promise<CacheAdapter | null> {
+  const client = createClient({
+    url: config.redisUrl,
+    socket: { connectTimeout: config.connectTimeoutMs },
+  })
+  client.on("error", () => {})
+  try {
+    await client.connect()
+  } catch {
+    try {
+      client.disconnect()
+    } catch {}
+    return null
+  }
+  return {
+    async get(key) {
+      try {
+        return await client.get(key)
+      } catch {
+        return null
+      }
+    },
+    async set(key, value, ttlSeconds) {
+      try {
+        await client.set(key, value, { EX: ttlSeconds })
+      } catch {}
+    },
+  }
+}
+
+async function adapter(config: CacheConfig | undefined): Promise<CacheAdapter | null> {
+  if (!config?.enabled || !config.redisUrl) return null
+  const id = keyFor(config)
+  if (!adapters.has(id)) {
+    adapters.set(id, (factoryOverride || connectRedis)(config))
+  }
+  return adapters.get(id)!
+}
+
+export async function cachedJson<T>(
+  config: CacheConfig | undefined,
+  opts: {
+    namespace: string
+    keyParts: unknown[]
+    ttlSeconds?: number
+    load: () => Promise<T>
+  },
+): Promise<T> {
+  const ttlSeconds = opts.ttlSeconds || config?.defaultTtlSeconds || 3600
+  const store = await adapter(config)
+  if (!store) return opts.load()
+  const key = fullKey(config!, opts.namespace, opts.keyParts)
+  const hit = await store.get(key)
+  if (hit !== null) {
+    try {
+      return JSON.parse(hit) as T
+    } catch {
+      // Bad JSON should not break the current run; reload and overwrite it.
+    }
+  }
+  const value = await opts.load()
+  await store.set(key, JSON.stringify(value), ttlSeconds)
+  return value
+}
+
+export function setCacheFactoryForTests(factory?: (config: CacheConfig) => Promise<CacheAdapter | null>): void {
+  factoryOverride = factory
+  adapters.clear()
+}