@modelprofile.com/browser-runtime 1.0.1 → 2.1.0

package/ts/errors.ts

@@ -1,6 +1,7 @@
 export type TBrowserRuntimeErrorCode =
   | 'ABORTED'
   | 'AUTHORIZATION_DENIED'
+  | 'ATTACHMENT_CONFLICT'
   | 'BUSY'
   | 'CAPABILITY_EXPIRED'
   | 'CAPABILITY_INVALID'
@@ -14,24 +15,29 @@ export type TBrowserRuntimeErrorCode =
   | 'NOT_RUNNING'
   | 'PROTOCOL_ERROR'
   | 'QUOTA_EXCEEDED'
+  | 'RESOURCE_NOT_FOUND'
+  | 'RESOURCE_RETIRED'
   | 'TIMEOUT';
 
 const publicMessages: Record<TBrowserRuntimeErrorCode, string> = {
   ABORTED: 'The operation was aborted.',
   AUTHORIZATION_DENIED: 'Capability authorization was denied.',
-  BUSY: 'The browser project is busy.',
+  ATTACHMENT_CONFLICT: 'The attachment binding conflicts with the current revision.',
+  BUSY: 'The browser resource 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.',
+  FENCED: 'The browser resource 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.',
+  RESOURCE_NOT_FOUND: 'The browser resource is not registered.',
+  RESOURCE_RETIRED: 'The browser resource has been retired.',
   TIMEOUT: 'The operation timed out.',
 };
 

package/ts/index.ts

@@ -10,37 +10,49 @@ 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 { TAcquireBrowserRuntimeLeaseOptions } from './classes.runtime.js';
 export type { TBrowserRuntimeErrorCode } from './errors.js';
 export type {
   IAttachTrustedFramedPeerOptions,
+  IApplyBrowserAttachmentBindingRequest,
+  IBrowserAttachmentBinding,
   IBrowserActionStateResult,
   IBrowserArtifactMetadata,
   IBrowserArtifactStoreOptions,
-  IBrowserCapabilityAuthorizationRequest,
-  IBrowserCapabilityDescriptor,
+  IBrowserMcpAuthenticatedBinding,
+  TBrowserCapabilityAuthorizationRequest,
+  TBrowserCapabilityDescriptor,
   IBrowserClickAction,
   IBrowserEgressConnectionOptions,
   IBrowserEgressProxyOptions,
   IBrowserEgressProxyStats,
+  IBrowserFlexCapabilityBinding,
+  IBrowserFlexSessionId,
   IBrowserFillAction,
   IBrowserNavigateAction,
   IBrowserObservationResult,
+  IBrowserOpenCodeSessionId,
   IBrowserPressAction,
-  IBrowserRuntimeAuditEvent,
+  TBrowserRuntimeAuditEvent,
+  TBrowserRuntimeOperationIdentity,
   IBrowserRuntimeFlexToolProviderOptions,
   IBrowserRuntimeFrameSubscription,
   IBrowserRuntimeFramedClientOptions,
   IBrowserRuntimeMcpOptions,
   IBrowserRuntimeOperationOptions,
   IBrowserRuntimeOptions,
+  IBrowserResourceKey,
+  IBrowserResourceRegistration,
   IBrowserRuntimeState,
   IBrowserRuntimeTabState,
   IBrowserScreenshotAction,
   IBrowserScreenshotResult,
   IBrowserSnapshotAction,
-  IIssueBrowserCapabilityRequest,
-  IIssuedBrowserCapability,
+  ICreateBrowserResourceRequest,
+  TIssueBrowserCapabilityRequest,
+  TIssuedBrowserCapability,
+  TQualifiedBrowserSessionId,
+  IRegisterBrowserResourceRequest,
   IResolvedBrowserFlexCapability,
   TBrowserActorRole,
   TBrowserAgentAction,
@@ -48,5 +60,6 @@ export type {
   TBrowserCapabilitySource,
   TBrowserDnsResolver,
   TBrowserEgressConnector,
+  TBrowserHarnessId,
   TBrowserRuntimeEvent,
 } from './interfaces.js';

package/ts/interfaces.ts

@@ -1,49 +1,131 @@
 import type * as plugins from './plugins.js';
+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 interface IBrowserCapabilityAuthorizationRequest {
+export interface IBrowserOpenCodeSessionId {
+  harnessId: 'opencode';
+  nativeId: string;
+}
+
+export interface IBrowserFlexSessionId {
+  harnessId: 'flex';
+  nativeId: string;
+}
+
+export type TQualifiedBrowserSessionId = IBrowserOpenCodeSessionId | IBrowserFlexSessionId;
+
+export interface IBrowserResourceKey {
   projectId: string;
+  browserResourceId: string;
+}
+
+export interface IBrowserAttachmentBinding {
+  attachmentAuthorityId: string;
+  attachmentRevision: number;
+  sessionId: TQualifiedBrowserSessionId | null;
+}
+
+export interface ICreateBrowserResourceRequest {
+  projectId: string;
+  attachmentBinding: IBrowserAttachmentBinding;
+}
+
+export interface IRegisterBrowserResourceRequest extends IBrowserResourceKey {
+  attachmentBinding: IBrowserAttachmentBinding;
+}
+
+export interface IApplyBrowserAttachmentBindingRequest extends IBrowserResourceKey {
+  attachmentBinding: IBrowserAttachmentBinding;
+}
+
+export interface IBrowserResourceRegistration extends IBrowserResourceKey {
+  registeredAt: number;
+  attachmentBinding: IBrowserAttachmentBinding;
+  incarnationStatus: 'absent' | 'running' | 'fenced';
+  incarnationGeneration: number;
+  retirementPending: boolean;
+}
+
+export interface IBrowserCapabilityBindingBase extends IBrowserResourceKey {
+  attachmentAuthorityId: string;
+  attachmentRevision: number;
   actorId: string;
-  role: TBrowserActorRole;
   peerId: string;
-  source: TBrowserCapabilitySource;
-  scopeId?: string;
-  sessionId?: string;
 }
 
-export interface IIssueBrowserCapabilityRequest extends IBrowserCapabilityAuthorizationRequest {
+export interface IBrowserHumanCapabilityBinding extends IBrowserCapabilityBindingBase {
+  role: 'human';
+  source: 'human';
+  sessionId?: never;
+  scopeId?: never;
+  channelId?: never;
+}
+
+export interface IBrowserFlexCapabilityBinding extends IBrowserCapabilityBindingBase {
+  role: 'agent';
+  source: 'flex';
+  sessionId: IBrowserFlexSessionId;
+  scopeId: string;
+  channelId: string;
+}
+
+export interface IBrowserMcpCapabilityBinding extends IBrowserCapabilityBindingBase {
+  role: 'agent';
+  source: 'mcp';
+  sessionId: IBrowserOpenCodeSessionId;
+  scopeId?: never;
+  channelId?: never;
+}
+
+export type TBrowserCapabilityAuthorizationRequest =
+  | IBrowserHumanCapabilityBinding
+  | IBrowserFlexCapabilityBinding
+  | IBrowserMcpCapabilityBinding;
+
+export type TIssueBrowserCapabilityRequest = TBrowserCapabilityAuthorizationRequest & {
   expiresInMs?: number;
   disconnect?: (signal: AbortSignal) => Promise<void> | void;
-}
+};
 
-export interface IBrowserCapabilityDescriptor extends IBrowserCapabilityAuthorizationRequest {
+export type TBrowserCapabilityDescriptor = TBrowserCapabilityAuthorizationRequest & {
   capabilityId: string;
   expiresAt: number;
-}
+};
 
-export interface IIssuedBrowserCapability extends IBrowserCapabilityDescriptor {
+export type TIssuedBrowserCapability = TBrowserCapabilityDescriptor & {
   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;
-}
+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>;
@@ -120,9 +202,9 @@ export interface ILiveBrowserSessionLike {
   ): Promise<void>;
 }
 
-export interface IBrowserConfinementProbeContext {
+export interface IBrowserConfinementProbeContext extends IBrowserResourceKey {
   session: ILiveBrowserSessionLike;
-  proxy: import('./classes.egressproxy.js').BrowserEgressProxy;
+  proxy: BrowserEgressProxy;
   signal: AbortSignal;
 }
 
@@ -134,27 +216,36 @@ export interface IBrowserRuntimeEnvironment {
 export interface IBrowserRuntimeOptions {
   runtimeDirectory: string;
   authorizeCapability(
-    request: IBrowserCapabilityAuthorizationRequest,
+    request: TBrowserCapabilityAuthorizationRequest,
     signal: AbortSignal,
   ): Promise<boolean> | boolean;
-  audit?(event: IBrowserRuntimeAuditEvent, signal: AbortSignal): Promise<void> | void;
-  maxProjectSlots?: number;
+  beforeOperation?(
+    operation: TBrowserRuntimeOperationIdentity,
+    signal: AbortSignal,
+  ): Promise<void> | void;
+  audit?(event: TBrowserRuntimeAuditEvent, signal: AbortSignal): Promise<void> | void;
+  maxResources?: number;
+  maxResourcesPerProject?: number;
+  maxRunningResources?: number;
+  maxRunningResourcesPerProject?: number;
   maxCapabilities?: number;
+  maxCapabilitiesPerResource?: number;
   maxCapabilitiesPerProject?: number;
   capabilityDefaultTtlMs?: number;
   capabilityMaximumTtlMs?: number;
   authorizationTimeoutMs?: number;
-  maxTabsPerProject?: number;
+  beforeOperationTimeoutMs?: number;
+  maxTabsPerResource?: number;
   operationTimeoutMs?: number;
   quiescenceTimeoutMs?: number;
   terminationGraceMs?: number;
   terminationForceMs?: number;
   auditTimeoutMs?: number;
   confinementProbeTimeoutMs?: number;
-  idleRetirementMs?: number;
+  idleTerminationMs?: number;
   maxFrameBytes?: number;
   frameAcknowledgementTimeoutMs?: number;
-  egress?: Omit<IBrowserEgressProxyOptions, 'projectId'>;
+  egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
   artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }
 
@@ -186,9 +277,8 @@ export interface IBrowserRuntimeState {
   };
 }
 
-export interface IBrowserArtifactMetadata {
+export interface IBrowserArtifactMetadata extends IBrowserResourceKey {
   artifactId: string;
-  projectId: string;
   mimeType: string;
   size: number;
   createdAt: number;
@@ -198,6 +288,8 @@ export interface IBrowserArtifactMetadata {
 export interface IBrowserArtifactStoreOptions {
   rootDirectory: string;
   maxFileBytes?: number;
+  maxArtifactsPerResource?: number;
+  maxResourceBytes?: number;
   maxArtifactsPerProject?: number;
   maxProjectBytes?: number;
   maxProjects?: number;
@@ -315,8 +407,7 @@ export type TBrowserEgressConnector = (
   options: IBrowserEgressConnectionOptions,
 ) => plugins.net.Socket;
 
-export interface IBrowserEgressProxyOptions {
-  projectId: string;
+export interface IBrowserEgressProxyOptions extends IBrowserResourceKey {
   allowedPorts?: number[];
   maxConnections?: number;
   maxActiveRequests?: number;
@@ -340,17 +431,24 @@ export interface IBrowserEgressProxyStats {
   activeConnections: number;
 }
 
-export interface IAttachTrustedFramedPeerOptions {
-  peerId: string;
-  scopeId: string;
-  sessionId: string;
+export interface IAttachTrustedFramedPeerOptions
+extends Omit<
+  IBrowserFlexCapabilityBinding,
+  'role' | 'source'
+> {
+  role: 'agent';
+  source: 'flex';
   readable: plugins.stream.Readable;
   writable: plugins.stream.Writable;
 }
 
-export interface IBrowserRuntimeFramedClientOptions {
-  scopeId: string;
-  sessionId: string;
+export interface IBrowserRuntimeFramedClientOptions
+extends Omit<
+  IBrowserFlexCapabilityBinding,
+  'role' | 'source'
+> {
+  role: 'agent';
+  source: 'flex';
   readable: plugins.stream.Readable;
   writable: plugins.stream.Writable;
   maxFrameBytes?: number;
@@ -358,8 +456,16 @@ export interface IBrowserRuntimeFramedClientOptions {
   requestTimeoutMs?: number;
 }
 
+export interface IBrowserMcpAuthenticatedBinding extends IBrowserCapabilityBindingBase {
+  role: 'agent';
+  source: 'mcp';
+  sessionId: IBrowserOpenCodeSessionId;
+  scopeId?: never;
+  channelId?: never;
+}
+
 export interface IBrowserRuntimeMcpOptions {
-  authenticateMcpRequest(request: Request): Promise<{ peerId: string }>;
+  authenticateMcpRequest(request: Request): Promise<IBrowserMcpAuthenticatedBinding>;
   trustedOrigins?: string[];
   allowedHosts?: string[];
   allowMissingOrigin?: boolean;
@@ -368,7 +474,7 @@ export interface IBrowserRuntimeMcpOptions {
 }
 
 export interface IBrowserRuntimeFlexToolProviderOptions<TScope> {
-  client: import('./classes.framed.js').BrowserRuntimeFramedClient;
+  client: BrowserRuntimeFramedClient;
   resolveCapability(
     context: plugins.flexharness.IFlexToolProviderContext<TScope>,
   ): Promise<IResolvedBrowserFlexCapability> | IResolvedBrowserFlexCapability;

package/ts/internal.testing.ts

@@ -1,6 +1,7 @@
 import type * as plugins from './plugins.js';
 import type {
   IBrowserConfinementProbeContext,
+  IBrowserRuntimeFramedClientOptions,
   IBrowserRuntimeOptions,
   IBrowserRuntimeEnvironment,
   ILiveBrowserSessionLike,
@@ -15,4 +16,15 @@ export interface IBrowserRuntimeTestingOptions extends IBrowserRuntimeOptions {
     options: plugins.smartpuppeteer.ILiveBrowserSessionOptions,
   ): ILiveBrowserSessionLike;
   confinementProbe(context: IBrowserConfinementProbeContext): Promise<void>;
+  beforeLeasePublication?(): Promise<void>;
+  beforeIdleTermination?(): Promise<void>;
+  beforeFrameFailureTermination?(): Promise<void>;
+  afterFrameFailureFence?(): Promise<void>;
+  beforeFramedPeerLeasePublication?(): Promise<void>;
+}
+
+export interface IBrowserRuntimeFramedClientTestingOptions
+extends IBrowserRuntimeFramedClientOptions {
+  [browserRuntimeTesting]: true;
+  afterAcquireResponse?(): Promise<void>;
 }

package/ts/mcp.ts

@@ -2,7 +2,10 @@ import * as plugins from './plugins.js';
 import type { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
 import { BrowserRuntimeError } from './errors.js';
 import { commitinfo } from './00_commitinfo_data.js';
-import type { IBrowserRuntimeMcpOptions } from './interfaces.js';
+import type {
+  IBrowserMcpAuthenticatedBinding,
+  IBrowserRuntimeMcpOptions,
+} from './interfaces.js';
 import { validateAgentActionResult } from './actions.js';
 import {
   validateBoundedString,
@@ -51,19 +54,17 @@ export const createBrowserRuntimeMcpHttpHandler = (
     context: plugins.smartmcp.ISmartMcpToolContext,
     action: (lease: BrowserRuntimeLease, signal: AbortSignal) => Promise<T>,
   ): Promise<T> => {
-    const peerId = validateBoundedString(context.authInfo?.clientId, 'peerId', 1, 128);
+    const binding = parseMcpAuthBinding(context.authInfo?.scopes);
     const capabilityToken = parseBearerToken(context.request);
     const signal = AbortSignal.any([context.extra.signal, context.request.signal]);
     signal.throwIfAborted();
-    const descriptor = runtime.authorizeCapability(capabilityToken, peerId, 'agent', 'mcp');
+    const descriptor = runtime.authorizeCapability(capabilityToken, binding);
     if (descriptor.capabilityId !== context.authInfo?.token) {
       throw new BrowserRuntimeError('CAPABILITY_INVALID');
     }
     const lease = await runtime.acquireLease({
       capabilityToken,
-      peerId,
-      expectedRole: 'agent',
-      expectedSource: 'mcp',
+      ...binding,
       signal,
     });
     try {
@@ -203,22 +204,16 @@ export const createBrowserRuntimeMcpHttpHandler = (
     maxToolResultBytes,
     redactError: () => 'Browser tool execution failed.',
     authorize: async ({ request }) => {
-      let peerId: string;
       let capabilityToken: string;
       try {
         const authentication = await options.authenticateMcpRequest(request);
-        peerId = validateBoundedString(authentication?.peerId, 'peerId', 1, 128);
+        const binding = validateMcpBinding(authentication);
         capabilityToken = parseBearerToken(request);
-        const descriptor = runtime.authorizeCapability(
-          capabilityToken,
-          peerId,
-          'agent',
-          'mcp',
-        );
+        const descriptor = runtime.authorizeCapability(capabilityToken, binding);
         return {
           token: descriptor.capabilityId,
-          clientId: peerId,
-          scopes: ['browser'],
+          clientId: binding.peerId,
+          scopes: [serializeMcpAuthBinding(binding)],
           expiresAt: descriptor.expiresAt,
         };
       } catch {
@@ -228,3 +223,59 @@ export const createBrowserRuntimeMcpHttpHandler = (
     tools,
   });
 };
+
+const validateMcpBinding = (value: unknown): IBrowserMcpAuthenticatedBinding => {
+  if (!value || typeof value !== 'object') throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  const binding = value as Record<string, unknown>;
+  if (binding.role !== 'agent' || binding.source !== 'mcp') {
+    throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  }
+  const session = binding.sessionId as Record<string, unknown> | undefined;
+  if (session?.harnessId !== 'opencode') throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  return {
+    projectId: validateBoundedString(binding.projectId, 'projectId', 1, 256),
+    browserResourceId: validateBoundedString(
+      binding.browserResourceId,
+      'browserResourceId',
+      16,
+      256,
+    ),
+    attachmentAuthorityId: validateBoundedString(
+      binding.attachmentAuthorityId,
+      'attachmentAuthorityId',
+      1,
+      256,
+    ),
+    attachmentRevision: validateInteger(
+      binding.attachmentRevision,
+      'attachmentRevision',
+      0,
+      Number.MAX_SAFE_INTEGER,
+    ),
+    actorId: validateBoundedString(binding.actorId, 'actorId', 1, 256),
+    role: 'agent',
+    peerId: validateBoundedString(binding.peerId, 'peerId', 1, 256),
+    source: 'mcp',
+    sessionId: {
+      harnessId: 'opencode',
+      nativeId: validateBoundedString(session.nativeId, 'sessionId.nativeId', 1, 256),
+    },
+  };
+};
+
+const serializeMcpAuthBinding = (
+  binding: IBrowserMcpAuthenticatedBinding,
+): string => plugins.Buffer.from(JSON.stringify(binding), 'utf8').toString('base64url');
+
+const parseMcpAuthBinding = (scopes: string[] | undefined): IBrowserMcpAuthenticatedBinding => {
+  if (!Array.isArray(scopes) || scopes.length !== 1) {
+    throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  }
+  try {
+    return validateMcpBinding(JSON.parse(
+      plugins.Buffer.from(scopes[0]!, 'base64url').toString('utf8'),
+    ));
+  } catch {
+    throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  }
+};