@capagents/forgeqe 2.2.2 → 2.2.3

package/docs/ARCHITECTURE.md

@@ -66,6 +66,8 @@ Copied from test-agent-nexus and trimmed to what a CLI run needs:
 
 **Finishing and the judge.** `_GOAL_VERIFICATION_SYSTEM_MESSAGE` is added to every agent's system prompt: `done` with success only when every field holds exactly what the goal asked for (pre-filled or extra values in multi-value fields removed), every setting the goal names is applied through the page's own controls and shown by the page, and findings are read from the page, items a list already shows are read from it in one step, and a tab that looks blank right after opening is still loading. The engine library's judge (`use_judge`) is off by default: `browser.judge: true` (passed to the engine as its judge setting) or `FORGEQE_ENGINE_USE_JUDGE=1` turns it on, and it then makes one model call over the steps and screenshots. It was turned off because it failed completed runs whose answer came from one screenshot (five result scores) instead of one step per item, and ForgeQE's agent then retried with ever stricter goals. When the agent says success and the judge's verdict is false, the run fails with the judge's `failure_reason` ahead of the agent's report; the verdict goes into `run.json` as `judge`. A judge call that errors leaves the agent's result as it was.
 
+**Window and video.** `window_launch_kwargs` sizes a local browser from `browser.viewport`: the page when headless, the window with `browser.window: viewport`. Otherwise a visible window opens screen-sized (the engine library's default) and, before the first page, `maximize_window` sets `windowState: maximized` over CDP. With `browser.video` on (the default), the browser is started before the replay or the agent, and `start_video` starts the library's recording watchdog on `<run>/video.mp4`; `stop_video` finishes it before the browser closes, and `run_with_events` adds it to the run's files. The watchdog encodes Chrome's screencast frames at 30 fps as they arrive, so the video's timing follows how often the page repaints, not the clock. The encoder (`browser-use[video]`: imageio with ffmpeg, numpy) is installed with the engine, and added to an engine set up before it. The report lists `video.mp4` among the run's files and plays it on the Artifacts tab.
+
 **Browser profile.** At the end of the first step (or before writing a trust-mode replay), `browser_profile` reads how the browser was set up: the engine's driver, channel and executable, headless, the default switches removed, extra HTTP headers (none), `Browser.getVersion`, and from the page `navigator.userAgent`, `navigator.webdriver`, language, time zone, and viewport. It goes into `run.json` as `browser`, and the handoff shows it so the coding agent can compare its test's browser with it.
 
 **Timeline.** `build_timeline` writes `steps.json` from the history (and the replayed steps): URL, title, the model's evaluation, memory and next goal, each action with its error, start time (`t0`) and duration, the part of it spent waiting for the model (`model_ms`, from wrapping `llm.ainvoke` and overlapping the calls with the step's `step_start_time`/`step_end_time`), and a JPEG of the page (max 1280 wide) under `steps/`, subject to `report.screenshots`. Each action on an element carries `box`: the element's `absolute_position` from the DOM snapshot the model saw, minus the page's scroll, as fractions of the viewport, so the report can outline it on that step's screenshot. Timeouts, stops, and crashes still write it from the partial history.
@@ -401,10 +403,12 @@ Before the model is called, `replay_known` asks `AppMemory.plan` for the goal's
   It checks mounts as uploads are checked (inside the project; nothing hidden, key-named or linked). It waits for a TCP or HTTP ready check. Docker's port proxy accepts connections before the service listens, so a TCP connection counts only when it stays open. It scrubs secrets from logs and errors, and tracks the containers it started, which the CLI removes on exit.
 - **`mock.ts`** makes WireMock stubs from `network.json` or a contract set.
 - **`compose.ts`** translates docker-compose services into forgeqe.yaml services, refusing settings that widen what a container reaches. `startOrder` (`config.ts`) orders services by `depends_on`. Every container joins the project network `forgeqe-<key>` under its service name.
-- **`tests.ts`** is a `runTestCommand` for `run_tests` with `containers.tests`. It runs the confirmed command with `sh -c` in the image, with the repository mounted at its own path, `--user` this machine's user, and only the environment's FORGEQE_* variables, the saved-login variables, and the listed env and secrets, by name.
+- **`tests.ts`** is a `runTestCommand` for `run_tests` with `containers.tests`. It runs the confirmed command with `sh -c` in the image, with the repository mounted at its own path, `--user` this machine's user, and only the environment's FORGEQE_* variables, the saved-login variables, and the listed env and secrets, by name. The repository's credential files are covered (`masks.ts`), and `docker top` finds the browsers the test launched.
+- **`workspace.ts`** is `containers.workspace`. `loadConfig` registers it for the repository (`active.ts`). Nothing starts until `openSession` or `runTestCommand` asks for it. Then one container per process and project waits (`sleep infinity`) with the repository, the home volume `forgeqe-<key>-home` and the project network. `openSession` sets the agent runtime's `SHELL` to a script that runs `exec --workdir "$PWD" … sh -c "$2"` in it, refuses a folder outside the repository, and adds `workspaceNote` to the agents' instructions. ForgeQE's own agent passes `hostShell`. `runTestCommand` sends a run in a covered folder to the workspace's runner (`tests.ts`, same image and home volume) unless `host` or `FORGEQE_HOST_RUN=1`.
+- **`browser.ts`** is `browser.provider: docker`. `startDockerBrowser` runs Microsoft's Playwright image with `BROWSER_SERVER` (Node.js, no packages) mounted read-only. It starts Chromium on 127.0.0.1:9222 inside, headless or on Xvfb, and a gateway on 9223 that pipes a connection only when the path starts with the random token (constant-time compare) and any `Origin` is local. The token goes to the runtime by name. ForgeQE waits for `/<token>/json/version` and returns `ws://127.0.0.1:<port>/<token>/devtools/browser/<id>`. `run.ts` starts one per browser run and gives the engine `FORGEQE_BROWSER_CDP_URL` (`docker_browser_launch_kwargs`). The coding loop starts one per job when the provider is docker or `run.json` says the run used one: the replay connects with `connectOverCDP` (`FORGEQE_REPLAY_CDP`, one pass), and the live browser's MCP server reads `PLAYWRIGHT_MCP_CDP_ENDPOINT` from `{env:FORGEQE_LIVE_CDP_URL}`.
 - **The agent's tools** are `services` and `mock_service` in `src/mcp/containertools.ts`, and the CLI is `forgeqe services` (`command.ts`).
 - **The agents' shell:** `BASH_PERMISSION` denies docker, podman, nerdctl and compose commands for the agent and Scribe.
-- **Tests:** `tests/containers.test.ts` uses a fake runtime. `tests/containers.live.test.ts` uses real Docker and is skipped without it.
+- **Tests:** `tests/containers.test.ts` and `tests/workspace.test.ts` use a fake runtime; `workspace.test.ts` also runs the gateway against a stand-in browser and the agent runtime against the workspace's script. `tests/containers.live.test.ts` uses real Docker and is skipped without it.
 
 ## Databases, test data and data flows (`src/data`, `py/forgeqe_data`)
 

package/docs/CONTAINERS.md

@@ -10,7 +10,7 @@ real Docker (and is skipped without it):
 
 `.github/workflows/forgeqe-containers.yml` runs both on GitHub's Docker. There, a skipped live test fails the job.
 
-ForgeQE uses Docker or Podman, when one is installed, for three jobs:
+ForgeQE uses Docker or Podman, when one is installed, for five jobs:
 
 - **Services a test run needs:** a database, a queue, a cache, or the API under test. The project declares them in
   forgeqe.yaml, or in a docker-compose file that forgeqe.yaml names.
@@ -18,6 +18,10 @@ ForgeQE uses Docker or Podman, when one is installed, for three jobs:
   the tests can run without the real service.
 - **The repository's tests in a container:** `run_tests` runs the command the user confirmed in an image, instead of
   on this machine, after starting the services the tests need.
+- **A workspace for the coding agents:** with `containers.workspace`, Scribe's shell commands (build, restore, run,
+  git) and every test ForgeQE runs for it go to a container of the project's image. The agents stay on this machine.
+- **A browser in a container:** with `browser.provider: docker`, the browser agent, the replay and Scribe's live
+  browser drive Chromium in a container of Microsoft's Playwright image.
 
 Scribe also has a `testcontainers` skill, for tests that start their own services from code (below).
 
@@ -146,6 +150,71 @@ Its confirmation says where the tests will run. The container:
 
 This needs a Linux or macOS machine, because the repository is mounted at its own path.
 
+## The workspace
+
+```yaml
+containers:
+  workspace:
+    image: mcr.microsoft.com/playwright/dotnet:v1.63.0-noble   # an exact version; the project's toolchain
+    services: [db]                       # started first; reached by name
+    env: { NEXUS_ENVIRONMENT: CI, DOTNET_ROLL_FORWARD: Major }
+    secrets: [TEST_DB_PASSWORD]          # by name; values from the environment or .env
+```
+
+With `containers.workspace` set:
+
+- **Scribe's shell runs in the container.** The agent runtime runs each command as `$SHELL -c <command>`. ForgeQE
+  sets `SHELL` to a script that runs the same command with `docker exec … sh -c <command>`, in the same folder,
+  in the workspace container. A folder outside the repository is refused, since the container has only the
+  repository. The agent is told its commands run in a Linux container of that image.
+- **Every test ForgeQE runs goes to the same image:** the coding loop's runs, `heal`, `suite`'s existing tests and
+  `run_tests`. Each run gets its own container (`docker run --rm`), so stopping a run removes it. Browsers the test
+  starts are found with `docker top`, as ForgeQE finds them on this machine.
+- **What stays on this machine:** the agent runtime, the model key, ForgeQE's other secrets, the file tools (read,
+  edit, write; the repository is the same folder in both places), and ForgeQE's own agent, which works with you
+  on this machine and keeps its shell here. `FORGEQE_HOST_RUN=1` runs everything on this machine for a session.
+- **The container:**
+  - one per ForgeQE process and project, `forgeqe-<project>-workspace-<id>`, removed when ForgeQE ends;
+  - the repository mounted read-write at its own path; credential files in it (`.env`, `.env.*` except templates,
+    `.npmrc`, `.netrc`, `*.pem`, `*.key`, `id_*` keys) covered with an empty read-only file, and `.ssh`, `.aws`,
+    `.azure`, `.docker`, `.kube` and `.forgeqe/sessions` with an empty folder;
+  - `HOME` on the project's volume `forgeqe-<project>-home`, so NuGet, npm and pip caches outlive the session. Docker
+    creates the volume for root, so ForgeQE runs `chown` in it once, with a fixed command;
+  - this machine's user (`--user uid:gid`), `no-new-privileges`, `--pids-limit 4096`, the project network;
+  - only `CI=1`, `HOME`, the `env` and `secrets` listed, and, in each command, the environment's `FORGEQE_APP_*` and
+    `FORGEQE_VAR_*` and the saved logins' variables, by name.
+- **`containers.tests`** still names the image `run_tests` uses when it is set. Without it, `run_tests` uses the
+  workspace's image.
+
+This needs a Linux or macOS machine, as tests in a container do.
+
+## The browser in a container
+
+```yaml
+browser:
+  provider: docker        # or per run: --browser-provider docker
+containers:
+  browser:                # optional
+    image: mcr.microsoft.com/playwright:v1.63.0-noble   # default; needs Node.js and /ms-playwright
+    headless: false       # default: browser.headless; a visible browser runs on a virtual display (Xvfb)
+```
+
+- **One container per use:** each browser run (a suite runs `suite.parallel` at once) gets its own, and a coding job
+  gets one that its replay and live browser share. Each is removed when its run or job ends.
+- **Connection:** Chromium listens on 127.0.0.1 inside the container. CDP has no authentication of its own, so a small
+  gateway in front of it (`BROWSER_SERVER` in `src/containers/browser.ts`, run with the image's Node.js) accepts a
+  connection only with a random 48-character token in its path, compared in constant time, and refuses a browser
+  `Origin` that is not local. The port is published on 127.0.0.1 only. The token reaches the engine, the replay and
+  the live browser's MCP server through the environment, never a file or a command line.
+- **Visible or headless:** a visible browser runs on Xvfb inside the container. Sites that turn headless browsers
+  away see an ordinary one, but you do not see it on your screen. Runs keep screenshots and traces as usual.
+- **Reaching the app:** the container joins the project network, so a declared service is reached by its name
+  (`http://order-api:8080`). An app this machine serves is `http://host.docker.internal:<port>`; `localhost` is the
+  container itself, and ForgeQE warns when a run starts there.
+- **Replay:** one pass, in a new browser context. The second pass (without Playwright's automation switches) needs a
+  launch, which a running browser does not have.
+- A run explored in a container is replayed in one even when the provider is changed back later (`run.json`).
+
 ## Testcontainers (Scribe)
 
 When a test needs a real service, or the repository already uses Testcontainers (Java, .NET, Node, Python, Go), Scribe
@@ -182,7 +251,8 @@ changed.
 
 ## Lifetime
 
-- **Services and mocks the agent starts** are removed when the shell, `forgeqe run`, or `forgeqe mcp` ends.
+- **Services and mocks the agent starts** are removed when the shell, `forgeqe run`, or `forgeqe mcp` ends, as are
+  the workspace and browser containers (`forgeqe.kind` `workspace` and `browser`). The home volume stays.
 - **`forgeqe services up`** keeps its services running after the command ends, until `forgeqe services down`.
 - **Container names** are `forgeqe-<project>-<service>`. `<project>` is a hash of the project folder, so two projects
   never share a container. Starting a service replaces its earlier container. Removing a container also removes the anonymous volumes its image declares (a database's data folder), so nothing is left on the machine. A container is never reused with old
@@ -219,9 +289,15 @@ text could mount the whole disk or run privileged, so:
 | `src/containers/run.ts` | The runtime (docker or podman), `run` arguments, mount and secret checks, start and wait, status, logs, stop, the session's containers |
 | `src/containers/mock.ts` | WireMock stubs from run traffic and from contract sets; values from JSON schemas |
 | `src/containers/compose.ts` | docker-compose files as services: what is translated, ignored, left out or refused |
-| `src/containers/tests.ts` | `run_tests` in a container: arguments, environment, mounts, output |
+| `src/containers/tests.ts` | `run_tests` in a container: arguments, environment, mounts, output, browsers from `docker top` |
+| `src/containers/workspace.ts` | `containers.workspace`: the container, its home volume, the agent's shell script, its test runner |
+| `src/containers/active.ts` | The registered workspaces, by repository: `runTestCommand` and `openSession` look them up |
+| `src/containers/masks.ts` | The repository's credential files and folders, covered in every container that mounts it |
+| `src/containers/browser.ts` | `browser.provider: docker`: the browser container, its token gateway, the endpoint |
 | `src/containers/command.ts` | `forgeqe services` |
 | `skills/testcontainers/SKILL.md` | Scribe's Testcontainers skill |
 | `src/mcp/containertools.ts` | The agent's `services` and `mock_service` |
 
-Tests: `bun test tests/containers.test.ts`, which uses a fake runtime that records each command. `tests/containers.live.test.ts` uses real Docker.
+Tests: `bun test tests/containers.test.ts tests/workspace.test.ts`, which use a fake runtime that records each command
+(`workspace.test.ts` also runs the gateway against a stand-in browser, and the agent runtime against the workspace's
+script). `tests/containers.live.test.ts` uses real Docker.