@modelprofile.com/browser-runtime 4.2.0 → 4.4.0

package/dist_ts/index.d.ts

@@ -6,6 +6,6 @@ export { BrowserRuntimeFramedClient, BrowserRuntimeFramedServerPeer, } from './c
 export { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
 export { BrowserRuntimeError } from './errors.js';
 export { createBrowserRuntimeMcpHttpHandler } from './mcp.js';
-export type { TAcquireBrowserRuntimeLeaseOptions } from './classes.runtime.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, 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';
+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, 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

@@ -3,7 +3,7 @@ import type { BrowserEgressProxy } from './classes.egressproxy.js';
 import type { BrowserRuntimeFramedClient } from './classes.framed.js';
 export type TBrowserActorRole = 'human' | 'agent';
 export type TBrowserCapabilitySource = 'human' | 'flex' | 'mcp';
-export type TBrowserHarnessId = 'opencode' | 'flex';
+export type TBrowserHarnessId = 'opencode' | 'flex' | 'codex';
 export interface IBrowserOpenCodeSessionId {
     harnessId: 'opencode';
     nativeId: string;
@@ -12,7 +12,11 @@ export interface IBrowserFlexSessionId {
     harnessId: 'flex';
     nativeId: string;
 }
-export type TQualifiedBrowserSessionId = IBrowserOpenCodeSessionId | IBrowserFlexSessionId;
+export interface IBrowserCodexSessionId {
+    harnessId: 'codex';
+    nativeId: string;
+}
+export type TQualifiedBrowserSessionId = IBrowserOpenCodeSessionId | IBrowserFlexSessionId | IBrowserCodexSessionId;
 export interface IBrowserResourceKey {
     projectId: string;
     browserResourceId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "4.2.0",
+  "version": "4.4.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",

package/readme.md

@@ -72,7 +72,7 @@ try {
 }
 ```
 
-Projects and qualified sessions may each own many resources. Human/agent arbitration, mutexes, leases, operation queues, profiles, proxies, frame subscriptions, and idle timers are per resource.
+Projects and qualified OpenCode, Flex, and Codex sessions may each own many resources. Codex attachment identities support human browser views; agent capabilities still require a supported Flex or OpenCode MCP transport. Human/agent arbitration, mutexes, leases, operation queues, profiles, proxies, frame subscriptions, and idle timers are per resource.
 
 `registerResource()` is idempotent only for the same project/resource key and identical attachment. `listResources()` reports process-local registration and incarnation metadata. `terminateResource()` terminates only the current incarnation and preserves registration, attachment, and artifacts. `retireResource()` permanently fences the process-local registration, revokes and quiesces authority, terminates its incarnation, purges exact-resource artifacts, and unregisters only after cleanup succeeds. The Controller separately owns durable retirement truth and must not rehydrate retired resources. Runtime tombstones and registrations are ephemeral, bounded process state. `stop()` attempts peer, capability, resource, artifact-store, and ownership cleanup even when an earlier stage fails, then reports all failures together. It removes only the current generation, durably marks its owner metadata relinquished, and releases the native ownership lease when ownership cleanup succeeds. It intentionally leaves `runtime.lock` and the mutex anchor in place. Failed local slot cleanup remains retryable and blocks a new generation; automatic ownership-loss shutdown performs one additional bounded cleanup attempt. `cleanupTimeoutMs` defaults to 30,000 milliseconds and accepts values from 100 through 120,000. If that caller-visible deadline expires, `stop()` rejects with `TIMEOUT` while Runtime retains cleanup still in flight; a later `stop()` rejoins it, and `start()` waits for all prior local cleanup before restarting.
 
@@ -114,6 +114,16 @@ A newer binding synchronously fences admission, revokes older capabilities, and
 
 Agent capabilities require the exact current non-detached qualified session. Human capabilities deliberately carry no session ID: they bind the exact project, resource, attachment authority, and revision and may be issued while detached. Any attachment revision advance invalidates both human and agent capabilities.
 
+Capabilities expire after five minutes by default. A host keeping a viewer open can call
+`await lease.renew({ signal })` before `lease.expiresAt`; the result is the new expiry
+time in Unix milliseconds. Renewal invokes `authorizeCapability` again and preserves
+the exact lease, browser incarnation, frame subscription and attachment identity.
+`expiresInMs` optionally selects a lifetime within the configured maximum. An expired,
+released, revoked or replaced lease cannot be renewed. A denied, cancelled or timed-out
+renewal leaves the original expiry unchanged. Only one authorization callback per lease
+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.
 
 Operations from one valid lease enter a strict bounded FIFO. `maxQueuedOperationsPerLease` defaults to 128 and accepts values from 1 through 1,024. Queue overflow fails with `QUOTA_EXCEEDED`; `BUSY` remains resource arbitration. A queued operation aborted by its caller, lease revocation, attachment transition, resource termination, or runtime shutdown never starts. Started work is never superseded, and cancellation does not complete until the work quiesces or the exact resource incarnation is fenced.

package/ts/00_commitinfo_data.ts

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

@@ -139,6 +139,12 @@ interface ILeaseRecord {
   releaseOwnsFence?: boolean;
 }
 
+export interface IBrowserRuntimeLeaseRenewalOptions {
+  signal?: AbortSignal;
+  /** Lifetime from successful reauthorization; defaults to the runtime capability lifetime. */
+  expiresInMs?: number;
+}
+
 interface IOperationRecord {
   operationId: string;
   lease: ILeaseRecord;
@@ -259,6 +265,8 @@ export class BrowserRuntime {
   private readonly failedRevocations = new Set<TCapabilityRecord>();
   private readonly capabilityMutex = new TransitionMutex();
   private readonly cleanupOperations = new Set<Promise<void>>();
+  // Retain admission until the host callback actually settles, including after cancellation.
+  private readonly leaseRenewals = new Set<ILeaseRecord>();
   private readonly framedPeers = new Set<BrowserRuntimeFramedServerPeer>();
   private startPromise?: Promise<void>;
   private stopPromise?: Promise<void>;
@@ -831,6 +839,7 @@ export class BrowserRuntime {
     const sessionId = requestArg.sessionId === undefined
       ? undefined
       : this.validateQualifiedSessionId(requestArg.sessionId);
+    if (sessionId?.harnessId === 'codex') throw new BrowserRuntimeError('INVALID_INPUT');
     if (
       (role === 'agent' && !sessionId)
       || (role === 'human' && sessionId !== undefined)
@@ -1129,6 +1138,75 @@ export class BrowserRuntime {
     return this.createLeaseAuthority(lease);
   }
 
+  /** @internal */
+  public async renewLease(
+    lease: ILeaseRecord,
+    optionsArg: IBrowserRuntimeLeaseRenewalOptions = {},
+  ): Promise<number> {
+    const options = validateExactKeys(optionsArg, ['signal', 'expiresInMs'], 'renewal');
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const lifetimeMs = validateOptionalInteger(
+      options.expiresInMs, 'expiresInMs', 1000,
+      this.options.capabilityMaximumTtlMs, this.options.capabilityDefaultTtlMs,
+    );
+    const authority = this.getLeaseAuthority(lease);
+    if (!this.isLeaseAuthorityCurrent(lease, authority)) throw new BrowserRuntimeError('FENCED');
+    if (this.leaseRenewals.has(lease)) throw new BrowserRuntimeError('BUSY');
+    if (this.leaseRenewals.size >= this.options.maxCapabilities) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    const controller = new AbortController();
+    const signal = AbortSignal.any([
+      controller.signal, this.lifecycleController.signal, lease.controller.signal,
+      ...(optionsArg.signal ? [optionsArg.signal] : []),
+    ]);
+    signal.throwIfAborted();
+    const timeout = setTimeout(() => controller.abort(new BrowserRuntimeError('TIMEOUT')),
+      Math.min(this.options.authorizationTimeoutMs, lease.capability.expiresAt - Date.now()));
+    timeout.unref();
+    const binding = this.describeCapabilityIdentity(lease.capability);
+    if (binding.sessionId) Object.freeze(binding.sessionId);
+    Object.freeze(binding);
+    this.leaseRenewals.add(lease);
+    const authorization = Promise.resolve().then(() => {
+      signal.throwIfAborted();
+      return this.options.authorizeCapability(binding, signal);
+    });
+    void authorization.then(
+      () => this.leaseRenewals.delete(lease),
+      () => this.leaseRenewals.delete(lease),
+    );
+    let abortListener: (() => void) | undefined;
+    try {
+      const authorized = await new Promise<boolean>((resolve, reject) => {
+        abortListener = () => reject(signal.reason ?? new BrowserRuntimeError('ABORTED'));
+        signal.addEventListener('abort', abortListener, { once: true });
+        if (signal.aborted) abortListener();
+        void authorization.then(resolve, () => reject(new BrowserRuntimeError('AUTHORIZATION_DENIED')));
+      });
+      signal.throwIfAborted();
+      if (authorized !== true) throw new BrowserRuntimeError('AUTHORIZATION_DENIED');
+      // Neither expiry, release, attachment change nor incarnation replacement may be revived.
+      if (!this.isLeaseAuthorityCurrent(lease, authority)) throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+      const capability = lease.capability;
+      const expiresAt = Date.now() + lifetimeMs;
+      clearTimeout(capability.expiryTimer);
+      capability.expiresAt = expiresAt;
+      capability.expiryTimer = setTimeout(() => {
+        if (capability.state === 'active') capability.state = 'expired';
+        this.trackCleanup(this.revokeCapabilityRecord(capability));
+      }, lifetimeMs);
+      capability.expiryTimer.unref();
+      return expiresAt;
+    } finally {
+      clearTimeout(timeout);
+      if (abortListener) signal.removeEventListener('abort', abortListener);
+      controller.abort(new BrowserRuntimeError('ABORTED'));
+    }
+  }
+
   /** @internal */
   public isLeaseAuthorityCurrent(
     lease: ILeaseRecord,
@@ -3787,7 +3865,7 @@ export class BrowserRuntime {
     if (Object.keys(record).some((key) => key !== 'harnessId' && key !== 'nativeId')) {
       throw new BrowserRuntimeError('INVALID_INPUT');
     }
-    if (record.harnessId !== 'opencode' && record.harnessId !== 'flex') {
+    if (record.harnessId !== 'opencode' && record.harnessId !== 'flex' && record.harnessId !== 'codex') {
       throw new BrowserRuntimeError('INVALID_INPUT');
     }
     return {
@@ -4127,6 +4205,15 @@ export class BrowserRuntimeLease {
     return this.record.capability.capabilityId;
   }
 
+  public get expiresAt(): number {
+    return this.record.capability.expiresAt;
+  }
+
+  /** Reauthorize this exact live lease without replacing its frame stream or browser incarnation. */
+  public renew(options?: IBrowserRuntimeLeaseRenewalOptions): Promise<number> {
+    return this.runtime.renewLease(this.record, options);
+  }
+
   public get role(): TBrowserActorRole {
     return this.record.role;
   }

package/ts/index.ts

@@ -10,7 +10,10 @@ export { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
 export { BrowserRuntimeError } from './errors.js';
 export { createBrowserRuntimeMcpHttpHandler } from './mcp.js';
 
-export type { TAcquireBrowserRuntimeLeaseOptions } from './classes.runtime.js';
+export type {
+  TAcquireBrowserRuntimeLeaseOptions,
+  IBrowserRuntimeLeaseRenewalOptions,
+} from './classes.runtime.js';
 export type { TBrowserRuntimeErrorCode } from './errors.js';
 export type {
   IAttachTrustedFramedPeerOptions,
@@ -28,6 +31,7 @@ export type {
   IBrowserEgressProxyStats,
   IBrowserFlexCapabilityBinding,
   IBrowserFlexSessionId,
+  IBrowserCodexSessionId,
   IBrowserFillAction,
   IBrowserNavigateAction,
   IBrowserObservationResult,

package/ts/interfaces.ts

@@ -4,7 +4,7 @@ import type { BrowserRuntimeFramedClient } from './classes.framed.js';
 
 export type TBrowserActorRole = 'human' | 'agent';
 export type TBrowserCapabilitySource = 'human' | 'flex' | 'mcp';
-export type TBrowserHarnessId = 'opencode' | 'flex';
+export type TBrowserHarnessId = 'opencode' | 'flex' | 'codex';
 
 export interface IBrowserOpenCodeSessionId {
   harnessId: 'opencode';
@@ -16,7 +16,12 @@ export interface IBrowserFlexSessionId {
   nativeId: string;
 }
 
-export type TQualifiedBrowserSessionId = IBrowserOpenCodeSessionId | IBrowserFlexSessionId;
+export interface IBrowserCodexSessionId {
+  harnessId: 'codex';
+  nativeId: string;
+}
+
+export type TQualifiedBrowserSessionId = IBrowserOpenCodeSessionId | IBrowserFlexSessionId | IBrowserCodexSessionId;
 
 export interface IBrowserResourceKey {
   projectId: string;