@rynx-ai/server 0.1.0 → 0.1.10-beta.2

package/dist/desktop-browser-host.js

@@ -0,0 +1,1018 @@
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS, DESKTOP_BROWSER_HOST_MAX_QUEUED_EVENTS, DESKTOP_BROWSER_HOST_PATH, DESKTOP_BROWSER_HOST_PROTOCOL_VERSION, parseDesktopBrowserHostCdpEndpointResult, parseDesktopBrowserHostClientFrame, parseDesktopBrowserHostCompletedResult, parseDesktopBrowserHostCreateResult, parseDesktopBrowserHostPageCdpEndpointResult, parseDesktopBrowserHostSurfaceFrame, parseDesktopBrowserHostSurfaceOpenResult, parseDesktopBrowserHostSnapshot, } from "@rynx-ai/protocol/desktop-browser-host";
+import { WebSocket, WebSocketServer } from "ws";
+import { SessionBrowserHostError, SessionBrowserSurfaceUnsupportedError, } from "./session-browser-service.js";
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000;
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000;
+const MAX_SOCKET_BUFFERED_BYTES = 1 * 1024 * 1024;
+const CLOSE_BAD_PROTOCOL = 4400;
+const CLOSE_UNSUPPORTED = 4406;
+const CLOSE_BACKPRESSURE = 4408;
+const CLOSE_REPLACED_OR_STALE = 4409;
+/**
+ * The daemon-side physical Browser Host. It is safe to construct before the
+ * HTTP server exists; an authenticated desktop socket makes it live later.
+ */
+export class DesktopBrowserHostRegistry {
+    commandTimeoutMilliseconds;
+    now;
+    idFactory;
+    handles = new Map();
+    connectedListeners = new Set();
+    leases = new Map();
+    idSequence = 0;
+    constructor(options = {}) {
+        this.commandTimeoutMilliseconds = boundedDuration(options.commandTimeoutMilliseconds ?? DEFAULT_COMMAND_TIMEOUT_MS, "commandTimeoutMilliseconds");
+        this.now = options.now ?? Date.now;
+        this.idFactory = options.idFactory ?? randomUUID;
+    }
+    get connected() {
+        return this.currentLeases().length > 0;
+    }
+    get directConnected() {
+        return this.currentLease("direct") !== undefined;
+    }
+    /** Runs after a fresh lease frame has been queued to the Host. Listener
+     * failures are isolated from the authenticated Host handshake. */
+    onConnected(listener) {
+        this.connectedListeners.add(listener);
+        return () => this.connectedListeners.delete(listener);
+    }
+    async createBrowser(input) {
+        const lease = this.requireLease();
+        try {
+            const result = await this.request(lease, {
+                method: "browser.create",
+                sessionId: input.sessionId,
+                browserGeneration: input.browserGeneration,
+                ...(input.url === undefined ? {} : { url: input.url }),
+            }, parseDesktopBrowserHostCreateResult);
+            if (!this.isCurrentLease(lease)) {
+                throw commandOutcomeError({ method: "browser.create", sessionId: input.sessionId, browserGeneration: input.browserGeneration }, "Desktop Browser Host create outcome is unknown after lease loss");
+            }
+            const key = browserKey(input.sessionId, input.browserGeneration);
+            const existing = this.handles.get(key);
+            if (existing) {
+                await this.request(lease, { method: "browser.close", sessionId: input.sessionId, browserGeneration: input.browserGeneration }, parseDesktopBrowserHostCompletedResult).catch(() => undefined);
+                throw new Error("Desktop Browser Host returned a duplicate Browser generation");
+            }
+            const handle = new DesktopBrowserHandle(this, lease, input, result.capabilities);
+            this.handles.set(key, handle);
+            return handle;
+        }
+        finally {
+            this.retireOffscreenIfIdle();
+        }
+    }
+    async deleteSessionData(sessionId) {
+        const attemptedPresentations = new Set();
+        const failures = [];
+        let attempted = false;
+        while (true) {
+            const leases = this.currentLeases()
+                .filter((lease) => !attemptedPresentations.has(lease.presentation));
+            if (leases.length === 0)
+                break;
+            attempted = true;
+            for (const lease of leases) {
+                attemptedPresentations.add(lease.presentation);
+            }
+            const results = await Promise.allSettled(leases.map((lease) => this.request(lease, { method: "browser.delete-data", sessionId }, parseDesktopBrowserHostCompletedResult)));
+            failures.push(...results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason));
+        }
+        this.retireOffscreenIfIdle();
+        if (!attempted)
+            throw new DesktopBrowserHostAbsentError();
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 0) {
+            throw new AggregateError(failures, "Desktop Browser Host profile cleanup failed");
+        }
+    }
+    /** Attachment-only: installs one lease per presentation role. Existing
+     * generations stay pinned to their Host while new generations prefer the
+     * direct App-window Host. */
+    acceptConnection(socket, hello, daemonInstanceId, heartbeatIntervalMilliseconds) {
+        const presentation = hello.capabilities.presentation;
+        const direct = this.currentLease("direct");
+        if (presentation === "offscreen" &&
+            direct) {
+            throw new DesktopBrowserHostProtocolError("an offscreen Desktop Browser Host is unnecessary while the direct Host is active", CLOSE_REPLACED_OR_STALE);
+        }
+        const previous = this.installedLease(presentation);
+        if (previous) {
+            this.detach(previous, hostUnavailable("Desktop Browser Host lease was replaced"));
+            closeSocket(previous.socket, CLOSE_REPLACED_OR_STALE, "Desktop Browser Host lease replaced");
+        }
+        const lease = {
+            leaseId: this.nextId("lease"),
+            daemonInstanceId,
+            hostInstanceId: hello.hostInstanceId,
+            presentation: hello.capabilities.presentation,
+            semanticPageBinding: hello.capabilities.semanticPageBinding,
+            surface: hello.capabilities.surface,
+            socket,
+            pending: new Map(),
+            nextEventSequence: 1,
+            detached: false,
+        };
+        this.leases.set(presentation, lease);
+        if (presentation === "direct")
+            this.retireOffscreenIfIdle();
+        queueMicrotask(() => {
+            if (!this.isCurrentLease(lease))
+                return;
+            for (const listener of this.connectedListeners) {
+                void Promise.resolve().then(listener).catch(() => undefined);
+            }
+        });
+        return {
+            type: "desktop.browser.host.lease",
+            protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+            leaseId: lease.leaseId,
+            daemonInstanceId,
+            commandTimeoutMilliseconds: this.commandTimeoutMilliseconds,
+            heartbeatIntervalMilliseconds,
+            capabilities: {
+                semanticPageBinding: hello.capabilities.semanticPageBinding,
+                surface: hello.capabilities.surface,
+            },
+        };
+    }
+    /** Attachment-only: validates lease scope before routing a client frame. */
+    receive(leaseId, frame) {
+        const lease = this.leaseById(leaseId);
+        if (!lease || frame.leaseId !== leaseId) {
+            throw new DesktopBrowserHostProtocolError("frame belongs to a stale lease", CLOSE_REPLACED_OR_STALE);
+        }
+        if (frame.type === "desktop.browser.host.reply") {
+            this.receiveReply(lease, frame);
+            return;
+        }
+        this.receiveEvent(lease, frame.eventSequence, frame.event);
+    }
+    /** Attachment-only: routes a fully identity-bound image envelope to one active Surface. */
+    receiveBinary(leaseId, frame) {
+        const lease = this.leaseById(leaseId);
+        if (!lease || lease.surface !== "binary-v1" || frame.leaseId !== leaseId) {
+            throw new DesktopBrowserHostProtocolError("binary frame belongs to a stale or unsupported lease", CLOSE_REPLACED_OR_STALE);
+        }
+        const handle = this.handles.get(browserKey(frame.sessionId, frame.browserGeneration));
+        if (!handle || handle.leaseId !== leaseId || !handle.available) {
+            throw new DesktopBrowserHostProtocolError("binary frame targets a stale Browser generation", CLOSE_REPLACED_OR_STALE);
+        }
+        handle.receiveSurfaceFrame(frame);
+    }
+    /** Attachment-only and identity-fenced: an old close cannot clear a new lease. */
+    disconnect(leaseId, reason = "Desktop Browser Host disconnected") {
+        const lease = this.installedLeaseById(leaseId);
+        if (!lease)
+            return;
+        this.detach(lease, hostUnavailable(reason));
+    }
+    async commandForHandle(handle, command, parseResult) {
+        const lease = this.requireCurrentHandle(handle);
+        return this.request(lease, command, parseResult);
+    }
+    forgetHandle(handle) {
+        const key = browserKey(handle.sessionId, handle.browserGeneration);
+        if (this.handles.get(key) === handle)
+            this.handles.delete(key);
+        this.retireOffscreenIfIdle();
+    }
+    createId(label) {
+        return this.nextId(label);
+    }
+    requireLease() {
+        const lease = this.currentLease("direct") ?? this.currentLease("offscreen");
+        if (!lease)
+            throw new DesktopBrowserHostAbsentError();
+        return lease;
+    }
+    requireCurrentHandle(handle) {
+        const lease = this.leaseById(handle.leaseId);
+        if (!lease ||
+            this.handles.get(browserKey(handle.sessionId, handle.browserGeneration)) !== handle ||
+            !handle.available)
+            throw hostUnavailable("Desktop Browser Host generation is unavailable");
+        return lease;
+    }
+    request(lease, command, parseResult) {
+        if (!this.isCurrentLease(lease)) {
+            return Promise.reject(command.method === "browser.create"
+                ? new DesktopBrowserHostAbsentError()
+                : hostUnavailable("Desktop Browser Host lease ended"));
+        }
+        if (lease.pending.size >= DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS) {
+            this.failLease(lease, CLOSE_BACKPRESSURE, "Desktop Browser Host command capacity exceeded");
+            return Promise.reject(new SessionBrowserHostError("capacity", "Desktop Browser Host command capacity exceeded"));
+        }
+        const commandId = this.nextId("command");
+        const deadlineUnixMilliseconds = this.now() + this.commandTimeoutMilliseconds;
+        const frame = {
+            type: "desktop.browser.host.command",
+            protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+            leaseId: lease.leaseId,
+            commandId,
+            deadlineUnixMilliseconds,
+            command,
+        };
+        const encoded = JSON.stringify(frame);
+        const encodedBytes = Buffer.byteLength(encoded, "utf8");
+        if (encodedBytes > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES ||
+            lease.socket.bufferedAmount + encodedBytes > MAX_SOCKET_BUFFERED_BYTES) {
+            this.failLease(lease, CLOSE_BACKPRESSURE, "Desktop Browser Host output capacity exceeded");
+            return Promise.reject(new SessionBrowserHostError("capacity", "Desktop Browser Host output capacity exceeded"));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const pending = lease.pending.get(commandId);
+                if (!pending)
+                    return;
+                lease.pending.delete(commandId);
+                reject(commandOutcomeError(command, `Desktop Browser Host ${command.method} timed out`));
+                if (!isReadOnlyCommand(command)) {
+                    this.failLease(lease, CLOSE_REPLACED_OR_STALE, `Desktop Browser Host ${command.method} outcome is unknown`);
+                }
+            }, this.commandTimeoutMilliseconds);
+            timer.unref?.();
+            lease.pending.set(commandId, {
+                command,
+                deadlineUnixMilliseconds,
+                parseResult,
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+            try {
+                lease.socket.send(encoded);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                lease.pending.delete(commandId);
+                this.failLease(lease, CLOSE_BACKPRESSURE, "Desktop Browser Host command could not be sent");
+                reject(commandOutcomeError(command, "Desktop Browser Host command could not be sent", error));
+            }
+        });
+    }
+    nextId(label) {
+        if (this.idSequence >= Number.MAX_SAFE_INTEGER) {
+            throw new SessionBrowserHostError("capacity", "Desktop Browser Host identity space is exhausted");
+        }
+        this.idSequence += 1;
+        const base = opaqueServerId(this.idFactory(), `${label} id`);
+        const value = `${base}.${this.idSequence.toString(36)}`;
+        return opaqueServerId(value, `${label} id`);
+    }
+    receiveReply(lease, frame) {
+        const pending = lease.pending.get(frame.commandId);
+        if (!pending) {
+            throw new DesktopBrowserHostProtocolError("reply commandId is unknown or expired", CLOSE_REPLACED_OR_STALE);
+        }
+        lease.pending.delete(frame.commandId);
+        clearTimeout(pending.timer);
+        if (this.now() >= pending.deadlineUnixMilliseconds) {
+            pending.reject(commandOutcomeError(pending.command, `Desktop Browser Host ${pending.command.method} replied after its deadline`));
+            if (!isReadOnlyCommand(pending.command)) {
+                this.failLease(lease, CLOSE_REPLACED_OR_STALE, `Desktop Browser Host ${pending.command.method} outcome is unknown`);
+            }
+            return;
+        }
+        if (!frame.ok) {
+            pending.reject(mapReplyError(frame, pending.command));
+            return;
+        }
+        try {
+            pending.resolve(pending.parseResult(frame.result));
+        }
+        catch (error) {
+            pending.reject(error);
+            this.failLease(lease, CLOSE_BAD_PROTOCOL, "Desktop Browser Host result is malformed");
+        }
+    }
+    receiveEvent(lease, eventSequence, event) {
+        if (eventSequence !== lease.nextEventSequence) {
+            throw new DesktopBrowserHostProtocolError("event sequence is stale or discontinuous", CLOSE_REPLACED_OR_STALE);
+        }
+        lease.nextEventSequence += 1;
+        const handle = this.handles.get(browserKey(event.sessionId, event.browserGeneration));
+        if (!handle || handle.leaseId !== lease.leaseId || !handle.available) {
+            throw new DesktopBrowserHostProtocolError("event targets a stale Browser generation", CLOSE_REPLACED_OR_STALE);
+        }
+        if (event.event === "surface.closed") {
+            handle.receiveSurfaceClosed(event.hostPageId, event.surfaceId, event.reason);
+            return;
+        }
+        const hostEvent = toSessionBrowserHostEvent(event);
+        if (!handle.pushEvent(hostEvent)) {
+            this.failLease(lease, CLOSE_BACKPRESSURE, "Desktop Browser Host event capacity exceeded");
+            return;
+        }
+        if (event.event === "unavailable") {
+            handle.markUnavailable();
+            this.forgetHandle(handle);
+            this.rejectCommandsFor(lease, event.sessionId, event.browserGeneration);
+        }
+    }
+    rejectCommandsFor(lease, sessionId, generation) {
+        for (const [commandId, pending] of lease.pending) {
+            if ("browserGeneration" in pending.command &&
+                pending.command.sessionId === sessionId &&
+                pending.command.browserGeneration === generation) {
+                lease.pending.delete(commandId);
+                clearTimeout(pending.timer);
+                pending.reject(commandOutcomeError(pending.command, "Desktop Browser Host generation became unavailable"));
+            }
+        }
+    }
+    failLease(lease, code, reason) {
+        if (this.isInstalledLease(lease))
+            this.detach(lease, hostUnavailable(reason));
+        closeSocket(lease.socket, code, reason);
+    }
+    detach(lease, error) {
+        if (lease.detached)
+            return;
+        lease.detached = true;
+        if (this.leases.get(lease.presentation) === lease) {
+            this.leases.delete(lease.presentation);
+        }
+        for (const pending of lease.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(commandOutcomeError(pending.command, error.message, error));
+        }
+        lease.pending.clear();
+        for (const handle of [...this.handles.values()]) {
+            if (handle.leaseId !== lease.leaseId)
+                continue;
+            handle.disconnect(error.message);
+            this.forgetHandle(handle);
+        }
+    }
+    currentLease(presentation) {
+        const lease = this.installedLease(presentation);
+        return lease && this.isCurrentLease(lease) ? lease : undefined;
+    }
+    currentLeases() {
+        return [...this.leases.values()].filter((lease) => this.isCurrentLease(lease));
+    }
+    leaseById(leaseId) {
+        return this.currentLeases().find((lease) => lease.leaseId === leaseId);
+    }
+    installedLease(presentation) {
+        const lease = this.leases.get(presentation);
+        return lease && this.isInstalledLease(lease) ? lease : undefined;
+    }
+    installedLeaseById(leaseId) {
+        return [...this.leases.values()].find((lease) => lease.leaseId === leaseId && this.isInstalledLease(lease));
+    }
+    isInstalledLease(lease) {
+        return !lease.detached && this.leases.get(lease.presentation) === lease;
+    }
+    isCurrentLease(lease) {
+        return this.isInstalledLease(lease) &&
+            lease.socket.readyState === WebSocket.OPEN;
+    }
+    retireOffscreenIfIdle() {
+        if (!this.directConnected)
+            return;
+        const offscreen = this.currentLease("offscreen");
+        if (!offscreen || offscreen.pending.size > 0)
+            return;
+        if ([...this.handles.values()].some((handle) => handle.available && handle.leaseId === offscreen.leaseId))
+            return;
+        this.detach(offscreen, hostUnavailable("Desktop Browser offscreen Host became idle"));
+        closeSocket(offscreen.socket, CLOSE_REPLACED_OR_STALE, "Desktop Browser offscreen Host became idle");
+    }
+}
+export class DesktopBrowserHostProtocolError extends Error {
+    closeCode;
+    constructor(message, closeCode = CLOSE_BAD_PROTOCOL) {
+        super(message);
+        this.closeCode = closeCode;
+        this.name = "DesktopBrowserHostProtocolError";
+    }
+}
+/** The only condition under which desktop-first composition may use Headless. */
+export class DesktopBrowserHostAbsentError extends SessionBrowserHostError {
+    constructor() {
+        super("unavailable", "Desktop Browser Host is not connected");
+        this.name = "DesktopBrowserHostAbsentError";
+    }
+}
+export function attachDesktopBrowserHostServer(server, options) {
+    assertManagementToken(options.managementToken);
+    const daemonInstanceId = opaqueServerId(options.daemonInstanceId, "daemonInstanceId");
+    const heartbeatIntervalMilliseconds = boundedDuration(options.heartbeatIntervalMilliseconds ?? DEFAULT_HEARTBEAT_INTERVAL_MS, "heartbeatIntervalMilliseconds");
+    const handshakeTimeoutMilliseconds = boundedDuration(options.handshakeTimeoutMilliseconds ?? DEFAULT_HANDSHAKE_TIMEOUT_MS, "handshakeTimeoutMilliseconds");
+    const wss = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+        maxPayload: DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES,
+    });
+    const handleUpgrade = (request, socket, head) => {
+        let url;
+        try {
+            url = new URL(request.url ?? "", "http://127.0.0.1");
+        }
+        catch {
+            return;
+        }
+        if (url.pathname !== DESKTOP_BROWSER_HOST_PATH)
+            return;
+        if (url.search.length > 0 || url.hash.length > 0) {
+            rejectUpgrade(socket, 400, "Desktop Browser Host path does not accept query parameters");
+            return;
+        }
+        if (!isLoopbackAddress(request.socket.remoteAddress)) {
+            rejectUpgrade(socket, 403, "daemon management is loopback-only");
+            return;
+        }
+        const token = singleHeader(request.headers["x-rynx-management-token"]);
+        if (!safeTokenEquals(token ?? "", options.managementToken)) {
+            rejectUpgrade(socket, 401, "invalid daemon management token");
+            return;
+        }
+        try {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                handleDesktopConnection(ws, {
+                    registry: options.registry,
+                    daemonInstanceId,
+                    heartbeatIntervalMilliseconds,
+                    handshakeTimeoutMilliseconds,
+                });
+            });
+        }
+        catch {
+            rejectUpgrade(socket, 400, "invalid Desktop Browser Host WebSocket upgrade");
+        }
+    };
+    server.on("upgrade", handleUpgrade);
+    wss.once("close", () => server.removeListener("upgrade", handleUpgrade));
+    return wss;
+}
+export function createDesktopFirstSessionBrowserHost(desktop, fallback) {
+    return new DesktopFirstSessionBrowserHost(desktop, fallback);
+}
+class DesktopFirstSessionBrowserHost {
+    desktop;
+    fallback;
+    constructor(desktop, fallback) {
+        this.desktop = desktop;
+        this.fallback = fallback;
+    }
+    async createBrowser(input) {
+        try {
+            return await this.desktop.createBrowser(input);
+        }
+        catch (error) {
+            if (!(error instanceof DesktopBrowserHostAbsentError))
+                throw error;
+            return this.fallback.createBrowser(input);
+        }
+    }
+    async deleteSessionData(sessionId) {
+        const attempts = [this.desktop.deleteSessionData, this.fallback.deleteSessionData]
+            .map((operation, index) => operation
+            ? Promise.resolve().then(() => operation.call(index === 0 ? this.desktop : this.fallback, sessionId))
+            : Promise.resolve());
+        const results = await Promise.allSettled(attempts);
+        const failures = results
+            .filter((result) => result.status === "rejected")
+            .map((result) => result.reason);
+        if (failures.length > 0)
+            throw new AggregateError(failures, "Browser session data deletion failed");
+    }
+}
+class DesktopBrowserHandle {
+    registry;
+    lease;
+    browserGeneration;
+    executionBackend = "embedded-electron";
+    capabilities;
+    events;
+    leaseId;
+    sessionId;
+    available = true;
+    closed = false;
+    surfaces = new Map();
+    openingSurfaces = new Set();
+    eventQueue = new BoundedAsyncQueue(DESKTOP_BROWSER_HOST_MAX_QUEUED_EVENTS);
+    constructor(registry, lease, input, capabilities) {
+        this.registry = registry;
+        this.lease = lease;
+        this.leaseId = lease.leaseId;
+        this.sessionId = input.sessionId;
+        this.browserGeneration = input.browserGeneration;
+        this.capabilities = [...capabilities];
+        this.events = this.eventQueue;
+    }
+    getCdpEndpoint() {
+        return this.command({ method: "browser.cdp-endpoint", ...this.generationScope() }, parseDesktopBrowserHostCdpEndpointResult);
+    }
+    getPageCdpEndpoint(hostPageId) {
+        return this.command({ method: "page.cdp-endpoint", ...this.pageScope(hostPageId) }, parseDesktopBrowserHostPageCdpEndpointResult);
+    }
+    async openSurface(input) {
+        if (this.lease.surface !== "binary-v1") {
+            throw new SessionBrowserSurfaceUnsupportedError();
+        }
+        if (input.browserGeneration !== this.browserGeneration) {
+            throw new SessionBrowserHostError("unavailable", "Desktop Browser Host generation is stale");
+        }
+        input.signal?.throwIfAborted();
+        if (this.surfaces.has(input.hostPageId) || this.openingSurfaces.has(input.hostPageId)) {
+            throw new SessionBrowserHostError("capacity", "Desktop Browser Host Page already has an active Surface");
+        }
+        const surfaceId = this.registry.createId("surface");
+        this.openingSurfaces.add(input.hostPageId);
+        let result;
+        try {
+            result = await this.command({
+                method: "surface.open",
+                ...this.pageScope(input.hostPageId),
+                surfaceId,
+                format: input.format,
+                quality: input.quality,
+                maximumFrameRate: input.maximumFrameRate,
+            }, (value) => {
+                const parsed = parseDesktopBrowserHostSurfaceOpenResult(value);
+                if (parsed.format !== input.format) {
+                    throw new TypeError("surface.open changed the negotiated format");
+                }
+                return parsed;
+            });
+        }
+        finally {
+            this.openingSurfaces.delete(input.hostPageId);
+        }
+        const source = new DesktopBrowserSurfaceSource(this, input.hostPageId, surfaceId, result);
+        this.surfaces.set(input.hostPageId, source);
+        if (input.signal?.aborted) {
+            await source.close().catch(() => undefined);
+            input.signal.throwIfAborted();
+        }
+        return source;
+    }
+    snapshot() {
+        return this.command({ method: "browser.snapshot", ...this.generationScope() }, parseDesktopBrowserHostSnapshot);
+    }
+    async createPage(url) {
+        await this.completed({ method: "page.create", ...this.generationScope(), ...(url === undefined ? {} : { url }) });
+    }
+    async closePage(hostPageId) {
+        await this.surfaces.get(hostPageId)?.close().catch(() => undefined);
+        await this.completed({ method: "page.close", ...this.pageScope(hostPageId) });
+    }
+    async activatePage(hostPageId) {
+        await this.completed({ method: "page.activate", ...this.pageScope(hostPageId) });
+    }
+    async navigatePage(hostPageId, url) {
+        await this.completed({ method: "page.navigate", ...this.pageScope(hostPageId), url });
+    }
+    async goBack(hostPageId) {
+        await this.completed({ method: "page.back", ...this.pageScope(hostPageId) });
+    }
+    async goForward(hostPageId) {
+        await this.completed({ method: "page.forward", ...this.pageScope(hostPageId) });
+    }
+    async reload(hostPageId) {
+        await this.completed({ method: "page.reload", ...this.pageScope(hostPageId) });
+    }
+    async bindPage(hostPageId, pageId) {
+        if (!this.lease.semanticPageBinding)
+            return;
+        await this.completed({ method: "page.bind", ...this.pageScope(hostPageId), pageId });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            await Promise.allSettled([...this.surfaces.values()].map((surface) => surface.close()));
+            if (this.available) {
+                await this.completed({ method: "browser.close", ...this.generationScope() });
+            }
+        }
+        finally {
+            this.available = false;
+            this.registry.forgetHandle(this);
+            this.eventQueue.end();
+        }
+    }
+    pushEvent(event) {
+        return this.eventQueue.push(event);
+    }
+    markUnavailable() {
+        this.available = false;
+        for (const surface of [...this.surfaces.values()])
+            surface.hostDisconnected();
+        this.surfaces.clear();
+        this.eventQueue.end();
+    }
+    disconnect(reason) {
+        if (!this.available)
+            return;
+        this.eventQueue.push({ type: "unavailable", browserGeneration: this.browserGeneration, reason });
+        this.markUnavailable();
+    }
+    receiveSurfaceFrame(frame) {
+        const surface = this.surfaces.get(frame.hostPageId);
+        if (!surface || surface.surfaceId !== frame.surfaceId) {
+            throw new DesktopBrowserHostProtocolError("binary frame targets an inactive Surface", CLOSE_REPLACED_OR_STALE);
+        }
+        surface.receiveFrame(frame);
+    }
+    receiveSurfaceClosed(hostPageId, surfaceId, reason) {
+        const surface = this.surfaces.get(hostPageId);
+        if (!surface || surface.surfaceId !== surfaceId) {
+            throw new DesktopBrowserHostProtocolError("surface.closed targets an inactive Surface", CLOSE_REPLACED_OR_STALE);
+        }
+        surface.hostClosed(reason);
+    }
+    forgetSurface(surface) {
+        if (this.surfaces.get(surface.hostPageId) === surface)
+            this.surfaces.delete(surface.hostPageId);
+    }
+    generationScope() {
+        return { sessionId: this.sessionId, browserGeneration: this.browserGeneration };
+    }
+    pageScope(hostPageId) {
+        return { ...this.generationScope(), hostPageId };
+    }
+    completed(command) {
+        return this.command(command, parseDesktopBrowserHostCompletedResult);
+    }
+    surfaceCompleted(command) {
+        return this.completed(command);
+    }
+    command(command, parseResult) {
+        return this.registry.commandForHandle(this, command, parseResult);
+    }
+}
+class DesktopBrowserSurfaceSource {
+    handle;
+    hostPageId;
+    surfaceId;
+    browserGeneration;
+    format;
+    frames;
+    frameQueue = new BoundedAsyncQueue(1);
+    viewport;
+    pendingFrameSequence;
+    lastFrameSequence = -1;
+    inputSequence = -1;
+    driver = "desktop";
+    closed = false;
+    closePromise;
+    constructor(handle, hostPageId, surfaceId, result) {
+        this.handle = handle;
+        this.hostPageId = hostPageId;
+        this.surfaceId = surfaceId;
+        this.browserGeneration = handle.browserGeneration;
+        this.format = result.format;
+        this.viewport = {
+            revision: result.viewportRevision,
+            width: result.width,
+            height: result.height,
+            deviceScaleFactor: result.deviceScaleFactor,
+        };
+        this.frames = this.frameQueue;
+    }
+    getViewport() {
+        return { ...this.viewport };
+    }
+    async setHumanDriver(driver) {
+        if (this.closed)
+            throw hostUnavailable("Desktop Browser Host Surface is closed");
+        if (this.driver === driver)
+            return;
+        await this.handle.surfaceCompleted({ method: "surface.driver", ...this.scope(), driver });
+        this.driver = driver;
+    }
+    async dispatchTrustedInput(input) {
+        if (this.closed)
+            throw hostUnavailable("Desktop Browser Host Surface is closed");
+        if (this.driver !== "stream") {
+            throw new SessionBrowserHostError("unavailable", "Desktop Browser Host Surface does not own the human driver");
+        }
+        if (input.browserGeneration !== this.browserGeneration || input.viewportRevision !== this.viewport.revision) {
+            throw new SessionBrowserHostError("unavailable", "Desktop Browser Host Surface scope is stale");
+        }
+        if (this.inputSequence >= Number.MAX_SAFE_INTEGER) {
+            throw new SessionBrowserHostError("capacity", "Desktop Browser Host Surface input identity is exhausted");
+        }
+        this.inputSequence += 1;
+        await this.handle.surfaceCompleted({
+            method: "surface.input",
+            ...this.scope(),
+            viewportRevision: input.viewportRevision,
+            inputSequence: this.inputSequence,
+            event: input.event,
+        });
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        if (this.closed)
+            return Promise.resolve();
+        this.closed = true;
+        this.pendingFrameSequence = undefined;
+        this.frameQueue.end();
+        this.closePromise = this.handle.available
+            ? this.handle.surfaceCompleted({ method: "surface.close", ...this.scope() }).then(() => {
+                this.handle.forgetSurface(this);
+            })
+            : Promise.resolve().then(() => {
+                this.handle.forgetSurface(this);
+            });
+        return this.closePromise;
+    }
+    receiveFrame(frame) {
+        // The native Host may already have queued its last frame when the close
+        // command crossed the socket. Exact-identity closing frames are harmless;
+        // keeping this tombstone registered still rejects every stale Surface ID.
+        if (this.closed)
+            return;
+        if (frame.browserGeneration !== this.browserGeneration || frame.format !== this.format ||
+            frame.frameSequence <= this.lastFrameSequence || this.pendingFrameSequence !== undefined) {
+            throw new DesktopBrowserHostProtocolError("Surface frame is stale, out of order, or violates ACK backpressure", CLOSE_BACKPRESSURE);
+        }
+        this.lastFrameSequence = frame.frameSequence;
+        this.pendingFrameSequence = frame.frameSequence;
+        this.viewport = {
+            revision: frame.viewportRevision,
+            width: frame.width,
+            height: frame.height,
+            deviceScaleFactor: frame.deviceScaleFactor,
+        };
+        let acknowledged = false;
+        const accepted = this.frameQueue.push({
+            browserGeneration: frame.browserGeneration,
+            viewportRevision: frame.viewportRevision,
+            timestampMilliseconds: frame.timestampMilliseconds,
+            width: frame.width,
+            height: frame.height,
+            deviceScaleFactor: frame.deviceScaleFactor,
+            format: frame.format,
+            encodedBytes: frame.encodedBytes,
+            acknowledge: () => {
+                if (acknowledged)
+                    return Promise.resolve();
+                if (this.pendingFrameSequence !== frame.frameSequence) {
+                    return Promise.reject(new SessionBrowserHostError("unavailable", "Desktop Browser Host Surface frame is stale"));
+                }
+                acknowledged = true;
+                this.pendingFrameSequence = undefined;
+                return this.handle.surfaceCompleted({
+                    method: "surface.frame.ack",
+                    ...this.scope(),
+                    frameSequence: frame.frameSequence,
+                }).then(() => undefined);
+            },
+        });
+        if (!accepted) {
+            throw new DesktopBrowserHostProtocolError("Surface frame queue capacity exceeded", CLOSE_BACKPRESSURE);
+        }
+    }
+    hostClosed(_reason) {
+        this.hostDisconnected();
+        this.handle.forgetSurface(this);
+    }
+    hostDisconnected() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.pendingFrameSequence = undefined;
+        this.frameQueue.end();
+    }
+    scope() {
+        return {
+            sessionId: this.handle.sessionId,
+            browserGeneration: this.browserGeneration,
+            hostPageId: this.hostPageId,
+            surfaceId: this.surfaceId,
+        };
+    }
+}
+function handleDesktopConnection(socket, options) {
+    let leaseId;
+    let alive = true;
+    const handshakeTimer = setTimeout(() => {
+        closeSocket(socket, CLOSE_UNSUPPORTED, "Desktop Browser Host hello timed out");
+    }, options.handshakeTimeoutMilliseconds);
+    handshakeTimer.unref?.();
+    const heartbeat = setInterval(() => {
+        if (!alive) {
+            socket.terminate();
+            return;
+        }
+        alive = false;
+        try {
+            socket.ping();
+        }
+        catch {
+            socket.terminate();
+        }
+    }, options.heartbeatIntervalMilliseconds);
+    heartbeat.unref?.();
+    socket.on("pong", () => { alive = true; });
+    socket.on("message", (data, binary) => {
+        try {
+            if (binary) {
+                if (!leaseId)
+                    throw new DesktopBrowserHostProtocolError("first frame must be Desktop Browser Host hello");
+                options.registry.receiveBinary(leaseId, parseDesktopBrowserHostSurfaceFrame(rawBytes(data)));
+                return;
+            }
+            const bytes = rawBytes(data);
+            if (bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES) {
+                throw new DesktopBrowserHostProtocolError("text control frame exceeds its byte limit", CLOSE_BACKPRESSURE);
+            }
+            const frame = parseDesktopBrowserHostClientFrame(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+            if (!leaseId) {
+                if (frame.type !== "desktop.browser.host.hello") {
+                    throw new DesktopBrowserHostProtocolError("first frame must be Desktop Browser Host hello");
+                }
+                clearTimeout(handshakeTimer);
+                const lease = options.registry.acceptConnection(socket, frame, options.daemonInstanceId, options.heartbeatIntervalMilliseconds);
+                leaseId = lease.leaseId;
+                socket.send(JSON.stringify(lease));
+                return;
+            }
+            if (frame.type === "desktop.browser.host.hello") {
+                throw new DesktopBrowserHostProtocolError("hello may only be sent once");
+            }
+            options.registry.receive(leaseId, frame);
+        }
+        catch (error) {
+            const code = error instanceof DesktopBrowserHostProtocolError
+                ? error.closeCode
+                : CLOSE_BAD_PROTOCOL;
+            closeSocket(socket, code, "invalid Desktop Browser Host frame");
+        }
+    });
+    socket.once("close", () => {
+        clearTimeout(handshakeTimer);
+        clearInterval(heartbeat);
+        if (leaseId)
+            options.registry.disconnect(leaseId);
+    });
+    socket.once("error", () => undefined);
+}
+function toSessionBrowserHostEvent(event) {
+    if (event.event === "changed") {
+        return { type: "changed", browserGeneration: event.browserGeneration };
+    }
+    if (event.event === "page.replaced") {
+        return {
+            type: "page.replaced",
+            browserGeneration: event.browserGeneration,
+            previousHostPageId: event.previousHostPageId,
+            page: event.page,
+        };
+    }
+    return {
+        type: "unavailable",
+        browserGeneration: event.browserGeneration,
+        reason: event.reason,
+    };
+}
+function mapReplyError(frame, command) {
+    if (command.method === "browser.create") {
+        if (frame.error.code === "capacity") {
+            return new SessionBrowserHostError("capacity", "Desktop Browser Host capacity was reached");
+        }
+        return commandOutcomeError(command, "Desktop Browser Host create outcome is unknown");
+    }
+    if (frame.error.code === "page_not_found") {
+        return new SessionBrowserHostError("page_not_found", "Desktop Browser Host Page was not found");
+    }
+    if (frame.error.code === "capacity") {
+        return new SessionBrowserHostError("capacity", "Desktop Browser Host capacity was reached");
+    }
+    if (frame.error.code === "unavailable" ||
+        frame.error.code === "stale_generation" ||
+        frame.error.code === "deadline_exceeded")
+        return hostUnavailable("Desktop Browser Host is unavailable");
+    if (frame.error.code === "internal") {
+        return commandOutcomeError(command, "Desktop Browser Host command outcome is unknown");
+    }
+    return new Error("Desktop Browser Host command failed");
+}
+function commandOutcomeError(command, message, cause) {
+    const readOnly = isReadOnlyCommand(command);
+    return new SessionBrowserHostError(readOnly ? "unavailable" : "outcome_unknown", message, cause === undefined ? undefined : { cause });
+}
+function isReadOnlyCommand(command) {
+    return command.method === "browser.snapshot" ||
+        command.method === "browser.cdp-endpoint" ||
+        command.method === "page.cdp-endpoint";
+}
+class BoundedAsyncQueue {
+    capacity;
+    values = [];
+    waiters = [];
+    ended = false;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    push(value) {
+        if (this.ended)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value, done: false });
+            return true;
+        }
+        if (this.values.length >= this.capacity)
+            return false;
+        this.values.push(value);
+        return true;
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0))
+            waiter({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const value = this.values.shift();
+                if (value !== undefined)
+                    return Promise.resolve({ value, done: false });
+                if (this.ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+        };
+    }
+}
+function rawBytes(data) {
+    let bytes;
+    if (data instanceof ArrayBuffer)
+        bytes = new Uint8Array(data);
+    else if (Array.isArray(data))
+        bytes = Buffer.concat(data);
+    else
+        bytes = data;
+    return bytes;
+}
+function browserKey(sessionId, generation) {
+    return `${sessionId}\u0000${generation}`;
+}
+function hostUnavailable(message, cause) {
+    return new SessionBrowserHostError("unavailable", message, cause === undefined ? undefined : { cause });
+}
+function closeSocket(socket, code, reason) {
+    if (socket.readyState !== WebSocket.OPEN && socket.readyState !== WebSocket.CONNECTING)
+        return;
+    try {
+        socket.close(code, reason.slice(0, 123));
+    }
+    catch {
+        socket.terminate();
+    }
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const body = `${message}\n`;
+    socket.end(`HTTP/1.1 ${status} ${status === 401 ? "Unauthorized" : status === 403 ? "Forbidden" : "Bad Request"}\r\n` +
+        "Connection: close\r\n" +
+        "Content-Type: text/plain; charset=utf-8\r\n" +
+        `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+}
+function singleHeader(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function safeTokenEquals(actual, expected) {
+    const left = Buffer.from(actual, "utf8");
+    const right = Buffer.from(expected, "utf8");
+    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}
+function isLoopbackAddress(value) {
+    const normalized = value?.startsWith("::ffff:") ? value.slice("::ffff:".length) : value;
+    return normalized === "127.0.0.1" || normalized === "::1";
+}
+function assertManagementToken(value) {
+    const bytes = typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0;
+    if (bytes < 32 || bytes > 256)
+        throw new Error("Desktop Browser Host management token is invalid");
+}
+function opaqueServerId(value, field) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._~-]{0,511}$/.test(value))
+        throw new Error(`${field} is invalid`);
+    return value;
+}
+function boundedDuration(value, field) {
+    if (!Number.isSafeInteger(value) || value < 10 || value > 10 * 60_000) {
+        throw new Error(`${field} must be an integer between 10 and 600000 milliseconds`);
+    }
+    return value;
+}