feat: browser run playwright sandbox

NOTICE

@@ -1 +1,5 @@
 webcmd is based on opencli (https://github.com/jackwener/opencli), Copyright 2025 jackwener, licensed under Apache-2.0.
+
+The browser-run QuickJS lifecycle is derived from dev-browser
+(https://github.com/SawyerHood/dev-browser), Copyright Sawyer Hood,
+licensed under the MIT License.

README.md

@@ -37,6 +37,20 @@ On top of live browser control, WebCMD adds 3 layers of learnings. Each layer co
 | 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable `webcmd <site>` adapter with structured output, so future agents spend tokens on the task instead of navigation. |
 | 4. Extend existing CLIs | The workflow is deterministic enough to stop browsing. | Extend the `webcmd <site>` adapter with a tailored command so the workflow runs instantly with the least amount of tokens. |
 
+For local, multi-step browser exploration, agents can send one sandboxed
+Playwright-style program to an existing CloakBrowser session:
+
+```bash
+webcmd browser work run --file explore.js
+printf 'const page = await browser.currentPage(); return await page.title();' \
+  | webcmd browser work run --stdin
+```
+
+`browser run` is additive: the existing `state`, `click`, `type`, `get`, and
+other primitive commands keep their current behavior. Reusable site adapters
+also keep using Webcmd's existing `IPage` contract; a browser-run program is
+reconnaissance or ad-hoc automation, not adapter source code.
+
 ## Demo
 
 https://github.com/user-attachments/assets/04eceadc-d398-4303-984d-ae3197bfa664

docs/cli-reference.mdx

@@ -55,6 +55,33 @@ webcmd web fetch-browser --url https://example.com/app-shell
 
 The old `web read` command has been renamed to `web fetch-browser`.
 
+## Local Browser Programs
+
+`browser run` executes one Playwright-style JavaScript program against an
+existing local CloakBrowser session:
+
+```bash
+webcmd browser work run --file explore.js
+webcmd browser work run --stdin --timeout 45 --observe diff
+```
+
+Exactly one of `--file <path>` or `--stdin` is required. The CLI reads files
+locally and sends source—not the path—to the local daemon. `--timeout` is in
+seconds, `--max-output` bounds returned results and logs, `--observe` accepts
+`diff`, `full`, or `none`, and `--tab <page-id>` targets an existing tab.
+
+The program runs in a fresh QuickJS sandbox. It can obtain the selected page
+with `await browser.currentPage()`, use the supported Page/Frame/Locator
+methods, and passively inspect request and response events. It cannot access
+Node.js, the filesystem, environment variables, raw CDP endpoints, browser
+launch/connect APIs, or browser-context ownership. Screenshot bytes are
+written to a Webcmd-owned cache directory and returned as a receipt.
+
+This command is currently local-only. Existing primitive browser commands are
+unchanged, and reusable adapters continue to use the existing `IPage` API.
+Playwright-style programs are for reconnaissance and ad-hoc multi-step work;
+they are not pasted into adapter modules.
+
 ## Top-Level Commands
 
 | Command | Purpose |
@@ -148,6 +175,7 @@ Register our internal `releasectl` binary as a Webcmd external CLI with a short
 | `~/.webcmd/` | User-level Webcmd state. |
 | `~/.webcmd/clis/` | Private adapters and local overrides. |
 | `~/.webcmd/cache/browser-network/` | Browser network capture cache. |
+| `~/.webcmd/cache/browser-run/` | Host-owned browser-run screenshot artifacts. |
 | `~/.webcmd/external-clis.yaml` | User external CLI registry. |
 | `skills/` | Bundled agent skills shipped with the package. |
 

package.json

@@ -21,6 +21,7 @@
     "./browser/ax-snapshot": "./dist/src/browser/ax-snapshot.js",
     "./browser/cdp": "./dist/src/browser/cdp.js",
     "./browser/page": "./dist/src/browser/page.js",
+    "./browser/run": "./dist/src/browser/run/index.js",
     "./browser/utils": "./dist/src/browser/utils.js",
     "./download": "./dist/src/download/index.js",
     "./download/article-download": "./dist/src/download/article-download.js",
@@ -97,6 +98,7 @@
     "js-yaml": "^4.3.0",
     "jsdom": "^29.0.2",
     "playwright-core": "1.61.1",
+    "quickjs-emscripten": "0.32.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^6.27.0",

skills/webcmd-adapter-author/SKILL.md

@@ -8,7 +8,10 @@ allowed-tools: Bash(webcmd:*), Read, Edit, Write, Grep
 
 You are an agent writing an adapter for a site. The goal of this skill is a 30-minute loop from zero context to a passing `webcmd browser verify`.
 
-Use the existing tools throughout: `webcmd browser *`, `webcmd doctor`, `webcmd browser init`, and `webcmd browser verify`. This skill does not introduce new commands.
+Use the existing tools throughout: `webcmd browser *`, including sandboxed
+`browser run` for reconnaissance, plus `webcmd doctor`, `webcmd browser init`,
+and `webcmd browser verify`. Browser-run programs are discovery evidence, not
+adapter source.
 
 Browser-profile auth commands must reuse `registerSiteAuthCommands`. Keep only site-specific `verify` and `openLogin` logic in the adapter. The login row must return `action_required` and `verify_command` (normally `webcmd <site> whoami`); after the user reports done, agents run that returned command and verification must succeed before retrying the original workflow. Credentials, MFA, and CAPTCHA always use human handoff: CAPTCHA stops automation until the user reports done and verification succeeds, and adapter code must not collect or type passwords or secrets.
 
@@ -148,6 +151,7 @@ Check these off step by step:
 [ ] 3. Recon (`site-recon.md`):
        [ ] **Preferred:** `webcmd browser analyze <url>` to get pattern, anti-bot signals, nearest adapter, and next step in one pass.
        [ ] If `analyze` is ambiguous, run manual checks: `open` -> `wait time 2` (or `wait xhr <regex>`) -> `network`.
+       [ ] Use `browser run` only when recon needs dependent Playwright-style steps, semantic locators, branching, or a request/response waiter armed before its trigger.
        [ ] Choose Pattern A / B / C / D / E.
 
 [ ] 4. API discovery (`api-discovery.md`) by Pattern:
@@ -182,6 +186,7 @@ Check these off step by step:
        [ ] `webcmd browser init <site>/<name>`, then set `strategy: Strategy.<strategy>` in the generated file
        [ ] Find the closest same-site or same-type adapter and copy it.
        [ ] Edit name, URL, and field mapping.
+       [ ] Use only the adapter-compatible path proven in Step 6A; never paste Playwright locators, `waitForResponse`, or browser-run globals into `func`.
 
 [ ] 10. Verification fixtures:
         [ ] After the first passing run, immediately use `--write-fixture` to seed `~/.webcmd/sites/<site>/verify/<cmd>.json`.
@@ -252,6 +257,7 @@ Check these off step by step:
 ## Key Conventions
 
 - Adapters import only `@agentrhq/webcmd/registry` and `@agentrhq/webcmd/errors`; do not add third-party dependencies.
+- Browser-run’s Playwright-style `page` and adapter `func(page,args)` are different contracts. Preserve evidence and behavior, not syntax. Implement adapters with the existing `IPage`, pipeline, Node-fetch, or interceptor APIs.
 - The `columns` array and `func` return object keys must match exactly, including order.
 - **Intermediate parsing object keys must not overlap any `columns` entry.** Otherwise silent-column-drop audits can misread the adapter. Use dedicated internal names and destructure with aliases when pushing rows.
 - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults.

skills/webcmd-adapter-author/references/adapter-template.md

@@ -2,6 +2,9 @@
 
 Use this after recon, endpoint verification, field decoding, output design, and strategy-note writing are complete.
 
+Playwright-style browser-run code is reconnaissance, not adapter source.
+Implement the observed behavior with the existing adapter APIs.
+
 ## Create The File
 
 For private iteration:

skills/webcmd-adapter-author/references/api-discovery.md

@@ -69,6 +69,27 @@ webcmd browser eval "await fetch('<url>', { credentials: 'include' }).then(r =>
 
 If Node-side replay works without page runtime state, prefer `PUBLIC_API` or `COOKIE_API`. If the endpoint only works in page context, document why before selecting `PAGE_FETCH`.
 
+For a request that exists only after a UI action, use `browser run` so the
+listener is attached before the trigger:
+
+```js
+const page = await browser.currentPage();
+const pending = page.waitForResponse(
+  response => response.url().includes('/api/target'),
+);
+await page.getByRole('button', { name: 'Load' }).click();
+const response = await pending;
+return {
+  url: response.url(),
+  method: response.request().method(),
+  status: response.status(),
+  body: await response.json(),
+};
+```
+
+This is recon evidence only. Choose the adapter strategy from the verified
+endpoint and UI evidence; do not copy the browser-run program into the adapter.
+
 ## Section 2 - State Extraction
 
 Use for Pattern B.

skills/webcmd-adapter-author/references/site-recon.md

@@ -48,6 +48,11 @@ Read `network` output this way:
 
 If data is loaded asynchronously, `wait time 2` may not be enough. Prefer `webcmd browser wait xhr '/api/path-fragment'` for a specific interface over blind `wait time 5`.
 
+When classification needs a dependent UI trigger plus a request/response
+waiter, use one sandboxed `browser run` program and arm the waiter before the
+trigger. Record the endpoint and UI evidence; do not copy the Playwright-style
+program into an adapter.
+
 ---
 
 ## Pattern A - SPA / JSON XHR