@capagents/forgeqe 2.2.1 → 2.2.3

package/forgeqe.example.yaml

@@ -86,9 +86,11 @@ browser:
   max_steps: 40 # a checkpoint: a run still making progress carries on, up to 3x
   timeout_seconds: 600 # whole run
   vision_detail: low # low | high
-  viewport:
+  viewport: # headless page size; a visible window too with window: viewport
     width: 1280
     height: 800
+  window: maximized # visible browser: maximized | viewport
+  video: true # video.mp4 of each run, shown in its report
   allowed_hosts: []
   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

package/llms.example.json

@@ -50,10 +50,8 @@
     },
     "copilot": {
       "provider": "github_copilot",
-      "model": "claude-sonnet-4.6",
-      "engine_model": "openai/gpt-4.1",
-      "github_org": "",
-      "description": "GitHub Copilot seat for ForgeQE's agent and Scribe (forgeqe auth login copilot); the browser engine uses GitHub Models with your GitHub sign-in"
+      "model": "gpt-4.1",
+      "description": "GitHub Copilot seat for the browser engine, through GitHub's Copilot SDK (forgeqe auth login copilot: a fine-grained token with Copilot Requests, or the GitHub CLI's sign-in)"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "2.2.1",
+  "version": "2.2.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": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "bin/",
+    "reporters/",
     "dist/",
     "py/forgeqe_engine/*.py",
     "py/forgeqe_desktop/*.py",
@@ -39,11 +40,13 @@
     "forgeqe": "bun src/index.ts",
     "start": "bun src/index.ts start",
     "test": "bun test",
+    "test:release": "bun scripts/release-tests.ts",
     "typecheck": "tsc --noEmit",
     "build:report": "cd report-ui && npm install --no-audit --no-fund && npm run build && cp dist/index.html ../src/report/template.html",
     "build": "bun scripts/build.ts",
     "notices": "bun scripts/gen-notices.ts",
-    "prepack": "bun scripts/build.ts && bun scripts/gen-notices.ts"
+    "prepack": "bun scripts/build.ts && bun scripts/gen-notices.ts",
+    "prepublishOnly": "bun run typecheck && bun scripts/release-tests.ts"
   },
   "keywords": [
     "forgeqe",

package/prompts/README.md

@@ -9,6 +9,7 @@ project; leave it as it is to keep getting ForgeQE's improvements when you updat
 | test-agent.md | Scribe, the coding agent: turns a verified browser run into a test in your repository |
 | test-rules.md | Rules for any test the agents write or change (included in test-agent, test-reviewer, heal) |
 | test-reviewer.md | The reviewer that checks a passing test tests the right thing the right way |
+| test-plan.md | Plans how a test you recorded by hand (`forgeqe record`) fits your repository, for you to agree before Scribe writes it |
 | heal.md | Heals tests the application has outgrown, and tells them apart from real bugs |
 | find-tests.md | Finds the automated tests that match a request |
 | pr-review.md | Reviews pull requests |

package/prompts/brain.md

@@ -255,6 +255,8 @@ When the user asks for a regression pack, or which tests to run for a release, a
 - You MUST report the tests by why they are in, the changes no test covers with the closest test for each, and the risk areas.
 - When the user did not say where to run the pack, you MUST ask one question: on this machine, on TestMu AI, or in a pipeline. You MUST NOT run a pack until the user agrees.
 - After a run, you MUST name the failing tests with their messages, and the tests that fail now but passed in the last run.
+- You MUST give the triage of the run: each failing test's route (flaky, environment, test code broken, heal, or an AI re-run decides) and why. You MUST offer only what the triage says. For heal and AI re-run tests, offer heal_tests with pack. When the environment was down, offer to run the pack again first. You MUST NOT offer heal_tests for flaky, environment, or test code failures.
+- You MUST file a bug only for an app_bug that heal_tests reports, not for a failure the triage routed.
 
 ### Writing tests
 When the user asks, or when the setup below says that passed runs become tests:
@@ -281,7 +283,7 @@ When the user asks, or when the setup below says that passed runs become tests:
 
 ### Repairing broken tests
 When the user says that tests fail, broke after a release, or need healing:
-- You MUST call heal_tests. Give the command when the user gave one or you know it. Otherwise use the test command below, or let the healing agent find it.
+- You MUST call heal_tests. After a regression pack run, give pack, and tests when the user named some. Otherwise give the command when the user gave one or you know it. Otherwise use the test command below, or let the healing agent find it.
 - You MUST report the verdict for each test: healed and confirmed, an application bug, or not healed. For an application bug, give what the browser run found.
 - You MUST also report the files that changed, and heal.md.
 - You MUST NOT delete, skip, or make tests weaker yourself to make a run pass.

package/prompts/test-plan.md

@@ -0,0 +1,61 @@
+---
+name: test-plan
+description: "Plans how a test recorded by hand fits the repository, for the tester to agree before Scribe writes it."
+used_by: "forgeqe record, write_test for a recording"
+kind: structured
+---
+{{> conventions}}
+
+## Role
+You plan how a test that a tester recorded by hand fits a test repository. You do not write or change files.
+
+## Objective
+Tell the tester where the test goes and which code it uses. The tester agrees before Scribe writes it.
+
+## Inputs
+- The handoff: the recorded steps in order, their locators, the tester's checks, variables, test data, and notes.
+- The repository's test setup: the framework, the page objects, the fixtures, and the test data.
+- The tools code_outline, code_element, and code_references. They show what the page objects already locate and do.
+
+## Rules
+Reading:
+- You MUST find the page-object members and methods that already locate each element of the steps. Use the code tools.
+- You SHOULD read only the files that the plan needs.
+
+Where the test goes:
+- You MUST name the test file and the test name. Follow the names and folders of the tests that are there.
+- When an existing test already does the first steps, you MAY propose to extend it. Name that test.
+
+Steps:
+- For each step, you MUST say which existing member or method does it, or which new one the test adds, and where.
+- A new member MUST go in the page object of the page where the step is.
+- You MUST NOT change what an existing member does for the other tests.
+
+Checks and data:
+- For each CHECK line, you MUST say the assertion and the step after which it comes.
+- A check that the tester gave only in words MUST stay in the plan. Say what on the page will show it.
+- For each value marked as test data, you MUST name its source: a fixture, a data file, or a parameter.
+- You MUST keep the secrets as environment variables.
+
+Questions:
+- You MUST ask a question only when the repository allows two good answers and the tester's choice changes the code.
+- You MUST NOT ask more than 3 questions. Give each question 2 to 4 short options, the recommended option first.
+- You MUST NOT ask what the handoff or the repository already answers.
+
+## Output
+The structured result: test_file, test_name, mode, steps, new members, checks, test data, questions, and a short summary.
+
+## Examples
+### Example 1
+Handoff: open the shop, search "pliers", open the first result, add it to the cart, CHECK the cart badge shows "1". The repository has pages/HomePage.ts with searchFor() and no product page object.
+- test_file tests/add-to-cart.spec.ts, test_name "adds pliers to the cart", mode new.
+- Steps: search with HomePage.searchFor(); open the product with a new HomePage.product(name); add to the cart with a new ProductPage.addToCart() in pages/ProductPage.ts.
+- Checks: after the add, expect ProductPage.cartQuantity to have the text "1".
+- Questions: none.
+
+### Example 2
+Handoff: sign in, type the coupon "SAVE10" (test data: coupon), CHECK the total shows text like "$40.00". The repository has tests/data/coupons.json and a fixture that signs in.
+- Steps: sign in with the signedIn fixture; type the coupon with a new CartPage.applyCoupon(code).
+- Test data: read the coupon from tests/data/coupons.json, with SAVE10 as the first entry.
+- Checks: after the coupon, expect CartPage.total to match /^\$\d+\.\d{2}$/.
+- Questions: "Add the coupon test to tests/cart.spec.ts, or a new file?" Options: "tests/cart.spec.ts", "A new file".

package/py/forgeqe_engine/browser.py

@@ -192,7 +192,20 @@ def _testmu_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+# browser.provider docker: ForgeQE starts the browser container and passes its gateway's endpoint (with its token) here.
+DOCKER_CDP_ENV = "FORGEQE_BROWSER_CDP_URL"
+
+
+def docker_browser_launch_kwargs() -> Dict[str, Any]:
+    url = (os.getenv(DOCKER_CDP_ENV) or "").strip()
+    if not url.startswith("ws://127.0.0.1:"):
+        raise RuntimeError(f"docker: {DOCKER_CDP_ENV} is not set to the browser container's local endpoint; ForgeQE starts that container itself.")
+    return {"cdp_url": url}
+
+
 def remote_browser_launch_kwargs(provider: str, remote: Dict[str, Any]) -> Dict[str, Any]:
+    if provider == "docker":
+        return docker_browser_launch_kwargs()
     endpoint = str(remote.get("endpoint") or "").strip().rstrip("/")
     if not endpoint:
         raise RuntimeError(f"{provider}: a remote endpoint is required.")
@@ -212,6 +225,8 @@ def browser_launch_kwargs(*, provider: str, headless: bool, remote: Optional[Dic
 def browser_connection_label(provider: str, launch: Dict[str, Any], remote: Optional[Dict[str, Any]] = None) -> str:
     if provider == "local":
         return str(launch.get("channel") or "chrome")
+    if provider == "docker":
+        return "Chromium in a container"
     browser = str((remote or {}).get("browser") or "")
     target = str((remote or {}).get("platform") or "").strip() or " ".join(
         x for x in [str((remote or {}).get("os") or "").strip(), str((remote or {}).get("os_version") or (remote or {}).get("osVersion") or "").strip()] if x
@@ -296,6 +311,93 @@ async def reopen_in_fresh_tab(browser: Any, url: str) -> None:
             await close.event_result(raise_if_any=False, raise_if_none=False)
 
 
+VIDEO_FILE = "video.mp4"
+
+
+def _size(value: Any) -> Optional[Dict[str, int]]:
+    """browser.viewport as [width, height], or None when it is not two sizes a screen can have."""
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        return None
+    try:
+        w, h = int(value[0]), int(value[1])
+    except (TypeError, ValueError):
+        return None
+    return {"width": w, "height": h} if 200 <= w <= 10000 and 200 <= h <= 10000 else None
+
+
+def window_launch_kwargs(browser_cfg: Dict[str, Any], *, headless: bool) -> Dict[str, Any]:
+    """
+    The size of a local browser. Headless: the page is browser.viewport. Visible: the window is that size with
+    browser.window: viewport, else the library's screen-sized window, which `maximize_window` then maximises.
+    """
+    if str(browser_cfg.get("provider") or "local") != "local":
+        return {}
+    size = _size(browser_cfg.get("viewport"))
+    if not size:
+        return {}
+    if headless:
+        return {"viewport": size}
+    return {"window_size": size} if browser_cfg.get("window") == "viewport" else {}
+
+
+def wants_maximized(browser_cfg: Dict[str, Any], *, headless: bool) -> bool:
+    return not headless and str(browser_cfg.get("provider") or "local") == "local" and browser_cfg.get("window") != "viewport"
+
+
+async def maximize_window(browser: Any) -> bool:
+    """Maximise the visible browser's window (the library only sizes it to the screen, under the menu bar and Dock)."""
+    try:
+        session = await browser.get_or_create_cdp_session()
+        send = browser.cdp_client.send.Browser
+        found = await send.getWindowForTarget(params={"targetId": session.target_id})
+        window_id = found["windowId"]
+        await send.setWindowBounds(params={"windowId": window_id, "bounds": {"windowState": "maximized"}})
+        # The page takes the new size a moment later; the video is sized from it.
+        for _ in range(10):
+            bounds = (await send.getWindowBounds(params={"windowId": window_id})).get("bounds") or {}
+            if bounds.get("windowState") == "maximized":
+                break
+            await asyncio.sleep(0.1)
+        await asyncio.sleep(0.3)
+        return True
+    except Exception as ex:
+        logger.debug("maximise window failed: %s", ex)
+        return False
+
+
+def video_available() -> bool:
+    try:
+        from browser_use.browser.video_recorder import IMAGEIO_AVAILABLE
+    except Exception:
+        return False
+    return bool(IMAGEIO_AVAILABLE)
+
+
+async def start_video(browser: Any, out_dir: Path) -> Optional[Path]:
+    """Record the agent's tab to <out_dir>/video.mp4 until `stop_video`; None when it could not start."""
+    watchdog = getattr(browser, "_recording_watchdog", None)
+    if watchdog is None or not video_available():
+        return None
+    try:
+        return Path(await watchdog.start_recording(out_dir / VIDEO_FILE))
+    except Exception as ex:
+        logger.debug("video recording did not start: %s", ex)
+        return None
+
+
+async def stop_video(browser: Any) -> Optional[Path]:
+    """Finish the video file; None when nothing was recorded."""
+    watchdog = getattr(browser, "_recording_watchdog", None)
+    if watchdog is None or not getattr(watchdog, "is_recording", False):
+        return None
+    try:
+        path = await asyncio.wait_for(watchdog.stop_recording(), timeout=120.0)
+    except Exception as ex:
+        logger.debug("video recording did not finish: %s", ex)
+        return None
+    return Path(path) if path and Path(path).is_file() and Path(path).stat().st_size else None
+
+
 async def _shutdown_browser_instance(browser: Any) -> None:
     """Stop the library gracefully, falling back to kill()."""
     if browser is None:
@@ -348,7 +450,10 @@ async def browser_profile(browser: Any, launch: Dict[str, Any], *, provider: str
         "extra_http_headers": {},
         "provider": provider,
     }
-    if provider != "local":
+    if provider == "docker":
+        # Not a browser on another machine: the coding agent's replay and live browser use the same kind of container.
+        profile["container"] = True
+    elif provider != "local":
         host = urlparse(str(launch.get("cdp_url") or "")).netloc
         profile["remote_browser"] = f"{'BrowserStack' if provider == 'browserstack' else 'TestMu AI'} via {host}"
         if remote:

package/py/forgeqe_engine/cli.py

@@ -9,9 +9,11 @@ Engine process protocol, used by the Bun CLI:
 
   python -m forgeqe_engine run
   python -m forgeqe_engine login   (stdin: {url, logins}, then "save")
+  python -m forgeqe_engine record  (stdin: {start_url, out_dir, ...}, then commands; "stop" or EOF ends it)
   python -m forgeqe_engine doctor
   python -m forgeqe_engine token   (stdin: an llms.json profile with auth: entra; prints {token, expires_on})
   python -m forgeqe_engine probe   (stdin: an llms.json profile; prints {ok, ms, structured, vision, error?})
+  python -m forgeqe_engine copilot-gateway   (GitHub Copilot as an OpenAI-style endpoint on 127.0.0.1; see copilot_gateway.py)
 """
 from __future__ import annotations
 
@@ -72,6 +74,14 @@ def _doctor(out: TextIO) -> int:
         info["azure_identity"] = version("azure-identity")
     except Exception:
         pass
+    try:
+        info["copilot_sdk"] = version("github-copilot-sdk")
+    except Exception:
+        pass
+    try:
+        info["video"] = version("imageio")
+    except Exception:
+        pass
     try:
         from .service import local_browser_launch_kwargs
 
@@ -155,6 +165,47 @@ def _login(out: TextIO) -> int:
     return asyncio.run(main())
 
 
+def _record(out: TextIO) -> int:
+    """stdin line 1: the recording request (recordsession.py); later lines are commands ("stop", or JSON {"cmd": ...}); EOF stops."""
+    from .recordsession import record_web
+
+    line = sys.stdin.readline()
+    payload = json.loads(line) if line.strip() else {}
+    lock = threading.Lock()
+
+    def emit(event: Dict[str, Any]) -> None:
+        with lock:
+            out.write(json.dumps(event, ensure_ascii=False, default=str) + "\n")
+            out.flush()
+
+    async def main() -> int:
+        loop = asyncio.get_running_loop()
+        commands: asyncio.Queue = asyncio.Queue()
+
+        def watch_stdin() -> None:
+            for raw in sys.stdin:
+                text = raw.strip()
+                if not text:
+                    continue
+                try:
+                    cmd = json.loads(text) if text.startswith("{") else {"cmd": text.lower()}
+                except ValueError:
+                    continue
+                if isinstance(cmd, dict):
+                    loop.call_soon_threadsafe(commands.put_nowait, cmd)
+            loop.call_soon_threadsafe(commands.put_nowait, {"cmd": "stop"})
+
+        threading.Thread(target=watch_stdin, daemon=True).start()
+        try:
+            result = await record_web(payload, emit, commands)
+        except Exception as e:
+            result = {"success": False, "error": f"{type(e).__name__}: {e}"}
+        emit({"type": "done", "result": result})
+        return 0 if result.get("success") else 1
+
+    return asyncio.run(main())
+
+
 def _token(out: TextIO) -> int:
     """stdin: an llms.json profile with auth: entra. Prints {token, expires_on} for its scope, or {error}."""
     from .llm import entra_credential, entra_scope
@@ -204,9 +255,15 @@ def main(argv: list[str] | None = None) -> int:
         return _run(out)
     if cmd == "login":
         return _login(out)
+    if cmd == "record":
+        return _record(out)
     if cmd == "token":
         return _token(out)
     if cmd == "probe":
         return _probe(out)
+    if cmd == "copilot-gateway":
+        from .copilot_gateway import main as copilot_gateway
+
+        return copilot_gateway(out)
     out.write(json.dumps({"type": "done", "result": {"success": False, "error": f"Unknown command {cmd}"}}) + "\n")
     return 2