@modelprofile.com/browser-runtime 5.0.0 → 5.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, IBrowserRuntimeLeaseRenewalOptions, } 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, IBrowserCodexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserRuntimeScreencastOptions, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeViewportResult, 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, IBrowserCodexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserRuntimeScreencastOptions, IBrowserRuntimeEventSubscriptionOptions, TBrowserRuntimeVideoOffer, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeViewportResult, 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

@@ -101,7 +101,7 @@ export type TBrowserRuntimeOperationIdentity = TReadonlyBrowserCapabilityAuthori
     readonly classification: TBrowserRuntimeOperationClassification;
     readonly startedAt: number;
 };
-export type TBrowserRuntimeOperationClassification = 'raw-input' | 'frame-stream' | 'viewport' | 'navigation' | 'tab' | 'agent-action';
+export type TBrowserRuntimeOperationClassification = 'raw-input' | 'frame-stream' | 'video-peer' | 'viewport' | 'navigation' | 'tab' | 'agent-action';
 /** The viewport accepted by the shared resource, which may be smaller than one viewer's request. */
 export interface IBrowserRuntimeViewportResult {
     viewport: plugins.smartpuppeteer.ILiveBrowserViewport;
@@ -126,6 +126,11 @@ export interface ILiveBrowserSessionLike {
     getState(): plugins.smartpuppeteer.ILiveBrowserState;
     getProcessState(): plugins.smartpuppeteer.ILiveBrowserProcessState;
     onEvent(listener: plugins.smartpuppeteer.TLiveBrowserEventListener): () => void;
+    setFrameCaptureEnabled(enabled: boolean, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+    openVideoPeer(peerId: string, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveVideoOffer>;
+    answerVideoPeer(peerId: string, negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+    closeVideoPeer(peerId: string): Promise<void>;
+    getVideoStatistics(peerId: string): Promise<plugins.smartpuppeteer.ILiveVideoStatistics>;
     refreshScreencast(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserFrameIdentity>;
     acknowledgeFrame(request: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest): Promise<plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgement>;
     createTab(options?: plugins.smartpuppeteer.ILiveBrowserCreateTabOptions, operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserTabState>;
@@ -193,6 +198,8 @@ export interface IBrowserRuntimeOptions {
     maxOutstandingFrames?: number;
     frameAcknowledgementTimeoutMs?: number;
     screencast?: IBrowserRuntimeScreencastOptions;
+    /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
+    video?: plugins.smartpuppeteer.ILiveVideoOptions;
     egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
     artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }
@@ -206,7 +213,13 @@ export interface IBrowserRuntimeTabState {
     appliedViewportRevision: number;
     streaming: boolean;
 }
+export interface IBrowserRuntimeEventSubscriptionOptions {
+    /** Set false for native video viewers. Defaults to true for image-frame consumers. */
+    includeFrames?: boolean;
+}
+export type TBrowserRuntimeVideoOffer = Omit<plugins.smartpuppeteer.ILiveVideoOffer, 'peerId'>;
 export interface IBrowserRuntimeState {
+    videoAcceleration?: plugins.smartpuppeteer.ILiveVideoAcceleration;
     status: 'stopped' | 'starting' | 'running' | 'stopping';
     activeTabId: string | null;
     viewportRevision: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "5.0.0",
+  "version": "5.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,13 +30,13 @@
     "@push.rocks/smartagent": "^6.0.0",
     "@push.rocks/smartipc": "^2.6.0",
     "@push.rocks/smartmcp": "^0.3.0",
-    "@push.rocks/smartpuppeteer": "^2.7.1",
+    "@push.rocks/smartpuppeteer": "^2.8.1",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "4.4.2",
+    "@git.zone/tsbuild": "4.4.3",
     "@git.zone/tsrun": "2.0.6",
-    "@git.zone/tstest": "4.0.0",
+    "@git.zone/tstest": "6.0.0",
     "@types/node": "26.4.1"
   },
   "files": [
@@ -44,7 +44,6 @@
     "dist_ts/**/*",
     ".smartconfig.json",
     "readme.md",
-    "readme.hints.md",
     "changelog.md",
     "license.md"
   ],

package/readme.md

@@ -2,6 +2,14 @@
 
 Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.
 
+## Native video viewers
+
+Human leases expose `openVideoPeer(options?)`, `answerVideoPeer(negotiationId, description, options?)`, `closeVideoPeer(options?)`, and `getVideoStatistics(options?)`. Each operation runs through the resource's bounded, authorized and audited operation queue. Peer IDs are private to the lease; offers expose the negotiation ID and exact tab/generation/viewport source identity. Agent leases cannot open media peers. Releasing or revoking a human lease closes only its peer, preserving other viewers and agent work. Failed peer cleanup remains owned for a subsequent release attempt.
+
+Set `video` on `BrowserRuntime` for trusted host limits or ICE configuration. Defaults use direct connections with no external STUN/TURN service and automatic GPU support. The private capture extension is loaded without weakening ordinary page proxy, DNS, permission or WebRTC confinement. `state.videoAcceleration` and peer statistics report actual browser acceleration/encoder support.
+
+Native viewers should call `lease.subscribeEvents(listener, { includeFrames: false })`. They receive state and errors without generating JPEG traffic. Existing image consumers retain the default `includeFrames: true`; capture starts for the first such subscriber and stops after the last closes. Agent snapshots remain independent of continuous capture. Image subscription cleanup is serialized, coalesced and retryable; a failed disable is retained until cleanup succeeds or its exact browser incarnation terminates.
+
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
@@ -126,13 +134,13 @@ renewal leaves the original expiry unchanged. Only one authorization callback pe
 may remain unsettled, including after timeout; runtime-wide renewal admission is bounded
 by `maxCapabilities`. Hosts must stop scheduling renewal when their viewer disconnects.
 
-Agent actions are exactly `navigate`, `snapshot`, `screenshot`, `click`, `fill`, and `press`. Human leases additionally expose tab lifecycle, viewport, raw input, frame subscription/acknowledgement and refresh, and exact-resource artifact reads/deletes. JavaScript evaluation is not public.
+Agent actions are exactly `navigate`, `snapshot`, `screenshot`, `click`, `fill`, and `press`. Agents can read or delete screenshots created by their exact lease using `readArtifact()` and `deleteArtifact()`. Human leases additionally expose tab lifecycle, viewport, raw input, frame subscription/acknowledgement and refresh, and exact-resource artifact reads/deletes. JavaScript evaluation is not public.
 
 All participants enter one strict resource FIFO. `maxQueuedOperationsPerLease` defaults to 128 and accepts 1 through 1,024; each participant has that bound, and the resource queue is bounded by its product with `maxCapabilitiesPerResource`. Overflow fails with `QUOTA_EXCEEDED`. Releasing a participant cancels only its queued and active work. Resource termination and shutdown cancel everyone. Started uncertain work must quiesce or the exact incarnation is terminated before operation settlement.
 
 `setViewport()` stores the viewer's preferred width, height and device scale factor and returns `IBrowserRuntimeViewportResult` with the effective `viewport` and `viewportRevision`. The effective values are the componentwise minima across active viewers that have supplied a preference. Unchanged effective sizes do not restart the stream. Removing a viewer recomputes the viewport in the resource FIFO. Held keys and buttons are tracked per participant; leaving releases only inputs that no other participant holds. Viewport and tab/navigation transitions clear held input before changing the target. Resource-owned departure cleanup is bounded and audited as `releaseParticipant`; it does not call the external `beforeOperation` gate after the participant has lost access.
 
-`beforeOperation` is an optional awaited fail-closed gate. It receives the complete immutable authority, operation/capability/lease IDs, action, classification, start time, and an `AbortSignal` after dequeue but before the browser side effect starts. Classifications are `raw-input`, `frame-stream`, `viewport`, `navigation`, `tab`, and `agent-action`. Hosts that require durable attempt-before-side-effect auditing should persist the attempt there. Rejection denies the operation. The default `beforeOperationTimeoutMs` is 10,000 milliseconds and accepts values from 100 through 120,000; timeout fails with `TIMEOUT`. The terminal `audit` callback remains a best-effort `completed`/`failed` notification correlated by the same operation ID and classification and runs after bounded operation cleanup releases or fences the exact reservation.
+`beforeOperation` is an optional awaited fail-closed gate. It receives the complete immutable authority, operation/capability/lease IDs, action, classification, start time, and an `AbortSignal` after dequeue but before the browser side effect starts. Classifications are `raw-input`, `frame-stream`, `video-peer`, `viewport`, `navigation`, `tab`, and `agent-action`. Hosts that require durable attempt-before-side-effect auditing should persist the attempt there. Rejection denies the operation. The default `beforeOperationTimeoutMs` is 10,000 milliseconds and accepts values from 100 through 120,000; timeout fails with `TIMEOUT`. The terminal `audit` callback remains a best-effort `completed`/`failed` notification correlated by the same operation ID and classification and runs after bounded operation cleanup releases or fences the exact reservation.
 
 `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.
 
@@ -142,7 +150,7 @@ Each human participant may have one independent frame subscription with a bounde
 
 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`.
+`screencast` tunes the Chromium image capture that starts when an image-frame subscriber joins. `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 producer error synchronously invalidates all current participants before their captured subscribers receive the error. Cleanup is coalesced for that exact incarnation and completes before affected operations settle.
 
@@ -164,7 +172,7 @@ The MCP tool list is exactly `browser_navigate`, `browser_snapshot`, `browser_sc
 
 Each running resource owns one authenticated loopback `BrowserEgressProxy` carrying immutable `projectId` and `browserResourceId`. HTTP, WebSocket Upgrade, and CONNECT share strict public-unicast DNS/IP validation, numeric dialing, bounded lifetimes, and fail-closed policy.
 
-Artifact identity and APIs use `(projectId, browserResourceId, artifactId)`. Keyed project/resource directories prevent caller IDs from entering paths. Admission is serialized across per-resource, per-project, and global count/byte quotas. Reads use no-follow handles and verify size and SHA-256. Agent, Flex, and MCP surfaces receive metadata only.
+Artifact identity and APIs use `(projectId, browserResourceId, artifactId)`. Keyed project/resource directories prevent caller IDs from entering paths. Admission is serialized across per-resource, per-project, and global count/byte quotas. Reads use no-follow handles and verify size and SHA-256. Screenshot actions return metadata. Direct agent leases can read/delete only artifacts created by that exact lease; other agent and human artifacts remain unavailable. Human artifact access remains scoped to the resource. Read completion revalidates the lease and clears bytes if authority ended during IO. The built-in framed/Flex/MCP action adapters continue to return metadata; hosts can return image content after a scoped lease read. The artifact store accepts an optional opaque owner ID on `store()` and an expected owner ID on `read()`/`delete()`; omitting an expected owner retains its trusted parent API.
 
 ## Verification
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '5.0.0',
+  version: '5.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.artifactstore.ts

@@ -15,6 +15,7 @@ import {
 interface IStoredArtifact {
   metadata: IBrowserArtifactMetadata;
   digest: string;
+  ownerId?: string;
 }
 
 interface IResourceArtifacts {
@@ -164,11 +165,14 @@ export class BrowserArtifactStore {
     browserResourceIdArg: string,
     mimeTypeArg: string,
     data: Uint8Array,
+    ownerIdArg?: string,
   ): Promise<IBrowserArtifactMetadata> {
     this.requireStarted();
     const projectId = this.validateProjectId(projectIdArg);
     const browserResourceId = this.validateResourceId(browserResourceIdArg);
     const mimeType = validateBoundedString(mimeTypeArg, 'mimeType', 1, 128);
+    const ownerId = ownerIdArg === undefined ? undefined
+      : validateBoundedString(ownerIdArg, 'ownerId', 1, 128);
     if (!(data instanceof Uint8Array)) {
       throw new BrowserRuntimeError('INVALID_INPUT', 'data must be Uint8Array');
     }
@@ -212,6 +216,7 @@ export class BrowserArtifactStore {
       const stored: IStoredArtifact = {
         metadata,
         digest: plugins.crypto.createHash('sha256').update(bytes).digest('hex'),
+        ...(ownerId === undefined ? {} : { ownerId }),
       };
       const resourceDirectory = this.resourcePath(project, resource);
       const finalPath = plugins.path.join(resourceDirectory, artifactId);
@@ -252,6 +257,7 @@ export class BrowserArtifactStore {
     projectIdArg: string,
     browserResourceIdArg: string,
     artifactIdArg: string,
+    expectedOwnerIdArg?: string,
   ): Promise<Uint8Array> {
     this.requireStarted();
     const projectId = this.validateProjectId(projectIdArg);
@@ -261,6 +267,7 @@ export class BrowserArtifactStore {
     let handle: plugins.fsPromises.FileHandle | undefined;
     try {
       const resolved = this.resolveArtifact(projectId, browserResourceId, artifactId);
+      this.assertArtifactOwner(resolved.stored, expectedOwnerIdArg);
       if (resolved.stored.metadata.expiresAt <= this.now()) {
         await this.deleteArtifact(projectId, browserResourceId, resolved);
         throw new BrowserRuntimeError('INVALID_INPUT', 'artifact is unavailable');
@@ -300,6 +307,7 @@ export class BrowserArtifactStore {
     projectIdArg: string,
     browserResourceIdArg: string,
     artifactIdArg: string,
+    expectedOwnerIdArg?: string,
   ): Promise<void> {
     this.requireStarted();
     const projectId = this.validateProjectId(projectIdArg);
@@ -307,16 +315,26 @@ export class BrowserArtifactStore {
     const artifactId = this.validateArtifactId(artifactIdArg);
     const release = await this.mutex.acquire();
     try {
+      const resolved = this.resolveArtifact(projectId, browserResourceId, artifactId);
+      this.assertArtifactOwner(resolved.stored, expectedOwnerIdArg);
       await this.deleteArtifact(
         projectId,
         browserResourceId,
-        this.resolveArtifact(projectId, browserResourceId, artifactId),
+        resolved,
       );
     } finally {
       release();
     }
   }
 
+  private assertArtifactOwner(storedArg: IStoredArtifact, expectedOwnerIdArg?: string): void {
+    if (expectedOwnerIdArg === undefined) return;
+    const expectedOwnerId = validateBoundedString(expectedOwnerIdArg, 'ownerId', 1, 128);
+    if (storedArg.ownerId !== expectedOwnerId) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'artifact is unavailable');
+    }
+  }
+
   public async purgeExpired(resource?: IBrowserResourceKey): Promise<number> {
     this.requireStarted();
     const validated = resource === undefined ? undefined : {