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

package/dist/headless-browser-host.js

@@ -3,13 +3,14 @@ import { execFile, spawn } from "node:child_process";
 import { accessSync, chmodSync, closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
 import { constants as fsConstants } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { rynxHome } from "@rynx-ai/core";
+import { rynxHome, diagnosticEvents, sessionDiagnosticDir, teeDiagnosticStream } from "@rynx-ai/core";
 import { RUNTIME_BROWSER_MAX_PAGES, RUNTIME_BROWSER_MAX_TITLE_CHARS, RUNTIME_BROWSER_MAX_URL_CHARS, } from "@rynx-ai/protocol/runtime-browser";
 import { RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_FRAME_RATE, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_HEIGHT, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_PIXELS, RUNTIME_BROWSER_SURFACE_MAX_VIEWPORT_WIDTH, } from "@rynx-ai/protocol/runtime-browser-surface";
 import { SessionBrowserHostError, } from "@rynx-ai/server";
 import WebSocket from "ws";
 import { createChromeForTestingArtifactStore, } from "./chrome-for-testing-store.js";
 import { cdpKeyboardEventParams } from "./cdp-keyboard-input.js";
+import { createPageCdpGateway } from "./page-cdp-gateway.js";
 const PROFILE_OWNER_FILE = ".rynx-headless-browser-profile.json";
 const PROCESS_LEASE_FILE = ".rynx-headless-browser-process.json";
 const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
@@ -124,6 +125,13 @@ class HeadlessBrowserHost {
             throw unavailable("Managed Chrome for Testing could not be launched", error);
         }
         const observed = observeProcess(child);
+        const logRoot = sessionDiagnosticDir("browser", input.sessionId);
+        const instance = String(input.browserGeneration);
+        const event = diagnosticEvents(join(logRoot, "browser-host.log"), { sessionId: input.sessionId, instance });
+        teeDiagnosticStream(child.stderr, join(logRoot, "instances", instance, "chrome.stderr.log"));
+        event("chrome.spawn", { pid: child.pid });
+        child.on("exit", (code, signal) => event("chrome.exit", { code, signal }));
+        child.on("error", (error) => event("chrome.error", { message: error.message }));
         const diagnostics = boundedStderr(child);
         let connection;
         let handle;
@@ -217,6 +225,7 @@ class HeadlessBrowserHandle {
     networkTargetTypeBySession = new Map();
     surfaceSources = new Map();
     loadingTargets = new Set();
+    automationGateways = new Map();
     activeTargetId = null;
     unavailableReason;
     closing = false;
@@ -224,8 +233,12 @@ class HeadlessBrowserHandle {
     operations = Promise.resolve();
     networkOperations = Promise.resolve();
     requestHeaders;
+    diagnostic;
     constructor(host) {
         this.host = host;
+        this.diagnostic = diagnosticEvents(join(sessionDiagnosticDir("browser", host.input.sessionId), "page-events.jsonl"), {
+            sessionId: host.input.sessionId, browserGeneration: host.input.browserGeneration,
+        });
         this.requestHeaders = cloneRequestHeadersConfig(host.input.requestHeaders ?? { enabled: false, headers: [] });
         this.events = this.eventQueue;
         this.host.connection.setEventHandler((event) => this.onCdpEvent(event));
@@ -253,7 +266,8 @@ class HeadlessBrowserHandle {
                 throw new Error("Headless Browser startup Page is unavailable");
             const pageSessionId = await this.pageSession(targetId);
             await this.host.connection.command("Page.navigate", { url: requestedUrl }, pageSessionId);
-            await this.resetPageNavigationHistory(targetId);
+            // Do not reset navigation history while child frames are committing.
+            // Chrome can discard a pending OOPIF navigation and leave it blank.
         }
     }
     async getCdpEndpoint() {
@@ -276,6 +290,53 @@ class HeadlessBrowserHandle {
             engineVersion: this.host.engineVersion,
         };
     }
+    async getPageAutomationEndpoint(hostPageId) {
+        this.ensureAvailable();
+        const target = this.requireTarget(hostPageId);
+        let gateway = this.automationGateways.get(hostPageId);
+        if (!gateway) {
+            gateway = createPageCdpGateway(this.host.endpoint, target.targetId, () => !this.closing && !this.unavailableReason && this.targets.has(hostPageId));
+            this.automationGateways.set(hostPageId, gateway);
+            void gateway.catch(() => { if (this.automationGateways.get(hostPageId) === gateway)
+                this.automationGateways.delete(hostPageId); });
+        }
+        return { endpoint: (await gateway).endpoint, engineVersion: this.host.engineVersion, pageTargetId: target.targetId };
+    }
+    acquireAutomationVisibility(hostPageId, canActivate = () => true) {
+        return this.exclusive(async () => {
+            this.ensureAvailable();
+            this.requireTarget(hostPageId);
+            if (!canActivate())
+                return { release: async () => undefined };
+            const previousTargetId = this.activeTargetId;
+            try {
+                await this.host.connection.command("Target.activateTarget", { targetId: hostPageId });
+            }
+            catch (error) {
+                throw this.mapOperationError(error);
+            }
+            let released = false;
+            return {
+                release: async (restoreFocus = true) => {
+                    if (released)
+                        return;
+                    released = true;
+                    await this.exclusive(async () => {
+                        // A user selection or closed generation supersedes the temporary activation.
+                        if (!restoreFocus || !canActivate() || this.closing || this.unavailableReason || !previousTargetId ||
+                            this.activeTargetId !== previousTargetId || !this.targets.has(previousTargetId))
+                            return;
+                        try {
+                            await this.host.connection.command("Target.activateTarget", { targetId: previousTargetId });
+                        }
+                        catch (error) {
+                            throw this.mapOperationError(error);
+                        }
+                    });
+                },
+            };
+        });
+    }
     openSurface(input) {
         return this.exclusive(async () => {
             this.ensureAvailable();
@@ -361,7 +422,8 @@ class HeadlessBrowserHandle {
                 if (url !== "about:blank") {
                     const pageSessionId = await this.pageSession(targetId);
                     await this.host.connection.command("Page.navigate", { url }, pageSessionId);
-                    await this.resetPageNavigationHistory(targetId);
+                    // Leave Chrome's native history intact. Resetting it here can
+                    // discard a pending cross-origin child navigation.
                 }
                 this.eventQueue.changed(this.browserGeneration);
             }
@@ -435,6 +497,8 @@ class HeadlessBrowserHandle {
             return this.closePromise;
         this.closing = true;
         this.closePromise = (async () => {
+            await Promise.allSettled([...this.automationGateways.values()].map(async (gateway) => (await gateway).close()));
+            this.automationGateways.clear();
             await Promise.allSettled([...this.surfaceSources.values()].map((source) => source.close()));
             let terminated = false;
             try {
@@ -483,24 +547,6 @@ class HeadlessBrowserHandle {
             }
         });
     }
-    async resetPageNavigationHistory(targetId) {
-        let lastError;
-        for (let attempt = 0; attempt < PAGE_SNAPSHOT_TRANSITION_ATTEMPTS; attempt += 1) {
-            const sessionId = await this.pageSession(targetId);
-            try {
-                await this.host.connection.command("Page.resetNavigationHistory", {}, sessionId);
-                return;
-            }
-            catch (error) {
-                if (!isMissingTargetError(error) && !isTransientPageTransitionError(error))
-                    throw error;
-                lastError = error;
-                this.dropAttachedSession(sessionId);
-                await delay(PAGE_SNAPSHOT_TRANSITION_POLL_MS);
-            }
-        }
-        throw lastError ?? new Error("Headless Browser could not reset Page navigation history");
-    }
     pageCommand(hostPageId, method, params) {
         return this.exclusive(async () => {
             this.ensureAvailable();
@@ -624,9 +670,11 @@ class HeadlessBrowserHandle {
         for (let attempt = 0; attempt < PAGE_SNAPSHOT_TRANSITION_ATTEMPTS; attempt += 1) {
             let history;
             try {
-                history = parseNavigationHistory(await this.host.connection.command("Page.getNavigationHistory", {}, sessionId));
+                history = parseNavigationHistory(await this.host.connection.command("Page.getNavigationHistory", {}, sessionId, 500));
             }
             catch (error) {
+                if (error instanceof CdpCommandTimeoutError)
+                    break;
                 if (!isTransientPageTransitionError(error))
                     throw error;
                 if (attempt < PAGE_SNAPSHOT_TRANSITION_ATTEMPTS - 1) {
@@ -634,21 +682,14 @@ class HeadlessBrowserHandle {
                 }
                 continue;
             }
-            let ready = "loading";
-            try {
-                ready = parseReadyState(await this.host.connection.command("Runtime.evaluate", { expression: "document.readyState", returnByValue: true }, sessionId));
-            }
-            catch (error) {
-                if (!isTransientPageTransitionError(error))
-                    throw error;
-            }
             const current = history.entries[history.currentIndex];
             const currentTarget = this.targets.get(target.targetId) ?? target;
             return {
                 hostPageId: target.targetId,
                 url: displayUrl(current?.url ?? currentTarget.url),
                 title: displayTitle(currentTarget.title),
-                loading: this.loadingTargets.has(target.targetId) || ready !== "complete",
+                // Renderer JS can be paused by DevTools or beforeunload while Chrome is healthy.
+                loading: this.loadingTargets.has(target.targetId),
                 canGoBack: history.currentIndex > 0,
                 canGoForward: history.currentIndex >= 0 && history.currentIndex < history.entries.length - 1,
             };
@@ -662,6 +703,7 @@ class HeadlessBrowserHandle {
             url: displayUrl((this.targets.get(target.targetId) ?? target).url),
             title: displayTitle((this.targets.get(target.targetId) ?? target).title),
             loading: true,
+            observationStale: true,
             canGoBack: false,
             canGoForward: false,
         };
@@ -704,6 +746,23 @@ class HeadlessBrowserHandle {
     onCdpEvent(event) {
         if (this.closing || this.unavailableReason)
             return;
+        const params = event.params;
+        const identity = { cdpSessionId: event.sessionId, targetId: event.sessionId ? this.targetBySession.get(event.sessionId) : params.targetId };
+        if (["Runtime.exceptionThrown", "Network.loadingFailed", "Target.targetCrashed", "Inspector.detached"].includes(event.method) ||
+            event.method === "Runtime.consoleAPICalled" && ["error", "warning", "assert"].includes(String(params.type))) {
+            this.diagnostic(event.method, { ...identity, details: params });
+        }
+        else if (event.method === "Network.requestWillBeSent") {
+            const request = params.request;
+            this.diagnostic(event.method, { ...identity, requestId: params.requestId, type: params.type, url: request?.url, method: request?.method });
+        }
+        else if (event.method === "Network.responseReceived") {
+            const response = params.response;
+            if (typeof response?.status === "number" && response.status >= 400)
+                this.diagnostic(event.method, {
+                    ...identity, requestId: params.requestId, url: response.url, status: response.status, statusText: response.statusText,
+                });
+        }
         if (event.method === "Fetch.requestPaused" && event.sessionId) {
             void this.continuePausedRequest(event.sessionId, event.params).catch((error) => {
                 if (isMissingFetchRequestError(error))
@@ -855,6 +914,10 @@ class HeadlessBrowserHandle {
         return target;
     }
     dropTarget(targetId) {
+        const gateway = this.automationGateways.get(targetId);
+        this.automationGateways.delete(targetId);
+        if (gateway)
+            void gateway.then((value) => value.close()).catch(() => undefined);
         const surface = this.surfaceSources.get(targetId);
         if (surface) {
             // Stop routing renderer events immediately; close remains best-effort
@@ -923,6 +986,11 @@ class HeadlessBrowserHandle {
                 await this.host.connection.command("Runtime.runIfWaitingForDebugger", {}, sessionId);
             }
             await this.host.connection.command("Network.enable", {}, sessionId);
+            // Enable exception/console observation after paused targets are resumed.
+            // Diagnostics failure must not reject an otherwise usable Page.
+            await this.host.connection.command("Runtime.enable", {}, sessionId).catch((error) => {
+                this.diagnostic("observer.enable_failed", { cdpSessionId: sessionId, error: String(error) });
+            });
         }
         catch (error) {
             if (isMissingTargetError(error) || isTransientPageTransitionError(error)) {
@@ -1031,6 +1099,9 @@ class HeadlessBrowserHandle {
         if (this.closing || this.unavailableReason)
             return;
         this.unavailableReason = reason;
+        for (const gateway of this.automationGateways.values())
+            void gateway.then((value) => value.close()).catch(() => undefined);
+        this.automationGateways.clear();
         for (const source of this.surfaceSources.values())
             source.closeAfterSourceLoss();
         this.host.connection.close();
@@ -1045,7 +1116,10 @@ class HeadlessBrowserHandle {
             this.markUnavailable("The native CDP observer disconnected");
             return unavailable("Headless Browser is unavailable", error);
         }
-        return unavailable("Headless Browser rejected the CDP operation", error);
+        if (error instanceof CdpCommandTimeoutError) {
+            return new SessionBrowserHostError("command_timeout", "Browser command timed out; an accepted action may still complete", { cause: error });
+        }
+        return new SessionBrowserHostError("operation_failed", "Headless Browser rejected the CDP operation", { cause: error });
     }
     exclusive(operation) {
         const result = this.operations.then(operation, operation);
@@ -1165,7 +1239,10 @@ class HeadlessBrowserSurfaceSource {
         this.ensureCurrent();
         const receivedAt = Date.now();
         this.lastScreencastFrameAt = receivedAt;
-        if (receivedAt - this.lastAcceptedFrameAt < this.minimumFrameIntervalMs) {
+        // Throttle immediate deliveries, not replacements behind a slow viewer.
+        // Coalesced CDP messages must still leave the latest paint in the bounded
+        // queue, otherwise its final frame can be permanently dropped.
+        if (receivedAt - this.lastAcceptedFrameAt < this.minimumFrameIntervalMs && !this.frameQueue.hasCurrentFrame()) {
             void acknowledge().catch(() => undefined);
             return;
         }
@@ -1444,6 +1521,7 @@ class LatestSurfaceFrameQueue {
     currentDelivered = false;
     waiter;
     closed = false;
+    hasCurrentFrame() { return this.current !== undefined; }
     push(frame) {
         const entry = this.wrap(frame);
         if (this.closed) {
@@ -1795,7 +1873,7 @@ class CdpConnection {
     setDisconnectHandler(handler) {
         this.disconnectHandler = handler;
     }
-    command(method, params = {}, sessionId) {
+    command(method, params = {}, sessionId, timeoutMs = this.commandTimeoutMs) {
         if (!this.connected)
             return Promise.reject(new CdpDisconnectedError("Native CDP is disconnected"));
         const id = this.nextId++;
@@ -1803,7 +1881,7 @@ class CdpConnection {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 rejectCommand(new CdpCommandTimeoutError(`Native CDP command ${method} timed out`));
-            }, this.commandTimeoutMs);
+            }, Math.min(timeoutMs, this.commandTimeoutMs));
             this.pending.set(id, { method, resolve: resolveCommand, reject: rejectCommand, timer });
             try {
                 this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
@@ -2347,7 +2425,7 @@ function observeProcess(child) {
 }
 function boundedStderr(child) {
     let value = "";
-    child.stderr?.setEncoding("utf8");
+    // Keep the underlying stream binary for the raw diagnostic tee.
     child.stderr?.on("data", (chunk) => {
         value = `${value}${chunk}`.slice(-16_000);
     });
@@ -2419,12 +2497,6 @@ function parseNavigationHistory(value) {
     }
     return { currentIndex, entries };
 }
-function parseReadyState(value) {
-    if (!isRecord(value) || !isRecord(value.result) || typeof value.result.value !== "string") {
-        return "loading";
-    }
-    return value.result.value;
-}
 function displayUrl(value) {
     if (value === "about:blank")
         return value;

package/dist/log-files.d.ts

@@ -0,0 +1,9 @@
+import { type AgentSessionRecord, type MachineSessionRecord } from "@rynx-ai/core";
+import type { PluginLogFileRoot } from "@rynx-ai/plugin-sdk";
+/** Node-wide files are intentionally separate from Session ownership. Plugins
+ * are installed local code; their remote-facing adapter must authorize node
+ * diagnostics, not merely task visibility, before calling this method. */
+export declare function nodeLogFiles(): Promise<PluginLogFileRoot[]>;
+/** Roots only: the off-process collector walks files. One Session per RPC
+ * bounds control messages independently of file count and file sizes. */
+export declare function sessionLogFiles(session: MachineSessionRecord, binding: AgentSessionRecord | null): Promise<PluginLogFileRoot[]>;

package/dist/log-files.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { tmpdir } from "node:os";
+import { access, readdir, readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { rynxHome, sessionDiagnosticDir } from "@rynx-ai/core";
+import { dbPath } from "./db.js";
+const family = (file) => [file, ...["-wal", "-shm", "-journal"].map((suffix) => file + suffix)];
+const root = (source, file, scope, optional = false) => {
+    const rel = relative(rynxHome(), file).split(sep).join("/");
+    return { source, path: file, scope, optional, archivePath: !rel.startsWith("../") && !isAbsolute(rel)
+            ? `files/rynx/${rel}` : `files/external-logs/${createHash("sha256").update(dirname(file)).digest("hex")}/${basename(file)}` };
+};
+/** Node-wide files are intentionally separate from Session ownership. Plugins
+ * are installed local code; their remote-facing adapter must authorize node
+ * diagnostics, not merely task visibility, before calling this method. */
+export async function nodeLogFiles() {
+    const logs = join(rynxHome(), "logs");
+    const files = (await readdir(logs).catch(() => []))
+        .filter((name) => /^(?:(?:out|err)|daemon\.(?:out|err))\.log(?:[.-].+)?$/.test(name));
+    return [
+        ...files.map((name) => root("daemon", join(logs, name), "host")),
+        root("browser", join(rynxHome(), "logs", "browser", "host"), "host", true),
+        ...family(dbPath()).map((file, i) => root("rynx-db", file, "host", i > 0)),
+    ];
+}
+/** Roots only: the off-process collector walks files. One Session per RPC
+ * bounds control messages independently of file count and file sizes. */
+export async function sessionLogFiles(session, binding) {
+    const extended = binding;
+    const state = (id) => join(rynxHome(), "runtime", "sessions", createHash("sha256").update(id).digest("hex").slice(0, 32));
+    const owner = extended?.runtimeHomeOwnerSessionId || session.id;
+    let home = state(owner);
+    const provider = session.execution.provider;
+    const legacy = join(tmpdir(), `rynx-${process.getuid?.() ?? "nouid"}`);
+    const exists = (file) => access(file).then(() => true, () => false);
+    const nativeName = provider === "codex" ? "codex-home" : "trae-home";
+    if (!(await exists(join(home, nativeName)))) {
+        const old = join(legacy, provider === "codex" ? "codex-native" : "traex-native", createHash("sha256").update(owner).digest("hex").slice(0, 32));
+        if (await exists(join(old, nativeName)))
+            home = old;
+    }
+    const result = [
+        root("runtime", sessionDiagnosticDir("runtime", session.id), "session", true),
+        root("browser", sessionDiagnosticDir("browser", session.id), "session", true),
+        root("browser", join(rynxHome(), "logs", "browser", "host"), "host", true),
+    ];
+    if (owner !== session.id)
+        result.push(root("runtime", sessionDiagnosticDir("runtime", owner), "runtime_home", true));
+    if (provider === "codex" || provider === "traex") {
+        const native = join(home, provider === "codex" ? "codex-home" : "trae-home");
+        const cli = provider === "codex" ? native : join(native, "cli");
+        result.push(root("runtime", join(native, "sessions"), "runtime_home"));
+        result.push(root("runtime", join(cli, "log"), "runtime_home", true));
+        for (const file of family(join(cli, "logs_2.sqlite")))
+            result.push(root("runtime-db", file, "runtime_home", true));
+    }
+    else if (provider === "claude") {
+        const bridgeOwner = extended?.bridgeOwnerSessionId || owner;
+        let bridge = join(state(bridgeOwner), "claude-bridge");
+        if (!(await exists(bridge))) {
+            const old = join(legacy, "claude-native", createHash("sha256").update(bridgeOwner).digest("hex").slice(0, 32));
+            if (await exists(old))
+                bridge = old;
+        }
+        for (const name of ["hooks.jsonl", "state.json", "message_deltas.jsonl", "interactions.jsonl", "interaction-acks.jsonl", "interaction-results", "history"]) {
+            result.push(root("runtime", join(bridge, name), "session", true));
+        }
+        const transcripts = new Set();
+        const note = (value) => { if (typeof value === "string" && isAbsolute(value))
+            transcripts.add(value); };
+        const bridges = [bridge, ...(await readdir(join(bridge, "history")).catch(() => [])).map((id) => join(bridge, "history", id))];
+        for (const directory of bridges) {
+            try {
+                note(JSON.parse(await readFile(join(directory, "state.json"), "utf8")).transcriptPath);
+            }
+            catch { /* older/never-started */ }
+            try {
+                const lines = createInterface({ input: createReadStream(join(directory, "hooks.jsonl")), crlfDelay: Infinity });
+                for await (const line of lines) {
+                    try {
+                        note(JSON.parse(line).payload?.transcript_path);
+                    }
+                    catch { /* partial live line */ }
+                }
+            }
+            catch { /* original files and collection warnings still report unreadable sources */ }
+        }
+        for (const transcript of transcripts) {
+            result.push(root("runtime", transcript, "session"));
+            result.push(root("runtime", join(dirname(transcript), basename(transcript, ".jsonl"), "subagents"), "session", true));
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,6 @@
+/** A helper epoch owns one transport connection. An upstream CLI must not
+ * silently restart and execute a write against this epoch's borrowed Page. */
+export declare function createPageAgentBrowserConnection(endpoint: string, isCurrent: () => boolean): Promise<{
+    endpoint: string;
+    close(): Promise<void>;
+}>;

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

@@ -0,0 +1,71 @@
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import WebSocket, { WebSocketServer } from "ws";
+/** A helper epoch owns one transport connection. An upstream CLI must not
+ * silently restart and execute a write against this epoch's borrowed Page. */
+export async function createPageAgentBrowserConnection(endpoint, isCurrent) {
+    const noncePath = "/devtools/browser/" + randomBytes(18).toString("hex");
+    const limit = 8 * 1024 * 1024;
+    let used = false, closed = false, authority = "";
+    let client, upstream;
+    const server = createServer((_request, response) => { response.writeHead(404).end(); });
+    const sockets = new WebSocketServer({ noServer: true, maxPayload: limit });
+    const disconnect = () => { client?.terminate(); upstream?.terminate(); };
+    server.on("upgrade", (request, socket, head) => {
+        if (closed || used || !isCurrent() || request.url !== noncePath || request.headers.origin !== undefined || request.headers.host !== authority) {
+            socket.destroy();
+            return;
+        }
+        used = true;
+        sockets.handleUpgrade(request, socket, head, (downstream) => {
+            client = downstream;
+            const native = new WebSocket(endpoint, { maxPayload: limit, handshakeTimeout: 5_000 });
+            upstream = native;
+            const early = [];
+            let buffered = 0;
+            downstream.on("close", disconnect);
+            downstream.on("error", disconnect);
+            native.on("close", disconnect);
+            native.on("error", disconnect);
+            downstream.on("message", (bytes, binary) => {
+                if (binary || !isCurrent() || native.bufferedAmount > limit) {
+                    disconnect();
+                    return;
+                }
+                const data = Buffer.from(bytes.toString());
+                if (native.readyState === WebSocket.OPEN)
+                    native.send(data, { binary: false });
+                else if (native.readyState === WebSocket.CONNECTING && early.length < 64 && buffered + data.length <= limit) {
+                    early.push(data);
+                    buffered += data.length;
+                }
+                else
+                    disconnect();
+            });
+            native.on("open", () => { for (const bytes of early)
+                native.send(bytes, { binary: false }); early.length = 0; buffered = 0; });
+            native.on("message", (bytes, binary) => {
+                if (binary || !isCurrent() || downstream.readyState !== WebSocket.OPEN || downstream.bufferedAmount > limit) {
+                    disconnect();
+                    return;
+                }
+                downstream.send(bytes, { binary: false });
+            });
+        });
+    });
+    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("Browser helper capability did not bind");
+    authority = "127.0.0.1:" + address.port;
+    return { endpoint: "ws://" + authority + noncePath, async close() {
+            if (closed)
+                return;
+            closed = true;
+            disconnect();
+            await Promise.all([new Promise((r) => sockets.close(() => r())), new Promise((r) => server.close(() => r()))]);
+        } };
+}

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

@@ -0,0 +1,14 @@
+import type { SessionBrowserAutomationBinding } from "@rynx-ai/server";
+export declare const PAGE_AGENT_BROWSER_VERSION = "0.36.0";
+export declare class PageAutomationError extends Error {
+    readonly code: "invalid_request" | "human_control_active" | "driver_restarted" | "outcome_unknown" | "command_failed" | "capacity" | "not_found";
+    constructor(code: "invalid_request" | "human_control_active" | "driver_restarted" | "outcome_unknown" | "command_failed" | "capacity" | "not_found", message: string, options?: ErrorOptions);
+}
+export interface PageAutomationDriver {
+    readonly version?: string;
+    execute(args: string[], beforeInvoke?: () => void): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+/** Resolve only the pinned dependency. Never use a PATH/global helper or run its Node wrapper. */
+export declare function pageAgentBrowserBinary(): string;
+export declare function createPageAgentBrowserDriver(root: string, binding: SessionBrowserAutomationBinding): Promise<PageAutomationDriver>;