@volter-ai-dev/supercode-browser-playwright 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# Supercode browser provider over Playwright
+
+`@volter-ai-dev/supercode-browser-playwright` is a Supercode browser provider
+that is an unmodified `playwright-core` client. It connects to a CDP endpoint
+with `chromium.connectOverCDP`, drives the first page of the first context, and
+answers Supercode's existing wire unchanged: `supercode/browser-provider-v1`
+envelopes carrying `supercode/browser-operation-v1` calls.
+
+The package owns that wire: the operation vocabulary, input parsers, results
+and error codes (`./protocol`). Every locator, action and snapshot is
+playwright-core 1.63.0's own, with Playwright's actionability waits.
+
+## Operations
+
+All 21 operations:
+
+| Operation | Over Playwright |
+|---|---|
+| `browser.status` | `{available, features, syntheticEvents, implementation: "playwright-core 1.63.0", endpoint: browser.version()}` |
+| `browser.snapshot` | `ariaSnapshot({mode: "ai"})` of the page or the locator's first match, bounded to 64 000 characters |
+| `browser.query` | `count()` and up to 50 inspections |
+| `browser.wait` | `locator.waitFor`, clamped to 9 s |
+| `browser.click` `fill` `press` `hover` `focus` `check` `uncheck` | the locator action with a 5 s actionability budget; the result is the element's inspection |
+| `browser.select` | `selectOption`, returning the selected values |
+| `browser.scroll` | `scrollBy` in the page, returning `scrollX`/`scrollY` |
+| `browser.box` | `boundingBox()` |
+| `browser.mouse` `wheel` `drag` | `page.mouse` |
+| `browser.back` `forward` `reload` | `goBack`/`goForward`/`reload`, waiting for commit |
+| `browser.script` | the author's source as `async (page, args)` with the real `page`, clamped to 9 s |
+
+Locators map one to one onto `page.locator`, `getByRole`, `getByText`,
+`getByTestId`, `getByLabel`, `getByPlaceholder`, `getByAltText` and
+`getByTitle`. A `{by: "ref"}` locator is a `[ref=…]` mark from
+`browser.snapshot`'s AI-mode aria snapshot, resolved by Playwright's `aria-ref`
+selector engine. An inspection's `ref` is the element's own aria ref, or `""`
+when Playwright assigns it none (an element that is not visible or does not
+receive pointer events).
+
+The page revision is a mutation counter kept in the page by a
+`MutationObserver` installed with `page.addInitScript`; a navigation starts a
+new document and so a new count. Playwright timeouts are `TIMED_OUT`, a closed
+page or disconnected browser is `NOT_AVAILABLE`, a strict-mode violation or a
+locator matching nothing is `NOT_FOUND`, a protocol error that says
+"unavailable" or "not supported" is `UNSUPPORTED`, anything else `FAILED`.
+
+The harness abandons a provider call at 12 s, so a script's timeout (default
+30 s on the wire) is clamped to 9 s and the result says so in `notice`. A
+script that outlives its deadline keeps running in the provider process; the
+call still returns. Listeners a script attaches to `page` are removed when it
+ends. A PNG a script returns (`await page.screenshot()`) crosses the wire as
+an image record `{dataUrl, format, width, height, fidelity}`, bounded
+to 768 KiB of data URL.
+
+## Framings
+
+Both carry the same envelope, `{protocol, id, token, call}` in and
+`{protocol, id, result}` out, with a 256 KiB request and 1 MiB response bound.
+
+- **TCP** is the wire the harness speaks (`crates/harness/src/browser.rs`): one
+  newline-terminated JSON request per connection, one JSON response, then the
+  provider closes. The provider listens on `127.0.0.1` and writes an owner-only
+  discovery record (file `0600`, directory `0700`) to
+  `<providers dir>/browser/playwright.cdp.<port>.json`, scoped to the
+  canonical workspace, and removes it on stop.
+- **HTTP** serves `POST /` with the request JSON as the body and answers `200`
+  with the response JSON, for a host that can reach the provider only by HTTP.
+  Other paths are `404`, other methods `405`, a body that is not JSON `400`,
+  an oversized one `413`.
+
+Calls are answered one at a time. If the browser disconnected or the page
+closed, the provider reconnects once for the call and otherwise answers
+`NOT_AVAILABLE`.
+
+## CLI
+
+```sh
+supercode-browser-playwright --cdp-url http://127.0.0.1:9222 --tcp 0 --workspace .
+supercode-browser-playwright --cdp-url ws://127.0.0.1:9222/devtools/browser/… --http 8765 --token <hex>
+```
+
+```
+--cdp-url <url>        CDP endpoint (http:// resolved through /json/version, or ws://)
+--tcp <port>           the harness framing; 0 picks a free port
+  --providers-dir <dir>  parent of browser/ (default: $SUPERCODE_HOME/providers, then
+                         $XDG_CONFIG_HOME/supercode/providers, then ~/.config/supercode/providers)
+  --workspace <path>     workspace the discovery record is scoped to (default: cwd)
+--http <port>          the HTTP framing; --token is required, the host passes it
+--token <hex>          at least 32 hex characters (default: 32 random bytes)
+--synthetic-events     the endpoint dispatches isTrusted:false input (an AlmostCDP endpoint)
+```
+
+When listening it prints one JSON line, `{"listening":{"framing":"tcp","port":…}}`.
+
+## Fidelity
+
+`browser.status` and the discovery record report `playwright-core 1.63.0` and
+the endpoint's `browser.version()`. `syntheticEvents` comes from
+`--synthetic-events`: native Chrome dispatches trusted input for CDP `Input.*`
+commands, an AlmostCDP endpoint dispatches `isTrusted: false` DOM events, and
+the provider cannot tell the two apart itself. `browser.script` runs with
+the full Playwright `Page`, including `page.evaluate`: allowing it trusts the
+agent with the page and the provider process.
+
+## Library
+
+```ts
+import { createPlaywrightBrowserProvider, serveTcp } from '@volter-ai-dev/supercode-browser-playwright';
+
+const provider = createPlaywrightBrowserProvider({
+  cdpUrl: 'http://127.0.0.1:9222',
+  token: crypto.randomBytes(32).toString('hex'),
+  syntheticEvents: false,
+});
+const server = await serveTcp(provider, { port: 0, syntheticEvents: false });
+// provider.handle(request) answers one envelope without any framing.
+```
+
+## In a browser
+
+Two entry points use no Node API:
+
+- `@volter-ai-dev/supercode-browser-playwright/protocol`: the wire alone
+  (`parseBrowserOperationCall`, `parseBrowserOperationResult`, the protocol
+  names, `BrowserActionRefusal`), with no dependency, for a host that relays
+  calls.
+- `@volter-ai-dev/supercode-browser-playwright/executor`:
+  `PlaywrightOperationExecutor` over any Playwright `Page`. It imports
+  `playwright-core`; a browser host aliases that to a browser build of it,
+  `@volter/almostcdp/playwright`, and answers the operations against an
+  AlmostCDP surface with no Node process.
+
+A host's `actionGuard(action)` is asked before each locator action (`click`,
+`fill`, `press`, `hover`, `focus`, `check`, `uncheck`, `select`, `drag`) with
+the action's `Locator` and value; throwing a `BrowserActionRefusal` answers the
+call with its code, such as `APPROVAL_REQUIRED`. `browser.script` is not
+guarded: a script is trusted with the page.

package/bin/supercode-browser-playwright

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import("../dist/index.mjs").then(
+  (module) => module.main(process.argv.slice(2)),
+).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `supercode-browser-playwright --cdp-url <url>
+ *   (--tcp <port> [--providers-dir <dir>] [--workspace <path>] | --http <port>)
+ *   [--token <hex>] [--synthetic-events]`
+ */
+import { type ServeHandle } from "./serve.js";
+export declare function main(argv: readonly string[]): Promise<ServeHandle>;

package/dist/executor.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Supercode's `supercode/browser-operation-v1` calls over a real Playwright
+ * `Page`: every locator, action and snapshot is playwright-core's own, driven
+ * over CDP. No Node API is used, so the executor also runs in a browser realm
+ * with a browser build of playwright-core (`@volter/almostcdp/playwright`).
+ */
+import { type Locator, type Page } from "playwright-core";
+import { type BrowserOperationErrorCode, type BrowserOperationResult } from "./protocol.js";
+/** The implementation this provider reports; the pinned playwright-core. */
+export declare const PLAYWRIGHT_IMPLEMENTATION = "playwright-core 1.63.0";
+/** The harness abandons a provider call at 12 s; a script must end before that. */
+export declare const SCRIPT_TIMEOUT_CLAMP_MS = 9000;
+/** Actionability budget for one locator action. */
+export declare const ACTION_TIMEOUT_MS = 5000;
+/** `browser.wait` accepts 30 s on the wire; the harness deadline caps what can be honoured. */
+export declare const WAIT_TIMEOUT_CLAMP_MS = 9000;
+/** The Playwright features `browser.status` reports. */
+export declare const PLAYWRIGHT_FEATURES: readonly string[];
+export interface PlaywrightOperationExecutorOptions {
+    /** True when the endpoint dispatches `isTrusted:false` input (an AlmostCDP endpoint); false for native Chrome. */
+    syntheticEvents: boolean;
+    /** `browser.version()` of the connected endpoint, reported by `browser.status`. */
+    endpoint: string;
+    /**
+     * The host's policy for one locator action, asked before it runs; throwing
+     * a `BrowserActionRefusal` refuses it with that code. `browser.script` is
+     * not guarded: a script is trusted with the page.
+     */
+    actionGuard?: (action: PlaywrightAction) => void | Promise<void>;
+}
+/** One locator action an operation is about to perform. */
+export interface PlaywrightAction {
+    action: "click" | "fill" | "press" | "hover" | "focus" | "check" | "uncheck" | "select" | "drag";
+    locator: Locator;
+    value?: unknown;
+}
+/** Map a Playwright failure onto the wire's error codes. */
+export declare function classifyPlaywrightError(error: unknown): BrowserOperationErrorCode;
+export declare class PlaywrightOperationExecutor {
+    private readonly page;
+    private readonly options;
+    private readonly ready;
+    constructor(page: Page, options: PlaywrightOperationExecutorOptions);
+    execute(raw: unknown): Promise<BrowserOperationResult>;
+    private locator;
+    /**
+     * Playwright's `aria-ref` engine resolves against the last AI-mode snapshot
+     * the page took. Refs are stable per element, so refreshing the whole-page
+     * snapshot before resolving one keeps every ref from `browser.snapshot`
+     * addressable even after an element-scoped snapshot replaced the map.
+     */
+    private refreshRefs;
+    private refOf;
+    private inspectAll;
+    private inspect;
+    /** Run a locator action; a failure on a locator that matches nothing is NOT_FOUND. */
+    private act;
+    /** The host's policy for an action; an element that is not there is the action's own failure. */
+    private guard;
+    private revision;
+    private executeCall;
+    private script;
+    private target;
+    private success;
+    private failure;
+}