@rynx-ai/server 0.1.0 → 0.1.9

package/dist/session-browser-service.js

@@ -0,0 +1,686 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { RUNTIME_BROWSER_MAX_PAGES, parseRuntimeBrowserCloseParams, parseRuntimeBrowserOpenParams, parseRuntimeBrowserPageCreateParams, parseRuntimeBrowserPageMutationParams, parseRuntimeBrowserPageNavigateParams, parseRuntimeBrowserState, parseRuntimeBrowserStateGetParams, } from "@rynx-ai/protocol/runtime-browser";
+import { parseRuntimeBrowserEndpointDescriptor, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+const MAX_HOST_PAGE_ID_CHARS = 2_048;
+const MAX_PAGE_ID_FACTORY_ATTEMPTS = 64;
+const MAX_RETIRED_HOST_PAGE_IDS = 64;
+export class SessionBrowserSurfaceUnsupportedError extends Error {
+    constructor() {
+        super("Browser Host does not support presentation");
+        this.name = "SessionBrowserSurfaceUnsupportedError";
+    }
+}
+/** Expected failure reported by a Browser Host implementation. */
+export class SessionBrowserHostError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SessionBrowserHostError";
+    }
+}
+/** Stable application error; transports map the code without exposing Host diagnostics. */
+export class SessionBrowserServiceError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SessionBrowserServiceError";
+    }
+}
+/**
+ * Transport-neutral owner of the Runtime -> Session -> Browser -> Page model.
+ * Every operation for one Session shares one queue; different Sessions remain independent.
+ */
+export class SessionBrowserService {
+    ports;
+    records = new Map();
+    generations = new Map();
+    queues = new Map();
+    deletingSessions = new Set();
+    observers = new Set();
+    pageIdFactory;
+    bootGenerationSeed;
+    shuttingDown = false;
+    closeAllPromise;
+    constructor(ports, options = {}) {
+        this.ports = ports;
+        this.pageIdFactory = options.pageIdFactory ?? (() => `page_${randomUUID()}`);
+        this.bootGenerationSeed = options.bootGenerationSeed ?? randomBootGenerationSeed();
+        if (!Number.isSafeInteger(this.bootGenerationSeed) ||
+            this.bootGenerationSeed < 0 ||
+            this.bootGenerationSeed >= Number.MAX_SAFE_INTEGER) {
+            throw new Error("Browser boot generation seed must be a nonnegative safe integer");
+        }
+    }
+    async getState(input) {
+        const params = parseInput(() => parseRuntimeBrowserStateGetParams(input), "Browser state request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.records.get(params.sessionId);
+            if (!record)
+                return null;
+            if (record.status === "ready")
+                await this.reconcileForRead(record);
+            return this.project(record);
+        });
+    }
+    /**
+     * Runtime-local automation handoff. This method is deliberately absent from
+     * RemoteRuntimeBrowserHost and Direct RPC so a CDP endpoint cannot cross a
+     * Runtime boundary.
+     */
+    async getRuntimeLocalEndpoint(sessionId) {
+        const parsedSessionId = parseInput(() => parseRuntimeBrowserStateGetParams({ sessionId }).sessionId, "Browser endpoint request is invalid");
+        return this.exclusive(parsedSessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(parsedSessionId);
+            const record = this.requireRecord(parsedSessionId);
+            if (record.status !== "ready") {
+                throw new SessionBrowserServiceError("unavailable", "Browser is not available");
+            }
+            try {
+                const endpoint = await record.handle.getCdpEndpoint();
+                return parseRuntimeBrowserEndpointDescriptor({
+                    sessionId: record.sessionId,
+                    browserGeneration: record.browserGeneration,
+                    executionBackend: record.executionBackend,
+                    endpoint: endpoint.endpoint,
+                    engineVersion: endpoint.engineVersion,
+                });
+            }
+            catch (error) {
+                record.status = "unavailable";
+                throw mapHostError(error, "Browser automation endpoint is unavailable");
+            }
+        });
+    }
+    /**
+     * Resolve one opaque Page to its generation-local Host source. This is the
+     * only presentation path allowed to cross the semantic/physical Page seam.
+     */
+    async validateSurfaceTarget(input) {
+        const params = parseInput(() => parseRuntimeBrowserPageMutationParams(input), "Browser Surface request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.requireReadyRecord(params.sessionId, params.browserGeneration);
+            await this.reconcileForMutation(record);
+            if (!record.pagesById.has(params.pageId)) {
+                throw new SessionBrowserServiceError("not_found", "Browser Page was not found");
+            }
+            if (!record.handle.openSurface)
+                throw new SessionBrowserSurfaceUnsupportedError();
+        });
+    }
+    async openSurface(input) {
+        const params = parseInput(() => parseRuntimeBrowserPageMutationParams({
+            sessionId: input.sessionId,
+            browserGeneration: input.browserGeneration,
+            pageId: input.pageId,
+        }), "Browser Surface request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.requireReadyRecord(params.sessionId, params.browserGeneration);
+            await this.reconcileForMutation(record);
+            const page = record.pagesById.get(params.pageId);
+            if (!page) {
+                throw new SessionBrowserServiceError("not_found", "Browser Page was not found");
+            }
+            if (!record.handle.openSurface)
+                throw new SessionBrowserSurfaceUnsupportedError();
+            try {
+                return await record.handle.openSurface({
+                    browserGeneration: params.browserGeneration,
+                    hostPageId: page.hostPageId,
+                    format: input.format,
+                    quality: input.quality,
+                    maximumFrameRate: input.maximumFrameRate,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+            }
+            catch (error) {
+                throw mapHostError(error, "Browser Surface could not open");
+            }
+        });
+    }
+    async open(input) {
+        const params = parseInput(() => parseRuntimeBrowserOpenParams(input), "Browser open request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const existing = this.records.get(params.sessionId);
+            if (existing?.status === "ready" || existing?.status === "opening") {
+                if (existing.status === "ready")
+                    await this.reconcileForRead(existing);
+                return this.project(existing);
+            }
+            if (existing)
+                await this.closeUnavailableForRecreate(existing);
+            return this.createBrowser(params);
+        });
+    }
+    async close(input) {
+        const params = parseInput(() => parseRuntimeBrowserCloseParams(input), "Browser close request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.requireRecord(params.sessionId);
+            this.requireGeneration(record, params.browserGeneration);
+            record.status = "closing";
+            try {
+                await record.handle.close();
+            }
+            catch (error) {
+                record.status = "unavailable";
+                throw new SessionBrowserServiceError("outcome_unknown", "Browser close outcome is unknown", { cause: error });
+            }
+            if (this.records.get(params.sessionId) === record)
+                this.records.delete(params.sessionId);
+            return { closed: true, browserGeneration: params.browserGeneration };
+        });
+    }
+    async createPage(input) {
+        const params = parseInput(() => parseRuntimeBrowserPageCreateParams(input), "Browser page creation request is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.requireReadyRecord(params.sessionId, params.browserGeneration);
+            await this.reconcileForMutation(record);
+            if (record.pagesById.size >= RUNTIME_BROWSER_MAX_PAGES) {
+                throw new SessionBrowserServiceError("capacity", `Browser already contains the maximum of ${RUNTIME_BROWSER_MAX_PAGES} Pages`);
+            }
+            return this.runMutation(record, () => record.handle.createPage(params.url));
+        });
+    }
+    closePage(input) {
+        return this.pageMutation(input, "Browser page close request is invalid", (record, hostPageId) => record.handle.closePage(hostPageId));
+    }
+    activatePage(input) {
+        return this.pageMutation(input, "Browser page activation request is invalid", (record, hostPageId) => record.handle.activatePage(hostPageId));
+    }
+    async navigatePage(input) {
+        const params = parseInput(() => parseRuntimeBrowserPageNavigateParams(input), "Browser page navigation request is invalid");
+        return this.pageMutationParsed(params, (record, hostPageId) => record.handle.navigatePage(hostPageId, params.url));
+    }
+    goBack(input) {
+        return this.pageMutation(input, "Browser page back request is invalid", (record, hostPageId) => record.handle.goBack(hostPageId));
+    }
+    goForward(input) {
+        return this.pageMutation(input, "Browser page forward request is invalid", (record, hostPageId) => record.handle.goForward(hostPageId));
+    }
+    reload(input) {
+        return this.pageMutation(input, "Browser page reload request is invalid", (record, hostPageId) => record.handle.reload(hostPageId));
+    }
+    /** Session deletion fence: no later Browser operation may enter for this Session ID. */
+    async cleanupSession(sessionId) {
+        const parsed = parseInput(() => parseRuntimeBrowserStateGetParams({ sessionId }).sessionId, "Browser Session cleanup request is invalid");
+        this.deletingSessions.add(parsed);
+        await this.exclusive(parsed, async () => {
+            const failures = [];
+            const record = this.records.get(parsed);
+            if (record) {
+                record.status = "closing";
+                this.records.delete(parsed);
+                try {
+                    await record.handle.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            try {
+                await this.ports.host.deleteSessionData?.(parsed);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            this.generations.delete(parsed);
+            if (failures.length > 0) {
+                throw new SessionBrowserServiceError("host_failure", "Browser Session cleanup did not complete", { cause: failures[0] });
+            }
+        }, true);
+    }
+    /** Daemon shutdown closes engines but intentionally preserves Session profile data. */
+    closeAll() {
+        if (this.closeAllPromise)
+            return this.closeAllPromise;
+        this.shuttingDown = true;
+        this.closeAllPromise = this.closeEveryRecord();
+        return this.closeAllPromise;
+    }
+    async closeEveryRecord() {
+        const failures = [];
+        // Operations admitted before the shutdown fence may still be creating a
+        // physical Browser. Drain them before snapshotting records to close.
+        await Promise.allSettled([...this.queues.values()]);
+        while (this.records.size > 0) {
+            const sessionIds = [...this.records.keys()];
+            await Promise.all(sessionIds.map((sessionId) => this.exclusive(sessionId, async () => {
+                const record = this.records.get(sessionId);
+                if (!record)
+                    return;
+                record.status = "closing";
+                this.records.delete(sessionId);
+                try {
+                    await record.handle.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }, true)));
+        }
+        await Promise.allSettled([...this.observers]);
+        if (failures.length > 0) {
+            throw new SessionBrowserServiceError("host_failure", "One or more Browsers did not close during shutdown", { cause: failures[0] });
+        }
+    }
+    async createBrowser(params) {
+        const previousGeneration = this.generations.get(params.sessionId)
+            ?? this.bootGenerationSeed;
+        if (previousGeneration >= Number.MAX_SAFE_INTEGER) {
+            throw new SessionBrowserServiceError("capacity", "Browser generation space is exhausted");
+        }
+        const browserGeneration = previousGeneration + 1;
+        this.generations.set(params.sessionId, browserGeneration);
+        let handle;
+        try {
+            handle = await this.ports.host.createBrowser({
+                sessionId: params.sessionId,
+                browserGeneration,
+                ...(params.url === undefined ? {} : { url: params.url }),
+            });
+        }
+        catch (error) {
+            throw mapHostError(error, "Browser Host could not create the Browser");
+        }
+        if (handle.browserGeneration !== browserGeneration) {
+            await handle.close().catch(() => undefined);
+            throw new SessionBrowserServiceError("host_failure", "Browser Host returned the wrong generation");
+        }
+        const record = {
+            sessionId: params.sessionId,
+            browserGeneration,
+            status: "opening",
+            executionBackend: handle.executionBackend,
+            capabilities: [...handle.capabilities],
+            handle,
+            pagesById: new Map(),
+            pageIdByHostId: new Map(),
+            retiredPageIdByHostId: new Map(),
+            boundPageIdByHostId: new Map(),
+            pageOrder: [],
+            activePageId: null,
+        };
+        if (this.shuttingDown) {
+            record.status = "closing";
+            this.records.set(params.sessionId, record);
+            try {
+                await handle.close();
+                if (this.records.get(params.sessionId) === record)
+                    this.records.delete(params.sessionId);
+                throw new SessionBrowserServiceError("shutting_down", "Browser service is shutting down");
+            }
+            catch (error) {
+                if (error instanceof SessionBrowserServiceError)
+                    throw error;
+                record.status = "unavailable";
+                throw new SessionBrowserServiceError("host_failure", "Browser created during shutdown could not be closed", { cause: error });
+            }
+        }
+        this.records.set(params.sessionId, record);
+        try {
+            await this.reconcile(record);
+            record.status = "ready";
+            const state = this.project(record);
+            this.observe(record);
+            return state;
+        }
+        catch (error) {
+            record.status = "unavailable";
+            try {
+                await handle.close();
+                if (this.records.get(params.sessionId) === record)
+                    this.records.delete(params.sessionId);
+            }
+            catch (closeError) {
+                this.observe(record);
+                throw new SessionBrowserServiceError("host_failure", "Browser Host state failed to initialize and could not be closed", { cause: new AggregateError([error, closeError]) });
+            }
+            throw new SessionBrowserServiceError("host_failure", "Browser Host state could not be initialized", { cause: error });
+        }
+    }
+    async closeUnavailableForRecreate(record) {
+        record.status = "closing";
+        try {
+            await record.handle.close();
+        }
+        catch (error) {
+            record.status = "unavailable";
+            throw new SessionBrowserServiceError("host_failure", "Unavailable Browser could not be closed before recreation", { cause: error });
+        }
+        if (this.records.get(record.sessionId) === record)
+            this.records.delete(record.sessionId);
+    }
+    pageMutation(input, invalidMessage, operation) {
+        const params = parseInput(() => parseRuntimeBrowserPageMutationParams(input), invalidMessage);
+        return this.pageMutationParsed(params, operation);
+    }
+    pageMutationParsed(params, operation) {
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const record = this.requireReadyRecord(params.sessionId, params.browserGeneration);
+            await this.reconcileForMutation(record);
+            const page = record.pagesById.get(params.pageId);
+            if (!page) {
+                throw new SessionBrowserServiceError("not_found", "Browser Page was not found");
+            }
+            return this.runMutation(record, () => operation(record, page.hostPageId));
+        });
+    }
+    async runMutation(record, operation) {
+        try {
+            await operation();
+        }
+        catch (error) {
+            if (error instanceof SessionBrowserHostError &&
+                (error.code === "unavailable" || error.code === "outcome_unknown")) {
+                record.status = "unavailable";
+            }
+            if (error instanceof SessionBrowserHostError && error.code === "page_not_found") {
+                await this.tryReconcileAfterRejectedMutation(record);
+            }
+            throw mapHostError(error, "Browser Host rejected the operation");
+        }
+        try {
+            await this.reconcile(record);
+            return this.project(record);
+        }
+        catch (error) {
+            record.status = "unavailable";
+            throw new SessionBrowserServiceError("outcome_unknown", "Browser operation completed but its outcome could not be reconciled", { cause: error });
+        }
+    }
+    async reconcileForRead(record) {
+        try {
+            await this.reconcile(record);
+        }
+        catch (error) {
+            record.status = "unavailable";
+            throw new SessionBrowserServiceError("host_failure", "Browser Host state could not be reconciled", { cause: error });
+        }
+    }
+    async reconcileForMutation(record) {
+        try {
+            await this.reconcile(record);
+        }
+        catch (error) {
+            record.status = "unavailable";
+            throw new SessionBrowserServiceError("unavailable", "Browser became unavailable while reconciling Host state", { cause: error });
+        }
+    }
+    async tryReconcileAfterRejectedMutation(record) {
+        try {
+            await this.reconcile(record);
+        }
+        catch {
+            record.status = "unavailable";
+        }
+    }
+    async reconcile(record) {
+        const snapshot = await record.handle.snapshot();
+        if (!Array.isArray(snapshot.pages) || snapshot.pages.length > RUNTIME_BROWSER_MAX_PAGES) {
+            throw new Error("Browser Host returned too many Pages");
+        }
+        const nextPagesById = new Map();
+        const nextPageIdByHostId = new Map();
+        const nextPageOrder = [];
+        for (const hostPage of snapshot.pages) {
+            validateHostPageId(hostPage.hostPageId);
+            if (nextPageIdByHostId.has(hostPage.hostPageId)) {
+                throw new Error("Browser Host returned duplicate Page identity");
+            }
+            const pageId = record.pageIdByHostId.get(hostPage.hostPageId)
+                ?? record.retiredPageIdByHostId.get(hostPage.hostPageId)
+                ?? this.createPageId(record, nextPagesById);
+            nextPageIdByHostId.set(hostPage.hostPageId, pageId);
+            nextPageOrder.push(pageId);
+            nextPagesById.set(pageId, {
+                pageId,
+                hostPageId: hostPage.hostPageId,
+                url: hostPage.url,
+                title: hostPage.title,
+                loading: hostPage.loading,
+                canGoBack: hostPage.canGoBack,
+                canGoForward: hostPage.canGoForward,
+            });
+        }
+        if (snapshot.activeHostPageId !== null &&
+            !nextPageIdByHostId.has(snapshot.activeHostPageId)) {
+            throw new Error("Browser Host active Page is absent from its snapshot");
+        }
+        const activePageId = snapshot.activeHostPageId === null
+            ? null
+            : nextPageIdByHostId.get(snapshot.activeHostPageId);
+        const parsed = parseRuntimeBrowserState({
+            sessionId: record.sessionId,
+            browserGeneration: record.browserGeneration,
+            status: record.status,
+            executionBackend: record.executionBackend,
+            activePageId,
+            pages: nextPageOrder.map((pageId) => nextPagesById.get(pageId)),
+            capabilities: record.capabilities,
+        });
+        if (!parsed)
+            throw new Error("Browser Host returned no state");
+        const nextBoundPageIdByHostId = new Map();
+        if (record.handle.bindPage) {
+            for (const [hostPageId, pageId] of nextPageIdByHostId) {
+                if (record.boundPageIdByHostId.get(hostPageId) !== pageId) {
+                    await record.handle.bindPage(hostPageId, pageId);
+                }
+                nextBoundPageIdByHostId.set(hostPageId, pageId);
+            }
+        }
+        for (const [hostPageId, pageId] of record.pageIdByHostId) {
+            if (!nextPageIdByHostId.has(hostPageId)) {
+                record.retiredPageIdByHostId.set(hostPageId, pageId);
+            }
+        }
+        for (const hostPageId of nextPageIdByHostId.keys()) {
+            record.retiredPageIdByHostId.delete(hostPageId);
+        }
+        while (record.retiredPageIdByHostId.size > MAX_RETIRED_HOST_PAGE_IDS) {
+            const oldest = record.retiredPageIdByHostId.keys().next().value;
+            if (oldest === undefined)
+                break;
+            record.retiredPageIdByHostId.delete(oldest);
+        }
+        record.pagesById = new Map(parsed.pages.map((page) => [
+            page.pageId,
+            { ...page, hostPageId: nextPagesById.get(page.pageId).hostPageId },
+        ]));
+        record.pageIdByHostId = nextPageIdByHostId;
+        record.boundPageIdByHostId = nextBoundPageIdByHostId;
+        record.pageOrder = parsed.pages.map((page) => page.pageId);
+        record.activePageId = parsed.activePageId;
+        record.capabilities = parsed.capabilities;
+    }
+    createPageId(record, pending) {
+        for (let attempt = 0; attempt < MAX_PAGE_ID_FACTORY_ATTEMPTS; attempt += 1) {
+            const pageId = this.pageIdFactory();
+            if (!record.pagesById.has(pageId) &&
+                !pending.has(pageId) &&
+                ![...record.retiredPageIdByHostId.values()].includes(pageId))
+                return pageId;
+        }
+        throw new Error("Browser Page identity factory did not produce a unique ID");
+    }
+    project(record) {
+        const parsed = parseRuntimeBrowserState({
+            sessionId: record.sessionId,
+            browserGeneration: record.browserGeneration,
+            status: record.status,
+            executionBackend: record.executionBackend,
+            activePageId: record.activePageId,
+            pages: record.pageOrder.map((pageId) => record.pagesById.get(pageId)),
+            capabilities: record.capabilities,
+        });
+        if (!parsed)
+            throw new Error("Browser record unexpectedly projected to absence");
+        return parsed;
+    }
+    observe(record) {
+        const observer = this.consumeEvents(record).finally(() => this.observers.delete(observer));
+        this.observers.add(observer);
+    }
+    async consumeEvents(record) {
+        let failed;
+        try {
+            for await (const event of record.handle.events) {
+                await this.exclusive(record.sessionId, async () => {
+                    if (!this.isCurrent(record, event.browserGeneration))
+                        return;
+                    if (event.type === "unavailable") {
+                        record.status = "unavailable";
+                        return;
+                    }
+                    if (record.status !== "ready")
+                        return;
+                    if (event.type === "page.replaced")
+                        this.applyReplacement(record, event);
+                    try {
+                        await this.reconcile(record);
+                    }
+                    catch {
+                        record.status = "unavailable";
+                    }
+                }, true);
+            }
+        }
+        catch (error) {
+            failed = error;
+        }
+        await this.exclusive(record.sessionId, async () => {
+            if (!this.isCurrent(record, record.browserGeneration))
+                return;
+            if (record.status === "ready" || failed !== undefined)
+                record.status = "unavailable";
+        }, true);
+    }
+    applyReplacement(record, event) {
+        validateHostPageId(event.previousHostPageId);
+        validateHostPageId(event.page.hostPageId);
+        const preservedPageId = record.pageIdByHostId.get(event.previousHostPageId)
+            ?? record.retiredPageIdByHostId.get(event.previousHostPageId);
+        if (!preservedPageId)
+            return;
+        const conflictingPageId = record.pageIdByHostId.get(event.page.hostPageId);
+        if (conflictingPageId && conflictingPageId !== preservedPageId) {
+            record.pagesById.delete(conflictingPageId);
+            record.pageOrder = record.pageOrder.filter((pageId) => pageId !== conflictingPageId);
+        }
+        record.pageIdByHostId.delete(event.previousHostPageId);
+        record.retiredPageIdByHostId.delete(event.previousHostPageId);
+        record.retiredPageIdByHostId.delete(event.page.hostPageId);
+        record.pageIdByHostId.set(event.page.hostPageId, preservedPageId);
+        const page = record.pagesById.get(preservedPageId);
+        if (page)
+            page.hostPageId = event.page.hostPageId;
+    }
+    isCurrent(record, generation) {
+        return this.records.get(record.sessionId) === record &&
+            record.browserGeneration === generation;
+    }
+    requireRecord(sessionId) {
+        const record = this.records.get(sessionId);
+        if (!record)
+            throw new SessionBrowserServiceError("not_found", "Browser was not found");
+        return record;
+    }
+    requireReadyRecord(sessionId, generation) {
+        const record = this.requireRecord(sessionId);
+        this.requireGeneration(record, generation);
+        if (record.status !== "ready") {
+            throw new SessionBrowserServiceError("unavailable", "Browser is not available");
+        }
+        return record;
+    }
+    requireGeneration(record, generation) {
+        if (record.browserGeneration !== generation) {
+            throw new SessionBrowserServiceError("generation_mismatch", "Browser generation is stale");
+        }
+    }
+    async ensureSessionExists(sessionId) {
+        if (this.deletingSessions.has(sessionId) ||
+            (this.ports.sessions && !(await this.ports.sessions.exists(sessionId)))) {
+            throw new SessionBrowserServiceError("not_found", "Session was not found");
+        }
+    }
+    ensureRunning() {
+        if (this.shuttingDown) {
+            throw new SessionBrowserServiceError("shutting_down", "Browser service is shutting down");
+        }
+    }
+    exclusive(sessionId, operation, allowShutdown = false) {
+        if (this.shuttingDown && !allowShutdown) {
+            return Promise.reject(new SessionBrowserServiceError("shutting_down", "Browser service is shutting down"));
+        }
+        const previous = this.queues.get(sessionId) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        const completion = result.then(() => undefined, () => undefined);
+        this.queues.set(sessionId, completion);
+        void completion.finally(() => {
+            if (this.queues.get(sessionId) === completion)
+                this.queues.delete(sessionId);
+        });
+        return result;
+    }
+}
+function parseInput(parse, message) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        throw new SessionBrowserServiceError("invalid_request", message, { cause: error });
+    }
+}
+function mapHostError(error, fallbackMessage) {
+    if (error instanceof SessionBrowserServiceError)
+        return error;
+    if (error instanceof SessionBrowserHostError) {
+        if (error.code === "page_not_found") {
+            return new SessionBrowserServiceError("not_found", "Browser Page was not found", {
+                cause: error,
+            });
+        }
+        if (error.code === "capacity") {
+            return new SessionBrowserServiceError("capacity", "Browser Host capacity was reached", {
+                cause: error,
+            });
+        }
+        if (error.code === "outcome_unknown") {
+            return new SessionBrowserServiceError("outcome_unknown", "Browser Host operation outcome is unknown", { cause: error });
+        }
+        return new SessionBrowserServiceError("unavailable", "Browser Host is unavailable", {
+            cause: error,
+        });
+    }
+    return new SessionBrowserServiceError("host_failure", fallbackMessage, { cause: error });
+}
+function validateHostPageId(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_HOST_PAGE_ID_CHARS ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new Error("Browser Host Page identity is invalid");
+    }
+}
+function randomBootGenerationSeed() {
+    // 48 random bits remain exactly representable as a JavaScript integer and
+    // leave ample monotonic headroom for generations within one daemon boot.
+    return randomBytes(6).readUIntBE(0, 6);
+}