@rynx-ai/server 0.1.11-beta.4 → 0.1.11-beta.41

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

@@ -1,10 +1,14 @@
 import type { AdmissionReservation } from "@rynx-ai/core";
-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 RuntimeBrowserCloseParams, type RuntimeBrowserCloseResult, type RuntimeBrowserExecutionBackend, type RuntimeBrowserOpenParams, type RuntimeBrowserPageCreateParams, type RuntimeBrowserPageMutationParams, type RuntimeBrowserPageNavigateParams, type RuntimeBrowserRequestHeadersConfig, type RuntimeBrowserRequestHeadersGetParams, type RuntimeBrowserRequestHeadersPolicy, type RuntimeBrowserRequestHeadersSetParams, 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;
+    /** Required at this internal boundary so every Host installs the policy
+     * before it permits the first navigation. Wire-version compatibility stays
+     * inside the concrete Host adapter. */
+    requestHeaders: RuntimeBrowserRequestHeadersConfig;
     url?: string;
 }
 /** Generation-scoped physical page state. `hostPageId` never leaves the service. */
@@ -136,6 +140,8 @@ export interface SessionBrowserHostHandle {
     goBack(hostPageId: string): Promise<void>;
     goForward(hostPageId: string): Promise<void>;
     reload(hostPageId: string): Promise<void>;
+    /** Replaces the Session-wide desired request Header projection for this generation. */
+    setRequestHeaders(config: RuntimeBrowserRequestHeadersConfig): Promise<void>;
     close(): Promise<void>;
 }
 /** Physical Browser factory selected by the Runtime composition root. */
@@ -156,19 +162,26 @@ export interface SessionBrowserServiceOptions {
     pageIdFactory?: () => string;
     /** Injectable boot nonce; production randomization fences stale pre-restart mutations. */
     bootGenerationSeed?: number;
+    /** Injectable only for deterministic CAS tests; production uses 128 random bits. */
+    requestHeaderRevisionSeed?: string;
     /**
      * Synchronous daemon admission fence. A successful reservation is held until
      * Browser open has either failed or registered the physical Host handle.
      */
     admissionReserve?: () => AdmissionReservation | undefined;
 }
-export type SessionBrowserHostErrorCode = "unavailable" | "page_not_found" | "capacity" | "outcome_unknown";
+export type SessionBrowserHostErrorCode = "unavailable" | "unsupported" | "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";
+/** Narrow Session-owned policy port used by transports and Plugin hosting. */
+export interface SessionBrowserRequestHeadersPort {
+    getRequestHeaders(input: RuntimeBrowserRequestHeadersGetParams): Promise<RuntimeBrowserRequestHeadersPolicy>;
+    setRequestHeaders(input: RuntimeBrowserRequestHeadersSetParams): Promise<RuntimeBrowserRequestHeadersPolicy>;
+}
+export type SessionBrowserServiceErrorCode = "invalid_request" | "not_found" | "generation_mismatch" | "revision_mismatch" | "unsupported" | "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;
@@ -178,15 +191,18 @@ export declare class SessionBrowserServiceError extends Error {
  * 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 {
+export declare class SessionBrowserService implements SessionBrowserRequestHeadersPort {
     private readonly ports;
     private readonly records;
     private readonly generations;
+    private readonly requestHeaderPolicies;
     private readonly queues;
     private readonly deletingSessions;
     private readonly observers;
     private readonly pageIdFactory;
     private readonly bootGenerationSeed;
+    private readonly requestHeaderRevisionSeed;
+    private requestHeaderRevision;
     private readonly admissionReserve?;
     private shuttingDown;
     private closeAllPromise?;
@@ -205,6 +221,8 @@ export declare class SessionBrowserService {
      */
     getInspectionPageEndpoint(input: RuntimeBrowserPageMutationParams): Promise<SessionBrowserInspectionEndpoint>;
     getState(input: RuntimeBrowserStateGetParams): Promise<RuntimeBrowserState | null>;
+    getRequestHeaders(input: RuntimeBrowserRequestHeadersGetParams): Promise<RuntimeBrowserRequestHeadersPolicy>;
+    setRequestHeaders(input: RuntimeBrowserRequestHeadersSetParams): Promise<RuntimeBrowserRequestHeadersPolicy>;
     /**
      * Runtime-local automation handoff. This method is deliberately absent from
      * RemoteRuntimeBrowserHost and Direct RPC so a CDP endpoint cannot cross a
@@ -233,6 +251,8 @@ export declare class SessionBrowserService {
     private closeEveryRecord;
     private createBrowser;
     private reserveOpenAdmission;
+    private currentRequestHeaders;
+    private nextRequestHeadersRevision;
     private closeUnavailableForRecreate;
     private pageMutation;
     private pageMutationParsed;

package/dist/session-browser-service.js

@@ -1,5 +1,5 @@
 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 { RUNTIME_BROWSER_MAX_PAGES, parseRuntimeBrowserRequestHeadersGetParams, parseRuntimeBrowserRequestHeadersSetParams, 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;
@@ -37,11 +37,14 @@ export class SessionBrowserService {
     ports;
     records = new Map();
     generations = new Map();
+    requestHeaderPolicies = new Map();
     queues = new Map();
     deletingSessions = new Set();
     observers = new Set();
     pageIdFactory;
     bootGenerationSeed;
+    requestHeaderRevisionSeed;
+    requestHeaderRevision = 0;
     admissionReserve;
     shuttingDown = false;
     closeAllPromise;
@@ -49,12 +52,17 @@ export class SessionBrowserService {
         this.ports = ports;
         this.pageIdFactory = options.pageIdFactory ?? (() => `page_${randomUUID()}`);
         this.bootGenerationSeed = options.bootGenerationSeed ?? randomBootGenerationSeed();
+        this.requestHeaderRevisionSeed = options.requestHeaderRevisionSeed ??
+            randomBytes(16).toString("base64url");
         this.admissionReserve = options.admissionReserve;
         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");
         }
+        if (!/^[A-Za-z0-9_-]{16,128}$/.test(this.requestHeaderRevisionSeed)) {
+            throw new Error("Browser request Header revision seed must be an opaque 16-128 character token");
+        }
     }
     /** Number of Session Browsers that still own a physical Host handle. */
     activeBrowserCount() {
@@ -144,6 +152,70 @@ export class SessionBrowserService {
             return this.project(record);
         });
     }
+    async getRequestHeaders(input) {
+        const params = parseInput(() => parseRuntimeBrowserRequestHeadersGetParams(input), "Browser request headers read is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            return cloneRequestHeadersPolicy(this.currentRequestHeaders(params.sessionId));
+        });
+    }
+    async setRequestHeaders(input) {
+        const params = parseInput(() => parseRuntimeBrowserRequestHeadersSetParams(input), "Browser request headers update is invalid");
+        return this.exclusive(params.sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(params.sessionId);
+            const current = this.currentRequestHeaders(params.sessionId);
+            if (params.expectedRevision !== current.revision) {
+                throw new SessionBrowserServiceError("revision_mismatch", "Browser request headers changed since they were read");
+            }
+            const nextConfig = {
+                enabled: params.enabled,
+                headers: params.headers.map((header) => ({ ...header })),
+            };
+            if (sameRequestHeadersConfig(current, nextConfig)) {
+                return cloneRequestHeadersPolicy(current);
+            }
+            // Reserve the next token before touching a live Host so revision-space
+            // exhaustion can never turn a successfully applied policy into an
+            // uncommitted outcome. Gaps after Host failure are harmless.
+            const nextRevision = this.nextRequestHeadersRevision();
+            const record = this.records.get(params.sessionId);
+            if (record && record.status !== "ready") {
+                await this.closeUnavailableForRecreate(record);
+            }
+            else if (record && !sameEffectiveRequestHeaders(current, nextConfig)) {
+                try {
+                    await record.handle.setRequestHeaders(nextConfig);
+                }
+                catch (error) {
+                    // A definite compatibility rejection did not touch the live Host.
+                    // Preserve both the current Browser and committed policy so callers
+                    // can upgrade the Host or close/reopen explicitly without data loss.
+                    if (error instanceof SessionBrowserHostError && error.code === "unsupported") {
+                        throw mapHostError(error, "Browser Host does not support request headers");
+                    }
+                    record.status = "unavailable";
+                    try {
+                        await record.handle.close();
+                        if (this.records.get(params.sessionId) === record) {
+                            this.records.delete(params.sessionId);
+                        }
+                    }
+                    catch (closeError) {
+                        throw new SessionBrowserServiceError("outcome_unknown", "Browser request headers may have been partially applied", { cause: new AggregateError([error, closeError]) });
+                    }
+                    throw mapHostError(error, "Browser Host rejected the request headers update");
+                }
+            }
+            const policy = {
+                ...nextConfig,
+                revision: nextRevision,
+            };
+            this.requestHeaderPolicies.set(params.sessionId, policy);
+            return cloneRequestHeadersPolicy(policy);
+        });
+    }
     /**
      * Runtime-local automation handoff. This method is deliberately absent from
      * RemoteRuntimeBrowserHost and Direct RPC so a CDP endpoint cannot cross a
@@ -314,6 +386,9 @@ export class SessionBrowserService {
         this.deletingSessions.add(parsed);
         await this.exclusive(parsed, async () => {
             const failures = [];
+            // Header values are runtime-only and may be sensitive. Forget them as
+            // soon as deletion owns the Session, even if physical cleanup fails.
+            this.requestHeaderPolicies.delete(parsed);
             const record = this.records.get(parsed);
             if (record) {
                 record.status = "closing";
@@ -367,6 +442,9 @@ export class SessionBrowserService {
             }, true)));
         }
         await Promise.allSettled([...this.observers]);
+        // Values may be sensitive. Once the service is fenced they have no valid
+        // reader, so do not retain them for the rest of a graceful process exit.
+        this.requestHeaderPolicies.clear();
         if (failures.length > 0) {
             throw new SessionBrowserServiceError("host_failure", "One or more Browsers did not close during shutdown", { cause: failures[0] });
         }
@@ -384,6 +462,7 @@ export class SessionBrowserService {
             handle = await this.ports.host.createBrowser({
                 sessionId: params.sessionId,
                 browserGeneration,
+                requestHeaders: cloneRequestHeadersConfig(this.currentRequestHeaders(params.sessionId)),
                 ...(params.url === undefined ? {} : { url: params.url }),
             });
         }
@@ -455,6 +534,20 @@ export class SessionBrowserService {
         }
         return admission;
     }
+    currentRequestHeaders(sessionId) {
+        return this.requestHeaderPolicies.get(sessionId) ?? {
+            enabled: false,
+            headers: [],
+            revision: `${this.requestHeaderRevisionSeed}.0`,
+        };
+    }
+    nextRequestHeadersRevision() {
+        if (this.requestHeaderRevision >= Number.MAX_SAFE_INTEGER) {
+            throw new SessionBrowserServiceError("capacity", "Browser request headers revision space is exhausted");
+        }
+        this.requestHeaderRevision += 1;
+        return `${this.requestHeaderRevisionSeed}.${this.requestHeaderRevision.toString(36)}`;
+    }
     async closeUnavailableForRecreate(record) {
         record.status = "closing";
         try {
@@ -768,12 +861,45 @@ function mapHostError(error, fallbackMessage) {
         if (error.code === "outcome_unknown") {
             return new SessionBrowserServiceError("outcome_unknown", "Browser Host operation outcome is unknown", { cause: error });
         }
+        if (error.code === "unsupported") {
+            return new SessionBrowserServiceError("unsupported", "Browser Host does not support this operation", { cause: error });
+        }
         return new SessionBrowserServiceError("unavailable", "Browser Host is unavailable", {
             cause: error,
         });
     }
     return new SessionBrowserServiceError("host_failure", fallbackMessage, { cause: error });
 }
+function cloneRequestHeadersConfig(config) {
+    return {
+        enabled: config.enabled,
+        headers: config.headers.map((header) => ({ ...header })),
+    };
+}
+function cloneRequestHeadersPolicy(policy) {
+    return {
+        ...cloneRequestHeadersConfig(policy),
+        revision: policy.revision,
+    };
+}
+function sameRequestHeadersConfig(left, right) {
+    return left.enabled === right.enabled && sameRequestHeaderRows(left.headers, right.headers, true);
+}
+function sameEffectiveRequestHeaders(left, right) {
+    return sameRequestHeaderRows(left.enabled ? left.headers : [], right.enabled ? right.headers : [], false);
+}
+function sameRequestHeaderRows(left, right, preserveNameCase) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((header, index) => {
+        const candidate = right[index];
+        return candidate !== undefined &&
+            (preserveNameCase
+                ? header.name === candidate.name
+                : header.name.toLowerCase() === candidate.name.toLowerCase()) &&
+            header.value === candidate.value;
+    });
+}
 function validateHostPageId(value) {
     if (typeof value !== "string" ||
         value.length === 0 ||

package/dist/session-pending-inputs.d.ts

@@ -0,0 +1,42 @@
+import type { UserContentPart } from "@rynx-ai/protocol";
+export interface MachineSessionPendingInput {
+    pendingId: string;
+    content: UserContentPart[];
+}
+export interface MachineSessionPendingInputRecord {
+    clientMessageId: string;
+    content: UserContentPart[];
+}
+export interface MachineSessionDrainedInput extends MachineSessionPendingInput {
+    clientMessageId: string;
+}
+export interface MachineSessionPendingInputPort {
+    record(sessionId: string, input: MachineSessionPendingInputRecord): string;
+    resolve(sessionId: string, pendingId: string): void;
+    peekOldest(sessionId: string): MachineSessionDrainedInput | undefined;
+    resolveOldest(sessionId: string): MachineSessionDrainedInput | undefined;
+    findByClientMessageId(sessionId: string, clientMessageId: string): MachineSessionPendingInput | undefined;
+    snapshotFor(sessionId: string): MachineSessionPendingInput[];
+    deleteSession(sessionId: string): void;
+}
+/**
+ * Process-live FIFO of web-composer inputs awaiting their native transcript
+ * echo. The message is deliberately not persisted when the send POST succeeds:
+ * the Provider transcript remains the sole durable writer. This index only
+ * keeps the temporary bubble recoverable across page rebinds until that echo
+ * arrives.
+ */
+export declare class SessionPendingInputIndex implements MachineSessionPendingInputPort {
+    private readonly ttlMs;
+    private readonly now;
+    private readonly entries;
+    constructor(ttlMs?: number, now?: () => number);
+    record(sessionId: string, input: MachineSessionPendingInputRecord): string;
+    resolve(sessionId: string, pendingId: string): void;
+    resolveOldest(sessionId: string): MachineSessionDrainedInput | undefined;
+    peekOldest(sessionId: string): MachineSessionDrainedInput | undefined;
+    findByClientMessageId(sessionId: string, clientMessageId: string): MachineSessionPendingInput | undefined;
+    snapshotFor(sessionId: string): MachineSessionPendingInput[];
+    deleteSession(sessionId: string): void;
+    private evictStale;
+}

package/dist/session-pending-inputs.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_PENDING_INPUT_TTL_MS = 10 * 60_000;
+/**
+ * Process-live FIFO of web-composer inputs awaiting their native transcript
+ * echo. The message is deliberately not persisted when the send POST succeeds:
+ * the Provider transcript remains the sole durable writer. This index only
+ * keeps the temporary bubble recoverable across page rebinds until that echo
+ * arrives.
+ */
+export class SessionPendingInputIndex {
+    ttlMs;
+    now;
+    entries = new Map();
+    constructor(ttlMs = DEFAULT_PENDING_INPUT_TTL_MS, now = Date.now) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    record(sessionId, input) {
+        this.evictStale(sessionId);
+        const pending = this.entries.get(sessionId) ?? new Map();
+        const pendingId = `pending_${randomUUID().replaceAll("-", "")}`;
+        pending.set(pendingId, {
+            pendingId,
+            clientMessageId: input.clientMessageId,
+            content: input.content.map((part) => ({ ...part })),
+            createdAt: this.now(),
+        });
+        this.entries.set(sessionId, pending);
+        return pendingId;
+    }
+    resolve(sessionId, pendingId) {
+        const pending = this.entries.get(sessionId);
+        if (!pending)
+            return;
+        pending.delete(pendingId);
+        if (pending.size === 0)
+            this.entries.delete(sessionId);
+    }
+    resolveOldest(sessionId) {
+        const input = this.peekOldest(sessionId);
+        if (input)
+            this.resolve(sessionId, input.pendingId);
+        return input;
+    }
+    peekOldest(sessionId) {
+        this.evictStale(sessionId);
+        const pending = this.entries.get(sessionId);
+        const pendingId = pending?.keys().next().value;
+        if (!pending || !pendingId)
+            return undefined;
+        const input = pending.get(pendingId);
+        return input ? cloneDrainedInput(input) : undefined;
+    }
+    findByClientMessageId(sessionId, clientMessageId) {
+        this.evictStale(sessionId);
+        const input = [...(this.entries.get(sessionId)?.values() ?? [])].find((entry) => entry.clientMessageId === clientMessageId);
+        return input ? clonePendingInput(input) : undefined;
+    }
+    snapshotFor(sessionId) {
+        this.evictStale(sessionId);
+        return [...(this.entries.get(sessionId)?.values() ?? [])].map(clonePendingInput);
+    }
+    deleteSession(sessionId) {
+        this.entries.delete(sessionId);
+    }
+    evictStale(sessionId) {
+        const pending = this.entries.get(sessionId);
+        if (!pending)
+            return;
+        const cutoff = this.now() - this.ttlMs;
+        for (const [pendingId, input] of pending) {
+            if (input.createdAt < cutoff)
+                pending.delete(pendingId);
+        }
+        if (pending.size === 0)
+            this.entries.delete(sessionId);
+    }
+}
+function clonePendingInput(input) {
+    return {
+        pendingId: input.pendingId,
+        content: input.content.map((part) => ({ ...part })),
+    };
+}
+function cloneDrainedInput(input) {
+    return { ...clonePendingInput(input), clientMessageId: input.clientMessageId };
+}

package/dist/session-portal.d.ts

@@ -0,0 +1,54 @@
+import { type IncomingMessage, type Server as HttpServer } from "node:http";
+import type { Duplex } from "node:stream";
+import Koa from "koa";
+export declare const SESSION_PORTAL_HEADER = "x-rynx-session-portal";
+export declare const SESSION_PORTAL_QUERY = "portal";
+export declare const SESSION_PORTAL_SECRET_HEADER = "x-rynx-session-portal-secret";
+export declare const SESSION_PORTAL_SECRET_QUERY = "portal_secret";
+export declare const SESSION_PORTAL_EMBED_ORIGIN_QUERY = "embed_origin";
+export interface SessionPortalAuthorization {
+    portalId: string;
+    pluginId: string;
+    scope: "plugin_sessions" | "single_session";
+    access: "read_only" | "read_write";
+    embedOrigin?: string;
+    sessionId?: string;
+    expiresAt: string;
+}
+export interface SessionPortalAuthorizationPorts {
+    redeem(ticket: string, embedOrigin?: string): (SessionPortalAuthorization & {
+        secret: string;
+    }) | undefined;
+    authorize(portalId: string, secret: string): SessionPortalAuthorization | undefined;
+    inspect(portalId: string): SessionPortalAuthorization | undefined;
+    subscribeRevocations?(listener: (portalIds: readonly string[]) => void | Promise<void>): () => void;
+    ownsSession(pluginId: string, sessionId: string): boolean;
+}
+export interface SessionPortalOptions {
+    host: string;
+    port: number;
+    scheme: "http" | "https";
+    authorization: SessionPortalAuthorizationPorts;
+    controlOrigin: string;
+    controlWebDist: string;
+    shutdownSignal?: AbortSignal;
+}
+export interface SessionPortalServer {
+    server: HttpServer;
+    stopAccepting(): void;
+    shutdown(): Promise<void>;
+}
+declare class SessionPortalTransportRegistry {
+    private readonly transports;
+    track(portalId: string, close: () => void): () => void;
+    revoke(portalIds: readonly string[]): Promise<void>;
+}
+/** Session Portal is a narrow adapter in front of the one Control service. It
+ * serves the native SPA, validates Portal grants, and forwards only authorized
+ * Session HTTP calls to Control; it owns no Session or Runtime handlers. */
+export declare function createSessionPortalApp(options: SessionPortalOptions, transports?: SessionPortalTransportRegistry): Koa;
+export declare function startSessionPortal(options: SessionPortalOptions): Promise<SessionPortalServer>;
+export declare function authorizeSessionPortalWebSocket(request: IncomingMessage, ports: SessionPortalAuthorizationPorts, runtimeSelector: string, sessionId: string): SessionPortalAuthorization | undefined;
+export declare function rejectSessionPortalUpgrade(socket: Duplex): void;
+export declare function scheduleSessionPortalExpiry(expiresAt: string, onExpire: () => void): () => void;
+export {};