@modelprofile.com/browser-runtime 1.0.0

package/ts/confinement.ts

@@ -0,0 +1,90 @@
+import * as plugins from './plugins.js';
+import type { IBrowserConfinementProbeContext } from './interfaces.js';
+import { BrowserRuntimeError } from './errors.js';
+
+const listenOnUnsupportedPort = async (
+  allowedPorts: ReadonlySet<number>,
+  onRequest: () => void,
+): Promise<{ server: plugins.http.Server; port: number }> => {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const server = plugins.http.createServer((_request, response) => {
+      onRequest();
+      response.writeHead(204);
+      response.end();
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (address && typeof address !== 'string' && !allowedPorts.has(address.port)) {
+      return { server, port: address.port };
+    }
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+  throw new BrowserRuntimeError('CONFINEMENT_FAILED');
+};
+
+export const runProductionConfinementProbe = async (
+  context: IBrowserConfinementProbeContext,
+): Promise<void> => {
+  let originHits = 0;
+  const fixture = await listenOnUnsupportedPort(
+    new Set(context.proxy.allowedTargetPorts),
+    () => { originHits += 1; },
+  );
+  const closeFixture = async (): Promise<void> => new Promise((resolve) => {
+    fixture.server.close(() => resolve());
+  });
+  try {
+    const beforeLoopback = context.proxy.getStats();
+    await context.session.navigate(
+      { url: `http://127.0.0.1:${fixture.port}/browser-runtime-probe`, timeoutMs: 3000 },
+      { signal: context.signal },
+    ).catch(() => undefined);
+    const afterLoopback = context.proxy.getStats();
+    if (
+      originHits !== 0
+      || afterLoopback.ordinaryRequests <= beforeLoopback.ordinaryRequests
+      || afterLoopback.rejectedRequests <= beforeLoopback.rejectedRequests
+    ) {
+      throw new BrowserRuntimeError('CONFINEMENT_FAILED');
+    }
+
+    const beforeInvalid = context.proxy.getStats();
+    await context.session.navigate(
+      { url: 'http://browser-runtime-confinement.invalid/', timeoutMs: 3000 },
+      { signal: context.signal },
+    ).catch(() => undefined);
+    const afterInvalid = context.proxy.getStats();
+    if (
+      afterInvalid.ordinaryRequests <= beforeInvalid.ordinaryRequests
+      || afterInvalid.rejectedRequests <= beforeInvalid.rejectedRequests
+    ) {
+      throw new BrowserRuntimeError('CONFINEMENT_FAILED');
+    }
+
+    const result = await context.session.evaluate(
+      `new Promise(async (resolve) => {
+        const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:1.1.1.1:3478' }] });
+        let emitted = false;
+        pc.onicecandidate = (event) => { if (event.candidate) emitted = true; };
+        pc.createDataChannel('probe');
+        try { await pc.setLocalDescription(await pc.createOffer()); } catch {}
+        setTimeout(() => { pc.close(); resolve({ candidateEmitted: emitted }); }, 1000);
+      })`,
+      { timeoutMs: 2500, maxOutputBytes: 1024 },
+      { signal: context.signal },
+    );
+    if (
+      !result
+      || typeof result !== 'object'
+      || Array.isArray(result)
+      || (result as Record<string, unknown>).candidateEmitted !== false
+    ) {
+      throw new BrowserRuntimeError('CONFINEMENT_FAILED');
+    }
+  } finally {
+    await closeFixture();
+  }
+};

package/ts/errors.ts

@@ -0,0 +1,63 @@
+export type TBrowserRuntimeErrorCode =
+  | 'ABORTED'
+  | 'AUTHORIZATION_DENIED'
+  | 'BUSY'
+  | 'CAPABILITY_EXPIRED'
+  | 'CAPABILITY_INVALID'
+  | 'CAPABILITY_REVOKED'
+  | 'CONFINEMENT_FAILED'
+  | 'EGRESS_DENIED'
+  | 'FENCED'
+  | 'FRAME_TOO_LARGE'
+  | 'INVALID_INPUT'
+  | 'LOCKED'
+  | 'NOT_RUNNING'
+  | 'PROTOCOL_ERROR'
+  | 'QUOTA_EXCEEDED'
+  | 'TIMEOUT';
+
+const publicMessages: Record<TBrowserRuntimeErrorCode, string> = {
+  ABORTED: 'The operation was aborted.',
+  AUTHORIZATION_DENIED: 'Capability authorization was denied.',
+  BUSY: 'The browser project is busy.',
+  CAPABILITY_EXPIRED: 'The capability has expired.',
+  CAPABILITY_INVALID: 'The capability is invalid.',
+  CAPABILITY_REVOKED: 'The capability has been revoked.',
+  CONFINEMENT_FAILED: 'Browser confinement could not be confirmed.',
+  EGRESS_DENIED: 'The egress target was denied.',
+  FENCED: 'The browser project is permanently fenced.',
+  FRAME_TOO_LARGE: 'The browser frame exceeded its limit.',
+  INVALID_INPUT: 'The request is invalid.',
+  LOCKED: 'The browser runtime is already locked.',
+  NOT_RUNNING: 'The browser runtime is not running.',
+  PROTOCOL_ERROR: 'The framed protocol request is invalid.',
+  QUOTA_EXCEEDED: 'A browser runtime quota was exceeded.',
+  TIMEOUT: 'The operation timed out.',
+};
+
+export class BrowserRuntimeError extends Error {
+  public readonly code: TBrowserRuntimeErrorCode;
+
+  constructor(code: TBrowserRuntimeErrorCode, internalMessage?: string) {
+    super(internalMessage ?? publicMessages[code]);
+    this.name = 'BrowserRuntimeError';
+    this.code = code;
+  }
+
+  public get publicMessage(): string {
+    return publicMessages[this.code];
+  }
+}
+
+export const toBrowserRuntimeError = (error: unknown): BrowserRuntimeError => {
+  if (error instanceof BrowserRuntimeError) {
+    return error;
+  }
+  if (
+    error instanceof Error
+    && (error.name === 'AbortError' || error.name === 'TimeoutError')
+  ) {
+    return new BrowserRuntimeError(error.name === 'TimeoutError' ? 'TIMEOUT' : 'ABORTED');
+  }
+  return new BrowserRuntimeError('ABORTED');
+};

package/ts/index.ts

@@ -0,0 +1,52 @@
+export { validateAgentAction, validateAgentActionResult } from './actions.js';
+export { BrowserArtifactStore } from './classes.artifactstore.js';
+export { BrowserEgressProxy } from './classes.egressproxy.js';
+export { BrowserRuntimeFlexToolProvider } from './classes.flexprovider.js';
+export {
+  BrowserRuntimeFramedClient,
+  BrowserRuntimeFramedServerPeer,
+} from './classes.framed.js';
+export { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
+export { BrowserRuntimeError } from './errors.js';
+export { createBrowserRuntimeMcpHttpHandler } from './mcp.js';
+
+export type { IAcquireBrowserRuntimeLeaseOptions } from './classes.runtime.js';
+export type { TBrowserRuntimeErrorCode } from './errors.js';
+export type {
+  IAttachTrustedFramedPeerOptions,
+  IBrowserActionStateResult,
+  IBrowserArtifactMetadata,
+  IBrowserArtifactStoreOptions,
+  IBrowserCapabilityAuthorizationRequest,
+  IBrowserCapabilityDescriptor,
+  IBrowserClickAction,
+  IBrowserEgressConnectionOptions,
+  IBrowserEgressProxyOptions,
+  IBrowserEgressProxyStats,
+  IBrowserFillAction,
+  IBrowserNavigateAction,
+  IBrowserObservationResult,
+  IBrowserPressAction,
+  IBrowserRuntimeAuditEvent,
+  IBrowserRuntimeFlexToolProviderOptions,
+  IBrowserRuntimeFrameSubscription,
+  IBrowserRuntimeFramedClientOptions,
+  IBrowserRuntimeMcpOptions,
+  IBrowserRuntimeOperationOptions,
+  IBrowserRuntimeOptions,
+  IBrowserRuntimeState,
+  IBrowserRuntimeTabState,
+  IBrowserScreenshotAction,
+  IBrowserScreenshotResult,
+  IBrowserSnapshotAction,
+  IIssueBrowserCapabilityRequest,
+  IIssuedBrowserCapability,
+  IResolvedBrowserFlexCapability,
+  TBrowserActorRole,
+  TBrowserAgentAction,
+  TBrowserAgentActionResult,
+  TBrowserCapabilitySource,
+  TBrowserDnsResolver,
+  TBrowserEgressConnector,
+  TBrowserRuntimeEvent,
+} from './interfaces.js';

package/ts/interfaces.ts

@@ -0,0 +1,375 @@
+import type * as plugins from './plugins.js';
+
+export type TBrowserActorRole = 'human' | 'agent';
+export type TBrowserCapabilitySource = 'human' | 'flex' | 'mcp';
+
+export interface IBrowserCapabilityAuthorizationRequest {
+  projectId: string;
+  actorId: string;
+  role: TBrowserActorRole;
+  peerId: string;
+  source: TBrowserCapabilitySource;
+  scopeId?: string;
+  sessionId?: string;
+}
+
+export interface IIssueBrowserCapabilityRequest extends IBrowserCapabilityAuthorizationRequest {
+  expiresInMs?: number;
+  disconnect?: (signal: AbortSignal) => Promise<void> | void;
+}
+
+export interface IBrowserCapabilityDescriptor extends IBrowserCapabilityAuthorizationRequest {
+  capabilityId: string;
+  expiresAt: number;
+}
+
+export interface IIssuedBrowserCapability extends IBrowserCapabilityDescriptor {
+  capabilityToken: string;
+}
+
+export interface IResolvedBrowserFlexCapability {
+  capabilityToken: string;
+}
+
+export interface IBrowserRuntimeAuditEvent {
+  operationId: string;
+  capabilityId: string;
+  projectId: string;
+  actorId: string;
+  role: TBrowserActorRole;
+  source: TBrowserCapabilitySource;
+  action: string;
+  phase: 'completed' | 'failed';
+  startedAt: number;
+  finishedAt: number;
+  errorCode?: string;
+}
+
+export interface ILiveBrowserSessionLike {
+  start(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+  stop(): Promise<void>;
+  terminate(
+    options?: plugins.smartpuppeteer.ILiveBrowserTerminationOptions,
+  ): Promise<plugins.smartpuppeteer.ILiveBrowserTerminationResult>;
+  getState(): plugins.smartpuppeteer.ILiveBrowserState;
+  getProcessState(): plugins.smartpuppeteer.ILiveBrowserProcessState;
+  onEvent(listener: plugins.smartpuppeteer.TLiveBrowserEventListener): () => void;
+  acknowledgeFrame(
+    request: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+  ): Promise<plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgement>;
+  createTab(
+    options?: plugins.smartpuppeteer.ILiveBrowserCreateTabOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<plugins.smartpuppeteer.ILiveBrowserTabState>;
+  activateTab(
+    tabId: string,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  closeTab(
+    tabId: string,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  navigate(
+    options: plugins.smartpuppeteer.ILiveBrowserNavigateOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  back(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  forward(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  reload(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  setViewport(
+    viewport: plugins.smartpuppeteer.ILiveBrowserViewport,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  dispatchMouse(input: plugins.smartpuppeteer.ILiveBrowserMouseInput): Promise<void>;
+  dispatchWheel(input: plugins.smartpuppeteer.ILiveBrowserWheelInput): Promise<void>;
+  dispatchKey(input: plugins.smartpuppeteer.ILiveBrowserKeyInput): Promise<void>;
+  insertText(input: plugins.smartpuppeteer.ILiveBrowserInsertTextInput): Promise<void>;
+  captureSnapshot(
+    options?: plugins.smartpuppeteer.ILiveBrowserSnapshotOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<plugins.smartpuppeteer.ILiveBrowserSnapshot>;
+  observe(
+    options?: plugins.smartpuppeteer.ILiveBrowserObserveOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<plugins.smartpuppeteer.ILiveBrowserObservation>;
+  evaluate(
+    expression: string,
+    options?: plugins.smartpuppeteer.ILiveBrowserEvaluateOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<plugins.smartpuppeteer.TLiveBrowserJsonValue>;
+  click(
+    options: plugins.smartpuppeteer.ILiveBrowserClickOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  fill(
+    options: plugins.smartpuppeteer.ILiveBrowserFillOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+  press(
+    options: plugins.smartpuppeteer.ILiveBrowserPressOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
+  ): Promise<void>;
+}
+
+export interface IBrowserConfinementProbeContext {
+  session: ILiveBrowserSessionLike;
+  proxy: import('./classes.egressproxy.js').BrowserEgressProxy;
+  signal: AbortSignal;
+}
+
+export interface IBrowserRuntimeEnvironment {
+  platform: NodeJS.Platform;
+  uid: number | undefined;
+}
+
+export interface IBrowserRuntimeOptions {
+  runtimeDirectory: string;
+  authorizeCapability(
+    request: IBrowserCapabilityAuthorizationRequest,
+    signal: AbortSignal,
+  ): Promise<boolean> | boolean;
+  audit?(event: IBrowserRuntimeAuditEvent, signal: AbortSignal): Promise<void> | void;
+  maxProjectSlots?: number;
+  maxCapabilities?: number;
+  maxCapabilitiesPerProject?: number;
+  capabilityDefaultTtlMs?: number;
+  capabilityMaximumTtlMs?: number;
+  authorizationTimeoutMs?: number;
+  maxTabsPerProject?: number;
+  operationTimeoutMs?: number;
+  quiescenceTimeoutMs?: number;
+  terminationGraceMs?: number;
+  terminationForceMs?: number;
+  auditTimeoutMs?: number;
+  confinementProbeTimeoutMs?: number;
+  idleRetirementMs?: number;
+  maxFrameBytes?: number;
+  frameAcknowledgementTimeoutMs?: number;
+  egress?: Omit<IBrowserEgressProxyOptions, 'projectId'>;
+  artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
+}
+
+export interface IBrowserRuntimeTabState {
+  id: string;
+  url: string;
+  title: string;
+  active: boolean;
+  status: 'open' | 'crashed';
+  generation: number;
+  appliedViewportRevision: number;
+  streaming: boolean;
+}
+
+export interface IBrowserRuntimeState {
+  status: 'stopped' | 'starting' | 'running' | 'stopping';
+  activeTabId: string | null;
+  viewportRevision: number;
+  viewport: {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+  };
+  tabs: IBrowserRuntimeTabState[];
+  lastError?: {
+    code: string;
+    fatal: boolean;
+    tabId?: string;
+  };
+}
+
+export interface IBrowserArtifactMetadata {
+  artifactId: string;
+  projectId: string;
+  mimeType: string;
+  size: number;
+  createdAt: number;
+  expiresAt: number;
+}
+
+export interface IBrowserArtifactStoreOptions {
+  rootDirectory: string;
+  maxFileBytes?: number;
+  maxArtifactsPerProject?: number;
+  maxProjectBytes?: number;
+  maxProjects?: number;
+  maxTotalArtifacts?: number;
+  maxTotalBytes?: number;
+  artifactTtlMs?: number;
+  now?: () => number;
+}
+
+export interface IBrowserNavigateAction {
+  action: 'navigate';
+  url: string;
+  tabId?: string;
+  timeoutMs?: number;
+}
+
+export interface IBrowserSnapshotAction {
+  action: 'snapshot';
+  tabId?: string;
+  maxCharacters?: number;
+}
+
+export interface IBrowserScreenshotAction {
+  action: 'screenshot';
+  tabId?: string;
+  format?: 'jpeg' | 'png';
+  quality?: number;
+}
+
+export interface IBrowserClickAction {
+  action: 'click';
+  selector: string;
+  tabId?: string;
+  timeoutMs?: number;
+}
+
+export interface IBrowserFillAction {
+  action: 'fill';
+  selector: string;
+  text: string;
+  tabId?: string;
+  timeoutMs?: number;
+}
+
+export interface IBrowserPressAction {
+  action: 'press';
+  selector: string;
+  key: string;
+  tabId?: string;
+  timeoutMs?: number;
+}
+
+export type TBrowserAgentAction =
+  | IBrowserNavigateAction
+  | IBrowserSnapshotAction
+  | IBrowserScreenshotAction
+  | IBrowserClickAction
+  | IBrowserFillAction
+  | IBrowserPressAction;
+
+export interface IBrowserActionStateResult {
+  action: 'navigate' | 'click' | 'fill' | 'press';
+  state: IBrowserRuntimeState;
+}
+
+export interface IBrowserObservationResult {
+  action: 'snapshot';
+  tabId: string;
+  url: string;
+  title: string;
+  text: string;
+  truncated: boolean;
+  state: IBrowserRuntimeState;
+}
+
+export interface IBrowserScreenshotResult {
+  action: 'screenshot';
+  artifact: IBrowserArtifactMetadata;
+}
+
+export type TBrowserAgentActionResult =
+  | IBrowserActionStateResult
+  | IBrowserObservationResult
+  | IBrowserScreenshotResult;
+
+export type TBrowserRuntimeEvent =
+  | { type: 'state'; state: IBrowserRuntimeState }
+  | { type: 'error'; error: { code: string; fatal: boolean; tabId?: string } }
+  | { type: 'frame'; frame: plugins.smartpuppeteer.ILiveBrowserFrame };
+
+export interface IBrowserRuntimeOperationOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  onOperationStarted?(operationId: string): void;
+}
+
+export interface IBrowserRuntimeFrameSubscription {
+  close(): Promise<void>;
+}
+
+export type TBrowserDnsResolver = (
+  hostname: string,
+  options: { all: true; verbatim: true; signal: AbortSignal },
+) => Promise<plugins.dns.LookupAddress[]>;
+
+export interface IBrowserEgressConnectionOptions {
+  address: string;
+  family: 4 | 6;
+  port: number;
+  hostname: string;
+  signal: AbortSignal;
+}
+
+export type TBrowserEgressConnector = (
+  options: IBrowserEgressConnectionOptions,
+) => plugins.net.Socket;
+
+export interface IBrowserEgressProxyOptions {
+  projectId: string;
+  allowedPorts?: number[];
+  maxConnections?: number;
+  maxActiveRequests?: number;
+  maxHeaderBytes?: number;
+  connectTimeoutMs?: number;
+  idleTimeoutMs?: number;
+  tunnelLifetimeMs?: number;
+  requestTimeoutMs?: number;
+  maxRequestBytes?: number;
+  maxResponseBytes?: number;
+  maxTunnelBytes?: number;
+  resolver?: TBrowserDnsResolver;
+  connector?: TBrowserEgressConnector;
+}
+
+export interface IBrowserEgressProxyStats {
+  ordinaryRequests: number;
+  upgradeRequests: number;
+  connectRequests: number;
+  rejectedRequests: number;
+  activeConnections: number;
+}
+
+export interface IAttachTrustedFramedPeerOptions {
+  peerId: string;
+  scopeId: string;
+  sessionId: string;
+  readable: plugins.stream.Readable;
+  writable: plugins.stream.Writable;
+}
+
+export interface IBrowserRuntimeFramedClientOptions {
+  scopeId: string;
+  sessionId: string;
+  readable: plugins.stream.Readable;
+  writable: plugins.stream.Writable;
+  maxFrameBytes?: number;
+  maxPendingRequests?: number;
+  requestTimeoutMs?: number;
+}
+
+export interface IBrowserRuntimeMcpOptions {
+  authenticateMcpRequest(request: Request): Promise<{ peerId: string }>;
+  trustedOrigins?: string[];
+  allowedHosts?: string[];
+  allowMissingOrigin?: boolean;
+  maxRequestBytes?: number;
+  maxToolResultBytes?: number;
+}
+
+export interface IBrowserRuntimeFlexToolProviderOptions<TScope> {
+  client: import('./classes.framed.js').BrowserRuntimeFramedClient;
+  resolveCapability(
+    context: plugins.flexharness.IFlexToolProviderContext<TScope>,
+  ): Promise<IResolvedBrowserFlexCapability> | IResolvedBrowserFlexCapability;
+}

package/ts/internal.testing.ts

@@ -0,0 +1,18 @@
+import type * as plugins from './plugins.js';
+import type {
+  IBrowserConfinementProbeContext,
+  IBrowserRuntimeOptions,
+  IBrowserRuntimeEnvironment,
+  ILiveBrowserSessionLike,
+} from './interfaces.js';
+
+export const browserRuntimeTesting = Symbol('browserRuntimeTesting');
+
+export interface IBrowserRuntimeTestingOptions extends IBrowserRuntimeOptions {
+  [browserRuntimeTesting]: true;
+  environment: IBrowserRuntimeEnvironment;
+  sessionFactory(
+    options: plugins.smartpuppeteer.ILiveBrowserSessionOptions,
+  ): ILiveBrowserSessionLike;
+  confinementProbe(context: IBrowserConfinementProbeContext): Promise<void>;
+}