@modelprofile.com/browser-runtime 5.2.1 → 5.3.0

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' | 'video-peer' | 'viewport' | 'navigation' | 'tab' | 'agent-action';
+export type TBrowserRuntimeOperationClassification = 'raw-input' | 'frame-stream' | 'video-peer' | 'devtools' | '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;
@@ -120,6 +120,7 @@ export type TBrowserRuntimeAuditEvent = TBrowserRuntimeOperationIdentity & {
     readonly errorCode?: string;
 };
 export interface ILiveBrowserSessionLike {
+    openDevTools?(options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions, operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection>;
     start(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
     stop(): Promise<void>;
     terminate(options?: plugins.smartpuppeteer.ILiveBrowserTerminationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserTerminationResult>;
@@ -200,6 +201,8 @@ export interface IBrowserRuntimeOptions {
     screencast?: IBrowserRuntimeScreencastOptions;
     /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
     video?: plugins.smartpuppeteer.ILiveVideoOptions;
+    /** Enables selected-tab DevTools for human leases only. Disabled by default. */
+    devTools?: boolean;
     egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
     artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "5.2.1",
+  "version": "5.3.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.8.1",
+    "@push.rocks/smartpuppeteer": "^2.9.0",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {

package/readme.md

@@ -2,6 +2,28 @@
 
 Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.
 
+## Selected-tab DevTools
+
+Set the trusted host option `devTools: true` to enable `humanLease.openDevTools({
+tabId, onMessage, onClose }, operationOptions?)`. Agent leases cannot acquire an
+inspector. The returned connection exposes `tabId`, `browserVersion`,
+`send(message)`, and `close()` using SmartPuppeteer's bounded CDP contract.
+
+DevTools commands run concurrently on a separate lane, so pausing JavaScript does
+not queue `Debugger.resume` behind a pending evaluation. The lane reserves interrupt
+capacity and applies the normal authorization hook and audit policy to every command;
+audit records contain the method and outcome, never expressions or response bodies.
+Lease, attachment, and browser incarnation authority are rechecked before execution
+and around every delivered event. Revocation closes pending and late-opening
+attachments. Failed cleanup terminates the exact owned browser incarnation.
+
+Await each `onMessage` delivery to preserve transport backpressure. Closing an
+inspector does not close the human lease or its video peer. The embedding application
+must close the inspector when changing the inspected tab or replacing its transport.
+No browser debugging port or browser-wide target discovery is exposed. Pair this
+connection with `DevToolsFrontend` from `@push.rocks/smartbrowser/web` for the official
+Chrome DevTools UI.
+
 ## 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.

package/ts/00_commitinfo_data.ts

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

@@ -105,6 +105,7 @@ interface INormalizedRuntimeOptions {
   frameAcknowledgementTimeoutMs: number;
   screencast: INormalizedScreencastOptions;
   video: Required<plugins.smartpuppeteer.ILiveVideoOptions>;
+  devTools: boolean;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
   ownership?: IBrowserRuntimeTestingOptions['ownership'];
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
@@ -144,10 +145,25 @@ interface ILeaseRecord {
   videoPeerId: string;
   videoPeerMayExist: boolean;
   frameCaptureUsed: boolean;
+  devTools?: IDevToolsRecord;
   heldKeys: Map<string, plugins.smartpuppeteer.ILiveBrowserKeyInput>;
   heldButtons: Map<string, plugins.smartpuppeteer.ILiveBrowserMouseInput>;
 }
 
+interface IDevToolsRecord {
+  authority: TBrowserRuntimeLeaseAuthority;
+  session: ILiveBrowserSessionLike;
+  controller: AbortController;
+  connection?: plugins.smartpuppeteer.ILiveBrowserDevToolsConnection;
+  opening?: Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection>;
+  closePromise?: Promise<void>;
+  pending: Set<Promise<void>>;
+  commands: number;
+  interrupts: number;
+  closed: boolean;
+  removeAbortListener(): void;
+}
+
 export interface IBrowserRuntimeLeaseRenewalOptions {
   signal?: AbortSignal;
   /** Lifetime from successful reauthorization; defaults to the runtime capability lifetime. */
@@ -318,6 +334,9 @@ export class BrowserRuntime {
     if (options.beforeOperation !== undefined && typeof options.beforeOperation !== 'function') {
       throw new BrowserRuntimeError('INVALID_INPUT', 'beforeOperation must be a function');
     }
+    if (options.devTools !== undefined && typeof options.devTools !== 'boolean') {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'devTools must be a boolean');
+    }
     const testingOptions = browserRuntimeTesting in options
       && options[browserRuntimeTesting] === true
       ? options as IBrowserRuntimeTestingOptions
@@ -570,6 +589,7 @@ export class BrowserRuntime {
       ),
       screencast,
       video: plugins.smartpuppeteer.normalizeLiveVideoOptions(options.video ?? {}),
+      devTools: options.devTools ?? false,
       egress: options.egress ?? {},
       ownership: testingOptions?.ownership,
       beforeLeasePublication: testingOptions?.beforeLeasePublication,
@@ -1374,6 +1394,148 @@ export class BrowserRuntime {
     });
   }
 
+  /** @internal */
+  public async leaseOpenDevTools(lease: ILeaseRecord, options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions: IBrowserRuntimeOperationOptions = {}): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection> {
+    this.requireHuman(lease);
+    if (!this.options.devTools) throw new BrowserRuntimeError('CAPABILITY_INVALID', 'DevTools is not enabled.');
+    if (!options || typeof options.onMessage !== 'function' || typeof options.onClose !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const tabId = validateBoundedString(options.tabId, 'tabId', 1, 128);
+    let created: IDevToolsRecord | undefined;
+    try {
+      return await this.runOperation(lease, 'openDevTools', 'devtools', operationOptions, async (signal, session) => {
+        if (!session.openDevTools) throw new BrowserRuntimeError('CAPABILITY_INVALID', 'The browser adapter does not support DevTools.');
+        if (lease.devTools) await this.closeLeaseDevTools(lease, lease.devTools);
+        const controller = new AbortController();
+        const record: IDevToolsRecord = {
+          authority: this.createLeaseAuthority(lease), session, controller,
+          pending: new Set(), commands: 0, interrupts: 0, closed: false,
+          removeAbortListener: () => lease.controller.signal.removeEventListener('abort', abort),
+        };
+        const abort = (): void => { this.trackCleanup(this.closeLeaseDevTools(lease, record)); };
+        lease.controller.signal.addEventListener('abort', abort, { once: true });
+        created = record;
+        lease.devTools = record;
+        record.opening = session.openDevTools({ tabId,
+          onMessage: async message => {
+            this.requireDevToolsAuthority(lease, record);
+            await options.onMessage(message);
+            this.requireDevToolsAuthority(lease, record);
+          },
+          onClose: reason => {
+            record.closed = true;
+            controller.abort(new BrowserRuntimeError('ABORTED'));
+            record.removeAbortListener();
+            options.onClose(reason);
+          },
+        }, { signal });
+        const connection = await record.opening;
+        record.connection = connection;
+        try {
+          signal.throwIfAborted();
+          this.requireDevToolsAuthority(lease, record);
+        } catch (error) { await this.closeLeaseDevTools(lease, record); throw error; }
+        return {
+          tabId: connection.tabId,
+          browserVersion: connection.browserVersion,
+          send: message => this.sendLeaseDevTools(lease, record, message),
+          close: () => this.closeLeaseDevTools(lease, record),
+        };
+      });
+    } catch (error) {
+      if (created) await this.closeLeaseDevTools(lease, created);
+      throw error;
+    }
+  }
+
+  private requireDevToolsAuthority(lease: ILeaseRecord, record: IDevToolsRecord): void {
+    this.requireHuman(lease);
+    if (record.closed || record.controller.signal.aborted || lease.devTools !== record
+      || lease.slot.session !== record.session || !this.isLeaseAuthorityCurrent(lease, record.authority)) {
+      throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+    }
+  }
+
+  private async sendLeaseDevTools(lease: ILeaseRecord, record: IDevToolsRecord, message: string): Promise<void> {
+    this.requireDevToolsAuthority(lease, record);
+    const limits = plugins.smartpuppeteer.liveBrowserDevToolsLimits;
+    if (typeof message !== 'string' || plugins.Buffer.byteLength(message) > limits.commandBytes) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    let command: { method?: unknown };
+    try { command = JSON.parse(message); } catch { throw new BrowserRuntimeError('INVALID_INPUT'); }
+    if (!command || typeof command.method !== 'string' || !/^[A-Za-z]+\.[A-Za-z]+$/.test(command.method)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const action = command.method;
+    const interrupt = limits.interruptMethods.includes(action);
+    if (interrupt ? record.interrupts >= limits.interruptCommands : record.commands >= limits.commands) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    if (interrupt) record.interrupts++; else record.commands++;
+    const startedAt = Date.now();
+    const operation: IOperationRecord = {
+      operationId: randomId(), lease, controller: record.controller, action, startedAt,
+      session: record.session, incarnationGeneration: record.authority.incarnationGeneration,
+      promise: Promise.resolve(),
+    };
+    const identity = this.createOperationIdentity(lease, operation, action, 'devtools', startedAt);
+    const task = (async () => {
+      let failed = false;
+      let failure: unknown;
+      try {
+        await this.runBeforeOperation(identity, record.controller.signal);
+        this.requireDevToolsAuthority(lease, record);
+        await record.connection!.send(message);
+        this.requireDevToolsAuthority(lease, record);
+      } catch (error) { failed = true; failure = error; }
+      finally {
+        try {
+          await this.emitAudit(Object.freeze({ ...identity, phase: failed ? 'failed' : 'completed',
+            finishedAt: Date.now(), ...(failed ? { errorCode: this.operationErrorCode(failure) } : {}) }));
+        } finally {
+          if (interrupt) record.interrupts--; else record.commands--;
+        }
+      }
+      if (failed) throw failure;
+    })();
+    record.pending.add(task);
+    void task.then(() => record.pending.delete(task), () => record.pending.delete(task));
+    return task;
+  }
+
+  private closeLeaseDevTools(lease: ILeaseRecord, record: IDevToolsRecord): Promise<void> {
+    if (record.closePromise) return record.closePromise;
+    record.closed = true;
+    record.controller.abort(new BrowserRuntimeError('ABORTED'));
+    record.removeAbortListener();
+    const closing = (async () => {
+      try {
+        const detached = await waitBounded((async () => {
+          // Opening may still be completing when lease revocation arrives.
+          await Promise.resolve();
+          const connection = record.connection ?? await record.opening?.catch(() => undefined);
+          await connection?.close();
+        })(), this.options.quiescenceTimeoutMs + 3500);
+        if (!detached.settled) throw new BrowserRuntimeError('TIMEOUT');
+        const pending = await waitBounded(Promise.allSettled([...record.pending]),
+          this.options.quiescenceTimeoutMs + this.options.auditTimeoutMs + this.options.beforeOperationTimeoutMs);
+        if (!pending.settled) throw new BrowserRuntimeError('TIMEOUT');
+      } catch (error) {
+        await this.terminateRegisteredResourceInternal(lease.slot, false, {
+          session: record.session, incarnationGeneration: record.authority.incarnationGeneration,
+        });
+        throw error;
+      } finally {
+        if (lease.devTools === record) lease.devTools = undefined;
+      }
+    })();
+    record.closePromise = closing;
+    return closing;
+  }
+
   /** @internal */
   public async leaseAnswerVideoPeer(lease: ILeaseRecord, negotiationId: string,
     description: plugins.smartpuppeteer.ILiveVideoDescription, options: IBrowserRuntimeOperationOptions = {}): Promise<void> {
@@ -2013,6 +2175,7 @@ export class BrowserRuntime {
         usePipe: true,
         allowEvaluation: true,
         video: this.options.video,
+        allowDevTools: this.options.devTools,
         screencast: {
           enabled: false,          maxOutstandingFrames: this.options.maxOutstandingFrames,
           quality: this.options.screencast.quality,
@@ -3477,6 +3640,7 @@ export class BrowserRuntime {
       release();
     }
     await this.closeFrameSubscriptionIfLease(lease);
+    if (lease.devTools) await this.closeLeaseDevTools(lease, lease.devTools);
     if (operation) {
       const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
       if (!settled.settled) {
@@ -4381,6 +4545,11 @@ export class BrowserRuntimeLease {
     return this.runtime.leaseOpenVideoPeer(this.record, options);
   }
 
+  public openDevTools(options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection> {
+    return this.runtime.leaseOpenDevTools(this.record, options, operationOptions);
+  }
+
   public answerVideoPeer(negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription,
     options?: IBrowserRuntimeOperationOptions): Promise<void> {
     return this.runtime.leaseAnswerVideoPeer(this.record, negotiationId, description, options);

package/ts/interfaces.ts

@@ -134,6 +134,7 @@ export type TBrowserRuntimeOperationClassification =
   | 'raw-input'
   | 'frame-stream'
   | 'video-peer'
+  | 'devtools'
   | 'viewport'
   | 'navigation'
   | 'tab'
@@ -160,6 +161,8 @@ export type TBrowserRuntimeAuditEvent = TBrowserRuntimeOperationIdentity & {
 };
 
 export interface ILiveBrowserSessionLike {
+  openDevTools?(options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection>;
   start(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
   stop(): Promise<void>;
   terminate(
@@ -300,6 +303,8 @@ export interface IBrowserRuntimeOptions {
   screencast?: IBrowserRuntimeScreencastOptions;
   /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
   video?: plugins.smartpuppeteer.ILiveVideoOptions;
+  /** Enables selected-tab DevTools for human leases only. Disabled by default. */
+  devTools?: boolean;
   egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
   artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }