@opengeni/sdk 0.52.1 → 0.57.0

package/src/interaction.ts

@@ -11,6 +11,15 @@ export const BROWSER_FRAME_MAX_BYTES = 24 * 1024 * 1024;
 export const BROWSER_FRAME_MAX_DIMENSION = 32_768;
 export const BROWSER_FRAME_MAX_PIXELS = 100_000_000;
 
+/** Latest-wins invalidation cursor for workspace Browser/Computer resources. */
+export type WorkspaceInteractionRevisionEvent = {
+  workspaceId: string;
+  sequence: number;
+  revision: number;
+  type: "workspace.interaction.changed";
+  occurredAt: string;
+};
+
 export type InteractionJsonValue =
   | null
   | string
@@ -103,6 +112,7 @@ export type BrowserSessionCapabilities = {
   downloads: boolean;
   uploads: boolean;
   clipboard: boolean;
+  permissions: boolean;
   diagnostics: boolean;
   rawCdp: boolean;
   linkedComputer: boolean;
@@ -135,6 +145,353 @@ export type BrowserSession = {
   failureCode: string | null;
 };
 
+export type BrowserClipboard = {
+  browserSessionId: string;
+  controllerGeneration: string;
+  revision: number;
+  text: string;
+  source: "empty" | "write" | "clear" | "copy" | "paste";
+  sourceTargetId: string | null;
+  updatedAt: string | null;
+};
+
+export type InteractionCredentialAuthorityRef = {
+  connectionId: string;
+  connectionSubjectId: string | null;
+  providerDomain: string;
+};
+
+export type NetworkRouteConfiguration =
+  | { kind: "direct" }
+  | {
+      kind: "proxy";
+      protocol: "http" | "https" | "socks5";
+      host: string;
+      port: number;
+      credential: InteractionCredentialAuthorityRef | null;
+    }
+  | {
+      kind: "managed";
+      providerId: string;
+      routeId: string;
+      egressClass: "datacenter" | "residential" | "isp";
+      region: string | null;
+      credential: InteractionCredentialAuthorityRef | null;
+    }
+  | { kind: "tunnel"; placement: InteractionPlacement; tunnelId: string };
+
+export type NetworkRouteConsistency = {
+  dns: "placement" | "proxy" | "provider";
+  expectedPublicIp: string | null;
+  expectedRegion: string | null;
+  locale: string | null;
+  timezone: string | null;
+  geolocation: {
+    latitude: number;
+    longitude: number;
+    accuracyMeters: number;
+  } | null;
+  webRtc: "default" | "disable_non_proxied_udp" | "proxy_only";
+  stability: "session" | "sticky" | "persistent";
+};
+
+export type NetworkRoute = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  name: string;
+  status: "active" | "archived";
+  configuration: NetworkRouteConfiguration;
+  consistency: NetworkRouteConsistency;
+  version: number;
+  createdBySubjectId: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type NetworkRouteListResponse = { revision: number; routes: NetworkRoute[] };
+export type CreateNetworkRouteRequest = {
+  operationId: string;
+  name: string;
+  configuration: NetworkRouteConfiguration;
+  consistency: NetworkRouteConsistency;
+};
+export type UpdateNetworkRouteRequest = {
+  operationId: string;
+  expectedVersion: number;
+  name?: string | undefined;
+  status?: "active" | "archived" | undefined;
+  configuration?: NetworkRouteConfiguration | undefined;
+  consistency?: NetworkRouteConsistency | undefined;
+};
+export type NetworkRouteMutationResponse = {
+  route: NetworkRoute;
+  operationId: string;
+  replayed: boolean;
+};
+
+export type SiteAuthFieldPurpose = "identifier" | "password" | "secret" | "totp";
+export type SiteAuthAuthority =
+  | {
+      id: string;
+      kind: "connection_fields";
+      label: string;
+      credential: InteractionCredentialAuthorityRef;
+      fields: Array<{
+        id: string;
+        purpose: SiteAuthFieldPurpose;
+        credentialKey: string;
+        digits?: number | undefined;
+        periodSeconds?: number | undefined;
+        algorithm?: "sha1" | "sha256" | "sha512" | undefined;
+      }>;
+    }
+  | {
+      id: string;
+      kind: "human";
+      label: string;
+      fields: Array<{ id: string; purpose: SiteAuthFieldPurpose }>;
+    }
+  | {
+      id: string;
+      kind: "external_provider";
+      label: string;
+      adapterId: string;
+      connectionId: string;
+      credential: InteractionCredentialAuthorityRef | null;
+    };
+
+export type SiteAuthMethod = {
+  id: string;
+  kind: "password" | "sso" | "magic_link" | "passkey" | "external";
+  label: string;
+  authorityIds: string[];
+};
+
+export type SiteAuthHealthPolicy = {
+  mode: "on_use" | "maintained";
+  intervalSeconds: number | null;
+  automaticRepair: boolean;
+};
+
+export type SiteAuthConnectionConfiguration = {
+  name: string;
+  accountLabel: string;
+  origins: string[];
+  loginUrl: string | null;
+  verificationUrlPrefixes: string[];
+  authorities: SiteAuthAuthority[];
+  methods: SiteAuthMethod[];
+  preferredIdentityId: string | null;
+  preferredPlacement: InteractionPlacement | null;
+  preferredNetworkRouteId: string | null;
+  healthPolicy: SiteAuthHealthPolicy;
+};
+
+export type SiteAuthConnection = SiteAuthConnectionConfiguration & {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  status: "active" | "archived";
+  verificationState: "unknown" | "verified" | "needs_repair" | "failed";
+  lastVerifiedAt: string | null;
+  lastVerifiedUrl: string | null;
+  lastCheckedAt: string | null;
+  nextCheckAt: string | null;
+  maintenance: {
+    action: "health_check" | "repair";
+    sessionId: string | null;
+    dueAt: string;
+    startedAt: string | null;
+  } | null;
+  repairCode: string | null;
+  version: number;
+  createdBySubjectId: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SiteAuthConnectionListResponse = {
+  revision: number;
+  connections: SiteAuthConnection[];
+};
+export type CreateSiteAuthConnectionRequest = SiteAuthConnectionConfiguration & {
+  operationId: string;
+};
+export type UpdateSiteAuthConnectionRequest = Partial<SiteAuthConnectionConfiguration> & {
+  operationId: string;
+  expectedVersion: number;
+  status?: "active" | "archived" | undefined;
+};
+export type SiteAuthConnectionMutationResponse = {
+  connection: SiteAuthConnection;
+  operationId: string;
+  replayed: boolean;
+};
+
+export type AuthRun = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  siteAuthConnectionId: string;
+  browserSessionId: string;
+  targetId: string;
+  controllerGeneration: string;
+  targetGeneration: string;
+  documentGeneration: string | null;
+  purpose: "authenticate" | "health_check" | "repair";
+  methodId: string | null;
+  authorityId: string | null;
+  state:
+    | "discovering"
+    | "awaiting_choice"
+    | "awaiting_secret"
+    | "awaiting_external_action"
+    | "working"
+    | "verified"
+    | "failed"
+    | "cancelled";
+  choices: Array<{ id: string; label: string; methodId: string }>;
+  pendingFields: Array<{ id: string; label: string; purpose: SiteAuthFieldPurpose }>;
+  externalAction: {
+    kind: "push" | "security_key" | "passkey" | "device" | "human" | "other";
+    label: string;
+    expiresAt: string | null;
+  } | null;
+  interventionId: string | null;
+  verifiedUrl: string | null;
+  failureCode: string | null;
+  version: number;
+  operationId: string;
+  createdBySubjectId: string;
+  createdAt: string;
+  updatedAt: string;
+  settledAt: string | null;
+};
+
+export type AuthRunListResponse = { runs: AuthRun[] };
+export type AuthRunMutationResponse = { run: AuthRun; operationId: string; replayed: boolean };
+export type StartAuthRunRequest = {
+  operationId: string;
+  siteAuthConnectionId: string;
+  targetId: string;
+  expectedTargetGeneration: string;
+  expectedDocumentGeneration: string | null;
+  purpose?: "authenticate" | "health_check" | "repair" | undefined;
+  methodId?: string | undefined;
+  authorityId?: string | undefined;
+};
+export type ReportAuthRunRequest = {
+  operationId: string;
+  expectedVersion: number;
+  methodId?: string | undefined;
+  authorityId?: string | undefined;
+  state:
+    | "awaiting_choice"
+    | "awaiting_secret"
+    | "awaiting_external_action"
+    | "working"
+    | "failed"
+    | "cancelled";
+  choices?: AuthRun["choices"] | undefined;
+  pendingFields?: AuthRun["pendingFields"] | undefined;
+  externalAction?: AuthRun["externalAction"] | undefined;
+  failureCode?: string | null | undefined;
+};
+export type ProtectedAuthFillRequest = {
+  operationId: string;
+  expectedVersion: number;
+  expectedTargetGeneration: string;
+  expectedDocumentGeneration: string | null;
+  expectedFrameId: string | null;
+  authorityId: string;
+  fields: Array<{ fieldId: string; locator: BrowserLocator }>;
+  submit:
+    | { type: "none" }
+    | { type: "click"; locator: BrowserLocator }
+    | { type: "press"; key: string; locator?: BrowserLocator | undefined };
+};
+export type ProtectedAuthFillResponse = {
+  run: AuthRun;
+  status: "submitted" | "working" | "needs_human" | "stale" | "failed";
+  operationId: string;
+  replayed: boolean;
+};
+export type ExternalAuthRunRequest = {
+  operationId: string;
+  expectedVersion: number;
+  action: "start" | "poll";
+};
+export type ExternalAuthRunResponse = {
+  run: AuthRun;
+  status: "working" | "needs_human" | "ready_to_verify" | "failed";
+  operationId: string;
+  replayed: boolean;
+};
+export type ExternalAuthInteractiveRequest = {
+  operationId: string;
+  expectedVersion: number;
+};
+export type ExternalAuthInteractiveResponse = {
+  authRunId: string;
+  url: string;
+  expiresAt: string | null;
+};
+export type VerifyAuthRunRequest = { operationId: string; expectedVersion: number };
+
+export type InteractionIntervention = {
+  id: string;
+  accountId: string;
+  workspaceId: string;
+  resourceKind: "browser_session" | "computer_session";
+  resourceId: string;
+  targetId: string;
+  controllerGeneration: string;
+  targetGeneration: string;
+  documentGeneration: string | null;
+  kind: "manual_login" | "mfa" | "external_action" | "confirmation" | "other";
+  reason: string;
+  status: "open" | "completed" | "dismissed" | "expired" | "cancelled";
+  authRunId: string | null;
+  originatingSessionId: string;
+  originatingTurnId: string | null;
+  originatingAttemptId: string | null;
+  originatingToolOperationId: string | null;
+  responseActorSubjectId: string | null;
+  version: number;
+  operationId: string;
+  expiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+  settledAt: string | null;
+};
+export type InteractionInterventionListResponse = {
+  interventions: InteractionIntervention[];
+};
+export type CreateInteractionInterventionRequest = {
+  operationId: string;
+  resourceKind: "browser_session" | "computer_session";
+  resourceId: string;
+  targetId: string;
+  expectedControllerGeneration: string;
+  expectedTargetGeneration: string;
+  expectedDocumentGeneration: string | null;
+  kind: InteractionIntervention["kind"];
+  reason: string;
+  authRunId?: string | undefined;
+  expiresInSeconds?: number | undefined;
+};
+export type ResolveInteractionInterventionRequest = {
+  operationId: string;
+  expectedVersion: number;
+  outcome: "completed" | "dismissed";
+};
+export type InteractionInterventionMutationResponse = {
+  intervention: InteractionIntervention;
+  operationId: string;
+  replayed: boolean;
+};
+
 export type BrowserIdentityStatus = "active" | "archived";
 export type BrowserRevisionComponentKind =
   | "chromium_profile"
@@ -185,6 +542,7 @@ export type BrowserIdentity = {
   workspaceId: string;
   name: string;
   status: BrowserIdentityStatus;
+  version: number;
   defaultRevisionId: string | null;
   headGeneration: number;
   revisionCount: number;
@@ -208,6 +566,14 @@ export type CreateBrowserIdentityRequest = {
   name: string;
 };
 
+export type UpdateBrowserIdentityRequest = {
+  operationId: string;
+  expectedVersion: number;
+  name?: string | undefined;
+  status?: BrowserIdentityStatus | undefined;
+  defaultRevisionId?: string | undefined;
+};
+
 export type BrowserIdentityMutationResponse = {
   identity: BrowserIdentity;
   operationId: string;
@@ -242,6 +608,51 @@ export type BrowserTarget = {
   createdAt: string;
 };
 
+export type BrowserDownloadStatus =
+  | "in_progress"
+  | "completed"
+  | "cancelled"
+  | "failed"
+  | "unavailable";
+
+/** One browser-produced file. Its bytes remain private to the exact browser
+ * controller until an explicit save publishes them into the workspace. */
+export type BrowserDownload = {
+  id: string;
+  browserSessionId: string;
+  controllerGeneration: string;
+  targetId: string | null;
+  filename: string;
+  status: BrowserDownloadStatus;
+  receivedBytes: number;
+  totalBytes: number | null;
+  sha256: string | null;
+  version: number;
+  startedAt: string;
+  settledAt: string | null;
+  failureCode: string | null;
+};
+
+export type BrowserDownloadListResponse = {
+  browserSessionId: string;
+  controllerGeneration: string;
+  downloads: BrowserDownload[];
+};
+
+export type BrowserDownloadSaveRequest = {
+  operationId: string;
+  destinationPath: string;
+  overwrite?: boolean | undefined;
+};
+
+export type BrowserDownloadSaveResponse = {
+  download: BrowserDownload;
+  destinationPath: string;
+  fileId: string;
+  operationId: string;
+  replayed: boolean;
+};
+
 export type InteractionRect = {
   x: number;
   y: number;
@@ -348,6 +759,20 @@ export type BrowserLocator =
   | { kind: "test_id"; value: string }
   | { kind: "css"; selector: string };
 
+export type BrowserPermission =
+  | "geolocation"
+  | "notifications"
+  | "camera"
+  | "microphone"
+  | "midi"
+  | "midi_sysex"
+  | "sensors"
+  | "idle_detection"
+  | "local_fonts"
+  | "window_management";
+
+export type BrowserPermissionSetting = "granted" | "denied" | "prompt";
+
 export type BrowserAction =
   | { type: "navigate"; url: string }
   | {
@@ -379,6 +804,7 @@ export type BrowserAction =
       deltaX?: number | undefined;
       deltaY?: number | undefined;
       button?: "left" | "right" | "middle" | undefined;
+      clickCount?: 1 | 2 | undefined;
     }
   | {
       type: "handle_dialog";
@@ -386,6 +812,18 @@ export type BrowserAction =
       promptText?: string | undefined;
     }
   | { type: "upload"; locator: BrowserLocator; workspaceFileIds: string[] }
+  | {
+      type: "clipboard";
+      operation: "write" | "clear" | "copy" | "paste";
+      text?: string | undefined;
+      locator?: BrowserLocator | undefined;
+      content?: "selection" | "value" | "text" | undefined;
+    }
+  | {
+      type: "permission";
+      permission: BrowserPermission;
+      setting: BrowserPermissionSetting;
+    }
   | {
       type: "wait";
       condition: "load" | "network_idle" | "visible" | "hidden";
@@ -448,9 +886,11 @@ export type CreateBrowserSessionRequest = {
   name?: string | undefined;
   initialUrl?: string | undefined;
   headless?: boolean | undefined;
+  engine?: "chromium" | "lightpanda" | undefined;
   placement?: InteractionPlacement | undefined;
   identityId?: string | undefined;
   baseRevisionId?: string | undefined;
+  networkRouteId?: string | undefined;
   linkedComputerSessionId?: string | undefined;
 };
 
@@ -488,6 +928,10 @@ export type InteractionFrameStreamAttachment<RelayKind extends 3 | 4 = 3 | 4> =
       };
     };
 
+export type ComputerFrameStreamAttachment =
+  | InteractionFrameStreamAttachment<4>
+  | { kind: "direct_rfb"; url: string; protocols: string[] };
+
 export type BrowserSessionAttachment = {
   browserSessionId: string;
   controllerGeneration: string;
@@ -508,6 +952,7 @@ export type BrowserActionRequest = {
   expectedTargetGeneration: string;
   expectedDocumentGeneration: string | null;
   expectedFrameId: string | null;
+  observationMode?: "full" | "none" | undefined;
   action: BrowserAction | BrowserActionBatch;
 };
 
@@ -539,10 +984,19 @@ export type ComputerSessionCapabilities = {
   semanticActions: boolean;
   pointerInput: boolean;
   keyboardInput: boolean;
+  clipboard: boolean;
   backgroundActions: boolean;
   parallelApps: boolean;
 };
 
+export type ComputerClipboard = {
+  computerSessionId: string;
+  controllerGeneration: string;
+  text: string | null;
+  truncated: boolean;
+  observedAt: string;
+};
+
 export type ComputerSession = {
   id: string;
   accountId: string;
@@ -632,6 +1086,11 @@ export type ComputerAction =
       button?: "left" | "right" | "middle" | undefined;
     }
   | { type: "keyboard"; action: "type" | "press"; value: string }
+  | {
+      type: "clipboard";
+      operation: "write" | "clear" | "copy" | "paste";
+      text?: string | undefined;
+    }
   | { type: "focus"; targetId: string }
   | { type: "launch"; applicationId: string };
 
@@ -674,7 +1133,7 @@ export type ComputerSessionAttachment = {
   computerSessionId: string;
   controllerGeneration: string;
   targetId: string;
-  stream: InteractionFrameStreamAttachment<4>;
+  stream: ComputerFrameStreamAttachment;
   expiresAt: string;
 };
 
@@ -721,6 +1180,113 @@ export type BrowserDiagnosticsOptions = {
 
 /** The exact HTTP surface needed by the framework-free interaction client. */
 export interface InteractionTransport {
+  listNetworkRoutes(
+    workspaceId: string,
+    options?: NetworkRouteListOptions,
+  ): Promise<NetworkRouteListResponse>;
+  getNetworkRoute(
+    workspaceId: string,
+    networkRouteId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<NetworkRoute>;
+  createNetworkRoute(
+    workspaceId: string,
+    request: CreateNetworkRouteRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<NetworkRouteMutationResponse>;
+  updateNetworkRoute(
+    workspaceId: string,
+    networkRouteId: string,
+    request: UpdateNetworkRouteRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<NetworkRouteMutationResponse>;
+  listSiteAuthConnections(
+    workspaceId: string,
+    options?: SiteAuthConnectionListOptions,
+  ): Promise<SiteAuthConnectionListResponse>;
+  getSiteAuthConnection(
+    workspaceId: string,
+    siteAuthConnectionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<SiteAuthConnection>;
+  createSiteAuthConnection(
+    workspaceId: string,
+    request: CreateSiteAuthConnectionRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<SiteAuthConnectionMutationResponse>;
+  updateSiteAuthConnection(
+    workspaceId: string,
+    siteAuthConnectionId: string,
+    request: UpdateSiteAuthConnectionRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<SiteAuthConnectionMutationResponse>;
+  listAuthRuns(workspaceId: string, options?: AuthRunListOptions): Promise<AuthRunListResponse>;
+  getAuthRun(
+    workspaceId: string,
+    authRunId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<AuthRun>;
+  startBrowserAuthRun(
+    workspaceId: string,
+    browserSessionId: string,
+    request: StartAuthRunRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<AuthRunMutationResponse>;
+  reportBrowserAuthRun(
+    workspaceId: string,
+    browserSessionId: string,
+    authRunId: string,
+    request: ReportAuthRunRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<AuthRunMutationResponse>;
+  protectedBrowserAuthFill(
+    workspaceId: string,
+    browserSessionId: string,
+    authRunId: string,
+    request: ProtectedAuthFillRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ProtectedAuthFillResponse>;
+  advanceExternalBrowserAuthRun(
+    workspaceId: string,
+    browserSessionId: string,
+    authRunId: string,
+    request: ExternalAuthRunRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ExternalAuthRunResponse>;
+  openExternalBrowserAuthFlow(
+    workspaceId: string,
+    browserSessionId: string,
+    authRunId: string,
+    request: ExternalAuthInteractiveRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ExternalAuthInteractiveResponse>;
+  verifyBrowserAuthRun(
+    workspaceId: string,
+    browserSessionId: string,
+    authRunId: string,
+    request: VerifyAuthRunRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<AuthRunMutationResponse>;
+  listInteractionInterventions(
+    workspaceId: string,
+    options?: InteractionInterventionListOptions,
+  ): Promise<InteractionInterventionListResponse>;
+  getInteractionIntervention(
+    workspaceId: string,
+    interventionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<InteractionIntervention>;
+  createInteractionIntervention(
+    workspaceId: string,
+    request: CreateInteractionInterventionRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<InteractionInterventionMutationResponse>;
+  resolveInteractionIntervention(
+    workspaceId: string,
+    interventionId: string,
+    request: ResolveInteractionInterventionRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<InteractionInterventionMutationResponse>;
   listAttachedBrowsers(
     workspaceId: string,
     options?: AttachedBrowserDeviceListOptions,
@@ -744,6 +1310,12 @@ export interface InteractionTransport {
     request: CreateBrowserIdentityRequest,
     options?: OpenGeniRequestOptions,
   ): Promise<BrowserIdentityMutationResponse>;
+  updateBrowserIdentity(
+    workspaceId: string,
+    identityId: string,
+    request: UpdateBrowserIdentityRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserIdentityMutationResponse>;
   listBrowserRevisions(
     workspaceId: string,
     identityId: string,
@@ -758,6 +1330,29 @@ export interface InteractionTransport {
     browserSessionId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<BrowserSession>;
+  readBrowserClipboard(
+    workspaceId: string,
+    browserSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserClipboard>;
+  listBrowserDownloads(
+    workspaceId: string,
+    browserSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserDownloadListResponse>;
+  getBrowserDownload(
+    workspaceId: string,
+    browserSessionId: string,
+    downloadId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserDownload>;
+  saveBrowserDownload(
+    workspaceId: string,
+    browserSessionId: string,
+    downloadId: string,
+    request: BrowserDownloadSaveRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserDownloadSaveResponse>;
   createBrowserSession(
     workspaceId: string,
     request: CreateBrowserSessionRequest,
@@ -773,13 +1368,13 @@ export interface InteractionTransport {
     browserSessionId: string,
     request?: BrowserOpenTargetRequest,
     options?: OpenGeniRequestOptions,
-  ): Promise<BrowserTarget>;
+  ): Promise<BrowserObservation>;
   selectBrowserTarget(
     workspaceId: string,
     browserSessionId: string,
     targetId: string,
     options?: OpenGeniRequestOptions,
-  ): Promise<BrowserTarget>;
+  ): Promise<BrowserObservation>;
   closeBrowserTarget(
     workspaceId: string,
     browserSessionId: string,
@@ -854,6 +1449,11 @@ export interface InteractionTransport {
     computerSessionId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerSession>;
+  readComputerClipboard(
+    workspaceId: string,
+    computerSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerClipboard>;
   createComputerSession(
     workspaceId: string,
     request: CreateComputerSessionRequest,
@@ -908,10 +1508,35 @@ export type BrowserIdentityListOptions = OpenGeniRequestOptions & {
   includeArchived?: boolean | undefined;
 };
 
+export type NetworkRouteListOptions = OpenGeniRequestOptions & {
+  includeArchived?: boolean | undefined;
+};
+
+export type SiteAuthConnectionListOptions = OpenGeniRequestOptions & {
+  includeArchived?: boolean | undefined;
+};
+
+export type AuthRunListOptions = OpenGeniRequestOptions & {
+  browserSessionId?: string | undefined;
+  siteAuthConnectionId?: string | undefined;
+  includeSettled?: boolean | undefined;
+};
+
+export type InteractionInterventionListOptions = OpenGeniRequestOptions & {
+  resourceKind?: "browser_session" | "computer_session" | undefined;
+  resourceId?: string | undefined;
+  includeSettled?: boolean | undefined;
+};
+
 export type AttachedBrowserDeviceListOptions = OpenGeniRequestOptions & {
   includeDisconnected?: boolean | undefined;
 };
 
+export type BrowserDownloadSaveOptions = OpenGeniRequestOptions & {
+  operationId?: string | undefined;
+  overwrite?: boolean | undefined;
+};
+
 export type CurrentOrOpenBrowserOptions = {
   workspaceId: string;
   associationSessionId: string;
@@ -922,6 +1547,7 @@ export type CurrentOrOpenBrowserOptions = {
   placement?: InteractionPlacement | undefined;
   identityId?: string | undefined;
   baseRevisionId?: string | undefined;
+  networkRouteId?: string | undefined;
   linkedComputerSessionId?: string | undefined;
   signal?: AbortSignal | undefined;
 };
@@ -938,15 +1564,303 @@ export type CurrentOrOpenComputerOptions = {
 /** Framework-free resource facade over the public interaction HTTP API. */
 export class OpenGeniInteractionClient {
   readonly attachedBrowsers: AttachedBrowserDeviceCollection;
+  readonly authRuns: AuthRunCollection;
   readonly browsers: BrowserSessionCollection;
   readonly computers: ComputerSessionCollection;
   readonly identities: BrowserIdentityCollection;
+  readonly interventions: InteractionInterventionCollection;
+  readonly networkRoutes: NetworkRouteCollection;
+  readonly siteAuthConnections: SiteAuthConnectionCollection;
 
   constructor(transport: BrowserInteractionTransport) {
     this.attachedBrowsers = new AttachedBrowserDeviceCollection(transport);
+    this.authRuns = new AuthRunCollection(transport);
     this.browsers = new BrowserSessionCollection(transport);
     this.computers = new ComputerSessionCollection(transport);
     this.identities = new BrowserIdentityCollection(transport);
+    this.interventions = new InteractionInterventionCollection(transport);
+    this.networkRoutes = new NetworkRouteCollection(transport);
+    this.siteAuthConnections = new SiteAuthConnectionCollection(transport);
+  }
+}
+
+export class NetworkRouteCollection {
+  constructor(private readonly transport: BrowserInteractionTransport) {}
+
+  async list(
+    workspaceId: string,
+    options: NetworkRouteListOptions = {},
+  ): Promise<NetworkRouteListResponse> {
+    return await this.transport.listNetworkRoutes(workspaceId, options);
+  }
+
+  route(workspaceId: string, networkRouteId: string): NetworkRouteResource {
+    return new NetworkRouteResource(this.transport, workspaceId, networkRouteId);
+  }
+
+  async create(
+    workspaceId: string,
+    request: CreateNetworkRouteRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<NetworkRouteResource> {
+    const response = await this.transport.createNetworkRoute(workspaceId, request, options);
+    return this.route(workspaceId, response.route.id);
+  }
+}
+
+export class NetworkRouteResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly id: string,
+  ) {}
+
+  async get(options: OpenGeniRequestOptions = {}): Promise<NetworkRoute> {
+    return await this.transport.getNetworkRoute(this.workspaceId, this.id, options);
+  }
+
+  async update(
+    request: UpdateNetworkRouteRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<NetworkRouteMutationResponse> {
+    return await this.transport.updateNetworkRoute(this.workspaceId, this.id, request, options);
+  }
+}
+
+export class SiteAuthConnectionCollection {
+  constructor(private readonly transport: BrowserInteractionTransport) {}
+
+  async list(
+    workspaceId: string,
+    options: SiteAuthConnectionListOptions = {},
+  ): Promise<SiteAuthConnectionListResponse> {
+    return await this.transport.listSiteAuthConnections(workspaceId, options);
+  }
+
+  connection(workspaceId: string, connectionId: string): SiteAuthConnectionResource {
+    return new SiteAuthConnectionResource(this.transport, workspaceId, connectionId);
+  }
+
+  async create(
+    workspaceId: string,
+    request: CreateSiteAuthConnectionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<SiteAuthConnectionResource> {
+    const response = await this.transport.createSiteAuthConnection(workspaceId, request, options);
+    return this.connection(workspaceId, response.connection.id);
+  }
+}
+
+export class SiteAuthConnectionResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly id: string,
+  ) {}
+
+  async get(options: OpenGeniRequestOptions = {}): Promise<SiteAuthConnection> {
+    return await this.transport.getSiteAuthConnection(this.workspaceId, this.id, options);
+  }
+
+  async update(
+    request: UpdateSiteAuthConnectionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<SiteAuthConnectionMutationResponse> {
+    return await this.transport.updateSiteAuthConnection(
+      this.workspaceId,
+      this.id,
+      request,
+      options,
+    );
+  }
+}
+
+export class AuthRunCollection {
+  constructor(private readonly transport: BrowserInteractionTransport) {}
+
+  async list(workspaceId: string, options: AuthRunListOptions = {}): Promise<AuthRunListResponse> {
+    return await this.transport.listAuthRuns(workspaceId, options);
+  }
+
+  async get(
+    workspaceId: string,
+    authRunId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRun> {
+    return await this.transport.getAuthRun(workspaceId, authRunId, options);
+  }
+
+  run(workspaceId: string, browserSessionId: string, authRunId: string): AuthRunResource {
+    return new AuthRunResource(this.transport, workspaceId, browserSessionId, authRunId);
+  }
+}
+
+export class BrowserAuthRunCollection {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+  ) {}
+
+  async list(
+    options: Omit<AuthRunListOptions, "browserSessionId"> = {},
+  ): Promise<AuthRunListResponse> {
+    return await this.transport.listAuthRuns(this.workspaceId, {
+      ...options,
+      browserSessionId: this.browserSessionId,
+    });
+  }
+
+  run(authRunId: string): AuthRunResource {
+    return new AuthRunResource(this.transport, this.workspaceId, this.browserSessionId, authRunId);
+  }
+
+  async start(
+    request: StartAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunResource> {
+    const response = await this.transport.startBrowserAuthRun(
+      this.workspaceId,
+      this.browserSessionId,
+      request,
+      options,
+    );
+    return this.run(response.run.id);
+  }
+}
+
+export class AuthRunResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+    readonly id: string,
+  ) {}
+
+  async get(options: OpenGeniRequestOptions = {}): Promise<AuthRun> {
+    const run = await this.transport.getAuthRun(this.workspaceId, this.id, options);
+    if (run.browserSessionId !== this.browserSessionId) {
+      throw new Error("AuthRun belongs to another BrowserSession");
+    }
+    return run;
+  }
+
+  async report(
+    request: ReportAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunMutationResponse> {
+    return await this.transport.reportBrowserAuthRun(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      request,
+      options,
+    );
+  }
+
+  async protectedFill(
+    request: ProtectedAuthFillRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ProtectedAuthFillResponse> {
+    return await this.transport.protectedBrowserAuthFill(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      request,
+      options,
+    );
+  }
+
+  async advanceExternal(
+    request: ExternalAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ExternalAuthRunResponse> {
+    return await this.transport.advanceExternalBrowserAuthRun(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      request,
+      options,
+    );
+  }
+
+  /** Human-session helper. Hosted provider URLs never appear in model tools. */
+  async openExternalFlow(
+    request: ExternalAuthInteractiveRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ExternalAuthInteractiveResponse> {
+    return await this.transport.openExternalBrowserAuthFlow(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      request,
+      options,
+    );
+  }
+
+  async verify(
+    request: VerifyAuthRunRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<AuthRunMutationResponse> {
+    return await this.transport.verifyBrowserAuthRun(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      request,
+      options,
+    );
+  }
+}
+
+export class InteractionInterventionCollection {
+  constructor(private readonly transport: BrowserInteractionTransport) {}
+
+  async list(
+    workspaceId: string,
+    options: InteractionInterventionListOptions = {},
+  ): Promise<InteractionInterventionListResponse> {
+    return await this.transport.listInteractionInterventions(workspaceId, options);
+  }
+
+  intervention(workspaceId: string, interventionId: string): InteractionInterventionResource {
+    return new InteractionInterventionResource(this.transport, workspaceId, interventionId);
+  }
+
+  async create(
+    workspaceId: string,
+    request: CreateInteractionInterventionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<InteractionInterventionResource> {
+    const response = await this.transport.createInteractionIntervention(
+      workspaceId,
+      request,
+      options,
+    );
+    return this.intervention(workspaceId, response.intervention.id);
+  }
+}
+
+export class InteractionInterventionResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly id: string,
+  ) {}
+
+  async get(options: OpenGeniRequestOptions = {}): Promise<InteractionIntervention> {
+    return await this.transport.getInteractionIntervention(this.workspaceId, this.id, options);
+  }
+
+  async resolve(
+    request: ResolveInteractionInterventionRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<InteractionInterventionMutationResponse> {
+    return await this.transport.resolveInteractionIntervention(
+      this.workspaceId,
+      this.id,
+      request,
+      options,
+    );
   }
 }
 
@@ -1015,6 +1929,13 @@ export class BrowserIdentityResource {
   async revisions(options: OpenGeniRequestOptions = {}): Promise<BrowserRevisionListResponse> {
     return await this.transport.listBrowserRevisions(this.workspaceId, this.id, options);
   }
+
+  async update(
+    request: UpdateBrowserIdentityRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserIdentityMutationResponse> {
+    return await this.transport.updateBrowserIdentity(this.workspaceId, this.id, request, options);
+  }
 }
 
 export class BrowserSessionCollection {
@@ -1065,6 +1986,7 @@ export class BrowserSessionCollection {
         ...(options.placement !== undefined ? { placement: options.placement } : {}),
         ...(options.identityId !== undefined ? { identityId: options.identityId } : {}),
         ...(options.baseRevisionId !== undefined ? { baseRevisionId: options.baseRevisionId } : {}),
+        ...(options.networkRouteId !== undefined ? { networkRouteId: options.networkRouteId } : {}),
         ...(options.linkedComputerSessionId !== undefined
           ? { linkedComputerSessionId: options.linkedComputerSessionId }
           : {}),
@@ -1075,6 +1997,9 @@ export class BrowserSessionCollection {
 }
 
 export class BrowserSessionResource {
+  readonly auth: BrowserAuthRunCollection;
+  readonly clipboard: BrowserClipboardResource;
+  readonly downloads: BrowserDownloadCollection;
   readonly tabs: BrowserTargetCollection;
   /** Alias for hosts that prefer the protocol term. */
   readonly targets: BrowserTargetCollection;
@@ -1084,6 +2009,9 @@ export class BrowserSessionResource {
     readonly workspaceId: string,
     readonly id: string,
   ) {
+    this.auth = new BrowserAuthRunCollection(transport, workspaceId, id);
+    this.clipboard = new BrowserClipboardResource(transport, workspaceId, id);
+    this.downloads = new BrowserDownloadCollection(transport, workspaceId, id);
     this.tabs = new BrowserTargetCollection(transport, workspaceId, id);
     this.targets = this.tabs;
   }
@@ -1176,6 +2104,97 @@ export class BrowserSessionResource {
   }
 }
 
+export class BrowserClipboardResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+  ) {}
+
+  async read(options: OpenGeniRequestOptions = {}): Promise<BrowserClipboard> {
+    const clipboard = await this.transport.readBrowserClipboard(
+      this.workspaceId,
+      this.browserSessionId,
+      options,
+    );
+    if (clipboard.browserSessionId !== this.browserSessionId) {
+      throw new Error("Browser clipboard belongs to another BrowserSession");
+    }
+    return clipboard;
+  }
+}
+
+export class BrowserDownloadCollection {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+  ) {}
+
+  async list(options: OpenGeniRequestOptions = {}): Promise<BrowserDownloadListResponse> {
+    return await this.transport.listBrowserDownloads(
+      this.workspaceId,
+      this.browserSessionId,
+      options,
+    );
+  }
+
+  download(downloadId: string): BrowserDownloadResource {
+    return new BrowserDownloadResource(
+      this.transport,
+      this.workspaceId,
+      this.browserSessionId,
+      downloadId,
+    );
+  }
+}
+
+export class BrowserDownloadResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+    readonly id: string,
+  ) {}
+
+  async get(options: OpenGeniRequestOptions = {}): Promise<BrowserDownload> {
+    const download = await this.transport.getBrowserDownload(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      options,
+    );
+    if (download.browserSessionId !== this.browserSessionId) {
+      throw new Error("BrowserDownload belongs to another BrowserSession");
+    }
+    return download;
+  }
+
+  /** Publish this exact private browser download into the source session's
+   * workspace. Pass an operationId when the caller needs retry identity across
+   * process boundaries; otherwise one is generated for this call. */
+  async saveToWorkspace(
+    destinationPath: string,
+    options: BrowserDownloadSaveOptions = {},
+  ): Promise<BrowserDownloadSaveResponse> {
+    const { operationId = crypto.randomUUID(), overwrite = false, ...requestOptions } = options;
+    const response = await this.transport.saveBrowserDownload(
+      this.workspaceId,
+      this.browserSessionId,
+      this.id,
+      { operationId, destinationPath, overwrite },
+      requestOptions,
+    );
+    if (
+      response.download.id !== this.id ||
+      response.download.browserSessionId !== this.browserSessionId
+    ) {
+      throw new Error("BrowserDownload save returned another resource");
+    }
+    return response;
+  }
+}
+
 export class BrowserTargetCollection {
   constructor(
     private readonly transport: BrowserInteractionTransport,
@@ -1191,7 +2210,7 @@ export class BrowserTargetCollection {
     );
   }
 
-  async open(url?: string, options: OpenGeniRequestOptions = {}): Promise<BrowserTarget> {
+  async open(url?: string, options: OpenGeniRequestOptions = {}): Promise<BrowserObservation> {
     return await this.transport.openBrowserTarget(
       this.workspaceId,
       this.browserSessionId,
@@ -1200,7 +2219,10 @@ export class BrowserTargetCollection {
     );
   }
 
-  async select(targetId: string, options: OpenGeniRequestOptions = {}): Promise<BrowserTarget> {
+  async select(
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserObservation> {
     return await this.transport.selectBrowserTarget(
       this.workspaceId,
       this.browserSessionId,
@@ -1269,6 +2291,7 @@ export class ComputerSessionResource {
   readonly targets: ComputerTargetCollection;
   /** Native application/window targets are also the public app collection. */
   readonly apps: ComputerTargetCollection;
+  readonly clipboard: ComputerClipboardResource;
 
   constructor(
     private readonly transport: BrowserInteractionTransport,
@@ -1277,6 +2300,7 @@ export class ComputerSessionResource {
   ) {
     this.targets = new ComputerTargetCollection(transport, workspaceId, id);
     this.apps = this.targets;
+    this.clipboard = new ComputerClipboardResource(transport, workspaceId, id);
   }
 
   async get(options: OpenGeniRequestOptions = {}): Promise<ComputerSession> {
@@ -1328,6 +2352,26 @@ export class ComputerSessionResource {
   }
 }
 
+export class ComputerClipboardResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly computerSessionId: string,
+  ) {}
+
+  async read(options: OpenGeniRequestOptions = {}): Promise<ComputerClipboard> {
+    const clipboard = await this.transport.readComputerClipboard(
+      this.workspaceId,
+      this.computerSessionId,
+      options,
+    );
+    if (clipboard.computerSessionId !== this.computerSessionId) {
+      throw new Error("Computer clipboard belongs to another ComputerSession");
+    }
+    return clipboard;
+  }
+}
+
 export class ComputerTargetCollection {
   constructor(
     private readonly transport: BrowserInteractionTransport,