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

package/dist/session-browser-service.d.ts

@@ -0,0 +1,248 @@
+import { type RuntimeBrowserCloseParams, type RuntimeBrowserCloseResult, type RuntimeBrowserExecutionBackend, type RuntimeBrowserOpenParams, type RuntimeBrowserPageCreateParams, type RuntimeBrowserPageMutationParams, type RuntimeBrowserPageNavigateParams, type RuntimeBrowserState, type RuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
+import type { RuntimeBrowserSurfaceFormat, RuntimeBrowserSurfaceInputEvent } from "@rynx-ai/protocol/runtime-browser-surface";
+import { type RuntimeBrowserEndpointDescriptor } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+export interface SessionBrowserHostCreateInput {
+    sessionId: string;
+    browserGeneration: number;
+    url?: string;
+}
+/** Generation-scoped physical page state. `hostPageId` never leaves the service. */
+export interface SessionBrowserHostPage {
+    hostPageId: string;
+    url: string;
+    title: string;
+    loading: boolean;
+    canGoBack: boolean;
+    canGoForward: boolean;
+}
+export interface SessionBrowserHostSnapshot {
+    pages: SessionBrowserHostPage[];
+    activeHostPageId: string | null;
+}
+/** Engine viewport used by pixels and trusted human input for one physical Page. */
+export interface SessionBrowserHostSurfaceViewport {
+    revision: number;
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+}
+/** A bounded Host frame. `acknowledge` releases its upstream frame exactly once. */
+export interface SessionBrowserHostSurfaceFrame {
+    browserGeneration: number;
+    viewportRevision: number;
+    timestampMilliseconds: number;
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    format: RuntimeBrowserSurfaceFormat;
+    encodedBytes: Uint8Array;
+    acknowledge(): Promise<void>;
+}
+export interface SessionBrowserHostSurfaceTrustedInput {
+    browserGeneration: number;
+    viewportRevision: number;
+    event: RuntimeBrowserSurfaceInputEvent;
+}
+/** One generation/page-scoped capture and trusted-input source. */
+export interface SessionBrowserHostSurfaceSource {
+    readonly browserGeneration: number;
+    readonly hostPageId: string;
+    readonly format: RuntimeBrowserSurfaceFormat;
+    readonly frames: AsyncIterable<SessionBrowserHostSurfaceFrame>;
+    getViewport(): SessionBrowserHostSurfaceViewport;
+    /** Optional atomic handoff between native guest input and streamed control. */
+    setHumanDriver?(driver: "desktop" | "stream"): Promise<void>;
+    dispatchTrustedInput(input: SessionBrowserHostSurfaceTrustedInput): Promise<void>;
+    /** Releases physical keys/buttons still held by the streamed driver. Hosts
+     * without a native desktop driver need this when a viewer releases and later
+     * retakes the same live Surface. */
+    resetTrustedInput?(): Promise<void>;
+    /** Idempotent. It ends `frames` and releases capture even after Host loss. */
+    close(): Promise<void>;
+}
+export interface SessionBrowserHostSurfaceOpenInput {
+    browserGeneration: number;
+    hostPageId: string;
+    format: RuntimeBrowserSurfaceFormat;
+    quality: number;
+    maximumFrameRate: number;
+    signal?: AbortSignal;
+}
+/** Semantic Page request used by presentation adapters; physical Page identity stays private. */
+export interface SessionBrowserSurfaceOpenInput {
+    sessionId: string;
+    browserGeneration: number;
+    pageId: string;
+    format: RuntimeBrowserSurfaceFormat;
+    quality: number;
+    maximumFrameRate: number;
+    signal?: AbortSignal;
+}
+export type SessionBrowserSurfaceSource = Omit<SessionBrowserHostSurfaceSource, "hostPageId">;
+/** One already-running semantic Page that can be exposed by a local inspection gateway. */
+export interface SessionBrowserInspectionTarget {
+    sessionId: string;
+    browserGeneration: number;
+    pageId: string;
+    executionBackend: RuntimeBrowserExecutionBackend;
+    url: string;
+    title: string;
+}
+/** Exact loopback Page endpoint resolved only after the semantic tuple is fenced. */
+export interface SessionBrowserInspectionEndpoint {
+    endpoint: string;
+    engineVersion: string;
+}
+export declare class SessionBrowserSurfaceUnsupportedError extends Error {
+    constructor();
+}
+export type SessionBrowserHostEvent = {
+    type: "changed";
+    browserGeneration: number;
+} | {
+    type: "page.replaced";
+    browserGeneration: number;
+    previousHostPageId: string;
+    page: SessionBrowserHostPage;
+} | {
+    type: "unavailable";
+    browserGeneration: number;
+    reason: string;
+};
+/** One physical Browser generation. Implementations must make `close` idempotent. */
+export interface SessionBrowserHostHandle {
+    readonly browserGeneration: number;
+    readonly executionBackend: RuntimeBrowserExecutionBackend;
+    readonly capabilities: readonly string[];
+    readonly events: AsyncIterable<SessionBrowserHostEvent>;
+    /** Runtime-local automation handoff. It is never projected into Browser state or Direct RPC. */
+    getCdpEndpoint(): Promise<{
+        endpoint: string;
+        engineVersion: string;
+        pageTargetId?: string;
+    }>;
+    /** Optional exact physical Page handoff for the daemon-local inspection gateway. */
+    getPageCdpEndpoint?(hostPageId: string): Promise<SessionBrowserInspectionEndpoint>;
+    /** Optional physical presentation primitive; it never projects native CDP. */
+    openSurface?(input: SessionBrowserHostSurfaceOpenInput): Promise<SessionBrowserHostSurfaceSource>;
+    snapshot(): Promise<SessionBrowserHostSnapshot>;
+    /** Optional idempotent handoff from physical identity to the semantic Page ID. */
+    bindPage?(hostPageId: string, pageId: string): Promise<void>;
+    createPage(url?: string): Promise<void>;
+    closePage(hostPageId: string): Promise<void>;
+    activatePage(hostPageId: string): Promise<void>;
+    navigatePage(hostPageId: string, url: string): Promise<void>;
+    goBack(hostPageId: string): Promise<void>;
+    goForward(hostPageId: string): Promise<void>;
+    reload(hostPageId: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** Physical Browser factory selected by the Runtime composition root. */
+export interface SessionBrowserHost {
+    createBrowser(input: SessionBrowserHostCreateInput): Promise<SessionBrowserHostHandle>;
+    deleteSessionData?(sessionId: string): Promise<void>;
+}
+export interface SessionBrowserRegistryPort {
+    exists(sessionId: string): boolean | Promise<boolean>;
+}
+export interface SessionBrowserServicePorts {
+    host: SessionBrowserHost;
+    /** Omit only when the caller has already established Session existence. */
+    sessions?: SessionBrowserRegistryPort;
+}
+export interface SessionBrowserServiceOptions {
+    /** Injectable only so opaque identity behavior is deterministic in tests. */
+    pageIdFactory?: () => string;
+    /** Injectable boot nonce; production randomization fences stale pre-restart mutations. */
+    bootGenerationSeed?: number;
+}
+export type SessionBrowserHostErrorCode = "unavailable" | "page_not_found" | "capacity" | "outcome_unknown";
+/** Expected failure reported by a Browser Host implementation. */
+export declare class SessionBrowserHostError extends Error {
+    readonly code: SessionBrowserHostErrorCode;
+    constructor(code: SessionBrowserHostErrorCode, message: string, options?: ErrorOptions);
+}
+export type SessionBrowserServiceErrorCode = "invalid_request" | "not_found" | "generation_mismatch" | "unavailable" | "capacity" | "host_failure" | "outcome_unknown" | "shutting_down";
+/** Stable application error; transports map the code without exposing Host diagnostics. */
+export declare class SessionBrowserServiceError extends Error {
+    readonly code: SessionBrowserServiceErrorCode;
+    constructor(code: SessionBrowserServiceErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Transport-neutral owner of the Runtime -> Session -> Browser -> Page model.
+ * Every operation for one Session shares one queue; different Sessions remain independent.
+ */
+export declare class SessionBrowserService {
+    private readonly ports;
+    private readonly records;
+    private readonly generations;
+    private readonly queues;
+    private readonly deletingSessions;
+    private readonly observers;
+    private readonly pageIdFactory;
+    private readonly bootGenerationSeed;
+    private shuttingDown;
+    private closeAllPromise?;
+    constructor(ports: SessionBrowserServicePorts, options?: SessionBrowserServiceOptions);
+    /** Number of Session Browsers that still own a physical Host handle. */
+    activeBrowserCount(): number;
+    /**
+     * Snapshot the current in-memory inspection inventory. Discovery is
+     * deliberately passive: it neither creates Browsers nor asks a Host to
+     * reconcile physical state.
+     */
+    listInspectionTargets(): SessionBrowserInspectionTarget[];
+    /**
+     * Resolve one semantic inspection target to an exact Runtime-local Page
+     * endpoint. The physical Page identity never enters discovery or Direct RPC.
+     */
+    getInspectionPageEndpoint(input: RuntimeBrowserPageMutationParams): Promise<SessionBrowserInspectionEndpoint>;
+    getState(input: RuntimeBrowserStateGetParams): Promise<RuntimeBrowserState | null>;
+    /**
+     * Runtime-local automation handoff. This method is deliberately absent from
+     * RemoteRuntimeBrowserHost and Direct RPC so a CDP endpoint cannot cross a
+     * Runtime boundary.
+     */
+    getRuntimeLocalEndpoint(sessionId: string): Promise<RuntimeBrowserEndpointDescriptor>;
+    /**
+     * Resolve one opaque Page to its generation-local Host source. This is the
+     * only presentation path allowed to cross the semantic/physical Page seam.
+     */
+    validateSurfaceTarget(input: Pick<SessionBrowserSurfaceOpenInput, "sessionId" | "browserGeneration" | "pageId">): Promise<void>;
+    openSurface(input: SessionBrowserSurfaceOpenInput): Promise<SessionBrowserSurfaceSource>;
+    open(input: RuntimeBrowserOpenParams): Promise<RuntimeBrowserState>;
+    close(input: RuntimeBrowserCloseParams): Promise<RuntimeBrowserCloseResult>;
+    createPage(input: RuntimeBrowserPageCreateParams): Promise<RuntimeBrowserState>;
+    closePage(input: RuntimeBrowserPageMutationParams): Promise<RuntimeBrowserState>;
+    activatePage(input: RuntimeBrowserPageMutationParams): Promise<RuntimeBrowserState>;
+    navigatePage(input: RuntimeBrowserPageNavigateParams): Promise<RuntimeBrowserState>;
+    goBack(input: RuntimeBrowserPageMutationParams): Promise<RuntimeBrowserState>;
+    goForward(input: RuntimeBrowserPageMutationParams): Promise<RuntimeBrowserState>;
+    reload(input: RuntimeBrowserPageMutationParams): Promise<RuntimeBrowserState>;
+    /** Session deletion fence: no later Browser operation may enter for this Session ID. */
+    cleanupSession(sessionId: string): Promise<void>;
+    /** Daemon shutdown closes engines but intentionally preserves Session profile data. */
+    closeAll(): Promise<void>;
+    private closeEveryRecord;
+    private createBrowser;
+    private closeUnavailableForRecreate;
+    private pageMutation;
+    private pageMutationParsed;
+    private runMutation;
+    private reconcileForRead;
+    private reconcileForMutation;
+    private tryReconcileAfterRejectedMutation;
+    private reconcile;
+    private createPageId;
+    private project;
+    private observe;
+    private consumeEvents;
+    private applyReplacement;
+    private isCurrent;
+    private requireRecord;
+    private requireReadyRecord;
+    private requireGeneration;
+    private ensureSessionExists;
+    private ensureRunning;
+    private exclusive;
+}