@rynx-ai/daemon 0.1.11-beta.45 → 0.1.11-beta.49

package/dist/page-agent-browser-driver.js

@@ -0,0 +1,216 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { diagnosticEvents, sessionDiagnosticDir, teeDiagnosticStream } from "@rynx-ai/core";
+import { createPageAgentBrowserConnection } from "./page-agent-browser-connection.js";
+const exec = promisify(execFile);
+export const PAGE_AGENT_BROWSER_VERSION = "0.36.0";
+const MAX_BYTES = 8 * 1024 * 1024;
+export class PageAutomationError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "PageAutomationError";
+    }
+}
+/** Resolve only the pinned dependency. Never use a PATH/global helper or run its Node wrapper. */
+export function pageAgentBrowserBinary() {
+    // Operator-owned absolute native binary. This is never read from request
+    // argv or the managed Agent's environment. Upgrading it needs no Rynx build.
+    const configured = process.env.RYNX_AGENT_BROWSER_EXECUTABLE;
+    if (configured) {
+        if (!isAbsolute(configured))
+            throw new Error("RYNX_AGENT_BROWSER_EXECUTABLE must be an absolute native binary path");
+        return resolve(configured);
+    }
+    const require = createRequire(import.meta.url);
+    const root = dirname(require.resolve("agent-browser/package.json"));
+    const metadata = require("agent-browser/package.json");
+    if (metadata.version !== PAGE_AGENT_BROWSER_VERSION)
+        throw new Error("Bundled agent-browser version mismatch");
+    const report = process.platform === "linux" ? process.report?.getReport() : undefined;
+    const platform = process.platform === "linux" && !report?.header?.glibcVersionRuntime ? "linux-musl" : process.platform;
+    const arch = process.platform === "win32" && process.arch === "arm64" ? "x64" : process.arch;
+    return join(root, "bin", `agent-browser-${platform}-${arch}${process.platform === "win32" ? ".exe" : ""}`).replace(/\.asar([/\\])/, ".asar.unpacked$1");
+}
+export async function createPageAgentBrowserDriver(root, binding) {
+    const binary = pageAgentBrowserBinary();
+    const id = randomBytes(6).toString("hex");
+    const logRoot = sessionDiagnosticDir("browser", binding.sessionId);
+    const event = diagnosticEvents(join(logRoot, "driver.log"), { sessionId: binding.sessionId, driverId: id, browserGeneration: binding.browserGeneration, pageId: binding.pageId });
+    let commandSeq = 0;
+    const directory = join(root, id);
+    await mkdir(directory, { mode: 0o700 });
+    const config = join(directory, "config.json");
+    await writeFile(config, "{}\n", { mode: 0o600, flag: "wx" });
+    // A native helper has no reason to inherit API tokens, proxies, agent
+    // settings, a provider, persistence, plugins or the caller's project config.
+    const env = {};
+    for (const key of ["PATH", "HOME", "USERPROFILE", "SYSTEMROOT", "WINDIR", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "DISPLAY", "XDG_RUNTIME_DIR"]) {
+        if (process.env[key] !== undefined)
+            env[key] = process.env[key];
+    }
+    env.AGENT_BROWSER_SOCKET_DIR = root;
+    env.AGENT_BROWSER_DEFAULT_TIMEOUT = "20000";
+    const { stdout: versionText } = await exec(binary, ["--version"], { cwd: directory, env, timeout: 5_000, maxBuffer: 4096 }).catch(async (error) => {
+        await rm(directory, { recursive: true, force: true });
+        throw new PageAutomationError("command_failed", `Browser engine cannot start (${String(error.code ?? "timeout")}); rebuild/reinstall the Rynx Runtime or check its configured native engine`, { cause: error });
+    });
+    const version = versionText.trim().match(/(?:agent-browser\s+)?(\d+\.\d+\.\d+(?:[-+][\w.-]+)?)/)?.[1];
+    if (!version) {
+        await rm(directory, { recursive: true, force: true });
+        throw new Error("Browser driver did not report a semantic version");
+    }
+    const connection = await createPageAgentBrowserConnection(binding.endpoint, binding.isCurrent).catch(async (error) => {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    });
+    let initialized = false;
+    let closed = false;
+    let owner;
+    const processIdentity = async (pid) => {
+        if (process.platform === "win32")
+            return undefined;
+        return (await exec("ps", ["-p", String(pid), "-o", "lstart=", "-o", "comm="], { timeout: 2_000, maxBuffer: 4096 }).catch(() => ({ stdout: "" }))).stdout.trim() || undefined;
+    };
+    const captureOwner = async () => {
+        const pid = Number((await readFile(join(root, id + ".pid"), "utf8").catch(() => "")).trim());
+        if (!Number.isSafeInteger(pid) || pid < 1)
+            return;
+        const identity = await processIdentity(pid);
+        if (identity)
+            owner = { pid, identity };
+    };
+    const ownerAlive = async () => Boolean(owner && await processIdentity(owner.pid) === owner.identity);
+    const ownerCurrent = async () => await ownerAlive() && Number((await readFile(join(root, id + ".pid"), "utf8").catch(() => "")).trim()) === owner?.pid;
+    const invoke = async (args, pin, timeout = 30_000) => {
+        const commandId = String(++commandSeq);
+        event("command.start", { commandId, command: args[0] });
+        let stdout;
+        try {
+            const pending = exec(binary, ["--config", config, "--session", id, "--cdp", connection.endpoint,
+                pin ? "--pin-tab" : "--no-pin-tab", "--idle-timeout", "900000", "--no-webmcp", "--no-auto-dialog", "--json", ...args], { cwd: directory, env, timeout, maxBuffer: MAX_BYTES, windowsHide: true, encoding: "buffer" });
+            teeDiagnosticStream(pending.child.stderr, join(logRoot, "instances", String(binding.browserGeneration), "drivers", id, commandId + ".stderr.log"));
+            stdout = (await pending).stdout.toString("utf8");
+            event("command.exit", { commandId });
+        }
+        catch (error) {
+            event("command.error", { commandId, code: error.code });
+            const failure = error;
+            if (failure.killed || !failure.stdout)
+                throw new PageAutomationError("outcome_unknown", "Browser driver did not return a complete response; do not replay the action", { cause: error });
+            stdout = failure.stdout.toString();
+        }
+        if (initialized && process.platform !== "win32" && !await ownerCurrent()) {
+            await captureOwner();
+            throw new PageAutomationError("driver_restarted", "Browser helper process changed; take a new snapshot before further actions");
+        }
+        if (args.includes("--help") || args.includes("-h") || args[0] === "help" || args[0] === "--version" || args[0] === "-V")
+            return { help: stdout };
+        let result;
+        try {
+            result = JSON.parse(stdout);
+        }
+        catch (error) {
+            throw new PageAutomationError("outcome_unknown", "Browser driver returned an invalid response; do not replay the action", { cause: error });
+        }
+        if (result.success !== true || !result.data || typeof result.data !== "object") {
+            // Return bounded upstream diagnostics to the authorized caller only;
+            // never write command arguments or response bodies to daemon logs.
+            throw new PageAutomationError("command_failed", typeof result.error === "string" ? result.error.slice(0, 2048) : "agent-browser command failed; run browser exec -- --help", { cause: result.error });
+        }
+        const lifecycle = result.data.lifecycle;
+        if (initialized && (lifecycle?.launched || lifecycle?.restartedBackground || lifecycle?.relaunchedBrowser)) {
+            await captureOwner();
+            throw new PageAutomationError("driver_restarted", "Browser helper restarted; run browser exec -- snapshot -i again");
+        }
+        return result.data;
+    };
+    const cleanup = async () => {
+        initialized = false;
+        if (!owner)
+            await captureOwner();
+        // Do not launch a new helper merely to close a helper that already exited.
+        if (await ownerAlive() || process.platform === "win32")
+            await invoke(["close"], true, 5_000).catch(() => undefined);
+        if (await ownerAlive()) {
+            const signalOwner = (signal) => {
+                try {
+                    process.kill(owner.pid, signal);
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        throw error;
+                }
+            };
+            signalOwner("SIGTERM");
+            for (let n = 0; n < 20 && await ownerAlive(); n++)
+                await new Promise((r) => setTimeout(r, 50));
+            if (await ownerAlive()) {
+                signalOwner("SIGKILL");
+                for (let n = 0; n < 20 && await ownerAlive(); n++)
+                    await new Promise((r) => setTimeout(r, 50));
+                if (await ownerAlive())
+                    throw new Error("Owned browser helper did not terminate");
+            }
+        }
+        await connection.close();
+        await rm(directory, { recursive: true, force: true });
+        for (const extension of ["pid", "sock", "port", "version", "config", "target"])
+            await rm(join(root, id + "." + extension), { force: true });
+    };
+    try {
+        if (!binding.isCurrent())
+            throw new PageAutomationError("not_found", "Browser Page closed before attachment");
+        await invoke(["tab", binding.pageTargetId], false);
+        await captureOwner();
+        initialized = true;
+        // Establish the sticky pin before the first command; this also detects a
+        // helper crash between initial target selection and the first user action.
+        await invoke(["tab", "list"], true);
+    }
+    catch (error) {
+        try {
+            await cleanup();
+        }
+        finally {
+            await connection.close();
+        }
+        throw error;
+    }
+    const execute = async (args, beforeInvoke) => {
+        if (closed || !binding.isCurrent())
+            throw new PageAutomationError("not_found", "Browser Page is no longer available");
+        if (process.platform !== "win32" && !await ownerCurrent())
+            throw new PageAutomationError("driver_restarted", "Browser helper process ended; take a new snapshot before further actions");
+        // Read-only preflight catches implicit helper restarts before any write.
+        const inventory = await invoke(["tab", "list"], true);
+        const tabs = inventory.tabs;
+        if (!Array.isArray(tabs) || !tabs.some((tab) => tab.active === true && tab.targetId === binding.pageTargetId)) {
+            throw new PageAutomationError("not_found", "Browser helper is no longer bound to the requested Page");
+        }
+        if (!binding.isCurrent())
+            throw new PageAutomationError("not_found", "Browser Page closed before command admission");
+        beforeInvoke?.();
+        return invoke(args, true);
+    };
+    return {
+        version,
+        execute,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await cleanup();
+            }
+            finally {
+                await connection.close();
+            }
+        },
+    };
+}

package/dist/page-agent-browser-policy.d.ts

@@ -0,0 +1,3 @@
+export declare function assertPageAgentBrowserArguments(argv: readonly string[]): void;
+/** Unknown commands pass through, but conservatively participate as writes. */
+export declare function isPageAgentBrowserRead(argv: readonly string[]): boolean;

package/dist/page-agent-browser-policy.js

@@ -0,0 +1,37 @@
+import { PageAutomationError } from "./page-agent-browser-driver.js";
+// Ownership boundary, not an allowlist of page commands or page options.
+const OWNER_OPTIONS = new Set([
+    "--cdp", "--session", "--session-name", "--namespace", "--config", "--provider", "-p",
+    "--auto-connect", "--pin-tab", "--no-pin-tab", "--executable-path", "--profile",
+    "--state", "--args", "--engine", "--plugins", "--extension", "--extensions",
+    "--enable", "--init-script", "--headed", "--idle-timeout", "--proxy",
+    "--proxy-bypass", "--proxy-username", "--proxy-password", "--headers",
+    "--allowed-domains", "--action-policy", "--confirm-actions", "--device",
+    "--auto-dialog", "--restore-save", "--restore-check-url", "--restore-check-text",
+    "--restore-check-fn", "--restore", "--allow-file-access", "--ignore-https-errors",
+    "--user-agent", "--color-scheme", "--webgpu", "--no-xvfb", "--json",
+]);
+const OWNER_COMMANDS = new Set([
+    "connect", "attach", "disconnect", "close", "quit", "exit", "install", "uninstall",
+    "update", "upgrade", "session", "tab", "window", "batch", "run", "recipe",
+    "dashboard", "auth", "plugin", "plugins", "doctor",
+]);
+export function assertPageAgentBrowserArguments(argv) {
+    for (const arg of argv) {
+        // Match the native parser, not arbitrary option-looking page text. In
+        // 0.36, --session=value is literal text; --restore=value is a real flag.
+        if (OWNER_OPTIONS.has(arg) || arg.startsWith("--restore="))
+            throw new PageAutomationError("invalid_request", "Rynx owns Browser connection, configuration and Session options; remove the override");
+    }
+    // Command-first means we need not duplicate upstream's evolving option arities.
+    const command = argv[0];
+    if (!command || (command.startsWith("-") && !["--help", "-h", "--version", "-V"].includes(command)))
+        throw new PageAutomationError("invalid_request", "Put the agent-browser command first, followed by its arguments and options");
+    if (OWNER_COMMANDS.has(command) || (command === "state" && argv[1] !== "save"))
+        throw new PageAutomationError("invalid_request", "This command changes helper/Browser ownership; use rynx browser resource commands instead");
+}
+/** Unknown commands pass through, but conservatively participate as writes. */
+export function isPageAgentBrowserRead(argv) {
+    return argv.includes("--help") || argv.includes("-h") ||
+        ["--version", "-V", "help", "snapshot", "screenshot", "get", "is", "frame", "mainframe"].includes(argv[0]);
+}

package/dist/page-automation-manager.d.ts

@@ -0,0 +1,29 @@
+import type { SessionBrowserAutomationBinding, SessionBrowserService } from "@rynx-ai/server";
+import { type RuntimeBrowserAutomationCommand, type RuntimeBrowserAutomationResult } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { type PageAutomationDriver } from "./page-agent-browser-driver.js";
+export interface PageAutomationManagerOptions {
+    createDriver?: (root: string, binding: SessionBrowserAutomationBinding) => Promise<PageAutomationDriver>;
+    idleMs?: number;
+    isHumanControlled?: (binding: SessionBrowserAutomationBinding) => boolean;
+    onCleanupError?: (error: unknown) => void;
+}
+/** The Runtime owns Page routing and queues. The upstream CLI owns argv, refs and results. */
+export declare class PageAutomationManager {
+    private readonly browsers;
+    private readonly options;
+    private readonly runs;
+    private readonly browserTails;
+    private root?;
+    private stopped;
+    private readonly timer;
+    constructor(browsers: Pick<SessionBrowserService, "resolveAutomationPage">, options?: PageAutomationManagerOptions);
+    execute(sessionId: string, input: RuntimeBrowserAutomationCommand): Promise<RuntimeBrowserAutomationResult>;
+    private assertCurrent;
+    private assertAdmission;
+    private enqueueBrowser;
+    private reportCleanupError;
+    private directory;
+    private retire;
+    private sweep;
+    shutdown(): Promise<void>;
+}

package/dist/page-automation-manager.js

@@ -0,0 +1,144 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseRuntimeBrowserAutomationCommand } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { createPageAgentBrowserDriver, PageAutomationError } from "./page-agent-browser-driver.js";
+import { assertPageAgentBrowserArguments, isPageAgentBrowserRead } from "./page-agent-browser-policy.js";
+/** The Runtime owns Page routing and queues. The upstream CLI owns argv, refs and results. */
+export class PageAutomationManager {
+    browsers;
+    options;
+    runs = new Map();
+    browserTails = new Map();
+    root;
+    stopped = false;
+    timer;
+    constructor(browsers, options = {}) {
+        this.browsers = browsers;
+        this.options = options;
+        this.timer = setInterval(() => { void this.sweep(); }, 2_000);
+        this.timer.unref?.();
+    }
+    async execute(sessionId, input) {
+        const command = parseRuntimeBrowserAutomationCommand(input);
+        assertPageAgentBrowserArguments(command.argv);
+        if (this.stopped)
+            throw new PageAutomationError("not_found", "Browser automation is stopping");
+        // Pin before queueing: a UI tab switch cannot redirect a queued command.
+        const binding = await this.browsers.resolveAutomationPage(sessionId, command.pageId);
+        const key = JSON.stringify([sessionId, binding.browserGeneration, binding.pageId, binding.pageTargetId, binding.endpoint]);
+        let run = this.runs.get(key);
+        if (!run || run.retired) {
+            if (this.runs.size >= 64)
+                throw new PageAutomationError("capacity", "Browser automation page capacity reached");
+            run = { binding, tail: Promise.resolve(), pending: 0, lastUsed: Date.now(), retired: false };
+            this.runs.set(key, run);
+        }
+        const selected = run;
+        if (selected.pending >= 32)
+            throw new PageAutomationError("capacity", "Browser Page command queue is full");
+        selected.pending++;
+        let submittedMutation = false;
+        const isRead = isPageAgentBrowserRead(command.argv);
+        const result = this.enqueueBrowser(binding, async () => {
+            let visibility;
+            try {
+                this.assertAdmission(selected, isRead);
+                visibility = await selected.binding.acquireAutomationVisibility(() => !this.options.isHumanControlled?.(selected.binding));
+                this.assertAdmission(selected, isRead);
+                if (!selected.driver) {
+                    const driver = await (this.options.createDriver ?? createPageAgentBrowserDriver)(await this.directory(), selected.binding);
+                    if (selected.retired || this.stopped) {
+                        await driver.close();
+                        this.assertCurrent(selected);
+                    }
+                    selected.driver = driver;
+                }
+                this.assertAdmission(selected, isRead);
+                const args = command.argv;
+                const data = await selected.driver.execute(args, () => {
+                    // Re-check takeover after helper preflight without disabling human-safe reads.
+                    this.assertAdmission(selected, isRead);
+                    submittedMutation = !isRead;
+                });
+                this.assertCurrent(selected);
+                return {
+                    schemaVersion: 2, completed: true, sessionId,
+                    browserGeneration: selected.binding.browserGeneration, pageId: selected.binding.pageId,
+                    ...(selected.driver.version ? { driverVersion: selected.driver.version } : {}), data,
+                };
+            }
+            catch (error) {
+                // Retire uncertain helpers before releasing shared rendering; never replay a command.
+                if (!(error instanceof PageAutomationError) || ["outcome_unknown", "driver_restarted", "not_found"].includes(error.code))
+                    await this.retire(key, selected);
+                if (submittedMutation && (!(error instanceof PageAutomationError) || ["not_found", "driver_restarted"].includes(error.code)))
+                    throw new PageAutomationError("outcome_unknown", "Browser action may have completed; inspect a new snapshot and do not replay it", { cause: error });
+                throw error;
+            }
+            finally {
+                await visibility?.release(!this.options.isHumanControlled?.(selected.binding)).catch((error) => this.reportCleanupError(error));
+            }
+        });
+        selected.tail = result.then(() => undefined, () => undefined);
+        try {
+            return await result;
+        }
+        finally {
+            selected.pending--;
+            selected.lastUsed = Date.now();
+        }
+    }
+    assertCurrent(run) {
+        if (this.stopped || run.retired || !run.binding.isCurrent())
+            throw new PageAutomationError("not_found", "Browser Page closed or was replaced; run browser pages");
+    }
+    assertAdmission(run, isRead) {
+        this.assertCurrent(run);
+        if (!isRead && this.options.isHumanControlled?.(run.binding))
+            throw new PageAutomationError("human_control_active", "Release Browser Control before Agent actions");
+    }
+    enqueueBrowser(binding, execute) {
+        const key = JSON.stringify([binding.sessionId, binding.browserGeneration]);
+        const result = (this.browserTails.get(key) ?? Promise.resolve()).then(execute);
+        const tail = result.then(() => undefined, () => undefined);
+        this.browserTails.set(key, tail);
+        void tail.then(() => { if (this.browserTails.get(key) === tail)
+            this.browserTails.delete(key); });
+        return result;
+    }
+    reportCleanupError(error) {
+        try {
+            this.options.onCleanupError?.(error);
+        }
+        catch { /* Preserve the command outcome. */ }
+    }
+    directory() {
+        return this.root ??= mkdtemp(join(process.platform === "win32" ? tmpdir() : "/tmp", "rynx-ab-"));
+    }
+    async retire(key, run) {
+        if (run.retired)
+            return;
+        run.retired = true;
+        if (this.runs.get(key) === run)
+            this.runs.delete(key);
+        try {
+            await run.driver?.close();
+        }
+        catch (error) {
+            this.reportCleanupError(error);
+        }
+    }
+    async sweep() {
+        await Promise.all([...this.runs].filter(([, run]) => !run.binding.isCurrent() || (run.pending === 0 && Date.now() - run.lastUsed > (this.options.idleMs ?? 600_000))).map(([key, run]) => this.retire(key, run)));
+    }
+    async shutdown() {
+        this.stopped = true;
+        clearInterval(this.timer);
+        const runs = [...this.runs];
+        await Promise.all(runs.map(([key, run]) => this.retire(key, run)));
+        await Promise.all(runs.map(([, run]) => run.tail));
+        if (this.root)
+            await rm(await this.root, { recursive: true, force: true });
+    }
+}

package/dist/page-cdp-gateway.d.ts

@@ -0,0 +1,5 @@
+/** A capability for one existing native target, never the whole Chrome process. */
+export declare function createPageCdpGateway(upstreamEndpoint: string, targetId: string, isCurrent: () => boolean): Promise<{
+    endpoint: string;
+    close(): Promise<void>;
+}>;

package/dist/page-cdp-gateway.js

@@ -0,0 +1,205 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+const CHILD_TYPES = new Set(["iframe", "worker", "service_worker", "shared_worker"]);
+const MAX_BYTES = 8 * 1024 * 1024;
+const TARGET_METHODS = new Set(["Target.getTargets", "Target.getTargetInfo", "Target.setDiscoverTargets", "Target.setAutoAttach", "Target.attachToTarget", "Target.detachFromTarget", "Target.activateTarget"]);
+const BROWSER_METHODS = new Set(["Browser.getVersion", "Browser.getWindowForTarget"]);
+/** A capability for one existing native target, never the whole Chrome process. */
+export async function createPageCdpGateway(upstreamEndpoint, targetId, isCurrent) {
+    const path = "/devtools/browser/" + randomBytes(18).toString("hex");
+    let endpoint = "";
+    let stopped = false;
+    let downstream;
+    let upstream;
+    // The daemon hands the nonce URL directly to its helper. Never publish that
+    // capability on an unauthenticated discovery endpoint.
+    const server = createServer((_request, response) => { response.writeHead(404).end(); });
+    const sockets = new WebSocketServer({ noServer: true, maxPayload: MAX_BYTES });
+    server.on("upgrade", (request, socket, head) => {
+        if (stopped || !isCurrent() || request.url !== path || downstream ||
+            request.headers.origin !== undefined || request.headers.host !== new URL(endpoint).host) {
+            socket.destroy();
+            return;
+        }
+        sockets.handleUpgrade(request, socket, head, (client) => sockets.emit("connection", client));
+    });
+    sockets.on("connection", (client) => {
+        downstream = client;
+        const native = new WebSocket(upstreamEndpoint, { maxPayload: MAX_BYTES, handshakeTimeout: 5_000 });
+        upstream = native;
+        const sessions = new Set();
+        const children = new Map();
+        const unacknowledged = new Set();
+        const pending = new Map();
+        const early = [];
+        const send = (message) => { if (client.readyState === WebSocket.OPEN)
+            client.send(JSON.stringify(message)); };
+        const reply = (request, result = {}) => send({ id: request.id, ...(request.sessionId ? { sessionId: request.sessionId } : {}), result });
+        const close = () => {
+            if (downstream === client)
+                downstream = undefined;
+            if (upstream === native)
+                upstream = undefined;
+            client.terminate();
+            native.terminate();
+        };
+        client.on("close", close);
+        client.on("error", close);
+        native.on("close", close);
+        native.on("error", close);
+        native.on("open", () => { for (const message of early)
+            native.send(message); early.length = 0; });
+        client.on("message", (bytes, binary) => {
+            let request;
+            try {
+                if (binary)
+                    throw new Error();
+                request = JSON.parse(bytes.toString());
+                if (!request || typeof request !== "object" || Array.isArray(request))
+                    throw new Error();
+            }
+            catch {
+                close();
+                return;
+            }
+            try {
+                if (!isCurrent() || !Number.isSafeInteger(request.id) || typeof request.method !== "string")
+                    throw new Error("Page capability expired or invalid command");
+                if (request.sessionId && !sessions.has(request.sessionId))
+                    throw new Error("Unknown Page child session");
+                const method = request.method;
+                const params = request.params ?? {};
+                if (method === "Browser.close") {
+                    reply(request);
+                    client.close(1000, "helper disconnected");
+                    return;
+                }
+                if ((method.startsWith("Target.") && !TARGET_METHODS.has(method)) ||
+                    (method.startsWith("Browser.") && !BROWSER_METHODS.has(method)) ||
+                    (!request.sessionId && !TARGET_METHODS.has(method) && !BROWSER_METHODS.has(method)))
+                    throw new Error("Rynx owns Browser-wide CDP and Page lifecycle");
+                if (method === "Target.setAutoAttach") {
+                    if (!request.sessionId) {
+                        reply(request);
+                        return;
+                    }
+                    request.params = { ...params, flatten: true, filter: [...CHILD_TYPES].map((type) => ({ type })).concat([{ exclude: true }]) };
+                }
+                if (method === "Target.getTargets")
+                    request.params = {};
+                if (["Target.attachToTarget", "Target.getTargetInfo", "Target.activateTarget", "Browser.getWindowForTarget"].includes(method)) {
+                    if (params.targetId !== undefined && params.targetId !== targetId && ![...children.values()].some((event) => event.params?.targetInfo?.targetId === params.targetId))
+                        throw new Error("Target is outside this Page");
+                    request.params = { ...params, targetId: params.targetId ?? targetId };
+                }
+                if (method === "Target.detachFromTarget" && !sessions.has(params.sessionId))
+                    throw new Error("Unknown Page child session");
+                // Physical activation belongs to the render lease, not helper tab pinning.
+                if (method === "Target.activateTarget" || method === "Page.bringToFront") {
+                    reply(request);
+                    return;
+                }
+                if (request.sessionId && /^(Runtime|Network|DOM|Accessibility)\.enable$/.test(method))
+                    unacknowledged.delete(request.sessionId);
+                // Some clients subscribe only after connect has enabled auto-attach.
+                // Replay unacknowledged child attachments before a later command; the
+                // first child domain enable acknowledges ownership. Never resume a pause.
+                if (method === "Runtime.evaluate")
+                    for (const sid of unacknowledged) {
+                        const event = children.get(sid);
+                        if (event)
+                            send({ ...event, params: { ...event.params, waitingForDebugger: false } });
+                    }
+                if (pending.size >= 256 || pending.has(request.id))
+                    throw new Error("Page CDP command capacity reached");
+                pending.set(request.id, request);
+                const serialized = JSON.stringify(request);
+                if (native.readyState === WebSocket.OPEN)
+                    native.send(serialized);
+                else if (native.readyState === WebSocket.CONNECTING && early.length < 64)
+                    early.push(serialized);
+                else {
+                    pending.delete(request.id);
+                    throw new Error("Page CDP is disconnected");
+                }
+            }
+            catch (error) {
+                send({ id: request.id, ...(request.sessionId ? { sessionId: request.sessionId } : {}), error: { code: -32000, message: error instanceof Error ? error.message : "Page command rejected" } });
+            }
+        });
+        native.on("message", (bytes, binary) => {
+            let message;
+            try {
+                if (binary)
+                    throw new Error();
+                message = JSON.parse(bytes.toString());
+            }
+            catch {
+                close();
+                return;
+            }
+            if (message.id !== undefined) {
+                const request = pending.get(message.id);
+                pending.delete(message.id);
+                if (!request)
+                    return;
+                if (request.method === "Target.getTargets" && message.result)
+                    message.result.targetInfos = (message.result.targetInfos ?? []).filter((target) => target.targetId === targetId);
+                if (request.method === "Target.attachToTarget" && typeof message.result?.sessionId === "string")
+                    sessions.add(message.result.sessionId);
+                send(message);
+                return;
+            }
+            const params = message.params ?? {};
+            if (message.method === "Target.attachedToTarget") {
+                const info = params.targetInfo ?? {};
+                if (info.targetId !== targetId && (!message.sessionId || !sessions.has(message.sessionId) || !CHILD_TYPES.has(info.type)))
+                    return;
+                if (typeof params.sessionId !== "string" || sessions.size >= 256) {
+                    close();
+                    return;
+                }
+                sessions.add(params.sessionId);
+                if (info.targetId !== targetId) {
+                    children.set(params.sessionId, message);
+                    unacknowledged.add(params.sessionId);
+                }
+            }
+            else if (message.method === "Target.detachedFromTarget") {
+                if (!sessions.delete(params.sessionId))
+                    return;
+                children.delete(params.sessionId);
+                unacknowledged.delete(params.sessionId);
+            }
+            else if (message.method?.startsWith("Target.target")) {
+                if ((params.targetInfo?.targetId ?? params.targetId) !== targetId)
+                    return;
+            }
+            else if (message.sessionId && !sessions.has(message.sessionId))
+                return;
+            else if (!message.sessionId)
+                return;
+            send(message);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Page CDP did not bind");
+    endpoint = "ws://127.0.0.1:" + address.port + path;
+    return {
+        endpoint,
+        async close() {
+            if (stopped)
+                return;
+            stopped = true;
+            downstream?.terminate();
+            upstream?.terminate();
+            await Promise.all([new Promise((r) => sockets.close(() => r())), new Promise((r) => server.close(() => r()))]);
+        },
+    };
+}