@rynx-ai/server 0.1.0 → 0.1.9

package/dist/session-browser-surface-coordinator.d.ts

@@ -0,0 +1,23 @@
+import { type RuntimeBrowserSurfaceOpenFrame } from "@rynx-ai/protocol/runtime-browser-surface";
+import { type DirectRuntimeBrowserSurfaceAttachment, type DirectRuntimeBrowserSurfaceHost } from "./direct-runtime-browser-surface-server.js";
+import { SessionBrowserService } from "./session-browser-service.js";
+export interface SessionBrowserSurfaceCoordinatorOptions {
+    frameAcknowledgeTimeoutMs?: number;
+    maxPendingEvents?: number;
+    maxPendingEventBytes?: number;
+}
+/**
+ * Owns the one-stream-per-Page lease, frame acknowledgement, and human-driver
+ * rules above physical Browser capture. It never exposes a Host Page ID or CDP.
+ */
+export declare class SessionBrowserSurfaceCoordinator implements DirectRuntimeBrowserSurfaceHost {
+    private readonly browsers;
+    private readonly attachments;
+    private readonly pageQueues;
+    private readonly frameAcknowledgeTimeoutMs;
+    private readonly maxPendingEvents;
+    private readonly maxPendingEventBytes;
+    constructor(browsers: SessionBrowserService, options?: SessionBrowserSurfaceCoordinatorOptions);
+    open(frame: RuntimeBrowserSurfaceOpenFrame, context: Parameters<DirectRuntimeBrowserSurfaceHost["open"]>[1]): Promise<DirectRuntimeBrowserSurfaceAttachment>;
+    private exclusivePage;
+}

package/dist/session-browser-surface-coordinator.js

@@ -0,0 +1,563 @@
+import { RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_FRAME_ACK_TIMEOUT_MS, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, } from "@rynx-ai/protocol/runtime-browser-surface";
+import { DirectRuntimeBrowserSurfaceHostError, } from "./direct-runtime-browser-surface-server.js";
+import { SessionBrowserHostError, SessionBrowserServiceError, SessionBrowserSurfaceUnsupportedError, } from "./session-browser-service.js";
+const DEFAULT_MAX_PENDING_EVENTS = 8;
+const DEFAULT_MAX_PENDING_EVENT_BYTES = RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES +
+    RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES * DEFAULT_MAX_PENDING_EVENTS;
+/**
+ * Owns the one-stream-per-Page lease, frame acknowledgement, and human-driver
+ * rules above physical Browser capture. It never exposes a Host Page ID or CDP.
+ */
+export class SessionBrowserSurfaceCoordinator {
+    browsers;
+    attachments = new Map();
+    pageQueues = new Map();
+    frameAcknowledgeTimeoutMs;
+    maxPendingEvents;
+    maxPendingEventBytes;
+    constructor(browsers, options = {}) {
+        this.browsers = browsers;
+        this.frameAcknowledgeTimeoutMs = options.frameAcknowledgeTimeoutMs
+            ?? RUNTIME_BROWSER_SURFACE_FRAME_ACK_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.frameAcknowledgeTimeoutMs) || this.frameAcknowledgeTimeoutMs < 1) {
+            throw new Error("Browser Surface frame acknowledgement timeout must be positive");
+        }
+        this.maxPendingEvents = positiveLimit(options.maxPendingEvents, DEFAULT_MAX_PENDING_EVENTS, "Browser Surface pending event limit");
+        this.maxPendingEventBytes = positiveLimit(options.maxPendingEventBytes, DEFAULT_MAX_PENDING_EVENT_BYTES, "Browser Surface pending event byte limit");
+    }
+    async open(frame, context) {
+        if (frame.requestedRole === "control" &&
+            !context.peer.subject.effectiveAuthorities.includes("daemon.full")) {
+            throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Runtime grant does not allow Browser control");
+        }
+        const pageKey = `${frame.sessionId}\u0000${frame.pageId}`;
+        return this.exclusivePage(pageKey, async () => {
+            context.signal.throwIfAborted();
+            try {
+                await this.browsers.validateSurfaceTarget({
+                    sessionId: frame.sessionId,
+                    browserGeneration: frame.browserGeneration,
+                    pageId: frame.pageId,
+                });
+            }
+            catch (error) {
+                throw mapSurfaceOpenError(error);
+            }
+            context.signal.throwIfAborted();
+            const previous = this.attachments.get(pageKey);
+            if (previous)
+                await previous.replace();
+            let source;
+            try {
+                source = await this.browsers.openSurface({
+                    sessionId: frame.sessionId,
+                    browserGeneration: frame.browserGeneration,
+                    pageId: frame.pageId,
+                    format: frame.format,
+                    quality: frame.quality,
+                    maximumFrameRate: frame.maximumFrameRate,
+                    signal: context.signal,
+                });
+            }
+            catch (error) {
+                throw mapSurfaceOpenError(error);
+            }
+            if (context.signal.aborted) {
+                await source.close().catch(() => undefined);
+                throw new DirectRuntimeBrowserSurfaceHostError("cancelled", "Browser Surface open was cancelled");
+            }
+            let attachment;
+            attachment = new CoordinatedSurfaceAttachment({
+                open: frame,
+                source,
+                signal: context.signal,
+                frameAcknowledgeTimeoutMs: this.frameAcknowledgeTimeoutMs,
+                maxPendingEvents: this.maxPendingEvents,
+                maxPendingEventBytes: this.maxPendingEventBytes,
+                onClose: () => {
+                    if (this.attachments.get(pageKey) === attachment)
+                        this.attachments.delete(pageKey);
+                },
+            });
+            this.attachments.set(pageKey, attachment);
+            attachment.start();
+            return attachment;
+        });
+    }
+    exclusivePage(pageKey, operation) {
+        const previous = this.pageQueues.get(pageKey) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        const completion = result.then(() => undefined, () => undefined);
+        this.pageQueues.set(pageKey, completion);
+        void completion.finally(() => {
+            if (this.pageQueues.get(pageKey) === completion)
+                this.pageQueues.delete(pageKey);
+        });
+        return result;
+    }
+}
+class CoordinatedSurfaceAttachment {
+    attachment;
+    ready;
+    events;
+    eventQueue;
+    abortHandler;
+    frameSequence = 0;
+    lastInputSequence = -1;
+    pendingInputCount = 0;
+    inputTail = Promise.resolve();
+    inputEpoch = 0;
+    acceptingInput = false;
+    inputResetRequired = false;
+    pendingFrame;
+    driver;
+    physicalDriver;
+    driverIntent = 0;
+    driverTransitionTail = Promise.resolve();
+    closing = false;
+    closePromise;
+    constructor(attachment) {
+        this.attachment = attachment;
+        this.eventQueue = new SurfaceEventQueue({
+            maxPendingEvents: attachment.maxPendingEvents,
+            maxPendingBytes: attachment.maxPendingEventBytes,
+        });
+        const viewport = attachment.source.getViewport();
+        this.ready = {
+            type: "browser.surface.ready",
+            subscriptionId: attachment.open.subscriptionId,
+            browserGeneration: attachment.open.browserGeneration,
+            viewportRevision: viewport.revision,
+            sourceWidth: viewport.width,
+            sourceHeight: viewport.height,
+            deviceScaleFactor: viewport.deviceScaleFactor,
+            format: attachment.open.format,
+            grantedRole: attachment.open.requestedRole,
+        };
+        this.driver = attachment.source.setHumanDriver ? "desktop" : "none";
+        this.physicalDriver = this.driver;
+        this.events = this.eventQueue;
+        this.abortHandler = () => {
+            void this.finish("cancelled", "Browser Surface connection was cancelled", true);
+        };
+        attachment.signal.addEventListener("abort", this.abortHandler, { once: true });
+    }
+    start() {
+        try {
+            this.emitDriverChanged();
+        }
+        catch (error) {
+            const mapped = mapSurfaceHostError(error, "Browser Surface event queue is full");
+            void this.finish(mapped.reason, mapped.message, true);
+            return;
+        }
+        void this.pumpFrames();
+    }
+    async handle(frame) {
+        if (this.closing)
+            return;
+        if (frame.subscriptionId !== this.attachment.open.subscriptionId) {
+            throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface subscription does not match");
+        }
+        switch (frame.type) {
+            case "browser.surface.frame.ack":
+                this.acknowledgeFrame(frame.frameSequence);
+                return;
+            case "browser.surface.driver.take":
+                this.requireGeneration(frame.browserGeneration);
+                this.requireControlRole();
+                if (!this.matchesViewport(frame.viewportRevision))
+                    return;
+                await this.takeDriver();
+                return;
+            case "browser.surface.driver.release":
+                this.requireGeneration(frame.browserGeneration);
+                await this.releaseDriver();
+                return;
+            case "browser.surface.input":
+                this.requireGeneration(frame.browserGeneration);
+                this.requireControlRole();
+                if (this.driver !== "stream" || !this.acceptingInput) {
+                    throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Browser Surface does not own the human driver");
+                }
+                if (!this.matchesViewport(frame.viewportRevision))
+                    return;
+                if (frame.inputSequence <= this.lastInputSequence) {
+                    throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface input sequence must increase");
+                }
+                if (this.pendingInputCount >= RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE) {
+                    throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface input queue is full");
+                }
+                this.lastInputSequence = frame.inputSequence;
+                this.pendingInputCount += 1;
+                const inputEpoch = this.inputEpoch;
+                try {
+                    const operation = this.inputTail.then(async () => {
+                        if (this.closing ||
+                            !this.acceptingInput ||
+                            this.driver !== "stream" ||
+                            inputEpoch !== this.inputEpoch)
+                            return;
+                        await this.attachment.source.dispatchTrustedInput({
+                            browserGeneration: frame.browserGeneration,
+                            viewportRevision: frame.viewportRevision,
+                            event: frame.event,
+                        });
+                    });
+                    this.inputTail = operation.then(() => undefined, () => undefined);
+                    await operation;
+                }
+                catch (error) {
+                    throw mapSurfaceHostError(error, "Browser Surface input failed");
+                }
+                finally {
+                    this.pendingInputCount -= 1;
+                }
+        }
+    }
+    close(_reason) {
+        return this.finish("cancelled", undefined, false);
+    }
+    replace() {
+        return this.finish("replaced", "Browser Surface was opened elsewhere", true);
+    }
+    async pumpFrames() {
+        try {
+            for await (const frame of this.attachment.source.frames) {
+                if (this.closing) {
+                    await frame.acknowledge();
+                    return;
+                }
+                if (frame.browserGeneration !== this.attachment.open.browserGeneration) {
+                    await frame.acknowledge();
+                    await this.finish("generation_changed", "Browser generation changed", true);
+                    return;
+                }
+                if (frame.format !== this.attachment.open.format) {
+                    await frame.acknowledge();
+                    throw new Error("Browser Host changed the Surface image format");
+                }
+                const sequence = ++this.frameSequence;
+                const released = new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        void this.finish("idle_timeout", "Browser Surface frame was not acknowledged", true);
+                    }, this.attachment.frameAcknowledgeTimeoutMs);
+                    timer.unref?.();
+                    this.pendingFrame = { sequence, release: resolve, timer };
+                });
+                const image = {
+                    subscriptionId: this.attachment.open.subscriptionId,
+                    frameSequence: sequence,
+                    viewportRevision: frame.viewportRevision,
+                    timestampMilliseconds: frame.timestampMilliseconds,
+                    width: frame.width,
+                    height: frame.height,
+                    format: frame.format,
+                    encodedBytes: frame.encodedBytes,
+                };
+                if (!this.eventQueue.push(image)) {
+                    const pending = this.pendingFrame;
+                    this.pendingFrame = undefined;
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        pending.release();
+                    }
+                    await frame.acknowledge();
+                    await this.finish("capacity", "Browser Surface event queue is full", true);
+                    return;
+                }
+                await released;
+                await frame.acknowledge();
+                if (this.closing)
+                    return;
+            }
+            if (!this.closing) {
+                await this.finish("browser_closed", "Browser Surface source ended", true);
+            }
+        }
+        catch (error) {
+            if (!this.closing) {
+                const mapped = mapSurfaceHostError(error, "Browser Surface source failed");
+                await this.finish(mapped.reason, mapped.message, true);
+            }
+        }
+    }
+    acknowledgeFrame(sequence) {
+        const pending = this.pendingFrame;
+        if (!pending || pending.sequence !== sequence) {
+            throw new DirectRuntimeBrowserSurfaceHostError("protocol_error", "Browser Surface frame acknowledgement is stale or unknown");
+        }
+        clearTimeout(pending.timer);
+        this.pendingFrame = undefined;
+        pending.release();
+    }
+    requireGeneration(generation) {
+        if (generation !== this.attachment.open.browserGeneration) {
+            throw new DirectRuntimeBrowserSurfaceHostError("generation_changed", "Browser generation changed");
+        }
+    }
+    matchesViewport(revision) {
+        return revision === this.attachment.source.getViewport().revision;
+    }
+    requireControlRole() {
+        if (this.ready.grantedRole !== "control") {
+            throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Browser Surface is view-only");
+        }
+    }
+    emitDriverChanged() {
+        const event = {
+            type: "browser.surface.driver.changed",
+            subscriptionId: this.attachment.open.subscriptionId,
+            browserGeneration: this.attachment.open.browserGeneration,
+            driver: this.driver,
+            ...(this.driver === "stream"
+                ? { driverSubscriptionId: this.attachment.open.subscriptionId }
+                : {}),
+        };
+        if (!this.eventQueue.push(event)) {
+            throw new DirectRuntimeBrowserSurfaceHostError("capacity", "Browser Surface event queue is full");
+        }
+    }
+    takeDriver() {
+        const intent = ++this.driverIntent;
+        const operation = this.enqueueDriverTransition(async () => {
+            if (this.closing || intent !== this.driverIntent)
+                return;
+            if (this.inputResetRequired) {
+                await this.inputTail;
+                await this.attachment.source.resetTrustedInput?.();
+                this.inputResetRequired = false;
+            }
+            if (this.closing || intent !== this.driverIntent)
+                return;
+            if (this.physicalDriver !== "stream") {
+                await this.attachment.source.setHumanDriver?.("stream");
+                this.physicalDriver = "stream";
+            }
+            if (this.closing || intent !== this.driverIntent)
+                return;
+            const changed = this.driver !== "stream";
+            this.inputEpoch += 1;
+            this.acceptingInput = true;
+            this.driver = "stream";
+            if (changed)
+                this.emitDriverChanged();
+        });
+        return operation.catch((error) => {
+            throw mapSurfaceHostError(error, "Browser Surface driver handoff failed");
+        });
+    }
+    releaseDriver() {
+        this.fenceInput();
+        this.inputResetRequired = true;
+        const intent = ++this.driverIntent;
+        const operation = this.enqueueDriverTransition(async () => {
+            await this.inputTail;
+            await this.attachment.source.resetTrustedInput?.();
+            this.inputResetRequired = false;
+            if (this.closing || intent !== this.driverIntent)
+                return;
+            const restingDriver = this.attachment.source.setHumanDriver ? "desktop" : "none";
+            if (this.physicalDriver !== restingDriver) {
+                await this.attachment.source.setHumanDriver?.("desktop");
+                this.physicalDriver = restingDriver;
+            }
+            if (this.closing || intent !== this.driverIntent)
+                return;
+            const changed = this.driver !== restingDriver;
+            this.driver = restingDriver;
+            if (changed)
+                this.emitDriverChanged();
+        });
+        return operation.catch((error) => {
+            throw mapSurfaceHostError(error, "Browser Surface driver release failed");
+        });
+    }
+    enqueueDriverTransition(operation) {
+        const result = this.driverTransitionTail.then(operation, operation);
+        this.driverTransitionTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    fenceInput() {
+        this.acceptingInput = false;
+        this.inputEpoch += 1;
+    }
+    finish(reason, message, notify) {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closing = true;
+        this.fenceInput();
+        this.inputResetRequired = true;
+        this.driverIntent += 1;
+        this.attachment.signal.removeEventListener("abort", this.abortHandler);
+        const pending = this.pendingFrame;
+        this.pendingFrame = undefined;
+        if (pending) {
+            clearTimeout(pending.timer);
+            pending.release();
+        }
+        this.eventQueue.close(notify
+            ? {
+                type: "browser.surface.closed",
+                subscriptionId: this.attachment.open.subscriptionId,
+                reason,
+                ...(message === undefined ? {} : { message: message.slice(0, 1_024) }),
+            }
+            : undefined);
+        const restingDriver = this.attachment.source.setHumanDriver ? "desktop" : "none";
+        const releaseDriver = this.enqueueDriverTransition(async () => {
+            await this.inputTail;
+            try {
+                await this.attachment.source.resetTrustedInput?.();
+                this.inputResetRequired = false;
+            }
+            catch {
+                // Closing remains fail-safe: capture must still be released if the
+                // renderer no longer accepts synthesized key/button releases.
+            }
+            if (this.physicalDriver !== restingDriver) {
+                try {
+                    await this.attachment.source.setHumanDriver?.("desktop");
+                    this.physicalDriver = restingDriver;
+                }
+                catch {
+                    // Closing remains fail-safe: capture is released even if Host handoff fails.
+                }
+            }
+            this.driver = restingDriver;
+        });
+        this.closePromise = releaseDriver.then(() => this.attachment.source.close())
+            .catch(() => undefined)
+            .finally(this.attachment.onClose);
+        return this.closePromise;
+    }
+}
+class SurfaceEventQueue {
+    options;
+    items = [];
+    queuedBytes = 0;
+    waiter;
+    ended = false;
+    constructor(options) {
+        this.options = options;
+    }
+    push(event) {
+        if (this.ended)
+            return false;
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter({ done: false, value: event });
+            return true;
+        }
+        const bytes = surfaceEventBytes(event);
+        const tail = this.items.at(-1);
+        if (tail &&
+            isDriverChanged(tail.event) &&
+            isDriverChanged(event)) {
+            const nextBytes = this.queuedBytes - tail.bytes + bytes;
+            if (nextBytes > this.options.maxPendingBytes)
+                return false;
+            tail.event = event;
+            tail.bytes = bytes;
+            this.queuedBytes = nextBytes;
+            return true;
+        }
+        if (this.items.length >= this.options.maxPendingEvents ||
+            this.queuedBytes + bytes > this.options.maxPendingBytes)
+            return false;
+        this.items.push({ event, bytes });
+        this.queuedBytes += bytes;
+        return true;
+    }
+    close(finalEvent) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.items.length = 0;
+        this.queuedBytes = 0;
+        if (finalEvent) {
+            if (this.waiter)
+                this.waiter({ done: false, value: finalEvent });
+            else {
+                const bytes = surfaceEventBytes(finalEvent);
+                this.items.push({ event: finalEvent, bytes });
+                this.queuedBytes = bytes;
+            }
+        }
+        else {
+            this.waiter?.({ done: true, value: undefined });
+        }
+        this.waiter = undefined;
+    }
+    [Symbol.asyncIterator]() {
+        return { next: () => this.next() };
+    }
+    next() {
+        const pending = this.items.shift();
+        if (pending) {
+            this.queuedBytes -= pending.bytes;
+            return Promise.resolve({ done: false, value: pending.event });
+        }
+        if (this.ended)
+            return Promise.resolve({ done: true, value: undefined });
+        if (this.waiter)
+            return Promise.reject(new Error("Browser Surface event read is already pending"));
+        return new Promise((resolve) => {
+            this.waiter = resolve;
+        });
+    }
+}
+function isDriverChanged(event) {
+    return "type" in event && event.type === "browser.surface.driver.changed";
+}
+function surfaceEventBytes(event) {
+    return "encodedBytes" in event
+        ? event.encodedBytes.byteLength + 128
+        : Buffer.byteLength(JSON.stringify(event), "utf8");
+}
+function positiveLimit(value, fallback, field) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1) {
+        throw new Error(`${field} must be a positive safe integer`);
+    }
+    return resolved;
+}
+function mapSurfaceOpenError(error) {
+    if (error instanceof SessionBrowserSurfaceUnsupportedError) {
+        return new DirectRuntimeBrowserSurfaceHostError("unsupported", error.message, { cause: error });
+    }
+    if (error instanceof SessionBrowserServiceError) {
+        switch (error.code) {
+            case "invalid_request":
+                return new DirectRuntimeBrowserSurfaceHostError("protocol_error", error.message, { cause: error });
+            case "not_found":
+                return new DirectRuntimeBrowserSurfaceHostError("page_closed", error.message, { cause: error });
+            case "generation_mismatch":
+                return new DirectRuntimeBrowserSurfaceHostError("generation_changed", error.message, { cause: error });
+            case "capacity":
+                return new DirectRuntimeBrowserSurfaceHostError("capacity", error.message, { cause: error });
+            case "unavailable":
+            case "shutting_down":
+                return new DirectRuntimeBrowserSurfaceHostError("browser_closed", error.message, { cause: error });
+            case "host_failure":
+            case "outcome_unknown":
+                return new DirectRuntimeBrowserSurfaceHostError("internal_error", error.message, { cause: error });
+        }
+    }
+    return mapSurfaceHostError(error, "Browser Surface could not open");
+}
+function mapSurfaceHostError(error, fallbackMessage) {
+    if (error instanceof DirectRuntimeBrowserSurfaceHostError)
+        return error;
+    if (error instanceof SessionBrowserHostError) {
+        const reason = error.code === "page_not_found"
+            ? "page_closed"
+            : error.code === "capacity"
+                ? "capacity"
+                : "browser_closed";
+        return new DirectRuntimeBrowserSurfaceHostError(reason, error.message, { cause: error });
+    }
+    const message = error instanceof Error ? error.message : fallbackMessage;
+    return new DirectRuntimeBrowserSurfaceHostError("internal_error", message, { cause: error });
+}