@modelprofile.com/browser-runtime 4.1.2 → 4.2.0

package/dist_ts/index.d.ts

@@ -8,4 +8,4 @@ export { BrowserRuntimeError } from './errors.js';
 export { createBrowserRuntimeMcpHttpHandler } from './mcp.js';
 export type { TAcquireBrowserRuntimeLeaseOptions } from './classes.runtime.js';
 export type { TBrowserRuntimeErrorCode } from './errors.js';
-export type { IAttachTrustedFramedPeerOptions, IApplyBrowserAttachmentBindingRequest, IBrowserAttachmentBinding, IBrowserActionStateResult, IBrowserArtifactMetadata, IBrowserArtifactStoreOptions, IBrowserMcpAuthenticatedBinding, TBrowserCapabilityAuthorizationRequest, TBrowserCapabilityDescriptor, IBrowserClickAction, IBrowserEgressConnectionOptions, IBrowserEgressProxyOptions, IBrowserEgressProxyStats, IBrowserFlexCapabilityBinding, IBrowserFlexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeTabState, IBrowserScreenshotAction, IBrowserScreenshotResult, IBrowserSnapshotAction, ICreateBrowserResourceRequest, TIssueBrowserCapabilityRequest, TIssuedBrowserCapability, TQualifiedBrowserSessionId, IRegisterBrowserResourceRequest, IResolvedBrowserFlexCapability, TBrowserActorRole, TBrowserAgentAction, TBrowserAgentActionResult, TBrowserCapabilitySource, TBrowserDnsResolver, TBrowserEgressConnector, TBrowserHarnessId, TBrowserRuntimeEvent, } from './interfaces.js';
+export type { IAttachTrustedFramedPeerOptions, IApplyBrowserAttachmentBindingRequest, IBrowserAttachmentBinding, IBrowserActionStateResult, IBrowserArtifactMetadata, IBrowserArtifactStoreOptions, IBrowserMcpAuthenticatedBinding, TBrowserCapabilityAuthorizationRequest, TBrowserCapabilityDescriptor, IBrowserClickAction, IBrowserEgressConnectionOptions, IBrowserEgressProxyOptions, IBrowserEgressProxyStats, IBrowserFlexCapabilityBinding, IBrowserFlexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserRuntimeScreencastOptions, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeTabState, IBrowserScreenshotAction, IBrowserScreenshotResult, IBrowserSnapshotAction, ICreateBrowserResourceRequest, TIssueBrowserCapabilityRequest, TIssuedBrowserCapability, TQualifiedBrowserSessionId, IRegisterBrowserResourceRequest, IResolvedBrowserFlexCapability, TBrowserActorRole, TBrowserAgentAction, TBrowserAgentActionResult, TBrowserCapabilitySource, TBrowserDnsResolver, TBrowserEgressConnector, TBrowserHarnessId, TBrowserRuntimeEvent, } from './interfaces.js';

package/dist_ts/interfaces.d.ts

@@ -147,6 +147,13 @@ export interface IBrowserRuntimeEnvironment {
     platform: NodeJS.Platform;
     uid: number | undefined;
 }
+export interface IBrowserRuntimeScreencastOptions {
+    quality?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    everyNthFrame?: number;
+    firstFrameTimeoutMs?: number;
+}
 export interface IBrowserRuntimeOptions {
     runtimeDirectory: string;
     authorizeCapability(request: TBrowserCapabilityAuthorizationRequest, signal: AbortSignal): Promise<boolean> | boolean;
@@ -176,6 +183,7 @@ export interface IBrowserRuntimeOptions {
     maxFrameBytes?: number;
     maxOutstandingFrames?: number;
     frameAcknowledgementTimeoutMs?: number;
+    screencast?: IBrowserRuntimeScreencastOptions;
     egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
     artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "private": false,
   "description": "Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.",
   "main": "dist_ts/index.js",
@@ -30,7 +30,7 @@
     "@push.rocks/smartagent": "^6.0.0",
     "@push.rocks/smartipc": "^2.6.0",
     "@push.rocks/smartmcp": "^0.3.0",
-    "@push.rocks/smartpuppeteer": "^2.6.0",
+    "@push.rocks/smartpuppeteer": "^2.7.0",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {

package/readme.hints.md

@@ -47,7 +47,10 @@ Durable implementation findings for `@modelprofile.com/browser-runtime`.
 - Framed messages contain no identity selectors. The parent binds project, resource, attachment authority/revision, actor, peer, role, source, qualified session, Flex scope, channel, and exact run out of band.
 - One qualified session can own multiple resource-specific framed channels. Capability revocation owns server-peer disconnect; peer-initiated release/close revokes only that channel's capability without recursively disconnecting itself.
 - Framed request counts and queued write bytes are bounded. Runtime shutdown has a bounded caller-visible cleanup deadline while retaining in-flight cleanup ownership for retry.
-- Frame delivery owns a bounded map of exact identities and configures SmartPuppeteer's separate private CDP-to-ack map to the same limit. Equal limits prevent private eviction while the application map has spare capacity, but private-first retirement at full capacity can make an exact acknowledgement fulfill `{ accepted: false }`. Both fulfilled booleans settle the application entry without proving successful upstream retirement; rejection or timeout fails closed. Application acknowledgement timeout and failed delivery deliberately fail the lease regardless of a fulfilled boolean. There is no cumulative frame protocol.
+- Frame delivery owns a bounded map of exact identities and configures SmartPuppeteer's separate private CDP-to-ack map to the same limit. Equal limits prevent private eviction while the application map has spare capacity, but private-first retirement at full capacity can make an exact acknowledgement fulfill `{ accepted: false }`. Both fulfilled booleans settle the application entry without proving successful upstream retirement; a rejected or timed-out acknowledgement operation toward SmartPuppeteer fails closed. Failed delivery (a throwing listener) deliberately fails the lease regardless of a fulfilled boolean. There is no cumulative frame protocol.
+- A late application acknowledgement (`frameAcknowledgementTimeoutMs`, default 10 s) is retired through `retireOutstandingFrame(subscription, key, false)`, the same path as oldest-first eviction: the entry is acknowledged toward SmartPuppeteer and the lease is untouched. It must never route through `handleFrameFailure`; one slow viewer acknowledgement previously fenced the slot and terminated the whole Chromium incarnation. A later explicit acknowledgement of the retired identity returns `false`.
+- A frame above `maxFrameBytes` is dropped, acknowledged in the background with `failLease=false`, and reported as `FRAME_TOO_LARGE` with `fatal: false`. `highestSequence` is advanced before the size check so the following frames stay valid. During an active refresh the oversized frame still fails the refresh with `FRAME_TOO_LARGE`, but the pushed error event is non-fatal.
+- `screencast` (`quality` 0..100 default 70, `maxWidth`/`maxHeight` 1..4096 each with `maxWidth * maxHeight <= 8_294_400` and defaults 2560/1600, `everyNthFrame` 1..60 default 1, `firstFrameTimeoutMs` 1000..60000 default left to SmartPuppeteer) is validated in the constructor with `validateExactKeys` plus the integer validators and forwarded to `LiveBrowserSession` next to `maxOutstandingFrames`. The ceilings deliberately match `@push.rocks/smartpuppeteer` 2.6's `LiveBrowserSession` validation (`maxViewportPixelArea = 8294400`, `maxTimeoutMs = 60000`); a looser runtime bound would let `new BrowserRuntime()` succeed and every incarnation launch fail instead. Without `quality`/`maxWidth`/`maxHeight`, SmartPuppeteer's defaults (quality 80, unbounded size) produced multi-megabyte frames on device-pixel-ratio 2 viewers.
 - During refresh, application entries plus refresh-owned acknowledgement promises share the same hard frame-window bound. ACK ownership is fixed at admission, refresh failures defer until the operation reservation is gone, and the exact failure fence completes before terminal audit, caller settlement, or FIFO advancement. Lifecycle teardown explicitly abandons an exact refresh record so stale state cannot retain `BUSY` admission.
 - Runtime state and error events preserve diagnostic messages only after truncating them to 2,048 characters. The first fatal session error invalidates exact capability admission synchronously, delivers once to the captured exact subscriber, and schedules revocation in `finally` so a throwing listener cannot retain authority.
 - Flex resolves only a capability token, and the provider's run must exactly match its trusted framed client. SmartAgent exposes exactly navigate, snapshot, screenshot, click, fill, and press.

package/readme.md

@@ -122,11 +122,17 @@ Operations from one valid lease enter a strict bounded FIFO. `maxQueuedOperation
 
 `lease.getAuthority()` returns an immutable process-local lease authority containing the runtime authority ID, exported `authorityGeneration`, incarnation generation, and complete capability binding. Every snapshot also binds the exact `capabilityId` and `leaseId`. `lease.isAuthorityCurrent(authority)` performs an exact synchronous revalidation suitable for a host-owned virtual stream. These values are not durable Controller state and do not replace attachment checks against the Controller database.
 
-Human frame delivery keeps a bounded exact-identity application window. `maxOutstandingFrames` defaults to 4 and accepts values from 1 through 32. Runtime passes the same bound to SmartPuppeteer's private CDP-to-ack window; the windows remain separately owned, but equal limits prevent private eviction while the application window still has spare capacity. At full capacity SmartPuppeteer retires its oldest private entry before publishing the next frame, so a later exact acknowledgement can fulfill with `{ accepted: false }`. A fulfilled `true` or `false` settles the Runtime entry locally without fencing; `false` does not prove that upstream retirement succeeded. Rejected or timed-out acknowledgement operations fail closed, as do application acknowledgement timeout and failed-delivery retirement regardless of a fulfilled boolean. Frame acknowledgement stays outside the operation FIFO.
+Human frame delivery keeps a bounded exact-identity application window. `maxOutstandingFrames` defaults to 4 and accepts values from 1 through 32. Runtime passes the same bound to SmartPuppeteer's private CDP-to-ack window; the windows remain separately owned, but equal limits prevent private eviction while the application window still has spare capacity. At full capacity SmartPuppeteer retires its oldest private entry before publishing the next frame, so a later exact acknowledgement can fulfill with `{ accepted: false }`. A fulfilled `true` or `false` settles the Runtime entry locally without fencing; `false` does not prove that upstream retirement succeeded. Rejected or timed-out acknowledgement operations toward SmartPuppeteer fail closed, as does failed-delivery retirement regardless of a fulfilled boolean. Frame acknowledgement stays outside the operation FIFO.
+
+A late application acknowledgement is not a lease failure. `frameAcknowledgementTimeoutMs` defaults to 10,000 milliseconds and accepts values from 100 through 60,000; when a delivered frame is still unacknowledged after that time, Runtime retires the entry through the same path as oldest-first window eviction: it acknowledges the frame toward SmartPuppeteer and leaves the lease, subscription, and incarnation untouched. A later explicit acknowledgement of that retired identity returns `false`. The same timeout still bounds each acknowledgement operation toward SmartPuppeteer, and that bound remains fail closed.
+
+An oversized frame is dropped, not fatal. `maxFrameBytes` defaults to 4 MiB and accepts values from 64 KiB through 16 MiB. A frame above the bound is acknowledged toward SmartPuppeteer in the background, never enters the application window, and is reported once on the subscription as `{ type: 'error', error: { code: 'FRAME_TOO_LARGE', fatal: false, tabId } }`. The sequence watermark advances past the dropped frame so later frames remain valid and continue to be delivered.
+
+`screencast` tunes the Chromium screencast that SmartPuppeteer starts for every incarnation. `quality` is the JPEG quality from 0 through 100 and defaults to 70. `maxWidth` and `maxHeight` accept values from 1 through 4,096 each, their product must not exceed 8,294,400 pixels (SmartPuppeteer's ceiling, so 3,840×2,160 is accepted and 4,096×4,096 is rejected with `INVALID_INPUT`), they default to 2,560 and 1,600, and they make Chromium scale captured frames to fit. `everyNthFrame` accepts values from 1 through 60 and defaults to 1. `firstFrameTimeoutMs` accepts values from 1,000 through 60,000 and is left to SmartPuppeteer's default when omitted. Runtime forwards these values together with `maxOutstandingFrames`; the defaults keep frames from device-pixel-ratio 2 viewers well below `maxFrameBytes`.
 
 Human state and error events retain an optional diagnostic `message` bounded to 2,048 characters. A fatal session error synchronously invalidates the exact capability before its captured subscriber is notified once, then revokes and cleans up the lease even when that subscriber throws.
 
-`humanLease.refreshFrameStream(options?: IBrowserRuntimeOperationOptions): Promise<void>` requires the lease's exact active frame subscription and enters the same audited FIFO as other browser mutations. Runtime retires the old application window, asks SmartPuppeteer for a new screencast generation, and succeeds only after the exact first new-generation frame was delivered through that subscription and validated against the current tab, viewport, lease, session, and incarnation. Existing and refresh-owned acknowledgement work share `maxOutstandingFrames`; synchronous listener acknowledgements cannot create an unbounded promise set. A missing or pre-execution-replaced subscription fails with `BUSY`. Refresh protocol, delivery, retirement, or acknowledgement failure returns `FRAME_STREAM_FAILED` or `FRAME_TOO_LARGE` only after the exact incarnation is fenced; stale authority returns `ABORTED` without touching its replacement. Pass `options.signal` for caller cancellation; active cancellation preserves a successfully restored stream.
+`humanLease.refreshFrameStream(options?: IBrowserRuntimeOperationOptions): Promise<void>` requires the lease's exact active frame subscription and enters the same audited FIFO as other browser mutations. Runtime retires the old application window, asks SmartPuppeteer for a new screencast generation, and succeeds only after the exact first new-generation frame was delivered through that subscription and validated against the current tab, viewport, lease, session, and incarnation. Existing and refresh-owned acknowledgement work share `maxOutstandingFrames`; synchronous listener acknowledgements cannot create an unbounded promise set. A missing or pre-execution-replaced subscription fails with `BUSY`. Refresh protocol, delivery, retirement, or acknowledgement failure returns `FRAME_STREAM_FAILED` or `FRAME_TOO_LARGE` only after the exact incarnation is fenced; an oversized frame during an active refresh still fails that refresh with `FRAME_TOO_LARGE` while the subscription's error event itself stays `fatal: false`. Stale authority returns `ABORTED` without touching its replacement. Pass `options.signal` for caller cancellation; active cancellation preserves a successfully restored stream.
 
 ## Trusted Pipe And Flex
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '4.1.2',
+  version: '4.2.0',
   description: 'Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.'
 }

package/ts/classes.runtime.ts

@@ -55,6 +55,17 @@ import {
 } from './utils.js';
 import { BrowserRuntimeFramedServerPeer } from './classes.framed.js';
 
+// @push.rocks/smartpuppeteer LiveBrowserSession rejects screencast bounds above this area.
+const maxScreencastPixelArea = 8_294_400;
+
+interface INormalizedScreencastOptions {
+  quality: number;
+  maxWidth: number;
+  maxHeight: number;
+  everyNthFrame: number;
+  firstFrameTimeoutMs?: number;
+}
+
 interface INormalizedRuntimeOptions {
   runtimeDirectory: string;
   authorizeCapability: IBrowserRuntimeOptions['authorizeCapability'];
@@ -89,6 +100,7 @@ interface INormalizedRuntimeOptions {
   maxFrameBytes: number;
   maxOutstandingFrames: number;
   frameAcknowledgementTimeoutMs: number;
+  screencast: INormalizedScreencastOptions;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
   ownership?: IBrowserRuntimeTestingOptions['ownership'];
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
@@ -295,6 +307,61 @@ export class BrowserRuntime {
       capabilityMaximumTtlMs,
       5 * 60_000,
     );
+    const screencastOptions = options.screencast === undefined
+      ? {}
+      : validateExactKeys(
+          options.screencast,
+          ['quality', 'maxWidth', 'maxHeight', 'everyNthFrame', 'firstFrameTimeoutMs'],
+          'screencast',
+        );
+    // Bounds mirror what @push.rocks/smartpuppeteer's LiveBrowserSession accepts, so a runtime
+    // that constructs successfully can never launch incarnations that fail on these values.
+    const screencast: INormalizedScreencastOptions = {
+      quality: validateOptionalInteger(
+        screencastOptions.quality,
+        'screencast.quality',
+        0,
+        100,
+        70,
+      ),
+      maxWidth: validateOptionalInteger(
+        screencastOptions.maxWidth,
+        'screencast.maxWidth',
+        1,
+        4096,
+        2560,
+      ),
+      maxHeight: validateOptionalInteger(
+        screencastOptions.maxHeight,
+        'screencast.maxHeight',
+        1,
+        4096,
+        1600,
+      ),
+      everyNthFrame: validateOptionalInteger(
+        screencastOptions.everyNthFrame,
+        'screencast.everyNthFrame',
+        1,
+        60,
+        1,
+      ),
+      ...(screencastOptions.firstFrameTimeoutMs === undefined
+        ? {}
+        : {
+            firstFrameTimeoutMs: validateInteger(
+              screencastOptions.firstFrameTimeoutMs,
+              'screencast.firstFrameTimeoutMs',
+              1000,
+              60_000,
+            ),
+          }),
+    };
+    if (screencast.maxWidth * screencast.maxHeight > maxScreencastPixelArea) {
+      throw new BrowserRuntimeError(
+        'INVALID_INPUT',
+        `screencast.maxWidth * screencast.maxHeight must not exceed ${maxScreencastPixelArea} pixels`,
+      );
+    }
     const environment = testingOptions?.environment ?? {
       platform: process.platform,
       uid: process.getuid?.(),
@@ -472,6 +539,7 @@ export class BrowserRuntime {
         60_000,
         10_000,
       ),
+      screencast,
       egress: options.egress ?? {},
       ownership: testingOptions?.ownership,
       beforeLeasePublication: testingOptions?.beforeLeasePublication,
@@ -1677,6 +1745,13 @@ export class BrowserRuntime {
         allowEvaluation: true,
         screencast: {
           maxOutstandingFrames: this.options.maxOutstandingFrames,
+          quality: this.options.screencast.quality,
+          maxWidth: this.options.screencast.maxWidth,
+          maxHeight: this.options.screencast.maxHeight,
+          everyNthFrame: this.options.screencast.everyNthFrame,
+          ...(this.options.screencast.firstFrameTimeoutMs === undefined
+            ? {}
+            : { firstFrameTimeoutMs: this.options.screencast.firstFrameTimeoutMs }),
         },
         launchOptions: {
           headless: true,
@@ -2613,7 +2688,9 @@ export class BrowserRuntime {
   ): void {
     if (frame.timer || subscription.closed || !subscription.outstanding.has(key)) return;
     const timer = setTimeout(() => {
-      this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
+      // A late application acknowledgement retires the entry exactly like oldest-first
+      // eviction: the frame is acknowledged toward the session and the lease is untouched.
+      this.trackCleanup(this.retireOutstandingFrame(subscription, key, false).then(() => undefined));
     }, this.options.frameAcknowledgementTimeoutMs);
     timer.unref();
     frame.timer = timer;
@@ -2725,23 +2802,20 @@ export class BrowserRuntime {
       }
       subscription.highestSequence = acknowledgement.sequence;
       if (event.frame.data.byteLength > this.options.maxFrameBytes) {
+        // An oversized frame is dropped, not fatal: the sequence watermark already advanced so
+        // later frames stay valid, and the subscriber is told without losing its lease.
         if (refresh) {
           this.failFrameRefresh(refresh, 'FRAME_TOO_LARGE');
           this.pushToSubscription(subscription, {
             type: 'error',
-            error: { code: 'FRAME_TOO_LARGE', fatal: true, tabId: event.frame.tabId },
+            error: { code: 'FRAME_TOO_LARGE', fatal: false, tabId: event.frame.tabId },
           });
           return;
         }
-        this.trackCleanup(this.acknowledgeFrameInBackground(
-          slot,
-          session,
-          acknowledgement,
-          true,
-        ));
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
         this.pushToSubscription(subscription, {
           type: 'error',
-          error: { code: 'FRAME_TOO_LARGE', fatal: true, tabId: event.frame.tabId },
+          error: { code: 'FRAME_TOO_LARGE', fatal: false, tabId: event.frame.tabId },
         });
         return;
       }

package/ts/index.ts

@@ -43,6 +43,7 @@ export type {
   IBrowserRuntimeMcpOptions,
   IBrowserRuntimeOperationOptions,
   IBrowserRuntimeOptions,
+  IBrowserRuntimeScreencastOptions,
   IBrowserResourceKey,
   IBrowserResourceRegistration,
   IBrowserRuntimeState,

package/ts/interfaces.ts

@@ -236,6 +236,14 @@ export interface IBrowserRuntimeEnvironment {
   uid: number | undefined;
 }
 
+export interface IBrowserRuntimeScreencastOptions {
+  quality?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+  everyNthFrame?: number;
+  firstFrameTimeoutMs?: number;
+}
+
 export interface IBrowserRuntimeOptions {
   runtimeDirectory: string;
   authorizeCapability(
@@ -271,6 +279,7 @@ export interface IBrowserRuntimeOptions {
   maxFrameBytes?: number;
   maxOutstandingFrames?: number;
   frameAcknowledgementTimeoutMs?: number;
+  screencast?: IBrowserRuntimeScreencastOptions;
   egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
   artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }