@rynx-ai/server 0.1.11-beta.45 → 0.1.11-beta.48

package/dist/control-api.d.ts

@@ -226,6 +226,6 @@ export declare function createControlRouter(opts: {
     providerClis?: ProviderCliManagementHost;
 }): Router;
 /** Derive a one-line session title from the first user message: collapse
- *  whitespace, trim, and truncate to `limit` chars + an ellipsis (reference implementation's
- *  rule — no LLM call). */
+ *  whitespace, trim, and fit within `limit` characters, including an ellipsis
+ *  when truncated. No LLM call is made. */
 export declare function synthesizeSessionTitle(message: string, limit?: number): string;

package/dist/control-api.js

@@ -15,7 +15,7 @@ import { DIRECT_RUNTIME_CONTROL_PATH, encodePairingCode, } from "@rynx-ai/protoc
 import { PLUGIN_CONSOLE_INSTALL_PREPARATIONS_PATH, PLUGIN_CONSOLE_MARKETPLACES_PATH, PLUGIN_INSTALL_PREPARATIONS_PATH, PLUGIN_MARKETPLACES_PATH, parsePluginInstallCommitInput, parsePluginInstallPrepareInput, parsePluginMarketplaceAddInput, } from "@rynx-ai/protocol/plugin-management";
 import { parseDaemonStatus } from "@rynx-ai/protocol/remote-runtime";
 import { materializeRemoteRuntimeSessionEvent, materializeRemoteRuntimeSessionRuntimeSnapshot, parseRemoteRuntimeRpcRequest, REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES, SESSION_IMAGE_MEDIA_TYPES, SESSION_RESOURCE_MAX_IMAGE_BYTES, SESSION_RESOURCE_MAX_FILENAME_CHARS, SESSION_RESOURCE_TRANSFER_CHUNK_BYTES, REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE, } from "@rynx-ai/protocol/remote-runtime-rpc";
-import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_EXECUTE_PATH, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserAutomationCommand, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
 import { encodeDaemonStatus } from "./remote-runtime.js";
 import { SessionRuntimeIndex } from "./session-runtime-index.js";
@@ -2124,6 +2124,71 @@ export function createControlRouter(opts) {
     router.post("/api/internal/runtimes/:selector/emulator/gesture", internalRuntimeCall(runtimeGestureEmulator));
     router.post("/api/internal/runtimes/:selector/emulator/kill", internalRuntimeCall((ctx) => runtimeDeviceCommand(ctx, "emulator.kill")));
     router.post("/api/internal/runtimes/:selector/emulator/shutdown", internalRuntimeCall((ctx) => runtimeDeviceCommand(ctx, "emulator.shutdown")));
+    const executeLocalBrowser = async (ctx, management) => {
+        if (!runtimeLocalBrowser?.executeForSession) {
+            notFound(ctx, "Page automation requires a Runtime upgrade");
+            return;
+        }
+        if (!isLoopbackRequest(ctx)) {
+            ctx.status = 403;
+            ctx.body = { error: "loopback_only" };
+            return;
+        }
+        let sessionId;
+        if (management) {
+            if (!isConfiguredDaemonManagement(daemonManagement)) {
+                notFound(ctx, "Daemon management is unavailable");
+                return;
+            }
+            if (!authorizeLoopbackManagementRequest(ctx, daemonManagement.managementToken))
+                return;
+            try {
+                sessionId = parseRuntimeBrowserStateGetParams({ sessionId: ctx.params.sessionId }).sessionId;
+            }
+            catch {
+                bad(ctx, "invalid Session id");
+                return;
+            }
+        }
+        else {
+            try {
+                const credential = parseRuntimeBrowserBootstrapCredential({
+                    sessionId: ctx.get(RUNTIME_BROWSER_SESSION_ID_HEADER), capability: ctx.get(RUNTIME_BROWSER_CAPABILITY_HEADER),
+                });
+                if (!await runtimeLocalBrowser.authorizeCredential(credential))
+                    throw new Error("unauthorized");
+                sessionId = credential.sessionId;
+            }
+            catch {
+                ctx.status = 401;
+                ctx.body = { error: "invalid Runtime Browser Session capability" };
+                return;
+            }
+        }
+        if (!ctx.is("application/json")) {
+            ctx.status = 415;
+            ctx.body = { error: "unsupported_media_type" };
+            return;
+        }
+        let command;
+        try {
+            command = parseRuntimeBrowserAutomationCommand(await readBoundedJson(ctx, 128 * 1024));
+        }
+        catch (error) {
+            ctx.status = error instanceof RequestBodyTooLargeError ? 413 : 400;
+            ctx.body = { error: "invalid_request" };
+            return;
+        }
+        try {
+            ctx.set("Cache-Control", "no-store");
+            ctx.body = await runtimeLocalBrowser.executeForSession(sessionId, command);
+        }
+        catch (error) {
+            runtimeLocalBrowserError(ctx, error);
+        }
+    };
+    router.post(RUNTIME_BROWSER_EXECUTE_PATH, (ctx) => executeLocalBrowser(ctx, false));
+    router.post(`${RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX}/:sessionId/execute`, (ctx) => executeLocalBrowser(ctx, true));
     router.get(RUNTIME_BROWSER_BOOTSTRAP_PATH, async (ctx) => {
         if (!runtimeLocalBrowser) {
             return notFound(ctx, "Runtime-local Browser automation is not configured");
@@ -3539,7 +3604,7 @@ export function createControlRouter(opts) {
     // ── sessions (channel-agnostic agent runs) ───────────────────────────────
     // Create a session bound to a preset agent (`agent`) or an inline spec
     // (`config`, the config-driven / remote-ready path), then drive it with
-    // messages over SSE. reference implementation-style: create carries no message.
+    // messages over SSE. Creating the session does not submit a message.
     // One unified list: every session is a machine-session record. The registry
     // (console + every channel) supplies identity — `source` is a plain field, not
     // parsed from the id — and the canonical log supplies recency. A legacy session
@@ -3891,8 +3956,8 @@ function abortAsNull(signal) {
     });
 }
 /** Derive a one-line session title from the first user message: collapse
- *  whitespace, trim, and truncate to `limit` chars + an ellipsis (reference implementation's
- *  rule — no LLM call). */
+ *  whitespace, trim, and fit within `limit` characters, including an ellipsis
+ *  when truncated. No LLM call is made. */
 export function synthesizeSessionTitle(message, limit = 60) {
     const collapsed = message.replace(/\s+/g, " ").trim();
     if (collapsed.length <= limit)
@@ -4341,9 +4406,19 @@ function runtimeLocalBrowserError(ctx, error) {
         ? error.code
         : undefined;
     switch (code) {
+        case "human_control_active":
+            ctx.status = 409;
+            ctx.body = { error: code, hint: "Release Browser Control before Agent actions." };
+            return;
+        case "command_timeout":
+            ctx.status = 504;
+            ctx.body = { error: "command_timeout", outcome: "unknown" };
+            return;
         case "invalid_request":
             ctx.status = 400;
-            ctx.body = { error: "invalid_request" };
+            ctx.body = { error: "invalid_request", ...(error instanceof Error && error.name === "PageAutomationError"
+                    ? { message: error.message.slice(0, 2048), hint: "Run rynx skills get browser for Browser resources; after opening a Browser, use rynx browser exec -- --help for page commands." }
+                    : {}) };
             return;
         case "not_found":
             ctx.status = 404;
@@ -4355,10 +4430,30 @@ function runtimeLocalBrowserError(ctx, error) {
             ctx.body = { error: "unavailable" };
             return;
         case "host_failure":
-        case "outcome_unknown":
             ctx.status = 502;
             ctx.body = { error: "operation_failed" };
             return;
+        case "outcome_unknown":
+            ctx.status = 502;
+            ctx.body = { error: "outcome_unknown", outcome: "unknown", hint: "Do not replay this action. Run rynx browser exec -- snapshot -i to inspect its outcome." };
+            return;
+        case "driver_restarted":
+        case "generation_mismatch":
+            ctx.status = 409;
+            ctx.body = { error: code, hint: "Run rynx browser exec -- snapshot -i for fresh Page references." };
+            return;
+        case "capacity":
+            ctx.status = 429;
+            ctx.body = { error: "capacity" };
+            return;
+        case "unsupported":
+            ctx.status = 501;
+            ctx.body = { error: "unsupported", hint: "Upgrade the Runtime and Desktop Host together." };
+            return;
+        case "command_failed":
+            ctx.status = 422;
+            ctx.body = { error: "command_failed", message: error instanceof Error ? error.message : "agent-browser command failed", hint: "Run rynx browser exec -- --help, or inspect a fresh snapshot before another action." };
+            return;
         default:
             ctx.status = 500;
             ctx.body = { error: "internal_error" };

package/dist/desktop-browser-host.d.ts

@@ -32,6 +32,7 @@ interface DesktopBrowserLease {
     surface: DesktopBrowserHostSurfaceCapability;
     socket: WebSocket;
     pending: Map<string, PendingCommand>;
+    expiredCommands: Set<string>;
     nextEventSequence: number;
     detached: boolean;
 }
@@ -120,6 +121,14 @@ declare class DesktopBrowserHandle implements SessionBrowserHostHandle {
         endpoint: string;
         engineVersion: string;
     }>;
+    getPageAutomationEndpoint(hostPageId: string): Promise<{
+        pageTargetId: string;
+        endpoint: string;
+        engineVersion: string;
+    }>;
+    acquireAutomationVisibility(hostPageId: string): Promise<{
+        release: () => Promise<void>;
+    }>;
     openSurface(input: SessionBrowserHostSurfaceOpenInput): Promise<SessionBrowserHostSurfaceSource>;
     snapshot(): Promise<SessionBrowserHostSnapshot>;
     createPage(url?: string): Promise<void>;

package/dist/desktop-browser-host.js

@@ -133,6 +133,7 @@ export class DesktopBrowserHostRegistry {
             surface: hello.capabilities.surface,
             socket,
             pending: new Map(),
+            expiredCommands: new Set(),
             nextEventSequence: 1,
             detached: false,
         };
@@ -253,8 +254,13 @@ export class DesktopBrowserHostRegistry {
                 if (!pending)
                     return;
                 lease.pending.delete(commandId);
-                reject(commandOutcomeError(command, `Desktop Browser Host ${command.method} timed out`));
-                if (!isReadOnlyCommand(command)) {
+                reject(commandDeadlineError(command, `Desktop Browser Host ${command.method} timed out`));
+                if (isRecoverableDeadline(command)) {
+                    lease.expiredCommands.add(commandId);
+                    if (lease.expiredCommands.size > 256)
+                        lease.expiredCommands.delete(lease.expiredCommands.values().next().value);
+                }
+                else {
                     this.failLease(lease, CLOSE_REPLACED_OR_STALE, `Desktop Browser Host ${command.method} outcome is unknown`);
                 }
             }, this.commandTimeoutMilliseconds);
@@ -290,13 +296,15 @@ export class DesktopBrowserHostRegistry {
     receiveReply(lease, frame) {
         const pending = lease.pending.get(frame.commandId);
         if (!pending) {
+            if (lease.expiredCommands.delete(frame.commandId))
+                return;
             throw new DesktopBrowserHostProtocolError("reply commandId is unknown or expired", CLOSE_REPLACED_OR_STALE);
         }
         lease.pending.delete(frame.commandId);
         clearTimeout(pending.timer);
         if (this.now() >= pending.deadlineUnixMilliseconds) {
-            pending.reject(commandOutcomeError(pending.command, `Desktop Browser Host ${pending.command.method} replied after its deadline`));
-            if (!isReadOnlyCommand(pending.command)) {
+            pending.reject(commandDeadlineError(pending.command, `Desktop Browser Host ${pending.command.method} replied after its deadline`));
+            if (!isRecoverableDeadline(pending.command)) {
                 this.failLease(lease, CLOSE_REPLACED_OR_STALE, `Desktop Browser Host ${pending.command.method} outcome is unknown`);
             }
             return;
@@ -536,6 +544,36 @@ class DesktopBrowserHandle {
     getPageCdpEndpoint(hostPageId) {
         return this.command({ method: "page.cdp-endpoint", ...this.pageScope(hostPageId) }, parseDesktopBrowserHostPageCdpEndpointResult);
     }
+    async getPageAutomationEndpoint(hostPageId) {
+        if (!this.capabilities.includes("page-automation-v1"))
+            throw new SessionBrowserHostError("unsupported", "Upgrade the Desktop Host for page automation");
+        const result = await this.command({ method: "page.automation-endpoint", ...this.pageScope(hostPageId) }, parseDesktopBrowserHostCdpEndpointResult);
+        if (!result.pageTargetId)
+            throw new SessionBrowserHostError("unsupported", "Desktop Host does not support page automation");
+        return { ...result, pageTargetId: result.pageTargetId };
+    }
+    async acquireAutomationVisibility(hostPageId) {
+        if (!this.capabilities.includes("page-automation-visibility-v1")) {
+            throw new SessionBrowserHostError("unsupported", "Upgrade the Desktop Host for automation rendering");
+        }
+        const scope = { ...this.pageScope(hostPageId), visibilityId: this.registry.createId("visibility") };
+        const release = async () => {
+            if (this.available && !this.closed)
+                await this.completed({ method: "page.automation-visibility.release", ...scope });
+        };
+        try {
+            await this.completed({ method: "page.automation-visibility.acquire", ...scope });
+        }
+        catch (error) {
+            await release().catch(() => undefined);
+            throw error;
+        }
+        let released = false;
+        return { release: async () => { if (!released) {
+                released = true;
+                await release();
+            } } };
+    }
     async openSurface(input) {
         if (this.lease.surface !== "binary-v1") {
             throw new SessionBrowserSurfaceUnsupportedError();
@@ -930,10 +968,14 @@ function mapReplyError(frame, command) {
         return new SessionBrowserHostError("capacity", "Desktop Browser Host capacity was reached");
     }
     if (frame.error.code === "unavailable" ||
-        frame.error.code === "stale_generation" ||
-        frame.error.code === "deadline_exceeded")
+        frame.error.code === "stale_generation")
         return hostUnavailable("Desktop Browser Host is unavailable");
+    if (frame.error.code === "deadline_exceeded") {
+        return new SessionBrowserHostError("command_timeout", "Desktop Browser command deadline exceeded");
+    }
     if (frame.error.code === "internal") {
+        if (isReadOnlyCommand(command))
+            return new SessionBrowserHostError("operation_failed", "Desktop Browser observation failed temporarily");
         return commandOutcomeError(command, "Desktop Browser Host command outcome is unknown");
     }
     return new Error("Desktop Browser Host command failed");
@@ -942,9 +984,16 @@ function commandOutcomeError(command, message, cause) {
     const readOnly = isReadOnlyCommand(command);
     return new SessionBrowserHostError(readOnly ? "unavailable" : "outcome_unknown", message, cause === undefined ? undefined : { cause });
 }
+function commandDeadlineError(command, message) {
+    return new SessionBrowserHostError(isReadOnlyCommand(command) ? "command_timeout" : "outcome_unknown", message);
+}
+function isRecoverableDeadline(command) {
+    return isReadOnlyCommand(command) || ["page.navigate", "page.reload", "page.back", "page.forward", "page.activate"].includes(command.method);
+}
 function isReadOnlyCommand(command) {
     return command.method === "browser.snapshot" ||
         command.method === "browser.cdp-endpoint" ||
+        command.method === "page.automation-endpoint" ||
         command.method === "page.cdp-endpoint";
 }
 class BoundedAsyncQueue {

package/dist/remote-runtime-dispatcher.js

@@ -352,6 +352,7 @@ function mapHostError(request, error) {
             case "shutting_down":
                 return { code: "failed_precondition", message: "Browser operation is unavailable" };
             case "outcome_unknown":
+            case "command_timeout":
                 return { code: "outcome_unknown", message: "Browser operation may have been applied" };
             case "host_failure":
                 return { code: "internal", message: "Browser Host request failed" };

package/dist/server.d.ts

@@ -27,13 +27,14 @@ import { type SessionTerminalHost } from "./session-terminal-host.js";
 import type { ProviderCliManagementHost } from "./provider-cli-host.js";
 import { type RuntimeWebAccessPolicy } from "./runtime-web-auth.js";
 import type { SessionBrowserRequestHeadersPort } from "./session-browser-service.js";
+import type { RuntimeBrowserAutomationCommand, RuntimeBrowserAutomationResult } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 export type { ProviderCliManagementHost, ProviderCliStatusHost, } from "./provider-cli-host.js";
 export { MachineSessionService, MachineSessionServiceFailure, MachineSessionServiceInputError, synthesizeSessionTitle, } from "./machine-session-service.js";
 export { SessionPendingInputIndex } from "./session-pending-inputs.js";
 export type { MachineSessionAgentCatalogPort, MachineSessionCreateInput, MachineSessionCreateResult, MachineSessionDeleteResult, MachineSessionForkInput, MachineSessionForkOperationRecord, MachineSessionForkOperationState, MachineSessionForkResult, MachineSessionForkStorePort, MachineSessionNativeRotationInput, MachineSessionInterruptPort, MachineSessionInterruptResult, MachineSessionInteractionResult, MachineSessionListInput, MachineSessionListPage, MachineSessionMessageResult, MachineSessionMessageEnqueueResult, MachineSessionMessageInput, MachineSessionMessageOperationState, MachineSessionPendingMessage, MachineSessionPendingMessagePort, MachineSessionPreparedInput, MachineSessionResourcePort, MachineSessionRunExecutionSelection, MachineSessionRunExecutionSnapshot, MachineSessionRunnerPort, MachineSessionRuntimeStatePort, MachineSessionServiceFailureCode, MachineSessionServiceOptions, MachineSessionServicePorts, MachineSessionSnapshotInput, MachineSessionSnapshotPage, MachineSessionWatch, StartedMachineSessionRun, } from "./machine-session-service.js";
 export type { MachineSessionPendingInput, MachineSessionPendingInputPort, } from "./session-pending-inputs.js";
 export { SessionBrowserHostError, SessionBrowserService, SessionBrowserServiceError, SessionBrowserSurfaceUnsupportedError, } from "./session-browser-service.js";
-export type { SessionBrowserHost, SessionBrowserHostCreateInput, SessionBrowserHostErrorCode, SessionBrowserHostEvent, SessionBrowserHostHandle, SessionBrowserHostPage, SessionBrowserHostSurfaceFrame, SessionBrowserHostSurfaceOpenInput, SessionBrowserHostSurfaceSource, SessionBrowserHostSurfaceTrustedInput, SessionBrowserHostSurfaceViewport, SessionBrowserHostSnapshot, SessionBrowserInspectionEndpoint, SessionBrowserInspectionTarget, SessionBrowserRegistryPort, SessionBrowserRequestHeadersPort, SessionBrowserServiceErrorCode, SessionBrowserServiceOptions, SessionBrowserServicePorts, SessionBrowserSurfaceOpenInput, SessionBrowserSurfaceSource, } from "./session-browser-service.js";
+export type { SessionBrowserHost, SessionBrowserAutomationBinding, SessionBrowserAutomationVisibility, SessionBrowserHostCreateInput, SessionBrowserHostErrorCode, SessionBrowserHostEvent, SessionBrowserHostHandle, SessionBrowserHostPage, SessionBrowserHostSurfaceFrame, SessionBrowserHostSurfaceOpenInput, SessionBrowserHostSurfaceSource, SessionBrowserHostSurfaceTrustedInput, SessionBrowserHostSurfaceViewport, SessionBrowserHostSnapshot, SessionBrowserInspectionEndpoint, SessionBrowserInspectionTarget, SessionBrowserRegistryPort, SessionBrowserRequestHeadersPort, SessionBrowserServiceErrorCode, SessionBrowserServiceOptions, SessionBrowserServicePorts, SessionBrowserSurfaceOpenInput, SessionBrowserSurfaceSource, } from "./session-browser-service.js";
 export { SessionEmulatorBindingConflictError, SessionEmulatorService, SessionEmulatorServiceError, } from "./session-emulator-service.js";
 export type { SessionEmulatorBindingRecord, SessionEmulatorBindingStore, SessionEmulatorServiceErrorCode, SessionEmulatorServiceOptions, SessionEmulatorSurface, } from "./session-emulator-service.js";
 export { SessionBrowserSurfaceCoordinator } from "./session-browser-surface-coordinator.js";
@@ -286,6 +287,7 @@ export interface DaemonManagementHost {
  * half of the credential was wrong.
  */
 export interface RuntimeLocalBrowserAutomationHost {
+    executeForSession?(sessionId: string, command: RuntimeBrowserAutomationCommand): Promise<RuntimeBrowserAutomationResult>;
     authorizeCredential(credential: RuntimeBrowserBootstrapCredential): boolean | Promise<boolean>;
     endpointForCredential(credential: RuntimeBrowserBootstrapCredential): Promise<RuntimeBrowserEndpointDescriptor | undefined>;
     endpointForSession(sessionId: string): Promise<RuntimeBrowserEndpointDescriptor>;

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

@@ -19,6 +19,7 @@ export interface SessionBrowserHostPage {
     loading: boolean;
     canGoBack: boolean;
     canGoForward: boolean;
+    observationStale?: boolean;
 }
 export interface SessionBrowserHostSnapshot {
     pages: SessionBrowserHostPage[];
@@ -128,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>;
@@ -158,6 +165,10 @@ 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. */
@@ -170,7 +181,18 @@ export interface SessionBrowserServiceOptions {
      */
     admissionReserve?: () => AdmissionReservation | undefined;
 }
-export type SessionBrowserHostErrorCode = "unavailable" | "unsupported" | "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;
@@ -181,7 +203,7 @@ 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";
+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;
@@ -193,11 +215,13 @@ export declare class SessionBrowserServiceError extends Error {
  */
 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;
@@ -229,6 +253,7 @@ export declare class SessionBrowserService implements SessionBrowserRequestHeade
      * 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.
@@ -260,6 +285,7 @@ export declare class SessionBrowserService implements SessionBrowserRequestHeade
     private reconcileForRead;
     private reconcileForMutation;
     private tryReconcileAfterRejectedMutation;
+    private retainRecoverableObservation;
     private reconcile;
     private createPageId;
     private project;

package/dist/session-browser-service.js

@@ -1,4 +1,6 @@
 import { randomBytes, randomUUID } from "node:crypto";
+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;
@@ -35,11 +37,13 @@ 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;
@@ -50,6 +54,7 @@ export class SessionBrowserService {
     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 ??
@@ -132,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");
@@ -242,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.
@@ -361,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));
@@ -583,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") {
@@ -596,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 });
         }
     }
@@ -605,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 });
         }
@@ -614,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 });
         }
@@ -622,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();
@@ -652,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 &&
@@ -704,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) {
@@ -724,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");
@@ -734,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;
@@ -751,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);
             }
@@ -760,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;
@@ -848,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,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/server",
-  "version": "0.1.11-beta.45",
+  "version": "0.1.11-beta.48",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -27,15 +27,15 @@
     "@koa/router": "^15.4.0",
     "koa": "^3.2.0",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.45",
-    "@rynx-ai/plugin-sdk": "0.1.11-beta.45",
-    "@rynx-ai/protocol": "0.1.11-beta.45",
-    "@rynx-ai/remote-runtime-e2ee": "0.1.11-beta.45",
-    "@rynx-ai/runtime": "0.1.11-beta.45"
+    "@rynx-ai/core": "0.1.11-beta.48",
+    "@rynx-ai/plugin-sdk": "0.1.11-beta.48",
+    "@rynx-ai/protocol": "0.1.11-beta.48",
+    "@rynx-ai/remote-runtime-e2ee": "0.1.11-beta.48",
+    "@rynx-ai/runtime": "0.1.11-beta.48"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",
-    "@rynx-ai/control-web": "0.1.11-beta.45"
+    "@rynx-ai/control-web": "0.1.11-beta.48"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json && mkdir -p dist/control-web && cp -R ../control-web/dist/. dist/control-web/",