@modelprofile.com/browser-runtime 2.0.0 → 2.1.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, 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, 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';

package/dist_ts/interfaces.d.ts

@@ -81,15 +81,22 @@ export type TIssuedBrowserCapability = TBrowserCapabilityDescriptor & {
 export interface IResolvedBrowserFlexCapability {
     capabilityToken: string;
 }
-export type TBrowserRuntimeAuditEvent = TBrowserCapabilityAuthorizationRequest & {
-    operationId: string;
-    capabilityId: string;
-    leaseId: string;
-    action: string;
-    phase: 'completed' | 'failed';
-    startedAt: number;
-    finishedAt: number;
-    errorCode?: string;
+type TReadonlyBrowserCapabilityAuthorizationRequest = Readonly<IBrowserHumanCapabilityBinding> | (Omit<Readonly<IBrowserFlexCapabilityBinding>, 'sessionId'> & {
+    readonly sessionId: Readonly<IBrowserFlexSessionId>;
+}) | (Omit<Readonly<IBrowserMcpCapabilityBinding>, 'sessionId'> & {
+    readonly sessionId: Readonly<IBrowserOpenCodeSessionId>;
+});
+export type TBrowserRuntimeOperationIdentity = TReadonlyBrowserCapabilityAuthorizationRequest & {
+    readonly operationId: string;
+    readonly capabilityId: string;
+    readonly leaseId: string;
+    readonly action: string;
+    readonly startedAt: number;
+};
+export type TBrowserRuntimeAuditEvent = TBrowserRuntimeOperationIdentity & {
+    readonly phase: 'completed' | 'failed';
+    readonly finishedAt: number;
+    readonly errorCode?: string;
 };
 export interface ILiveBrowserSessionLike {
     start(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
@@ -130,6 +137,7 @@ export interface IBrowserRuntimeEnvironment {
 export interface IBrowserRuntimeOptions {
     runtimeDirectory: string;
     authorizeCapability(request: TBrowserCapabilityAuthorizationRequest, signal: AbortSignal): Promise<boolean> | boolean;
+    beforeOperation?(operation: TBrowserRuntimeOperationIdentity, signal: AbortSignal): Promise<void> | void;
     audit?(event: TBrowserRuntimeAuditEvent, signal: AbortSignal): Promise<void> | void;
     maxResources?: number;
     maxResourcesPerProject?: number;
@@ -141,6 +149,7 @@ export interface IBrowserRuntimeOptions {
     capabilityDefaultTtlMs?: number;
     capabilityMaximumTtlMs?: number;
     authorizationTimeoutMs?: number;
+    beforeOperationTimeoutMs?: number;
     maxTabsPerResource?: number;
     operationTimeoutMs?: number;
     quiescenceTimeoutMs?: number;
@@ -347,3 +356,4 @@ export interface IBrowserRuntimeFlexToolProviderOptions<TScope> {
     client: BrowserRuntimeFramedClient;
     resolveCapability(context: plugins.flexharness.IFlexToolProviderContext<TScope>): Promise<IResolvedBrowserFlexCapability> | IResolvedBrowserFlexCapability;
 }
+export {};

package/package.json

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

@@ -17,6 +17,7 @@ Durable implementation findings for `@modelprofile.com/browser-runtime`.
 - Agent capabilities require the exact current non-detached qualified session. Human capabilities bind the exact resource, project, attachment authority, and revision but intentionally carry no session ID and may be issued while detached. Any attachment advance revokes both human and agent capabilities.
 - Capability tokens are returned once. Runtime records retain only SHA-256 digests and use `timingSafeEqual`. Authorization is rechecked after asynchronous host authorization, during lease acquisition, and before and after every operation.
 - Capability, audit, and lease identity includes immutable project, resource, attachment authority and revision, actor, peer, role, source, qualified agent session, and Flex scope/channel where applicable.
+- `beforeOperation` reserves the exact resource and lets the host persist policy/audit through an awaited fail-closed gate. Runtime then atomically revalidates lease, attachment, session, arbitration generation, and incarnation before starting the side effect. Terminal audit remains best effort, uses the same operation ID, and runs after bounded cleanup releases or fences the exact reservation.
 
 ## Browser confinement
 

package/readme.md

@@ -27,6 +27,7 @@ import {
 const runtime = new BrowserRuntime({
   runtimeDirectory: '/var/lib/example/browser-runtime',
   authorizeCapability: async (binding) => hostPolicy.authorizeBrowser(binding),
+  beforeOperation: async (operation) => hostAudit.recordAttempt(operation),
 });
 
 try {
@@ -96,6 +97,8 @@ Agent capabilities require the exact current non-detached qualified session. Hum
 
 Agent actions are exactly `navigate`, `snapshot`, `screenshot`, `click`, `fill`, and `press`. Human leases additionally expose tab lifecycle, viewport, raw input, frame subscription/acknowledgement, and exact-resource artifact reads/deletes. JavaScript evaluation is not public.
 
+`beforeOperation` is an optional awaited fail-closed gate. It receives the complete immutable authority, operation/capability/lease IDs, action, start time, and an `AbortSignal` after resource admission but before the browser side effect starts. 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 runs after bounded operation cleanup releases or fences the exact reservation.
+
 ## Trusted Pipe And Flex
 
 Trusted framed peers and clients receive the complete authority out of band: project, resource, attachment authority/revision, actor, peer, role, source, qualified session, Flex scope, and resource-specific channel. Incoming frames cannot select identity. One session may use multiple resource-specific channels concurrently.

package/ts/00_commitinfo_data.ts

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

@@ -19,6 +19,7 @@ import type {
   IBrowserConfinementProbeContext,
   IBrowserObservationResult,
   TBrowserRuntimeAuditEvent,
+  TBrowserRuntimeOperationIdentity,
   IBrowserRuntimeFrameSubscription,
   IBrowserRuntimeOperationOptions,
   IBrowserRuntimeOptions,
@@ -53,6 +54,7 @@ import { BrowserRuntimeFramedServerPeer } from './classes.framed.js';
 interface INormalizedRuntimeOptions {
   runtimeDirectory: string;
   authorizeCapability: IBrowserRuntimeOptions['authorizeCapability'];
+  beforeOperation?: IBrowserRuntimeOptions['beforeOperation'];
   audit?: IBrowserRuntimeOptions['audit'];
   sessionFactory: (
     options: plugins.smartpuppeteer.ILiveBrowserSessionOptions,
@@ -69,6 +71,7 @@ interface INormalizedRuntimeOptions {
   capabilityDefaultTtlMs: number;
   capabilityMaximumTtlMs: number;
   authorizationTimeoutMs: number;
+  beforeOperationTimeoutMs: number;
   maxTabsPerResource: number;
   operationTimeoutMs: number;
   quiescenceTimeoutMs: number;
@@ -121,6 +124,8 @@ interface IOperationRecord {
   controller: AbortController;
   action: string;
   startedAt: number;
+  session: ILiveBrowserSessionLike;
+  incarnationGeneration: number;
   promise: Promise<void>;
 }
 
@@ -212,6 +217,9 @@ export class BrowserRuntime {
     if (options.audit !== undefined && typeof options.audit !== 'function') {
       throw new BrowserRuntimeError('INVALID_INPUT', 'audit must be a function');
     }
+    if (options.beforeOperation !== undefined && typeof options.beforeOperation !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'beforeOperation must be a function');
+    }
     const testingOptions = browserRuntimeTesting in options
       && options[browserRuntimeTesting] === true
       ? options as IBrowserRuntimeTestingOptions
@@ -244,6 +252,7 @@ export class BrowserRuntime {
     this.options = {
       runtimeDirectory: options.runtimeDirectory,
       authorizeCapability: options.authorizeCapability,
+      beforeOperation: options.beforeOperation,
       audit: options.audit,
       sessionFactory: testingOptions?.sessionFactory ?? ((sessionOptions) => (
         new plugins.smartpuppeteer.LiveBrowserSession(sessionOptions)
@@ -308,6 +317,13 @@ export class BrowserRuntime {
         120_000,
         10_000,
       ),
+      beforeOperationTimeoutMs: validateOptionalInteger(
+        options.beforeOperationTimeoutMs,
+        'beforeOperationTimeoutMs',
+        100,
+        120_000,
+        10_000,
+      ),
       maxTabsPerResource: validateOptionalInteger(
         options.maxTabsPerResource,
         'maxTabsPerResource',
@@ -1504,16 +1520,20 @@ export class BrowserRuntime {
       operationOptions.onOperationStarted !== undefined
       && typeof operationOptions.onOperationStarted !== 'function'
     ) throw new BrowserRuntimeError('INVALID_INPUT');
-    operationOptions.signal?.throwIfAborted();
+    if (operationOptions.signal?.aborted) throw new BrowserRuntimeError('ABORTED');
     const slot = lease.slot;
     const release = slot.mutex.tryAcquire();
     if (!release) throw new BrowserRuntimeError('BUSY');
     let operation: IOperationRecord;
-    let executionPromise: Promise<T>;
+    let executionPromise: Promise<T> | undefined;
     let combinedSignal: AbortSignal;
     let timeout: ReturnType<typeof setTimeout>;
     let session: ILiveBrowserSessionLike;
     let generation: number;
+    let incarnationGeneration: number;
+    let externalAbort = false;
+    let onExternalAbort: (() => void) | undefined;
+    let resolvePreflight!: () => void;
     const startedAt = Date.now();
     try {
       this.requireValidLease(lease);
@@ -1521,6 +1541,7 @@ export class BrowserRuntime {
       if (slot.operation) throw new BrowserRuntimeError('BUSY');
       session = slot.session!;
       generation = slot.arbitrationGeneration;
+      incarnationGeneration = slot.incarnationGeneration;
       const timeoutMs = operationOptions.timeoutMs === undefined
         ? this.options.operationTimeoutMs
         : validateInteger(operationOptions.timeoutMs, 'timeoutMs', 100, 120_000);
@@ -1530,20 +1551,25 @@ export class BrowserRuntime {
         timeoutController.abort(new BrowserRuntimeError('TIMEOUT'));
       }, timeoutMs);
       timeout.unref();
+      const externalSignal = operationOptions.signal;
+      onExternalAbort = () => { externalAbort = true; };
+      externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
+      if (externalSignal?.aborted) externalAbort = true;
       combinedSignal = AbortSignal.any([
         controller.signal,
         lease.controller.signal,
-        operationOptions.signal ?? new AbortController().signal,
+        externalSignal ?? new AbortController().signal,
         timeoutController.signal,
       ]);
-      executionPromise = Promise.resolve().then(() => execute(combinedSignal, session));
       operation = {
         operationId: randomId(18),
         lease,
         controller,
         action,
         startedAt,
-        promise: executionPromise.then(() => undefined, () => undefined),
+        session,
+        incarnationGeneration,
+        promise: new Promise<void>((resolve) => { resolvePreflight = resolve; }),
       };
       slot.operation = operation;
       try {
@@ -1555,17 +1581,39 @@ export class BrowserRuntime {
       release();
     }
 
-    let phase: 'completed' | 'failed' = 'completed';
-    let errorCode: string | undefined;
+    const operationIdentity = this.createOperationIdentity(lease, operation, action, startedAt);
+
+    let result: T | undefined;
+    let failed = false;
+    let failure: unknown;
+    let executionStarted = false;
     try {
+      await this.runBeforeOperation(operationIdentity, combinedSignal);
+      const executionRelease = await slot.mutex.acquire();
+      try {
+        combinedSignal.throwIfAborted();
+        this.requireValidLease(lease);
+        this.assertSlotAvailable(slot);
+        this.assertCapabilityStillAttached(lease.capability, slot);
+        if (
+          slot.operation !== operation
+          || slot.session !== session
+          || slot.arbitrationGeneration !== generation
+          || slot.incarnationGeneration !== incarnationGeneration
+        ) throw new BrowserRuntimeError('ABORTED');
+        executionStarted = true;
+        executionPromise = execute(combinedSignal, session);
+        operation.promise = executionPromise.then(() => undefined, () => undefined);
+      } finally {
+        executionRelease();
+      }
       let onAbort!: () => void;
       const aborted = new Promise<never>((_resolve, reject) => {
         onAbort = () => reject(combinedSignal.reason ?? new BrowserRuntimeError('ABORTED'));
         combinedSignal.addEventListener('abort', onAbort, { once: true });
       });
-      let result: T;
       try {
-        result = await Promise.race([executionPromise!, aborted]);
+        result = await Promise.race([executionPromise, aborted]);
       } finally {
         combinedSignal.removeEventListener('abort', onAbort);
       }
@@ -1575,46 +1623,131 @@ export class BrowserRuntime {
       if (slot.session !== session! || slot.arbitrationGeneration !== generation!) {
         throw new BrowserRuntimeError('ABORTED');
       }
-      return result;
     } catch (error) {
-      phase = 'failed';
-      errorCode = error instanceof BrowserRuntimeError
-        ? error.code
-        : error instanceof Error
-          ? truncateString(error.name, 64)
-          : 'Error';
-      if (combinedSignal!.aborted) {
-        this.trackCleanup(this.enforceOperationQuiescence(operation!));
-        const reason = combinedSignal!.reason;
-        throw reason instanceof BrowserRuntimeError
-          ? reason
-          : new BrowserRuntimeError(
-              reason instanceof Error && reason.name === 'TimeoutError' ? 'TIMEOUT' : 'ABORTED',
-            );
-      }
-      throw error;
+      failed = true;
+      failure = this.normalizeOperationError(error, combinedSignal!, externalAbort);
     } finally {
       clearTimeout(timeout!);
-      executionPromise!.finally(async () => {
+      operationOptions.signal?.removeEventListener('abort', onExternalAbort!);
+      resolvePreflight();
+      const cleanupSlot = async (): Promise<void> => {
         const cleanupRelease = await slot.mutex.acquire();
         try {
-          if (slot.operation === operation!) slot.operation = undefined;
+          if (slot.operation === operation) slot.operation = undefined;
         } finally {
           cleanupRelease();
         }
-      }).catch(() => undefined);
-      await this.emitAudit({
-        ...this.describeCapabilityIdentity(lease.capability),
-        operationId: operation!.operationId,
-        capabilityId: lease.capability.capabilityId,
-        leaseId: lease.leaseId,
-        action,
-        phase,
-        startedAt,
+      };
+      if (executionStarted) {
+        if (combinedSignal!.aborted) {
+          await this.enforceOperationQuiescence(operation).catch(() => undefined);
+        }
+        if (slot.operation === operation) {
+          const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
+          if (settled.settled) await cleanupSlot();
+        }
+      } else {
+        await cleanupSlot();
+      }
+      const errorCode = failed ? this.operationErrorCode(failure) : undefined;
+      await this.emitAudit(Object.freeze({
+        ...operationIdentity,
+        phase: failed ? 'failed' : 'completed',
         finishedAt: Date.now(),
         ...(errorCode ? { errorCode } : {}),
-      });
+      }));
+    }
+    if (failed) throw failure;
+    return result as T;
+  }
+
+  private normalizeOperationError(
+    errorArg: unknown,
+    signalArg: AbortSignal,
+    externalAbortArg: boolean,
+  ): unknown {
+    if (signalArg.aborted) {
+      if (externalAbortArg) return new BrowserRuntimeError('ABORTED');
+      const reason = signalArg.reason;
+      if (reason instanceof BrowserRuntimeError) return reason;
+      return new BrowserRuntimeError(
+        reason instanceof Error && reason.name === 'TimeoutError' ? 'TIMEOUT' : 'ABORTED',
+      );
+    }
+    if (errorArg instanceof BrowserRuntimeError) return errorArg;
+    if (errorArg instanceof Error && errorArg.name === 'TimeoutError') {
+      return new BrowserRuntimeError('TIMEOUT');
     }
+    if (errorArg instanceof Error && errorArg.name === 'AbortError') {
+      return new BrowserRuntimeError('ABORTED');
+    }
+    return errorArg;
+  }
+
+  private operationErrorCode(errorArg: unknown): string {
+    return errorArg instanceof BrowserRuntimeError
+      ? errorArg.code
+      : errorArg instanceof Error
+        ? truncateString(errorArg.name, 64)
+        : 'Error';
+  }
+
+  private async runBeforeOperation(
+    operationArg: TBrowserRuntimeOperationIdentity,
+    signalArg: AbortSignal,
+  ): Promise<void> {
+    if (!this.options.beforeOperation) return;
+    signalArg.throwIfAborted();
+    const controller = new AbortController();
+    const signal = AbortSignal.any([signalArg, controller.signal]);
+    const hook = Promise.resolve().then(() => this.options.beforeOperation!(operationArg, signal));
+    void hook.catch(() => undefined);
+    let onAbort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      onAbort = () => reject(signal.reason ?? new BrowserRuntimeError('ABORTED'));
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+    let result: Awaited<ReturnType<typeof waitBounded<void>>>;
+    try {
+      try {
+        result = await waitBounded(
+          Promise.race([hook, aborted]),
+          this.options.beforeOperationTimeoutMs,
+        );
+      } catch {
+        if (signalArg.aborted) throw signalArg.reason;
+        controller.abort(new BrowserRuntimeError('AUTHORIZATION_DENIED'));
+        throw new BrowserRuntimeError('AUTHORIZATION_DENIED');
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort);
+    }
+    if (!result.settled) {
+      controller.abort(new BrowserRuntimeError('TIMEOUT'));
+      throw new BrowserRuntimeError('TIMEOUT');
+    }
+    signalArg.throwIfAborted();
+  }
+
+  private createOperationIdentity(
+    leaseArg: ILeaseRecord,
+    operationArg: IOperationRecord,
+    actionArg: string,
+    startedAtArg: number,
+  ): TBrowserRuntimeOperationIdentity {
+    const identity = this.describeCapabilityIdentity(leaseArg.capability);
+    const sessionId = identity.role === 'agent'
+      ? Object.freeze({ ...identity.sessionId })
+      : undefined;
+    return Object.freeze({
+      ...identity,
+      ...(sessionId ? { sessionId } : {}),
+      operationId: operationArg.operationId,
+      capabilityId: leaseArg.capability.capabilityId,
+      leaseId: leaseArg.leaseId,
+      action: actionArg,
+      startedAt: startedAtArg,
+    }) as TBrowserRuntimeOperationIdentity;
   }
 
   private async executeAgentActionInternal(
@@ -2192,9 +2325,42 @@ export class BrowserRuntime {
   }
 
   private async enforceOperationQuiescence(operation: IOperationRecord): Promise<void> {
-    const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
-    if (settled.settled || operation.lease.released) return;
-    await this.revokeCapabilityRecord(operation.lease.capability);
+    let settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
+    if (settled.settled) return;
+    let cleanupError: unknown;
+    try {
+      if (!operation.lease.released) {
+        await this.revokeCapabilityRecord(operation.lease.capability);
+      } else if (operation.lease.releasePromise) {
+        await waitBounded(operation.lease.releasePromise, this.options.quiescenceTimeoutMs);
+      }
+    } catch (error) {
+      cleanupError = error;
+    }
+    if (operation.lease.slot.operation !== operation) {
+      if (cleanupError) throw cleanupError;
+      return;
+    }
+    settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
+    if (settled.settled) {
+      if (cleanupError) throw cleanupError;
+      return;
+    }
+    const slot = operation.lease.slot;
+    const release = await slot.mutex.acquire();
+    try {
+      if (
+        slot.operation === operation
+        && (
+          slot.permanentlyFenced
+          || slot.session !== operation.session
+          || slot.incarnationGeneration !== operation.incarnationGeneration
+        )
+      ) slot.operation = undefined;
+    } finally {
+      release();
+    }
+    if (cleanupError) throw cleanupError;
   }
 
   private async terminateSlotSession(

package/ts/index.ts

@@ -34,6 +34,7 @@ export type {
   IBrowserOpenCodeSessionId,
   IBrowserPressAction,
   TBrowserRuntimeAuditEvent,
+  TBrowserRuntimeOperationIdentity,
   IBrowserRuntimeFlexToolProviderOptions,
   IBrowserRuntimeFrameSubscription,
   IBrowserRuntimeFramedClientOptions,

package/ts/interfaces.ts

@@ -104,15 +104,27 @@ export interface IResolvedBrowserFlexCapability {
   capabilityToken: string;
 }
 
-export type TBrowserRuntimeAuditEvent = TBrowserCapabilityAuthorizationRequest & {
-  operationId: string;
-  capabilityId: string;
-  leaseId: string;
-  action: string;
-  phase: 'completed' | 'failed';
-  startedAt: number;
-  finishedAt: number;
-  errorCode?: string;
+type TReadonlyBrowserCapabilityAuthorizationRequest =
+  | Readonly<IBrowserHumanCapabilityBinding>
+  | (Omit<Readonly<IBrowserFlexCapabilityBinding>, 'sessionId'> & {
+      readonly sessionId: Readonly<IBrowserFlexSessionId>;
+    })
+  | (Omit<Readonly<IBrowserMcpCapabilityBinding>, 'sessionId'> & {
+      readonly sessionId: Readonly<IBrowserOpenCodeSessionId>;
+    });
+
+export type TBrowserRuntimeOperationIdentity = TReadonlyBrowserCapabilityAuthorizationRequest & {
+  readonly operationId: string;
+  readonly capabilityId: string;
+  readonly leaseId: string;
+  readonly action: string;
+  readonly startedAt: number;
+};
+
+export type TBrowserRuntimeAuditEvent = TBrowserRuntimeOperationIdentity & {
+  readonly phase: 'completed' | 'failed';
+  readonly finishedAt: number;
+  readonly errorCode?: string;
 };
 
 export interface ILiveBrowserSessionLike {
@@ -207,6 +219,10 @@ export interface IBrowserRuntimeOptions {
     request: TBrowserCapabilityAuthorizationRequest,
     signal: AbortSignal,
   ): Promise<boolean> | boolean;
+  beforeOperation?(
+    operation: TBrowserRuntimeOperationIdentity,
+    signal: AbortSignal,
+  ): Promise<void> | void;
   audit?(event: TBrowserRuntimeAuditEvent, signal: AbortSignal): Promise<void> | void;
   maxResources?: number;
   maxResourcesPerProject?: number;
@@ -218,6 +234,7 @@ export interface IBrowserRuntimeOptions {
   capabilityDefaultTtlMs?: number;
   capabilityMaximumTtlMs?: number;
   authorizationTimeoutMs?: number;
+  beforeOperationTimeoutMs?: number;
   maxTabsPerResource?: number;
   operationTimeoutMs?: number;
   quiescenceTimeoutMs?: number;