@rynx-ai/server 0.1.11-beta.5 → 0.1.11-beta.51

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. */
@@ -15,6 +19,7 @@ export interface SessionBrowserHostPage {
     loading: boolean;
     canGoBack: boolean;
     canGoForward: boolean;
+    observationStale?: boolean;
 }
 export interface SessionBrowserHostSnapshot {
     pages: SessionBrowserHostPage[];
@@ -124,6 +129,12 @@ export interface SessionBrowserHostHandle {
     }>;
     /** Optional exact physical Page handoff for the daemon-local inspection gateway. */
     getPageCdpEndpoint?(hostPageId: string): Promise<SessionBrowserInspectionEndpoint>;
+    /** Automation facade, distinct from raw DevTools inspection; binds exactly one existing Page. */
+    getPageAutomationEndpoint?(hostPageId: string): Promise<SessionBrowserInspectionEndpoint & {
+        pageTargetId: string;
+    }>;
+    /** Temporary renderability, never semantic Page selection or human window focus. */
+    acquireAutomationVisibility?(hostPageId: string, canActivate?: () => boolean): Promise<SessionBrowserAutomationVisibility>;
     /** Optional physical presentation primitive; it never projects native CDP. */
     openSurface?(input: SessionBrowserHostSurfaceOpenInput): Promise<SessionBrowserHostSurfaceSource>;
     snapshot(): Promise<SessionBrowserHostSnapshot>;
@@ -136,6 +147,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. */
@@ -152,23 +165,45 @@ export interface SessionBrowserServicePorts {
     sessions?: SessionBrowserRegistryPort;
 }
 export interface SessionBrowserServiceOptions {
+    onObservationError?: (error: unknown, target: {
+        sessionId: string;
+        browserGeneration: number;
+    }) => void;
     /** Injectable only so opaque identity behavior is deterministic in tests. */
     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 interface SessionBrowserAutomationVisibility {
+    /** Always releases resources; false suppresses physical focus restoration after human takeover. */
+    release(restoreFocus?: boolean): Promise<void>;
+}
+export interface SessionBrowserAutomationBinding extends RuntimeBrowserEndpointDescriptor {
+    pageId: string;
+    pageTargetId: string;
+    /** Synchronous physical identity fence; long driver commands never hold the Session lock. */
+    isCurrent(): boolean;
+    acquireAutomationVisibility(canActivate?: () => boolean): Promise<SessionBrowserAutomationVisibility>;
+}
+export type SessionBrowserHostErrorCode = "unavailable" | "command_timeout" | "operation_failed" | "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" | "command_timeout" | "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 +213,20 @@ 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 options;
     private readonly records;
     private readonly generations;
+    private readonly requestHeaderPolicies;
     private readonly queues;
     private readonly deletingSessions;
+    private readonly closingAutomationPages;
     private readonly observers;
     private readonly pageIdFactory;
     private readonly bootGenerationSeed;
+    private readonly requestHeaderRevisionSeed;
+    private requestHeaderRevision;
     private readonly admissionReserve?;
     private shuttingDown;
     private closeAllPromise?;
@@ -205,12 +245,15 @@ 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
      * Runtime boundary.
      */
     getRuntimeLocalEndpoint(sessionId: string): Promise<RuntimeBrowserEndpointDescriptor>;
+    resolveAutomationPage(sessionId: string, pageId?: string): Promise<SessionBrowserAutomationBinding>;
     /**
      * Resolve one opaque Page to its generation-local Host source. This is the
      * only presentation path allowed to cross the semantic/physical Page seam.
@@ -233,6 +276,8 @@ export declare class SessionBrowserService {
     private closeEveryRecord;
     private createBrowser;
     private reserveOpenAdmission;
+    private currentRequestHeaders;
+    private nextRequestHeadersRevision;
     private closeUnavailableForRecreate;
     private pageMutation;
     private pageMutationParsed;
@@ -240,6 +285,7 @@ export declare class SessionBrowserService {
     private reconcileForRead;
     private reconcileForMutation;
     private tryReconcileAfterRejectedMutation;
+    private retainRecoverableObservation;
     private reconcile;
     private createPageId;
     private project;

package/dist/session-browser-service.js

@@ -1,5 +1,7 @@
 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 { join } from "node:path";
+import { diagnosticEvents, sessionDiagnosticDir } from "@rynx-ai/core";
+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;
@@ -35,26 +37,37 @@ export class SessionBrowserServiceError extends Error {
  */
 export class SessionBrowserService {
     ports;
+    options;
     records = new Map();
     generations = new Map();
+    requestHeaderPolicies = new Map();
     queues = new Map();
     deletingSessions = new Set();
+    closingAutomationPages = new Map();
     observers = new Set();
     pageIdFactory;
     bootGenerationSeed;
+    requestHeaderRevisionSeed;
+    requestHeaderRevision = 0;
     admissionReserve;
     shuttingDown = false;
     closeAllPromise;
     constructor(ports, options = {}) {
         this.ports = ports;
+        this.options = options;
         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() {
@@ -124,7 +137,7 @@ export class SessionBrowserService {
             }
             catch (error) {
                 if (error instanceof SessionBrowserHostError &&
-                    (error.code === "unavailable" || error.code === "outcome_unknown")) {
+                    error.code === "unavailable") {
                     record.status = "unavailable";
                 }
                 throw mapHostError(error, "Browser inspection endpoint is unavailable");
@@ -144,6 +157,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
@@ -170,11 +247,53 @@ export class SessionBrowserService {
                 });
             }
             catch (error) {
-                record.status = "unavailable";
+                if (!this.retainRecoverableObservation(record, error))
+                    record.status = "unavailable";
                 throw mapHostError(error, "Browser automation endpoint is unavailable");
             }
         });
     }
+    async resolveAutomationPage(sessionId, pageId) {
+        parseInput(() => parseRuntimeBrowserStateGetParams({ sessionId }), "Browser Session is invalid");
+        return this.exclusive(sessionId, async () => {
+            this.ensureRunning();
+            await this.ensureSessionExists(sessionId);
+            const record = this.requireRecord(sessionId);
+            if (record.status !== "ready")
+                throw new SessionBrowserServiceError("unavailable", "Browser is not available");
+            const selected = pageId ?? record.activePageId;
+            const page = selected ? record.pagesById.get(selected) : undefined;
+            if (!page)
+                throw new SessionBrowserServiceError("not_found", "Browser Page was not found; run browser pages");
+            if (!record.handle.getPageAutomationEndpoint) {
+                throw new SessionBrowserServiceError("unsupported", "Browser Host needs an upgrade for page automation");
+            }
+            const endpoint = await record.handle.getPageAutomationEndpoint(page.hostPageId);
+            const descriptor = parseRuntimeBrowserEndpointDescriptor({
+                sessionId, browserGeneration: record.browserGeneration,
+                executionBackend: record.executionBackend, ...endpoint,
+            });
+            const isCurrent = () => !this.shuttingDown && !this.deletingSessions.has(sessionId) && this.records.get(sessionId) === record &&
+                record.status === "ready" && !this.closingAutomationPages.has(JSON.stringify([sessionId, record.browserGeneration, page.pageId])) &&
+                record.pagesById.get(page.pageId)?.hostPageId === page.hostPageId;
+            return {
+                ...descriptor, pageId: page.pageId, pageTargetId: endpoint.pageTargetId, isCurrent,
+                acquireAutomationVisibility: async (canActivate) => {
+                    if (!isCurrent())
+                        throw new SessionBrowserServiceError("not_found", "Browser Page closed before render admission");
+                    if (!record.handle.acquireAutomationVisibility) {
+                        throw new SessionBrowserServiceError("unsupported", "Upgrade the Browser Host for automation rendering");
+                    }
+                    const visibility = await record.handle.acquireAutomationVisibility(page.hostPageId, canActivate);
+                    if (!isCurrent()) {
+                        await visibility.release(false).catch(() => undefined);
+                        throw new SessionBrowserServiceError("not_found", "Browser Page closed during render admission");
+                    }
+                    return visibility;
+                },
+            };
+        });
+    }
     /**
      * Resolve one opaque Page to its generation-local Host source. This is the
      * only presentation path allowed to cross the semantic/physical Page seam.
@@ -289,8 +408,20 @@ export class SessionBrowserService {
             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));
+    async closePage(input) {
+        const params = parseInput(() => parseRuntimeBrowserPageMutationParams(input), "Browser page close request is invalid");
+        const key = JSON.stringify([params.sessionId, params.browserGeneration, params.pageId]);
+        this.closingAutomationPages.set(key, (this.closingAutomationPages.get(key) ?? 0) + 1);
+        try {
+            return await this.pageMutation(params, "Browser page close request is invalid", (record, hostPageId) => record.handle.closePage(hostPageId));
+        }
+        finally {
+            const remaining = this.closingAutomationPages.get(key) - 1;
+            if (remaining)
+                this.closingAutomationPages.set(key, remaining);
+            else
+                this.closingAutomationPages.delete(key);
+        }
     }
     activatePage(input) {
         return this.pageMutation(input, "Browser page activation request is invalid", (record, hostPageId) => record.handle.activatePage(hostPageId));
@@ -314,6 +445,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 +501,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 +521,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 +593,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 {
@@ -490,7 +642,7 @@ export class SessionBrowserService {
         }
         catch (error) {
             if (error instanceof SessionBrowserHostError &&
-                (error.code === "unavailable" || error.code === "outcome_unknown")) {
+                error.code === "unavailable") {
                 record.status = "unavailable";
             }
             if (error instanceof SessionBrowserHostError && error.code === "page_not_found") {
@@ -503,7 +655,8 @@ export class SessionBrowserService {
             return this.project(record);
         }
         catch (error) {
-            record.status = "unavailable";
+            if (!this.retainRecoverableObservation(record, error))
+                record.status = "unavailable";
             throw new SessionBrowserServiceError("outcome_unknown", "Browser operation completed but its outcome could not be reconciled", { cause: error });
         }
     }
@@ -512,6 +665,8 @@ export class SessionBrowserService {
             await this.reconcile(record);
         }
         catch (error) {
+            if (this.retainRecoverableObservation(record, error))
+                return;
             record.status = "unavailable";
             throw new SessionBrowserServiceError("host_failure", "Browser Host state could not be reconciled", { cause: error });
         }
@@ -521,6 +676,9 @@ export class SessionBrowserService {
             await this.reconcile(record);
         }
         catch (error) {
+            if (this.retainRecoverableObservation(record, error)) {
+                throw mapHostError(error, "Browser state observation is temporarily unavailable");
+            }
             record.status = "unavailable";
             throw new SessionBrowserServiceError("unavailable", "Browser became unavailable while reconciling Host state", { cause: error });
         }
@@ -529,9 +687,24 @@ export class SessionBrowserService {
         try {
             await this.reconcile(record);
         }
-        catch {
-            record.status = "unavailable";
+        catch (error) {
+            if (!this.retainRecoverableObservation(record, error))
+                record.status = "unavailable";
+        }
+    }
+    retainRecoverableObservation(record, error) {
+        if (!(error instanceof SessionBrowserHostError) ||
+            !["command_timeout", "operation_failed", "outcome_unknown"].includes(error.code))
+            return false;
+        record.observationStale = true;
+        try {
+            this.options.onObservationError?.(error, {
+                sessionId: record.sessionId,
+                browserGeneration: record.browserGeneration,
+            });
         }
+        catch { /* A diagnostic sink cannot change Browser readiness. */ }
+        return true;
     }
     async reconcile(record) {
         const snapshot = await record.handle.snapshot();
@@ -559,6 +732,7 @@ export class SessionBrowserService {
                 loading: hostPage.loading,
                 canGoBack: hostPage.canGoBack,
                 canGoForward: hostPage.canGoForward,
+                ...(hostPage.observationStale === undefined ? {} : { observationStale: hostPage.observationStale }),
             });
         }
         if (snapshot.activeHostPageId !== null &&
@@ -611,6 +785,7 @@ export class SessionBrowserService {
         record.pageOrder = parsed.pages.map((page) => page.pageId);
         record.activePageId = parsed.activePageId;
         record.capabilities = parsed.capabilities;
+        record.observationStale = parsed.pages.some((page) => page.observationStale);
     }
     createPageId(record, pending) {
         for (let attempt = 0; attempt < MAX_PAGE_ID_FACTORY_ATTEMPTS; attempt += 1) {
@@ -631,6 +806,7 @@ export class SessionBrowserService {
             activePageId: record.activePageId,
             pages: record.pageOrder.map((pageId) => record.pagesById.get(pageId)),
             capabilities: record.capabilities,
+            ...(record.observationStale ? { observationStale: true } : {}),
         });
         if (!parsed)
             throw new Error("Browser record unexpectedly projected to absence");
@@ -641,9 +817,13 @@ export class SessionBrowserService {
         this.observers.add(observer);
     }
     async consumeEvents(record) {
+        const log = diagnosticEvents(join(sessionDiagnosticDir("browser", record.sessionId), "page-events.jsonl"), { sessionId: record.sessionId });
+        const lifecycle = diagnosticEvents(join(sessionDiagnosticDir("browser", record.sessionId), "browser-host.log"), { sessionId: record.sessionId, browserGeneration: record.browserGeneration });
+        lifecycle("browser.observer.started");
         let failed;
         try {
             for await (const event of record.handle.events) {
+                log("browser.observation", { ...event });
                 await this.exclusive(record.sessionId, async () => {
                     if (!this.isCurrent(record, event.browserGeneration))
                         return;
@@ -658,8 +838,9 @@ export class SessionBrowserService {
                     try {
                         await this.reconcile(record);
                     }
-                    catch {
-                        record.status = "unavailable";
+                    catch (error) {
+                        if (!this.retainRecoverableObservation(record, error))
+                            record.status = "unavailable";
                     }
                 }, true);
             }
@@ -667,6 +848,7 @@ export class SessionBrowserService {
         catch (error) {
             failed = error;
         }
+        lifecycle("browser.observer.ended", { ...(failed ? { error: String(failed) } : {}) });
         await this.exclusive(record.sessionId, async () => {
             if (!this.isCurrent(record, record.browserGeneration))
                 return;
@@ -755,6 +937,12 @@ function mapHostError(error, fallbackMessage) {
     if (error instanceof SessionBrowserServiceError)
         return error;
     if (error instanceof SessionBrowserHostError) {
+        if (error.code === "command_timeout") {
+            return new SessionBrowserServiceError("command_timeout", "Browser command timed out; do not automatically repeat an accepted action", { cause: error });
+        }
+        if (error.code === "operation_failed") {
+            return new SessionBrowserServiceError("host_failure", fallbackMessage, { cause: error });
+        }
         if (error.code === "page_not_found") {
             return new SessionBrowserServiceError("not_found", "Browser Page was not found", {
                 cause: error,
@@ -768,12 +956,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-browser-surface-coordinator.d.ts

@@ -20,5 +20,7 @@ export declare class SessionBrowserSurfaceCoordinator implements DirectRuntimeBr
     private readonly maxPendingEventBytes;
     constructor(browsers: SessionBrowserService, options?: SessionBrowserSurfaceCoordinatorOptions);
     open(frame: RuntimeBrowserSurfaceOpenFrame, context: Parameters<DirectRuntimeBrowserSurfaceHost["open"]>[1]): Promise<DirectRuntimeBrowserSurfaceAttachment>;
+    isHumanControlled(sessionId: string, browserGeneration: number, pageId: string): boolean;
+    isBrowserHumanControlled(sessionId: string, browserGeneration: number): boolean;
     private exclusivePage;
 }

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

@@ -95,6 +95,17 @@ export class SessionBrowserSurfaceCoordinator {
             return attachment;
         });
     }
+    isHumanControlled(sessionId, browserGeneration, pageId) {
+        const page = this.pages.get(`${sessionId}\u0000${pageId}`);
+        return page?.browserGeneration === browserGeneration && page.hasHumanControl();
+    }
+    isBrowserHumanControlled(sessionId, browserGeneration) {
+        for (const [key, page] of this.pages) {
+            if (key.startsWith(`${sessionId}\u0000`) && page.browserGeneration === browserGeneration && page.hasHumanControl())
+                return true;
+        }
+        return false;
+    }
     exclusivePage(pageKey, operation) {
         const previous = this.pageQueues.get(pageKey) ?? Promise.resolve();
         const result = previous.then(operation, operation);
@@ -173,6 +184,9 @@ class SharedPageSurface {
     getViewport() {
         return this.page.source.getViewport();
     }
+    hasHumanControl() {
+        return Boolean(this.owner || this.desiredOwner);
+    }
     driverState() {
         return this.owner
             ? { driver: "stream", driverSubscriptionId: this.owner.subscriptionId }
@@ -647,6 +661,7 @@ function mapSurfaceOpenError(error) {
             case "shutting_down":
                 return new DirectRuntimeBrowserSurfaceHostError("browser_closed", error.message, { cause: error });
             case "host_failure":
+            case "command_timeout":
             case "outcome_unknown":
                 return new DirectRuntimeBrowserSurfaceHostError("internal_error", error.message, { cause: error });
         }

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;
+}