@ai-agent-forge/agent-forge 0.88.4 → 0.88.6

package/bundled-plugins/browser-playwright/dist/playwright-driver.js

@@ -0,0 +1,953 @@
+/**
+ * Playwright-backed driver for the browser capability.
+ *
+ * Playwright is resolved lazily at connect time through
+ * `createRequire(<browser-deps>/package.json)` — the deliberate optional-heavy
+ * dependency load point; this package never imports Playwright types, so the
+ * surface used here is declared structurally below. A missing module throws
+ * the structured guidance message (exact install commands plus the
+ * `browser_setup` hint), which the capability layer surfaces verbatim.
+ *
+ * Bounded results: aria snapshots are capped at 16KiB, DOM captures and all
+ * JSON payloads (console/network entries, performance metrics, evaluate
+ * results, storage/tab/viewport state) at 64KiB, screenshots at 4MiB of PNG
+ * bytes. Styles capture is declared `not_supported_in_this_build` (parameter
+ * stays accepted for contract compatibility). Console and network evidence
+ * come from 200-entry ring buffers attached to every opened page.
+ *
+ * Built-in policies (no dedicated tools): `dialog` events are auto-accepted
+ * and logged into the console ring as a `[dialog]` entry; `download` events
+ * are saved into `<agentDir>/browser-deps/downloads/` and the most recent
+ * download filename is attached to snapshot results.
+ */
+import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { buildPluginResultV1, } from "@agent-forge/plugin-sdk";
+import { BROWSER_DEFAULT_EVALUATE_TIMEOUT_MS_V1, clampDragStepsV1, clampViewportDimensionV1, clampWaitMsV1, filterConsoleEntriesV1, filterNetworkEntriesV1, parseScrollDirectiveV1, parseUploadPathsV1, scrollWheelDeltaV1, serializeJsonPayloadV1, shapePerformanceV1, waitMissingInput, } from "./operations.js";
+import { BROWSER_BROWSERS_DIR_NAME_V1, boundedPreviewV1, browserDepsDirFor, installGuidanceMessage, resolvePlaywrightModule, setupBrowserDepsPlaywrightV1, } from "./setup.js";
+export const BROWSER_MAX_SNAPSHOT_CHARS_V1 = 16 * 1024;
+export const BROWSER_MAX_DOM_CHARS_V1 = 64 * 1024;
+export const BROWSER_MAX_EVIDENCE_CHARS_V1 = 64 * 1024;
+export const BROWSER_MAX_SCREENSHOT_BYTES_V1 = 4 * 1024 * 1024;
+export const BROWSER_RING_BUFFER_SIZE_V1 = 200;
+export const BROWSER_DOWNLOADS_DIR_NAME_V1 = "downloads";
+const BROWSER_CONDITION_LABEL_CHARS_V1 = 256;
+const placeholder = (text) => (text.trim() === "" ? "(empty)" : text);
+const sanitizeUrlV1 = (value) => {
+    try {
+        const parsed = new URL(value);
+        return `${parsed.origin}${parsed.pathname.slice(0, 512)}`;
+    }
+    catch {
+        return value.slice(0, 512);
+    }
+};
+const conditionLabel = (condition, index) => {
+    const raw = condition.kind === "url"
+        ? `url ${condition.equals !== undefined ? `equals ${JSON.stringify(condition.equals)}` : ""}${condition.contains !== undefined ? ` contains ${JSON.stringify(condition.contains)}` : ""}`
+        : condition.kind === "element"
+            ? `element ${condition.locator.kind}=${JSON.stringify(condition.locator.value)} state ${condition.state}`
+            : condition.kind === "text"
+                ? `text contains ${JSON.stringify(condition.contains)}`
+                : condition.kind === "console"
+                    ? `console contains ${JSON.stringify(condition.contains)}`
+                    : `network containsUrl ${JSON.stringify(condition.containsUrl)}`;
+    return `${index + 1}: ${raw.trim()}`.slice(0, BROWSER_CONDITION_LABEL_CHARS_V1);
+};
+const locatorLabel = (locator) => `${locator.kind}=${locator.value.slice(0, 64)}${locator.name === undefined ? "" : ` name=${locator.name.slice(0, 64)}`}`;
+/**
+ * In-page performance collection evaluated through `page.evaluate`. Must stay a
+ * closure-free function object: real Playwright stringifies it and runs it in
+ * the page. Passing an equivalent `() => {...}` *string* is silently wrong —
+ * real Playwright evaluates the string, serializes the resulting function
+ * object, and yields `undefined` on the Node side.
+ */
+const collectPerformanceInPage = () => {
+    const entries = (type) => performance.getEntriesByType(type);
+    const nav = entries("navigation")[0] ?? null;
+    const paints = entries("paint").map((entry) => ({ name: String(entry.name), startTimeMs: entry.startTime }));
+    const resources = entries("resource").map((entry) => ({
+        url: String(entry.name),
+        durationMs: entry.duration,
+        transferBytes: entry.transferSize,
+    }));
+    return {
+        navigation: nav === null
+            ? null
+            : {
+                ttfbMs: nav.responseStart - nav.startTime,
+                domContentLoadedMs: nav.domContentLoadedEventEnd - nav.startTime,
+                loadMs: nav.loadEventEnd - nav.startTime,
+            },
+        paints,
+        resources,
+        domNodes: document.getElementsByTagName("*").length,
+    };
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * `page.evaluate` with a wall-clock escape: Playwright itself cannot cancel a
+ * hung script, so the race rejects after `timeoutMs` and leaves the page-side
+ * evaluation to finish on its own.
+ */
+async function evaluateWithTimeout(page, expression, arg, timeoutMs) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`browser_evaluate timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([page.evaluate(expression, arg), timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+const isTimeoutError = (error) => error instanceof Error && error.name === "TimeoutError";
+export class PlaywrightBrowserDriver {
+    depsDir;
+    headless;
+    resolveModule;
+    loadPlaywright;
+    ensureDir;
+    browser;
+    context;
+    page;
+    pages = [];
+    pageIndex = 0;
+    consoleRing = [];
+    networkRing = [];
+    lastDownload;
+    constructor(options = {}) {
+        this.depsDir =
+            options.browserDepsDir ?? (options.agentDir === undefined ? "" : browserDepsDirFor(options.agentDir));
+        this.headless = options.headless ?? true;
+        this.resolveModule = options.resolvePlaywright ?? resolvePlaywrightModule;
+        this.loadPlaywright = options.loadPlaywright;
+        this.ensureDir = options.ensureDir ?? ((dir) => mkdirSync(dir, { recursive: true }));
+    }
+    /** Resolves Playwright, launches Chromium, and opens the context. Idempotent. */
+    async connect() {
+        if (this.browser !== undefined)
+            return;
+        const playwright = this.loadModule();
+        // Point the Playwright registry at the same isolated directory the setup
+        // flow installs browsers into; never override an explicit user setting.
+        // Without this, `browser_setup` binaries land in <deps>/browsers while
+        // launch silently looks in the shared OS cache and fails on a fresh host.
+        if (this.depsDir !== "") {
+            process.env.PLAYWRIGHT_BROWSERS_PATH ??= join(this.depsDir, BROWSER_BROWSERS_DIR_NAME_V1);
+        }
+        let browser;
+        try {
+            browser = await playwright.chromium.launch({ headless: this.headless });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "";
+            // The module resolves but the browser binaries were never installed.
+            if (/Executable doesn't exist|playwright install/i.test(message)) {
+                throw new Error(installGuidanceMessage(this.depsDir), {
+                    cause: error instanceof Error ? error : undefined,
+                });
+            }
+            throw error;
+        }
+        this.browser = browser;
+        this.context = await browser.newContext();
+    }
+    /** Idempotent best-effort teardown; never throws. */
+    close() {
+        const browser = this.browser;
+        this.browser = undefined;
+        this.context = undefined;
+        this.page = undefined;
+        this.pages = [];
+        this.pageIndex = 0;
+        this.consoleRing = [];
+        this.networkRing = [];
+        this.lastDownload = undefined;
+        if (browser === undefined)
+            return;
+        void browser.close().catch(() => undefined);
+    }
+    async navigate(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        await this.connect();
+        const page = this.page ?? (await this.openPage());
+        await page.goto(input.url, { waitUntil: input.waitUntil ?? "load" });
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "succeeded",
+            summary: `Navigated to ${sanitizeUrlV1(page.url())}`,
+            artifacts: [],
+            evidence: [],
+        });
+    }
+    async snapshot(input = {}, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const evidence = evidenceBuilder(operationId);
+        const parts = [];
+        if (input.includeStyles === true)
+            parts.push("styles: not_supported_in_this_build");
+        if (input.includeA11y !== false) {
+            evidence.add("structure", placeholder(boundedPreviewV1(await page.locator("body").ariaSnapshot(), BROWSER_MAX_SNAPSHOT_CHARS_V1)));
+            parts.push("a11y");
+        }
+        if (input.includeDom === true) {
+            evidence.add("dom", placeholder(boundedPreviewV1(await page.content(), BROWSER_MAX_DOM_CHARS_V1)));
+            parts.push("dom");
+        }
+        if (input.includeScreenshot === true) {
+            const png = await page.screenshot({ type: "png" });
+            if (png.byteLength > BROWSER_MAX_SCREENSHOT_BYTES_V1) {
+                return failed(operationId, "screenshot_too_large", "Screenshot exceeds the 4MiB evidence budget");
+            }
+            evidence.add("screenshot", `data:image/png;base64,${png.toString("base64")}`);
+            parts.push("screenshot");
+        }
+        if (this.lastDownload !== undefined) {
+            const filename = this.lastDownload.slice(0, 256);
+            evidence.add("log", `download: ${filename}`);
+            parts.push(`download: ${filename}`);
+        }
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "succeeded",
+            summary: `Captured browser snapshot (${parts.length === 0 ? "none" : parts.join(", ")})`,
+            artifacts: [],
+            evidence: evidence.refs,
+        });
+    }
+    async locatorAction(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const missing = actionMissingInput(input);
+        if (missing !== undefined) {
+            return failed(operationId, "browser_action_invalid", `The ${input.action} action requires ${missing}`);
+        }
+        const locator = resolveLocator(page, input.locator);
+        switch (input.action) {
+            case "click":
+                await locator.click();
+                break;
+            case "dblclick":
+                await locator.dblclick();
+                break;
+            case "rightclick":
+                await locator.click({ button: "right" });
+                break;
+            case "fill":
+                await locator.fill(input.value ?? "");
+                break;
+            case "type":
+                await locator.type(input.value ?? "", input.delay === undefined ? {} : { delay: input.delay });
+                break;
+            case "press":
+                await locator.press(input.key ?? "");
+                break;
+            case "hover":
+                await locator.hover();
+                break;
+            case "select":
+                await locator.selectOption(input.value ?? "");
+                break;
+            case "check":
+                await locator.check();
+                break;
+            case "uncheck":
+                await locator.uncheck();
+                break;
+            case "clear":
+                await locator.clear();
+                break;
+            case "upload": {
+                let paths;
+                try {
+                    paths = parseUploadPathsV1(input.value ?? "");
+                }
+                catch (error) {
+                    return failed(operationId, "browser_action_invalid", error instanceof Error ? error.message : "Invalid upload value");
+                }
+                await locator.setInputFiles([...paths]);
+                break;
+            }
+            case "scroll": {
+                let directive;
+                try {
+                    directive = parseScrollDirectiveV1(input.value ?? "");
+                }
+                catch (error) {
+                    return failed(operationId, "browser_action_invalid", error instanceof Error ? error.message : "Invalid scroll value");
+                }
+                await locator.scrollIntoViewIfNeeded();
+                // Wheel scrolls whatever scrollable container is under the cursor,
+                // so park the cursor over the target element first; otherwise the
+                // delta lands on whatever the mouse happened to hover before.
+                const scrollBox = await locator.boundingBox();
+                if (scrollBox !== null) {
+                    await page.mouse.move(scrollBox.x + scrollBox.width / 2, scrollBox.y + scrollBox.height / 2);
+                }
+                const delta = scrollWheelDeltaV1(directive);
+                await page.mouse.wheel(delta.deltaX, delta.deltaY);
+                break;
+            }
+        }
+        const evidence = evidenceBuilder(operationId);
+        evidence.add("structure", placeholder(boundedPreviewV1(await page.locator("body").ariaSnapshot(), BROWSER_MAX_SNAPSHOT_CHARS_V1)));
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "succeeded",
+            summary: `Performed ${input.action}`,
+            artifacts: [],
+            evidence: evidence.refs,
+        });
+    }
+    async assertPostcondition(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const conditions = Array.isArray(input) ? input : [input];
+        const checks = [];
+        const failedChecks = [];
+        for (const [index, condition] of conditions.entries()) {
+            const label = conditionLabel(condition, index);
+            const passed = await this.checkCondition(page, condition);
+            checks.push(`${label}:${passed ? "passed" : "failed"}`);
+            if (!passed)
+                failedChecks.push(label);
+        }
+        if (failedChecks.length === 0) {
+            return buildPluginResultV1({
+                version: 1,
+                operationId,
+                status: "succeeded",
+                summary: `All ${checks.length} postcondition(s) passed`,
+                artifacts: [],
+                evidence: [],
+                verification: { version: 1, status: "passed", checks },
+            });
+        }
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "failed",
+            summary: "One or more postconditions failed",
+            artifacts: [],
+            evidence: [],
+            verification: { version: 1, status: "failed", checks },
+            error: {
+                version: 1,
+                code: "postcondition_failed",
+                message: boundedPreviewV1(`Failed postconditions: ${failedChecks.join("; ")}`, 2048),
+            },
+        });
+    }
+    async collectEvidence(kind, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const evidence = evidenceBuilder(operationId);
+        if (kind === "console") {
+            const text = this.consoleRing.map((entry) => `[${entry.type}] ${entry.text}`).join("\n");
+            evidence.add("log", placeholder(boundedPreviewV1(text, BROWSER_MAX_EVIDENCE_CHARS_V1)));
+        }
+        else if (kind === "network") {
+            const text = this.networkRing.map((entry) => `${entry.status} ${entry.url}`).join("\n");
+            evidence.add("network", placeholder(boundedPreviewV1(text, BROWSER_MAX_EVIDENCE_CHARS_V1)));
+        }
+        else {
+            evidence.add("structure", placeholder(boundedPreviewV1(await page.locator("body").ariaSnapshot(), BROWSER_MAX_SNAPSHOT_CHARS_V1)));
+        }
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "succeeded",
+            summary: `Collected ${kind} evidence`,
+            artifacts: [],
+            evidence: evidence.refs,
+        });
+    }
+    async evaluate(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const started = Date.now();
+        const value = await evaluateWithTimeout(page, input.expression, input.arg, BROWSER_DEFAULT_EVALUATE_TIMEOUT_MS_V1);
+        const evidence = evidenceBuilder(operationId);
+        evidence.add("log", placeholder(boundedPreviewV1(serializeJsonPayloadV1(value), BROWSER_MAX_EVIDENCE_CHARS_V1)));
+        return buildPluginResultV1({
+            version: 1,
+            operationId,
+            status: "succeeded",
+            summary: `Evaluated expression in ${Date.now() - started}ms`,
+            artifacts: [],
+            evidence: evidence.refs,
+        });
+    }
+    async consoleEntries(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        let result;
+        try {
+            result = filterConsoleEntriesV1(this.consoleRing, input);
+        }
+        catch (error) {
+            return failed(operationId, "browser_console_invalid", error instanceof Error ? error.message : "Invalid console filter");
+        }
+        return payloadResult(operationId, `Read console: ${result.total} entry(ies), ${result.returned.length} returned`, "log", result);
+    }
+    async networkEntries(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const result = filterNetworkEntriesV1(this.networkRing, input);
+        return payloadResult(operationId, `Read network: ${result.total} entry(ies), ${result.returned.length} returned`, "network", result);
+    }
+    async performance(options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const raw = await page.evaluate(collectPerformanceInPage);
+        const payload = shapePerformanceV1(raw);
+        return payloadResult(operationId, `Collected performance metrics (${payload.resources.count} resource(s), ${payload.domNodes} DOM nodes)`, "trace", payload);
+    }
+    async wait(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const missing = waitMissingInput(input);
+        if (missing !== undefined) {
+            return failed(operationId, "browser_wait_invalid", `The ${input.until} wait requires ${missing}`);
+        }
+        const effectiveMs = clampWaitMsV1(input.ms);
+        const started = Date.now();
+        let label;
+        try {
+            switch (input.until) {
+                case "selector": {
+                    const locator = resolveLocator(page, input.locator);
+                    await locator.waitFor({ state: "visible", timeout: effectiveMs });
+                    label = `selector ${locatorLabel(input.locator)}`;
+                    break;
+                }
+                case "navigation":
+                    await page.waitForLoadState("load", { timeout: effectiveMs });
+                    label = "navigation";
+                    break;
+                case "networkidle":
+                    await page.waitForLoadState("networkidle", { timeout: effectiveMs });
+                    label = "networkidle";
+                    break;
+                case "time":
+                    await sleep(effectiveMs);
+                    label = "time";
+                    break;
+            }
+        }
+        catch (error) {
+            if (!isTimeoutError(error))
+                throw error;
+            return failed(operationId, "browser_wait_timeout", `Wait for ${input.until} timed out after ${effectiveMs}ms: ${boundedPreviewV1(error.message, 2048)}`);
+        }
+        const waitedMs = Date.now() - started;
+        const payload = {
+            until: input.until,
+            ...(input.ms === undefined ? {} : { requestedMs: input.ms }),
+            effectiveMs,
+            waitedMs,
+        };
+        return payloadResult(operationId, `Waited ${waitedMs}ms for ${label}`, "log", payload);
+    }
+    async drag(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const steps = clampDragStepsV1(input.steps);
+        const from = resolveLocator(page, input.from);
+        const to = resolveLocator(page, input.to);
+        await from.hover();
+        await page.mouse.down();
+        // Deliberately no `to.hover()` while the button is down: pages that call
+        // setPointerCapture (the standard drag idiom) retarget pointer events to
+        // the from-element, so Playwright's hover hit-target check would retry
+        // until timeout. Move by geometry instead.
+        const box = await to.boundingBox();
+        if (box !== null) {
+            await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps });
+        }
+        await page.mouse.up();
+        const payload = {
+            steps,
+            toCenter: box === null ? null : { x: box.x + box.width / 2, y: box.y + box.height / 2 },
+        };
+        return payloadResult(operationId, `Dragged from ${locatorLabel(input.from)} to ${locatorLabel(input.to)}`, "log", payload);
+    }
+    async mouse(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        const buttonOptions = input.button === undefined ? {} : { button: input.button };
+        let summary;
+        switch (input.action) {
+            case "move":
+                await page.mouse.move(input.x, input.y);
+                summary = `Mouse moved to (${input.x}, ${input.y})`;
+                break;
+            case "click":
+                await page.mouse.click(input.x, input.y, buttonOptions);
+                summary = `Mouse clicked (${input.button ?? "left"}) at (${input.x}, ${input.y})`;
+                break;
+            case "dblclick":
+                await page.mouse.dblclick(input.x, input.y, buttonOptions);
+                summary = `Mouse double-clicked (${input.button ?? "left"}) at (${input.x}, ${input.y})`;
+                break;
+            case "rightclick":
+                await page.mouse.click(input.x, input.y, { ...buttonOptions, button: "right" });
+                summary = `Mouse right-clicked at (${input.x}, ${input.y})`;
+                break;
+            case "wheel": {
+                const deltaX = input.deltaX ?? 0;
+                const deltaY = input.deltaY ?? 0;
+                await page.mouse.wheel(deltaX, deltaY);
+                summary = `Mouse wheel (${deltaX}, ${deltaY})`;
+                break;
+            }
+        }
+        return payloadResult(operationId, summary, "log", input);
+    }
+    async pressKey(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        await page.keyboard.press(input.key, input.delay === undefined ? {} : { delay: input.delay });
+        return payloadResult(operationId, `Pressed key ${input.key}`, "log", input);
+    }
+    async tabs(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        if (input.action === "new") {
+            await this.connect();
+            const page = await this.openPage();
+            if (input.url !== undefined)
+                await page.goto(input.url, { waitUntil: "load" });
+            return payloadResult(operationId, `Opened tab ${this.pageIndex}`, "log", {
+                index: this.pageIndex,
+                title: await page.title(),
+                url: page.url(),
+            });
+        }
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        if (input.action === "list") {
+            const tabs = [];
+            for (const [index, entry] of this.pages.entries()) {
+                tabs.push({ index, title: await entry.title(), url: entry.url() });
+            }
+            return payloadResult(operationId, `Listed ${tabs.length} tab(s), current ${this.pageIndex}`, "log", {
+                currentIndex: this.pageIndex,
+                tabs,
+            });
+        }
+        if (input.action === "switch") {
+            if (input.index === undefined ||
+                !Number.isInteger(input.index) ||
+                input.index < 0 ||
+                input.index >= this.pages.length) {
+                return failed(operationId, "browser_tabs_invalid", `switch requires an index between 0 and ${this.pages.length - 1}`);
+            }
+            this.pageIndex = input.index;
+            this.page = this.pages[this.pageIndex];
+            return payloadResult(operationId, `Switched to tab ${this.pageIndex}`, "log", {
+                index: this.pageIndex,
+                title: await this.page.title(),
+                url: this.page.url(),
+            });
+        }
+        // close
+        if (input.index === undefined ||
+            !Number.isInteger(input.index) ||
+            input.index < 0 ||
+            input.index >= this.pages.length) {
+            return failed(operationId, "browser_tabs_invalid", `close requires an index between 0 and ${this.pages.length - 1}`);
+        }
+        const closing = this.pages[input.index];
+        await closing.close();
+        this.pages.splice(input.index, 1);
+        if (this.pageIndex >= input.index)
+            this.pageIndex = Math.max(0, this.pageIndex - 1);
+        this.page = this.pages[this.pageIndex];
+        return payloadResult(operationId, `Closed tab ${input.index}; ${this.pages.length} remaining`, "log", {
+            closedIndex: input.index,
+            remaining: this.pages.length,
+            ...(this.page === undefined ? {} : { currentIndex: this.pageIndex }),
+        });
+    }
+    async storage(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        switch (input.action) {
+            case "get-cookies": {
+                const context = this.context;
+                if (context === undefined)
+                    return sessionRequired(operationId);
+                const cookies = await context.cookies();
+                return payloadResult(operationId, `Read ${cookies.length} cookie(s)`, "log", { cookies });
+            }
+            case "set-cookie": {
+                const context = this.context;
+                if (context === undefined)
+                    return sessionRequired(operationId);
+                if (input.name === undefined || input.value === undefined || input.domain === undefined) {
+                    return failed(operationId, "browser_storage_invalid", "set-cookie requires name, value, and domain");
+                }
+                await context.addCookies([
+                    {
+                        name: input.name,
+                        value: input.value,
+                        domain: input.domain,
+                        ...(input.path === undefined ? {} : { path: input.path }),
+                        ...(input.expires === undefined ? {} : { expires: input.expires }),
+                    },
+                ]);
+                return payloadResult(operationId, `Set cookie ${input.name}`, "log", {
+                    name: input.name,
+                    domain: input.domain,
+                    ...(input.path === undefined ? {} : { path: input.path }),
+                    ...(input.expires === undefined ? {} : { expires: input.expires }),
+                });
+            }
+            case "clear-cookies": {
+                const context = this.context;
+                if (context === undefined)
+                    return sessionRequired(operationId);
+                await context.clearCookies();
+                return payloadResult(operationId, "Cleared cookies", "log", { cleared: "cookies" });
+            }
+            case "get-local": {
+                const page = this.page;
+                if (page === undefined)
+                    return sessionRequired(operationId);
+                if (input.key === undefined) {
+                    return failed(operationId, "browser_storage_invalid", "get-local requires a key");
+                }
+                const value = await page.evaluate((key) => window.localStorage.getItem(key), input.key);
+                return payloadResult(operationId, `Read localStorage["${input.key}"]`, "log", { key: input.key, value });
+            }
+            case "set-local": {
+                const page = this.page;
+                if (page === undefined)
+                    return sessionRequired(operationId);
+                if (input.key === undefined || input.value === undefined) {
+                    return failed(operationId, "browser_storage_invalid", "set-local requires key and value");
+                }
+                await page.evaluate(({ key, value }) => {
+                    window.localStorage.setItem(key, value);
+                }, { key: input.key, value: input.value });
+                return payloadResult(operationId, `Set localStorage["${input.key}"]`, "log", { key: input.key });
+            }
+            case "clear-local": {
+                const page = this.page;
+                if (page === undefined)
+                    return sessionRequired(operationId);
+                await page.evaluate(() => {
+                    window.localStorage.clear();
+                });
+                return payloadResult(operationId, "Cleared localStorage", "log", { cleared: "local" });
+            }
+        }
+    }
+    async viewport(input, options = {}) {
+        const operationId = options.operationId ?? "browser-tool-call";
+        if (options.signal?.aborted)
+            return cancelled(operationId);
+        const page = this.page;
+        if (page === undefined)
+            return sessionRequired(operationId);
+        if (input.action === "get") {
+            const viewport = page.viewportSize();
+            return payloadResult(operationId, "Read viewport size", "log", {
+                width: viewport?.width ?? null,
+                height: viewport?.height ?? null,
+            });
+        }
+        if (input.width === undefined || input.height === undefined) {
+            return failed(operationId, "browser_viewport_invalid", "set requires width and height");
+        }
+        const width = clampViewportDimensionV1(input.width);
+        const height = clampViewportDimensionV1(input.height);
+        await page.setViewportSize({ width, height });
+        const clamped = width !== input.width || height !== input.height;
+        return payloadResult(operationId, `Viewport set to ${width}x${height}${clamped ? " (clamped)" : ""}`, "log", {
+            width,
+            height,
+            ...(clamped ? { requestedWidth: input.width, requestedHeight: input.height } : {}),
+        });
+    }
+    loadModule() {
+        if (this.loadPlaywright !== undefined)
+            return this.loadPlaywright();
+        if (this.depsDir === "")
+            throw new Error(installGuidanceMessage());
+        if (this.resolveModule(this.depsDir) === undefined)
+            throw new Error(installGuidanceMessage(this.depsDir));
+        try {
+            const require = createRequire(join(this.depsDir, "package.json"));
+            return require("playwright");
+        }
+        catch (error) {
+            throw new Error(installGuidanceMessage(this.depsDir), {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    downloadsDir() {
+        return this.depsDir === "" ? undefined : join(this.depsDir, BROWSER_DOWNLOADS_DIR_NAME_V1);
+    }
+    async openPage() {
+        const context = this.context;
+        if (context === undefined)
+            throw new Error("Browser context is not initialized; connect first");
+        const page = await context.newPage();
+        page.on("console", (message) => {
+            const location = message.location();
+            this.pushRing(this.consoleRing, {
+                type: message.type(),
+                text: message.text(),
+                timestamp: Date.now(),
+                ...(location.url === "" ? {} : { location }),
+            }, BROWSER_RING_BUFFER_SIZE_V1);
+        });
+        page.on("response", (response) => {
+            this.pushRing(this.networkRing, networkEntryOf(response), BROWSER_RING_BUFFER_SIZE_V1);
+        });
+        // Built-in dialog policy: auto-accept and keep a bounded trace entry so
+        // assert/evidence tools can observe that a dialog appeared.
+        page.on("dialog", (dialog) => {
+            void dialog.accept().catch(() => undefined);
+            this.pushRing(this.consoleRing, { type: "dialog", text: `[dialog] ${dialog.type()}: ${dialog.message()}`, timestamp: Date.now() }, BROWSER_RING_BUFFER_SIZE_V1);
+        });
+        // Built-in download policy: persist into <agentDir>/browser-deps/downloads.
+        page.on("download", (download) => {
+            const filename = download.suggestedFilename();
+            this.lastDownload = filename;
+            const dir = this.downloadsDir();
+            if (dir === undefined)
+                return;
+            try {
+                this.ensureDir(dir);
+            }
+            catch (error) {
+                this.pushRing(this.consoleRing, {
+                    type: "download",
+                    text: `[download] could not create ${dir}: ${error instanceof Error ? error.message : "unknown error"}`,
+                    timestamp: Date.now(),
+                }, BROWSER_RING_BUFFER_SIZE_V1);
+                return;
+            }
+            void download.saveAs(join(dir, filename)).catch((error) => {
+                this.pushRing(this.consoleRing, {
+                    type: "download",
+                    text: `[download] could not save ${filename}: ${error instanceof Error ? error.message : "unknown error"}`,
+                    timestamp: Date.now(),
+                }, BROWSER_RING_BUFFER_SIZE_V1);
+            });
+        });
+        this.pages.push(page);
+        this.pageIndex = this.pages.length - 1;
+        this.page = page;
+        return page;
+    }
+    pushRing(ring, entry, maximum) {
+        ring.push(entry);
+        if (ring.length > maximum)
+            ring.splice(0, ring.length - maximum);
+    }
+    async checkCondition(page, condition) {
+        if (condition.kind === "url") {
+            const url = page.url();
+            if (condition.equals !== undefined && url !== condition.equals)
+                return false;
+            if (condition.contains !== undefined && !url.includes(condition.contains))
+                return false;
+            return true;
+        }
+        if (condition.kind === "element") {
+            const locator = resolveLocator(page, condition.locator);
+            if (condition.state === "visible")
+                return locator.isVisible();
+            if (condition.state === "hidden")
+                return locator.isHidden();
+            const value = await locator.inputValue();
+            return condition.value === undefined || value === condition.value;
+        }
+        if (condition.kind === "text") {
+            const text = condition.locator === undefined
+                ? ((await page.locator("body").textContent()) ?? "")
+                : ((await resolveLocator(page, condition.locator).textContent()) ?? "");
+            return text.includes(condition.contains);
+        }
+        if (condition.kind === "console") {
+            return this.consoleRing.some((entry) => entry.text.includes(condition.contains) &&
+                (condition.level === undefined || entry.type === condition.level));
+        }
+        return this.networkRing.some((entry) => entry.url.includes(condition.containsUrl) &&
+            (condition.status === undefined || entry.status === condition.status));
+    }
+}
+/** Shapes a ring-buffer response event into a bounded network entry. */
+function networkEntryOf(response) {
+    const request = response.request();
+    let durationMs;
+    const timing = request.timing();
+    if (timing.responseEnd > 0 && timing.responseEnd >= timing.startTime) {
+        durationMs = Math.round(timing.responseEnd - timing.startTime);
+    }
+    const contentLength = response.headers()["content-length"];
+    const sizeBytes = contentLength === undefined ? undefined : Number.parseInt(contentLength, 10);
+    return {
+        method: request.method(),
+        url: response.url(),
+        status: response.status(),
+        timestamp: Date.now(),
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(sizeBytes === undefined || Number.isNaN(sizeBytes) ? {} : { sizeBytes }),
+    };
+}
+/** Builds a succeeded result carrying one bounded JSON payload as evidence. */
+function payloadResult(operationId, summary, kind, payload) {
+    const evidence = evidenceBuilder(operationId);
+    evidence.add(kind, placeholder(boundedPreviewV1(serializeJsonPayloadV1(payload), BROWSER_MAX_EVIDENCE_CHARS_V1)));
+    return buildPluginResultV1({
+        version: 1,
+        operationId,
+        status: "succeeded",
+        summary,
+        artifacts: [],
+        evidence: evidence.refs,
+    });
+}
+/**
+ * Production runtime: one driver per session plus the `browser_setup`
+ * self-install face. Hosts and tests may inject `spawnSync` and
+ * `resolvePlaywright` through the setup options.
+ */
+export class PlaywrightBrowserRuntimeV1 {
+    options;
+    driver;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async connect() {
+        if (this.driver === undefined)
+            this.driver = new PlaywrightBrowserDriver(this.options);
+        await this.driver.connect();
+        return this.driver;
+    }
+    async setup() {
+        return setupBrowserDepsPlaywrightV1(this.options);
+    }
+}
+const actionMissingInput = (input) => {
+    if ((input.action === "fill" ||
+        input.action === "type" ||
+        input.action === "select" ||
+        input.action === "upload" ||
+        input.action === "scroll") &&
+        input.value === undefined)
+        return "a value";
+    if (input.action === "press" && input.key === undefined)
+        return "a key";
+    return undefined;
+};
+const resolveLocator = (page, locator) => {
+    if (locator.kind === "id")
+        return page.locator(`#${locator.value}`);
+    if (locator.kind === "role")
+        return page.getByRole(locator.value, locator.name === undefined ? {} : { name: locator.name });
+    if (locator.kind === "text")
+        return page.getByText(locator.value);
+    if (locator.kind === "test-id")
+        return page.getByTestId(locator.value);
+    return page.locator(locator.value);
+};
+const cancelled = (operationId) => failed(operationId, "cancelled", "Browser operation was cancelled");
+const sessionRequired = (operationId) => failed(operationId, "browser_session_required", "No active browser session. Call browser_navigate first.");
+function failed(operationId, code, message) {
+    return buildPluginResultV1({
+        version: 1,
+        operationId,
+        status: code === "cancelled" ? "cancelled" : "failed",
+        summary: message,
+        artifacts: [],
+        evidence: [],
+        error: { version: 1, code, message },
+    });
+}
+function evidenceBuilder(operationId) {
+    const refs = [];
+    let index = 1;
+    return {
+        refs,
+        add(kind, summary) {
+            refs.push({
+                version: 1,
+                evidenceId: `${operationId}-evidence-${index}`,
+                kind,
+                operationId,
+                summary,
+            });
+            index += 1;
+        },
+    };
+}
+//# sourceMappingURL=playwright-driver.js.map