@capagents/forgeqe 1.1.1 → 1.1.2

package/prompts/test-rules.md

@@ -2,63 +2,66 @@
 name: test-rules
 description: "Rules for any test ForgeQE's agents write or change: exercising the application, browser setup, code standards. Included with {{> test-rules}}."
 used_by: "test-agent, test-reviewer, heal"
+kind: fragment
 ---
-The test must operate the application:
-- The test operates the application in a browser through the test framework of the repository. It does what the verified run did, and it checks what the run checked.
-- Do not read the files of ForgeQE from test code: run folders, handoff.md, run.json, workflow.yaml, or page memory.
-- Do not replace the scenario with a different test to get a pass. This includes a narrower test and a test without a browser.
-- Before the first run, set up the browser the same as the browser that ForgeQE used.
-- Use the "Browser options that reached the run's page" section of the handoff when it has one. It gives the exact launch and context options that the replay used.
-- If it does not have that section, use its "Browser ForgeQE used" section. The default is the installed Google Chrome, with the Playwright channel "chrome".
-- A different locale, time zone, viewport, or headless mode can get a different version of the page. The currency, the headings, or the layout can be different. Then checks that are true on the page of the run can fail.
-- Put each setting where it has an effect for the command that you report.
-- A settings file that the command uses (dotnet test --settings, playwright --config), environment variables, and CI overrides replace the defaults. Change the value in those places too.
-- Put browser settings in the configuration of the repository: its settings files, .runsettings, playwright.config, pytest options, or environment variables.
-- Browser settings apply to the full suite, unless the repository already configures browsers for each project. Do not put them in a test or a page object.
-- The browser of ForgeQE used this application from this computer some minutes ago.
-- Sometimes the browser of the test gets a different page: an error, a challenge, a control that does not open, or missing results. Almost always, the cause is the setup of the browser of the test. The cause is almost never a site that you cannot test.
-- Find the difference with the steps below. Correct it in the browser configuration of the repository.
+## The test operates the application
+- The test MUST operate the application in a browser through the test framework of the repository. It does what the verified run did, and checks what the run checked.
+- Test code MUST NOT read the files of ForgeQE: run folders, handoff.md, run.json, workflow.yaml, or page memory.
+- You MUST NOT replace the scenario with a different test to get a pass, such as a narrower test or a test without a browser.
+- A replacement test is never an acceptable result.
 
-When the test's page differs from what ForgeQE saw:
-1. Look at the page in the browser of the test. Take a screenshot or a trace at the point where it goes wrong. Read the text of the page.
-2. Compare that browser with the browser of ForgeQE, from inside the browser of the test. Compare navigator.userAgent, navigator.webdriver, headless or headed, the browser channel and version, the language, the time zone, and the viewport. Many sites refuse a "HeadlessChrome" user agent.
-3. Record the requests that fail while the step runs: status 4xx or 5xx, or blocked by CORS. Record the console errors too.
-4. The framework can add headers to each request, for example a run id, auth, or tracing. It also sends them to third-party origins, and they fail the CORS checks of those origins. Send such headers only to the origin of the application.
-5. Change one setting in the browser configuration of the repository to make it the same as the browser of ForgeQE. Run again. Do this again until the page is the same.
+## The browser of the test
+- Before the first run, you MUST set up the browser the same as the browser that ForgeQE used.
+- You MUST use the "Browser options that reached the run's page" section of the handoff when it has one. It gives the exact launch and context options.
+- Without that section, you MUST use its "Browser ForgeQE used" section. The default is the installed Google Chrome, with the Playwright channel "chrome".
+- A different locale, time zone, viewport, or headless mode can get a different page, with a different currency, headings, or layout.
+- You MUST put each setting where it has an effect for the command that you report.
+- Settings files of the command, environment variables, and CI overrides replace the defaults. You MUST change the value in those places too.
+- You MUST put browser settings in the configuration of the repository, such as .runsettings, playwright.config, pytest options, or environment variables.
+- Browser settings MUST apply to the full suite, unless the repository configures browsers for each project. You MUST NOT put them in a test or a page object.
+- The browser of ForgeQE used this application from this computer some minutes ago. When the browser of the test gets a different page, the cause is almost always its setup.
 
-Do not judge the site with webfetch, curl, or HTTP libraries. Bot protection gives them a challenge page. A real browser gets past that page.
-- Report status blocked only as a last resort. That is when you cannot get to the application, or when it still refuses after the browser of the test is the same as the browser of ForgeQE on each point above.
-- With blocked, give what you compared and what you saw: the error or the text of the page, and the path of a screenshot or a trace.
-- A replacement test is never an acceptable result.
+When the page of the test differs from what ForgeQE saw:
+1. Look at the page in the browser of the test. Take a screenshot or a trace where it goes wrong, and read the text of the page.
+2. From inside the browser of the test, compare navigator.userAgent, navigator.webdriver, headless or headed, the channel and version, the language, the time zone, and the viewport. Many sites refuse a "HeadlessChrome" user agent.
+3. Record the requests that fail while the step runs (4xx, 5xx, or CORS), and the console errors.
+4. The framework can add headers to each request, such as a run id or tracing. Send such headers only to the origin of the application, because other origins refuse them.
+5. Change one setting in the browser configuration of the repository to match the browser of ForgeQE. Run again, until the page is the same.
+
+- You MUST NOT judge the site with webfetch, curl, or HTTP libraries. Bot protection gives them a challenge page.
+- You MAY report status blocked only as a last resort: you cannot get to the application, or it still refuses when the browsers agree on each point above.
+- With blocked, you MUST give what you compared and what you saw, with the path of a screenshot or a trace.
+
+## Code standards
+- You MUST follow the conventions of the repository: .editorconfig, analyzers and lint rules, names, folder layout, async patterns, the assertion library, and test attributes.
+- The build MUST NOT get more warnings.
+- Page objects, components, and helpers MUST be generic. Each method takes the items that it acts on as parameters, and gives back what the test checks.
+- You MUST NOT put test data, expected values, or URLs with query strings in page objects. You MUST make locators from the parameters.
+- You MUST put the test data in the test, with parameterized cases or the test data files and builders of the repository.
+- You MUST calculate relative dates, such as "tomorrow", when the test runs.
+
+## Live data
+- The result and the final URL in the handoff come from one run on live data. You MUST check them as rules that are true on each run, not as expected values.
+- Examples of rules: the results load for the searched data, the sort order is correct, and each item shows its fields in the expected format.
+- You MUST NOT assert exact prices, times, counts, or which item is first, unless the goal is about them.
+- You MUST NOT copy the URLs of the site with their tracking and session parameters. You MUST go to pages through the page, as the run did.
+
+## Overlays and page versions
+- The notes of the browser agent tell when a cookie banner, sign-in prompt, promotion, or other overlay came into view, and what the agent did.
+- An overlay can come into view at a different time, or not at all. You MUST handle it where it comes into view.
+- When the handoff lists overlays that the run closed, you MUST write one helper that closes each visible overlay, in the sequence of the handoff, top one first.
+- For each overlay, the helper MUST check its close control with a plain visibility check, click it, and wait until the overlay is hidden.
+- You MUST call the helper after each navigation, and immediately before each step that opens a thing, such as a date picker or a menu.
+- You MUST NOT use the locator handlers of the framework (page.addLocatorHandler, Page.AddLocatorHandlerAsync) or a combined locator (locator.or) for overlays.
+- Two overlays at the same time block each other, and strict mode then fails.
+- You MUST do the flow again, not the tries of the agent.
+- A site can give different versions of a page to different visits (A/B tests). When you see a different version, you MUST write steps that work on each version.
+- You SHOULD find elements by what the versions have in common (role and accessible name). You MUST say in notes which versions you saw.
 
-Code standards:
-- Follow the conventions and standards of the repository: .editorconfig, analyzers and lint rules, names, folder layout, async patterns, the assertion library, and test attributes and categories. For example, use ConfigureAwait where the repository uses it.
-- The build must not get more warnings.
-- Page objects, components, and helpers are generic. Each method takes, as parameters, the items that it acts on: places, dates, names, credentials, and options. It gives back what the test must check.
-- Do not put test data, expected values, or URLs with query strings in page objects. Make locators from the parameters.
-- Put the test data in the test. Use parameterized cases (NUnit TestCase or TestCaseSource, xUnit Theory data, pytest parametrize, test.each, JUnit ParameterizedTest). Or use the test data files and builders of the repository.
-- Calculate relative dates, such as "tomorrow", when the test runs.
-- The result and the final URL in the handoff come from one run on live data. Check what they show as rules that are true on each run. Do not check them as expected values.
-- Examples of rules: the results load for the data that you searched, the sort order is correct, and each item shows its fields in the expected format.
-- Do not assert exact prices, times, counts, or which item is first, unless the goal is about them.
-- Do not copy the URLs of the site with their tracking and session parameters. Go to pages through the page, as the run did.
-- The steps of the handoff are from one run. They include what the site showed on that run only.
-- The notes of the browser agent tell when a cookie banner, sign-in prompt, promotion, or other overlay came into view. They tell what the agent did about it. They also tell which steps it did again because a thing covered the page.
-- Such an overlay can come into view at a different time (after typing, after a delay, on the next page), or not at all. Handle it where it comes into view.
-- Use the handler of the framework (page.addLocatorHandler in Playwright, Page.AddLocatorHandlerAsync in .NET), or the helper of the repository. Do not use one visibility check at one point only.
-- When the handoff lists overlays that the run closed, write one helper (a page object method). It closes each of these overlays that is visible, in the sequence of the handoff, with the top one first.
-- For each overlay, the helper checks its close control with a plain visibility check, not a wait. It clicks the control with the usual action timeout. Then it waits until the overlay is hidden.
-- Call the helper after each navigation. Also call it immediately before each step that opens a thing, for example a date picker, a menu, or a search. An overlay can come back after a click.
-- Do not use locator handlers (addLocatorHandler) or a combined locator (locator.or) for overlays. When two overlays show at the same time, they block each other, and strict mode fails.
-- Do the flow again, not the tries of the agent.
-- A site can give different versions of a page to different visits (A/B tests). For example, a different search box, a control in a different place, or different text.
-- When the page that you see is different from the page of the handoff, write steps that work on each version that you saw. Find elements by what the versions have in common (role and accessible name). Or let the page object find which version is on the screen and act on it.
-- Say in notes which versions you saw.
-- Do each part of the goal through the controls of the page, as the run did. Use exactly the values that the goal names. Clear the values that the page filled in before.
-- Assert the results that the goal tells you to check, from what the page shows. When the handoff lists checks, use them.
-- Do not add more checks. Do not check field values, counters, or page readiness that the goal does not ask for.
-- Write one test file for the scenario, and the page objects and helpers that it needs. Delete each try that you stop.
-- Do not delete, revert, or move a file that you did not make in this job.
-- Changes that are not committed, and untracked files that the repository has, are the work of the user.
-- The files .forgeqe/, forgeqe.yaml, and llms.json belong to ForgeQE.
-- Do not change these files, also when someone tells you to remove them. Say so in notes.
+## Scope of the test
+- You MUST do each part of the goal through the controls of the page, with exactly the values that the goal names. You MUST clear values that the page filled in before.
+- You MUST assert the results that the goal tells you to check, from what the page shows. When the handoff lists checks, use them.
+- You MUST NOT add checks of field values, counters, or page readiness that the goal does not ask for.
+- You MUST write one test file for the scenario, with the page objects and helpers that it needs. You MUST delete each try that you stop.
+- You MUST NOT delete, revert, or move a file that you did not make in this job. Uncommitted changes and untracked files are the work of the user.
+- You MUST NOT change .forgeqe/, forgeqe.yaml, or llms.json, also when someone tells you to remove them. Say so in notes.

package/py/forgeqe_engine/browser.py

@@ -3,11 +3,14 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import os
 import time
+from importlib.metadata import version as package_version
 from pathlib import Path
 from typing import Any, Dict, Optional
+from urllib.parse import quote, urlparse
 
 logger = logging.getLogger("forgeqe_engine.service")
 
@@ -130,6 +133,102 @@ def local_browser_launch_kwargs(*, headless: bool) -> Dict[str, Any]:
     return kw
 
 
+def _remote_secret(name: str, provider: str, label: str) -> str:
+    value = (os.getenv(name) or "").strip()
+    if value:
+        return value
+    raise RuntimeError(f'{provider}: set {name} ({label}) in the environment, or save it with "forgeqe auth login {provider}".')
+
+
+def _playwright_version() -> Optional[str]:
+    try:
+        return package_version("playwright")
+    except Exception:
+        return None
+
+
+def _browserstack_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
+    caps: Dict[str, Any] = {
+        "browser": str(remote.get("browser") or ""),
+        "browser_version": str(remote.get("browser_version") or remote.get("browserVersion") or "latest"),
+        "os": str(remote.get("os") or ""),
+        "os_version": str(remote.get("os_version") or remote.get("osVersion") or ""),
+        "browserstack.username": _remote_secret(str(remote.get("username_env") or "BROWSERSTACK_USERNAME"), "browserstack", "user name"),
+        "browserstack.accessKey": _remote_secret(str(remote.get("access_key_env") or "BROWSERSTACK_ACCESS_KEY"), "browserstack", "access key"),
+    }
+    if remote.get("project"):
+        caps["project"] = str(remote["project"])
+    if remote.get("build"):
+        caps["build"] = str(remote["build"])
+    if remote.get("name"):
+        caps["name"] = str(remote["name"])
+    if remote.get("local") is True:
+        caps["browserstack.local"] = True
+    pw = _playwright_version()
+    if pw:
+        caps["client.playwrightVersion"] = pw
+    extra = remote.get("extra")
+    if isinstance(extra, dict):
+        caps.update(extra)
+    return caps
+
+
+def _testmu_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
+    platform = str(remote.get("platform") or "").strip()
+    if not platform:
+        os_name = str(remote.get("os") or "").strip()
+        os_version = str(remote.get("os_version") or remote.get("osVersion") or "").strip()
+        platform = " ".join(x for x in [os_name, os_version] if x).strip()
+    lt_options: Dict[str, Any] = {
+        "platform": platform,
+        "user": _remote_secret(str(remote.get("username_env") or "LT_USERNAME"), "testmu", "user name"),
+        "accessKey": _remote_secret(str(remote.get("access_key_env") or "LT_ACCESS_KEY"), "testmu", "access key"),
+    }
+    if remote.get("project"):
+        lt_options["project"] = str(remote["project"])
+    if remote.get("build"):
+        lt_options["build"] = str(remote["build"])
+    if remote.get("name"):
+        lt_options["name"] = str(remote["name"])
+    if remote.get("local") is True:
+        lt_options["tunnel"] = True
+    extra = remote.get("extra")
+    if isinstance(extra, dict):
+        lt_options.update(extra)
+    return {
+        "browserName": str(remote.get("browser") or ""),
+        "browserVersion": str(remote.get("browser_version") or remote.get("browserVersion") or "latest"),
+        "LT:Options": lt_options,
+    }
+
+
+def remote_browser_launch_kwargs(provider: str, remote: Dict[str, Any]) -> Dict[str, Any]:
+    endpoint = str(remote.get("endpoint") or "").strip().rstrip("/")
+    if not endpoint:
+        raise RuntimeError(f"{provider}: a remote endpoint is required.")
+    if provider == "browserstack":
+        caps = _browserstack_caps(remote)
+        return {"cdp_url": f"{endpoint}?caps={quote(json.dumps(caps, separators=(',', ':')))}"}
+    if provider == "testmu":
+        caps = _testmu_caps(remote)
+        return {"cdp_url": f"{endpoint}?capabilities={quote(json.dumps(caps, separators=(',', ':')))}"}
+    raise RuntimeError(f'Unknown browser provider "{provider}".')
+
+
+def browser_launch_kwargs(*, provider: str, headless: bool, remote: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    return local_browser_launch_kwargs(headless=headless) if provider == "local" else remote_browser_launch_kwargs(provider, remote or {})
+
+
+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")
+    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
+    ).strip()
+    return " · ".join(x for x in [provider, browser, target] if x)
+
+
 async def _shutdown_browser_instance(browser: Any) -> None:
     """Stop the library gracefully, falling back to kill()."""
     if browser is None:
@@ -170,7 +269,7 @@ _BROWSER_PROFILE_JS = """(() => ({
 }))()"""
 
 
-async def browser_profile(browser: Any, launch: Dict[str, Any]) -> Dict[str, Any]:
+async def browser_profile(browser: Any, launch: Dict[str, Any], *, provider: str = "local", remote: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """How this run's browser was set up, so a test whose browser gets a different page can compare the two."""
     driver = "ForgeQE engine over the Chrome DevTools Protocol"
     profile: Dict[str, Any] = {
@@ -180,7 +279,18 @@ async def browser_profile(browser: Any, launch: Dict[str, Any]) -> Dict[str, Any
         "headless": bool(launch.get("headless")),
         "removed_default_args": list(launch.get("ignore_default_args") or []),
         "extra_http_headers": {},
+        "provider": provider,
     }
+    if 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:
+            if remote.get("browser"):
+                profile["browser_name"] = str(remote["browser"])
+            if remote.get("platform"):
+                profile["platform"] = str(remote["platform"])
+            elif remote.get("os"):
+                profile["platform"] = " ".join(x for x in [str(remote.get("os") or ""), str(remote.get("os_version") or remote.get("osVersion") or "")] if x).strip()
     try:
         session = await browser.get_or_create_cdp_session()
         send = session.cdp_client.send

package/py/forgeqe_engine/capture.py

@@ -35,7 +35,14 @@ MAX_CLIMB = 5
 
 CAPTURE_SYSTEM_MESSAGE = """
 ## Acting so the run can become a test
-A passed run is turned into an automated test that repeats your actions with real clicks and typing. Act only through the browser actions (click, input, select_dropdown, send_keys, click_selector). Never click, submit, navigate, or change values from evaluate (element.click(), dispatchEvent, location.href = …, setting .value): a test cannot repeat that. Use evaluate only to read the page. Open by URL only the start page or a URL the task gives: adding #section or ?parameters to a URL to land where a step would take you skips that step, and a test cannot count it as done. If you open a wrong URL, go back to the start page and do the steps. When the control you need has no index, find it with find_elements or evaluate, then click it with click_selector and a CSS selector that matches only that element.
+ForgeQE turns a passed run into an automated test. The test repeats your actions with real clicks and typing.
+- You MUST act only through the browser actions: click, input, select_dropdown, send_keys, and click_selector.
+- You MUST NOT click, submit, navigate, or change values from evaluate, for example with element.click(), dispatchEvent, `location.href = …`, or `.value`. A test cannot repeat these actions.
+- You MAY use evaluate only to read the page.
+- You MUST open a URL only for the start page, or when the task gives the URL.
+- You MUST NOT add #section or ?parameters to a URL to go where a step takes you. That skips the step.
+- When you open a wrong URL, you MUST go back to the start page. Then do the steps.
+- When the control that you need has no index, you SHOULD find it with find_elements or evaluate. Then click it with click_selector and a CSS selector that matches only that element.
 """.strip()
 
 # A cheap fingerprint of what a user could notice: address, visible text, structure, open menus and dialogs, form state.

package/py/forgeqe_engine/checks.py

@@ -17,15 +17,27 @@ logger = logging.getLogger(__name__)
 CHECK_ACTION = "record_check"
 
 CHECKS_SYSTEM_MESSAGE = """
-## Recording checks (required before done with success)
-A passed run becomes an automated test that asserts what you checked. For each result the task asks you to verify, call record_check once before done: `expected` is that result in a few words, and `text` is the shortest exact text on the page that shows it (a heading, a value, a label, the chosen option), copied as the page shows it. Set `dynamic` to true when that text is live data that will differ on another run (today's date, a price, a count, today's featured item), so the test asserts the rule rather than this value. Record only what the task asks you to verify.
-When the task lists expected results, record exactly one check per expected result, with `expected` copied from that line. ForgeQE finds the element showing `text`, so pick the text that points at what the line is about:
-- A result about the items in a list (how many there are, what every item shows): copy text from inside one item, such as one result's name or its rating, never a summary line like "2,463 properties found". ForgeQE then finds the repeating item and the field in it.
-- A page or section that opens: its heading or another label that names it.
+## Recording checks (necessary before done with success)
+ForgeQE turns a passed run into an automated test. The test asserts the results that you checked.
+- For each result that the task tells you to verify, you MUST call record_check one time before done.
+- You MUST set `expected` to that result, in a few words.
+- You MUST set `text` to the shortest exact text on the page that shows the result, such as a heading, a value, or a label. Copy it as the page shows it.
+- You MUST set `dynamic` to true for live data that changes on a different run, such as the date, a price, or a count. The test then asserts the rule, not this value.
+- You MUST record only the results that the task tells you to verify.
+- When the task lists expected results, you MUST record one check for each, and copy `expected` from that line.
+- ForgeQE finds the element that shows `text`. You MUST select text that points to the subject of the line:
+  - For the items in a list, copy text from one item, such as the name of one result. Do not copy a summary line such as "2,463 properties found".
+  - For a page or a section that opens, copy its heading or a different label that names it.
 
-## When an expected result does not hold
-This is a test: an expected result that does not hold is a valid result, the test failing, not a mistake for you to work around. Do every step of the task first, each through the page's own controls as the step says.
-Settle each expected result with one read of the element it is about (the infobox row, the heading, the result card): when that element shows something else, record holds=false straight away. Do not try other spellings, number formats, or searches for the expected value. When the page does not show what an expected result says (another value, another text), record it once with record_check holds=false, text being exactly what the page shows instead, then go on with the remaining steps and expected results. Do not search the page again for the expected value, look for it elsewhere, or redo steps to make it hold. Finish with done success=false, starting with "Expected result not met:" and naming each one with what the page showed. Use success=false for the task itself only when a step could not be done.
+## When an expected result is not true
+This is a test. An expected result that is not true is a correct result: the test fails. It is not a mistake for you to go around.
+- You MUST first do all the steps of the task, each through the controls of the page.
+- You MUST read the element of each expected result one time, such as the infobox row, the heading, or the result card.
+- When that element shows a different thing, you MUST record holds=false immediately, with `text` set to what the page shows.
+- You MUST NOT try other spellings, number formats, or searches for the expected value. You MUST NOT do the steps again to make it true.
+- You MUST then continue with the other steps and expected results.
+- You MUST finish with done success=false. Start the message with "Expected result not met:". Name each result, and say what the page showed.
+- You MUST use success=false for the task only when a result is not true or you could not do a step.
 """.strip()
 
 # Visible text, plus the values of form fields, which visible text leaves out.

package/py/forgeqe_engine/prompts.py

@@ -9,6 +9,15 @@ from typing import Dict
 
 _OVERRIDES: Dict[str, str] = {}
 
+# How the browser agent's rules are stated (prompts/conventions.md): the RFC 2119 key words. It comes first in the
+# agent's added instructions and in the skill picker's prompt.
+CONVENTIONS = """
+## Conventions
+- The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this prompt are as in RFC 2119.
+- MUST and MUST NOT are absolute rules. SHOULD and SHOULD NOT are strong defaults: you MAY break one only for a reason that you state. MAY is a free choice.
+- A numbered step in a procedure is a MUST, unless the step says SHOULD or MAY.
+""".strip()
+
 
 def use_prompts(prompts: Dict[str, str]) -> None:
     """Set the prompts for this run (name -> text); a name not given keeps the engine's own."""

package/py/forgeqe_engine/report.py

@@ -46,14 +46,21 @@ class CaseReport(BaseModel):
     steps: List[CaseStepResult] = Field(description="One entry per numbered test step, in order")
 
 
-CASE_REPORT_INSTRUCTION = (
-    "## Test step report\n"
-    "This task is a test case with {n} numbered steps. When you finish (success or failure), report every step from 1 to {n}: "
-    "passed when it was done and its expected result holds, failed when it could not be done or its expected result does not hold, "
-    "not_run when you never reached it. For each step say what the page actually showed, and for a failed step its cause: app (a product "
-    "defect), test_case (the test case does not fit the application), environment (the app or something it needs was unavailable), or "
-    "automation (a control that is there could not be operated). Finish with success only if every step passed."
-)
+CASE_REPORT_INSTRUCTION = """
+## Test step report
+This task is a test case with {n} numbered steps.
+- When you finish, with success or failure, you MUST report each step from 1 to {n} with one of these verdicts:
+  - passed: you did the step, and its expected result is true.
+  - failed: you could not do the step, or its expected result is not true.
+  - not_run: you did not get to the step.
+- For each step, you MUST say what the page showed.
+- For a failed step, you MUST give one of these causes:
+  - app: the product has a defect.
+  - test_case: the test case does not agree with the application.
+  - environment: the app, or a service that it needs, was not available.
+  - automation: a control is on the page, but you could not operate it.
+- You MUST finish with success only if all steps passed.
+""".strip()
 
 
 def case_report_from_history(history: Any) -> Optional[Dict[str, Any]]:

package/py/forgeqe_engine/service.py

@@ -22,7 +22,7 @@ from . import brand
 from .diagnostics import Diagnostics, box_for
 from .logins import load_sessions, parse_logins, prompt_block, save_sessions, use_logins
 from .memory import READ_ONLY_ACTIONS, MemoryStore, compact_step, flow_step, page_id
-from .prompts import text as prompt_text, use_prompts
+from .prompts import CONVENTIONS, text as prompt_text, use_prompts
 from .report import CASE_REPORT_INSTRUCTION, CaseReport, build_timeline, case_report_from_history
 from .replay import ReplayOutcome, handoff_task, replay_flow
 from .settings import (
@@ -44,7 +44,8 @@ from .llm import (
     _agent_usage,
 )
 from .browser import (
-    local_browser_launch_kwargs,
+    browser_connection_label,
+    browser_launch_kwargs,
     settle_page,
     _shutdown_browser_instance,
     _stop_agent_instance,
@@ -95,6 +96,7 @@ class RunRequest:
     headed: Optional[bool] = None
     max_steps: Optional[int] = None
     allowed_hosts: List[str] = field(default_factory=list)
+    browser: Dict[str, Any] = field(default_factory=dict)
     session_id: Optional[str] = None
     extend_system_message: Optional[str] = None
     # {"dir": path, "replay": "verify" | "trust" | "off"}; no dir means no memory.
@@ -150,6 +152,7 @@ class RunRequest:
             headed=d.get("headed") if isinstance(d.get("headed"), bool) else None,
             max_steps=int(d["max_steps"]) if str(d.get("max_steps") or "").isdigit() else None,
             allowed_hosts=[str(h) for h in (d.get("allowed_hosts") or []) if str(h).strip()],
+            browser=dict(d["browser"]) if isinstance(d.get("browser"), dict) else {},
             session_id=(str(d["session_id"]) if d.get("session_id") else None),
             extend_system_message=(str(d["extend_system_message"]) if d.get("extend_system_message") else None),
             memory=dict(d.get("memory") or {}),
@@ -182,43 +185,59 @@ def _agent_initial_actions_construction_error(exc: BaseException) -> bool:
 
 # Appended to the library's Agent system prompt so the model does not blindly proceed past UI failures.
 _BROWSER_ERROR_RECOVERY_SYSTEM_MESSAGE = """
-## Error detection and recovery (required)
-After each meaningful action, and before you treat a sub-step as done or advance the scenario:
-
-1. **Read the live page** (including modals and corners) for failure signals: `alert()` dialogs, toast/snackbar errors, banner alerts, form validation (red borders, field-level error text), empty required fields, **HTTP error pages** (4xx/5xx), generic “Something went wrong” / “Error” / “Failed” copy, access denied, rate limits, or an unexpected **login / session expired** wall when you expected to be authenticated.
-
-2. **If any error or blocking state is visible**, do **not** continue the happy path. **Recover first**: note what failed, dismiss only when safe, fix invalid inputs, choose a different control, navigate back to a good state, or complete sign-in / MFA if required—then **re-attempt** the failed step with the corrected approach.
-
-3. **Proceed** to the next scenario action only when the UI consistently shows a non-error state for the current goal (success confirmation, expected next screen, etc.).
-
-4. If you cannot recover after **3–4** attempts on the **same** control (search box, autocomplete, outlet picker, dropdown), **stop immediately** and state clearly what blocked you so the user can fix data, environment, or credentials. Do **not** keep retrying the same search/select pattern indefinitely.
+## Error detection and recovery (necessary)
+You MUST do these steps after each important action, before you think that a sub-step is done, and before the next action.
+
+1. **Read the live page**, and include modals and corners. Look for these failure signals:
+   - `alert()` dialogs, toast or snackbar errors, and banner alerts.
+   - Form validation: red borders, error text at a field, or required fields that are empty.
+   - **HTTP error pages** (4xx or 5xx).
+   - General text such as “Something went wrong”, “Error”, or “Failed”.
+   - Access denied, or rate limits.
+   - A **login or session expired** page when you expected to be signed in.
+
+2. **If you see an error or a blocking state**, you MUST NOT continue on the usual path. **Recover first**:
+   - Make a note of what failed.
+   - Close a message only when this is safe.
+   - Correct the inputs that are not valid.
+   - Select a different control, or go back to a good state.
+   - Complete the sign-in or MFA if necessary.
+   - Then **do the failed step again** with the correction.
+
+3. **Go to the next action** only when the page shows no error for the current goal, such as a success message or the expected next screen.
+
+4. When you cannot recover after **3–4** tries on the **same** control, such as a search box, an autocomplete, or a dropdown, you MUST **stop immediately**. Say clearly what blocked you, so that the user can correct the data, the environment, or the credentials. You MUST NOT repeat the same search or selection again and again.
 """.strip()
 
 # A run that passes becomes a test, so "done" must mean the goal holds on the page, not an approximation of it.
 _GOAL_VERIFICATION_SYSTEM_MESSAGE = """
-## Finishing (required)
-Call done with success=true only when every part of the goal holds on the page right now:
-- Each field shows exactly what the goal asked for. Sites pre-fill fields (a default origin, dates, passengers) or keep earlier choices, and fields that take several values add yours to them: remove every value the goal did not ask for.
-- Every setting the goal names (sort order, filters, dates, options) is applied through the page's own controls and the page shows it (the sort control reads the chosen order, the summary or URL shows the dates). Scanning unsorted results by eye does not replace applying the sort or filter.
-- Whatever the goal asks you to find or check, you read from the page, and your final answer says what you saw.
-- Items the page already lists (result cards, rows, prices, scores) are read from that list in one step; open an item only when the goal needs something the list does not show.
-- A tab that looks blank right after it opened is still loading: wait for it once, and do not conclude it is empty.
-If a part is not met and you cannot make it so, call done with success=false and name that part.
+## Finishing (necessary)
+You MUST call done with success=true only when all parts of the goal are true on the page now:
+- Each field MUST show exactly what the goal tells you. Sites fill in some fields before you start, and keep earlier selections. You MUST remove each value that the goal does not ask for.
+- You MUST apply each setting that the goal names (sort order, filters, dates, options) through the controls of the page. The page MUST show the setting. To look through results that are not sorted is not the same as to apply the sort.
+- You MUST read from the page all that the goal tells you to find or check. Your final answer MUST say what you saw.
+- You SHOULD read the items that the page lists (result cards, rows, prices, scores) from that list in one step. Open an item only when the goal needs data that the list does not show.
+- A tab can look empty immediately after it opens because it is loading. You MUST wait for it one time before you think that it is empty.
+
+When a part is not true and you cannot make it true, you MUST call done with success=false, and name that part.
 """.strip()
 
 _BLUEPRINT_STEP_EFFICIENCY = """
 ## Efficiency (automation blueprint)
-Advance through the scenario with one clear action per step. If the page shows an error, toast, validation failure, or blocking modal, recover briefly and retry—do not re-audit the entire page after every click.
+- You SHOULD go through the scenario with one clear action in each step.
+- When the page shows an error, a toast, a validation failure, or a modal that blocks you, you MUST recover quickly. Then try again.
+- You SHOULD NOT examine the full page again after each click.
 """.strip()
 
 
 def _compose_agent_extend_system_message(extra: Optional[str], *, include_error_recovery: bool = True) -> Optional[str]:
     """Merge default recovery instructions with optional caller-provided system extension."""
+    conventions = prompt_text("conventions", CONVENTIONS)
     goal_check = prompt_text("browser-goal-verification", _GOAL_VERIFICATION_SYSTEM_MESSAGE)
     if _truthy_env("BROWSER_USE_SKIP_ERROR_RECOVERY_PROMPT"):
-        return "\n\n".join(p for p in (goal_check, (extra or "").strip()) if p)
+        return "\n\n".join(p for p in (conventions, goal_check, (extra or "").strip()) if p)
     recovery = prompt_text("browser-error-recovery", _BROWSER_ERROR_RECOVERY_SYSTEM_MESSAGE) if include_error_recovery else prompt_text("browser-efficiency", _BLUEPRINT_STEP_EFFICIENCY)
-    parts = [p for p in (recovery, goal_check, (extra or "").strip()) if p]
+    parts = [p for p in (conventions, recovery, goal_check, (extra or "").strip()) if p]
     if not parts:
         return None
     return "\n\n".join(parts)
@@ -754,7 +773,10 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
     use_prompts(req.prompts)
     diag = Diagnostics(accessibility=req.accessibility, network=req.network, axe=req.axe or None, vitals=req.vitals, visual=req.visual)
 
-    browser_kw = local_browser_launch_kwargs(headless=headless)
+    browser_cfg = req.browser if isinstance(req.browser, dict) else {}
+    browser_provider = str(browser_cfg.get("provider") or "local")
+    browser_remote = browser_cfg.get("remote") if isinstance(browser_cfg.get("remote"), dict) else {}
+    browser_kw = browser_launch_kwargs(provider=browser_provider, remote=browser_remote, headless=headless)
     if allowed_domains is not None:
         browser_kw["allowed_domains"] = allowed_domains
     logins = parse_logins(req.logins)
@@ -770,7 +792,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
         {
             "type": "log",
             "level": "info",
-            "text": f"ForgeQE engine · {browser_kw.get('channel')} · {'headless' if headless else 'visible'}"
+            "text": f"ForgeQE engine · {browser_connection_label(browser_provider, browser_kw, browser_remote)} · {'headless' if headless else 'visible'}"
             + (f" · opening {normalized_initial}" if normalized_initial else " · agent picks the site"),
         }
     )
@@ -929,7 +951,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                     "usage": {"input": 0, "output": 0},
                     "steps": replay.emitted,
                     "step_events": collected_steps,
-                    "browser": await browser_profile(browser, browser_kw),
+                    "browser": await browser_profile(browser, browser_kw, provider=browser_provider, remote=browser_remote),
                 }
                 _save(out, "memory_replay")
                 return out
@@ -1118,7 +1140,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                     emit({"type": "log", "level": "warn", "text": budget_state["message"]})
                     agent_ref.stop()
             if not launch_profile:
-                launch_profile.update(await browser_profile(browser, browser_kw))
+                launch_profile.update(await browser_profile(browser, browser_kw, provider=browser_provider, remote=browser_remote))
             await diag.sample(browser)
             with contextlib.suppress(Exception):
                 await _save_logins()
@@ -1273,7 +1295,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
             "usage": _usage_from_history(history),
             "steps": len(history.history or []) + replay_offset,
             "step_events": collected_steps,
-            "browser": dict(launch_profile) if launch_profile else await browser_profile(browser, browser_kw),
+            "browser": dict(launch_profile) if launch_profile else await browser_profile(browser, browser_kw, provider=browser_provider, remote=browser_remote),
         }
         if judge is not None:
             out["judge"] = judge