@opengeni/sdk 0.52.1 → 1.0.0

package/src/interaction.ts

@@ -1,4 +1,17 @@
 import type { OpenGeniRequestOptions } from "./client";
+import { browserSessionStorageMode } from "@opengeni/contracts/browser-storage";
+import type {
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
+  BrowserTargetState,
+} from "@opengeni/contracts";
+export type {
+  BrowserDomReadRequest,
+  BrowserDomReadResponse,
+  BrowserDomSafeAttribute,
+  BrowserTargetState,
+} from "@opengeni/contracts";
+import { OpenGeniApiError } from "./errors";
 import type { RetainedArtifactReference } from "./types";
 
 /** Public Browser/Computer protocol version. Driver and provider details stay private. */
@@ -11,6 +24,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
@@ -19,6 +41,83 @@ export type InteractionJsonValue =
   | InteractionJsonValue[]
   | { [key: string]: InteractionJsonValue };
 
+export type InteractionControlFailureCode =
+  | "unknown"
+  | "unsupported"
+  | "os"
+  | "not_found"
+  | "consent_required"
+  | "timeout"
+  | "draining"
+  | "protocol"
+  | "stream"
+  | "agent_offline"
+  | "fenced"
+  | "payload_too_large";
+
+export type InteractionControlFailure = {
+  layer: "connected_machine";
+  surface: "browser" | "computer";
+  code: InteractionControlFailureCode;
+  retryable: boolean;
+  outcomeUnknown: boolean;
+  requestId: string | undefined;
+  controlRequestId: string | undefined;
+  message: string;
+};
+
+/** Decodes the bounded typed control-failure details emitted by OpenGeni. Raw
+ * provider/OS detail is intentionally absent; both correlation ids are opaque. */
+export function interactionControlFailureFromError(
+  error: unknown,
+): InteractionControlFailure | null {
+  if (!(error instanceof OpenGeniApiError)) return null;
+  const details = error.details;
+  if (!details || details.interactionLayer !== "connected_machine") return null;
+  const surface = details.interactionSurface;
+  const code = details.controlFailureCode;
+  if ((surface !== "browser" && surface !== "computer") || !isControlFailureCode(code)) {
+    return null;
+  }
+  const controlRequestId = boundedOpaqueCorrelation(details.controlRequestId);
+  return {
+    layer: "connected_machine",
+    surface,
+    code,
+    retryable: error.retryable,
+    outcomeUnknown: error.outcomeUnknown,
+    requestId: error.correlationId,
+    controlRequestId,
+    message: error.message,
+  };
+}
+
+function isControlFailureCode(value: unknown): value is InteractionControlFailureCode {
+  return (
+    typeof value === "string" &&
+    [
+      "unknown",
+      "unsupported",
+      "os",
+      "not_found",
+      "consent_required",
+      "timeout",
+      "draining",
+      "protocol",
+      "stream",
+      "agent_offline",
+      "fenced",
+      "payload_too_large",
+    ].includes(value)
+  );
+}
+
+function boundedOpaqueCorrelation(value: unknown): string | undefined {
+  return typeof value === "string" && value.length <= 128 && /^[A-Za-z0-9._:-]+$/u.test(value)
+    ? value
+    : undefined;
+}
+
 export type InteractionPlacement =
   | { kind: "sandbox_group"; sandboxGroupId: string }
   | { kind: "connected_machine"; sandboxId: string }
@@ -62,8 +161,18 @@ export type AttachedBrowserDevice = {
   updatedAt: string;
 };
 
+export type AttachedBrowserBridge = {
+  enrollmentId: string;
+  state: "online" | "offline";
+  bridgeGeneration: string;
+  inventoryRevision: number;
+  connectedProfileCount: number;
+  lastSeenAt: string;
+};
+
 export type AttachedBrowserDeviceListResponse = {
   revision: number;
+  bridges: AttachedBrowserBridge[];
   devices: AttachedBrowserDevice[];
 };
 
@@ -103,6 +212,7 @@ export type BrowserSessionCapabilities = {
   downloads: boolean;
   uploads: boolean;
   clipboard: boolean;
+  permissions: boolean;
   diagnostics: boolean;
   rawCdp: boolean;
   linkedComputer: boolean;
@@ -135,6 +245,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 +642,7 @@ export type BrowserIdentity = {
   workspaceId: string;
   name: string;
   status: BrowserIdentityStatus;
+  version: number;
   defaultRevisionId: string | null;
   headGeneration: number;
   revisionCount: number;
@@ -208,6 +666,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 +708,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;
@@ -303,6 +814,17 @@ export type BrowserObservation = {
   frameId: string | null;
   semantic: InteractionSemanticSnapshot | InteractionSemanticDiff | null;
   screenshot: RetainedArtifactReference | null;
+  viewport?:
+    | {
+        width: number;
+        height: number;
+        visualWidth: number;
+        visualHeight: number;
+        deviceScaleFactor: number;
+        maxTouchPoints: number;
+      }
+    | null
+    | undefined;
   focusedRef: string | null;
   changedRegions: InteractionRect[];
   diagnostics: InteractionDiagnosticSummary;
@@ -348,8 +870,31 @@ 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 }
+  | { type: "history"; direction: "back" | "forward" }
+  | { type: "activate" }
+  | {
+      type: "viewport";
+      width: number;
+      height: number;
+      mobile: boolean;
+      deviceScaleFactor?: number | undefined;
+    }
   | {
       type: "click";
       locator: BrowserLocator;
@@ -379,6 +924,7 @@ export type BrowserAction =
       deltaX?: number | undefined;
       deltaY?: number | undefined;
       button?: "left" | "right" | "middle" | undefined;
+      clickCount?: 1 | 2 | undefined;
     }
   | {
       type: "handle_dialog";
@@ -386,6 +932,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";
@@ -393,7 +951,11 @@ export type BrowserAction =
       timeoutMs?: number | undefined;
     };
 
-export type BrowserActionBatch = { type: "batch"; actions: BrowserAction[] };
+export type BrowserActionBatch = {
+  type: "batch";
+  actions: BrowserAction[];
+  fenceEachAction?: true | undefined;
+};
 
 export type InteractionError = {
   code:
@@ -448,9 +1010,12 @@ export type CreateBrowserSessionRequest = {
   name?: string | undefined;
   initialUrl?: string | undefined;
   headless?: boolean | undefined;
+  storageMode?: "private_profile" | "ephemeral_context" | undefined;
+  engine?: "chromium" | "lightpanda" | undefined;
   placement?: InteractionPlacement | undefined;
   identityId?: string | undefined;
   baseRevisionId?: string | undefined;
+  networkRouteId?: string | undefined;
   linkedComputerSessionId?: string | undefined;
 };
 
@@ -488,11 +1053,18 @@ export type InteractionFrameStreamAttachment<RelayKind extends 3 | 4 = 3 | 4> =
       };
     };
 
+export type ComputerFrameStreamAttachment =
+  | InteractionFrameStreamAttachment<4>
+  | { kind: "direct_rfb"; url: string; protocols: string[]; inputAllowed: boolean };
+
 export type BrowserSessionAttachment = {
   browserSessionId: string;
   controllerGeneration: string;
   targetId: string;
   stream: InteractionFrameStreamAttachment<3>;
+  /** Negotiated from this attachment’s live controller, absent on older helpers. */
+  fencedInputBatches?: true | undefined;
+  focusedInputObservations?: true | undefined;
   expiresAt: string;
 };
 
@@ -508,6 +1080,10 @@ export type BrowserActionRequest = {
   expectedTargetGeneration: string;
   expectedDocumentGeneration: string | null;
   expectedFrameId: string | null;
+  /** `input` is negotiated by focusedInputObservations on a live attachment.
+   * It returns optional native-select metadata after a pointer click, and null
+   * for ordinary input. Use full for agent observations. */
+  observationMode?: "full" | "none" | "input" | undefined;
   action: BrowserAction | BrowserActionBatch;
 };
 
@@ -539,10 +1115,21 @@ export type ComputerSessionCapabilities = {
   semanticActions: boolean;
   pointerInput: boolean;
   keyboardInput: boolean;
+  clipboard: boolean;
   backgroundActions: boolean;
+  /** Raw window input stays in the background. Absent means foreground-only. */
+  backgroundInput?: boolean | undefined;
   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 +1219,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,10 +1266,19 @@ export type ComputerSessionAttachment = {
   computerSessionId: string;
   controllerGeneration: string;
   targetId: string;
-  stream: InteractionFrameStreamAttachment<4>;
+  /** Viewer posture when attached; actions still reauthorize the live source. */
+  inputAllowed?: boolean | undefined;
+  stream: ComputerFrameStreamAttachment;
   expiresAt: string;
 };
 
+/** Caller-specific hint only; every action still requires live authorization. */
+export type ComputerSessionInputPosture = {
+  computerSessionId: string;
+  controllerGeneration: string;
+  inputAllowed: boolean;
+};
+
 export type ComputerSessionAttachmentRequest = {
   targetId: string;
   expiresInSeconds?: number | undefined;
@@ -721,6 +1322,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 +1452,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 +1472,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 +1510,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,
@@ -792,6 +1529,26 @@ export interface InteractionTransport {
     targetId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<BrowserObservation>;
+  getBrowserTargetState(
+    workspaceId: string,
+    browserSessionId: string,
+    targetId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserTargetState>;
+  readBrowserDom(
+    workspaceId: string,
+    browserSessionId: string,
+    targetId: string,
+    request: BrowserDomReadRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserDomReadResponse>;
+  captureBrowserTarget(
+    workspaceId: string,
+    browserSessionId: string,
+    targetId: string,
+    options?: OpenGeniRequestOptions,
+    captureOptions?: BrowserScreenshotOptions,
+  ): Promise<BrowserFrame>;
   actInBrowser(
     workspaceId: string,
     browserSessionId: string,
@@ -854,6 +1611,16 @@ export interface InteractionTransport {
     computerSessionId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerSession>;
+  getComputerInputPosture?(
+    workspaceId: string,
+    computerSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerSessionInputPosture>;
+  readComputerClipboard(
+    workspaceId: string,
+    computerSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerClipboard>;
   createComputerSession(
     workspaceId: string,
     request: CreateComputerSessionRequest,
@@ -870,6 +1637,12 @@ export interface InteractionTransport {
     targetId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerObservation>;
+  captureComputerTarget(
+    workspaceId: string,
+    computerSessionId: string,
+    targetId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerFrame>;
   actInComputer(
     workspaceId: string,
     computerSessionId: string,
@@ -895,58 +1668,373 @@ export interface InteractionTransport {
   ): Promise<ComputerSessionHeartbeatResponse>;
   endComputerSession(
     workspaceId: string,
-    computerSessionId: string,
-    request: ComputerSessionLifecycleRequest,
-    options?: OpenGeniRequestOptions,
-  ): Promise<ComputerSessionMutationResponse>;
+    computerSessionId: string,
+    request: ComputerSessionLifecycleRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerSessionMutationResponse>;
+}
+
+/** @deprecated Use InteractionTransport. */
+export type BrowserInteractionTransport = InteractionTransport;
+
+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;
+  operationId?: string | undefined;
+  name?: string | undefined;
+  initialUrl?: string | undefined;
+  headless?: boolean | undefined;
+  storageMode?: "private_profile" | "ephemeral_context" | undefined;
+  placement?: InteractionPlacement | undefined;
+  identityId?: string | undefined;
+  baseRevisionId?: string | undefined;
+  networkRouteId?: string | undefined;
+  linkedComputerSessionId?: string | undefined;
+  signal?: AbortSignal | undefined;
+};
+
+export type CurrentOrOpenComputerOptions = {
+  workspaceId: string;
+  associationSessionId: string;
+  operationId?: string | undefined;
+  name?: string | undefined;
+  placement?: InteractionPlacement | undefined;
+  signal?: AbortSignal | undefined;
+};
+
+/** 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);
+  }
 }
 
-/** @deprecated Use InteractionTransport. */
-export type BrowserInteractionTransport = InteractionTransport;
+export class BrowserAuthRunCollection {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+  ) {}
 
-export type BrowserIdentityListOptions = OpenGeniRequestOptions & {
-  includeArchived?: boolean | undefined;
-};
+  async list(
+    options: Omit<AuthRunListOptions, "browserSessionId"> = {},
+  ): Promise<AuthRunListResponse> {
+    return await this.transport.listAuthRuns(this.workspaceId, {
+      ...options,
+      browserSessionId: this.browserSessionId,
+    });
+  }
 
-export type AttachedBrowserDeviceListOptions = OpenGeniRequestOptions & {
-  includeDisconnected?: boolean | undefined;
-};
+  run(authRunId: string): AuthRunResource {
+    return new AuthRunResource(this.transport, this.workspaceId, this.browserSessionId, authRunId);
+  }
 
-export type CurrentOrOpenBrowserOptions = {
-  workspaceId: string;
-  associationSessionId: string;
-  operationId?: string | undefined;
-  name?: string | undefined;
-  initialUrl?: string | undefined;
-  headless?: boolean | undefined;
-  placement?: InteractionPlacement | undefined;
-  identityId?: string | undefined;
-  baseRevisionId?: string | undefined;
-  linkedComputerSessionId?: string | undefined;
-  signal?: AbortSignal | undefined;
-};
+  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 type CurrentOrOpenComputerOptions = {
-  workspaceId: string;
-  associationSessionId: string;
-  operationId?: string | undefined;
-  name?: string | undefined;
-  placement?: InteractionPlacement | undefined;
-  signal?: AbortSignal | undefined;
-};
+export class AuthRunResource {
+  constructor(
+    private readonly transport: BrowserInteractionTransport,
+    readonly workspaceId: string,
+    readonly browserSessionId: string,
+    readonly id: string,
+  ) {}
 
-/** Framework-free resource facade over the public interaction HTTP API. */
-export class OpenGeniInteractionClient {
-  readonly attachedBrowsers: AttachedBrowserDeviceCollection;
-  readonly browsers: BrowserSessionCollection;
-  readonly computers: ComputerSessionCollection;
-  readonly identities: BrowserIdentityCollection;
+  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;
+  }
 
-  constructor(transport: BrowserInteractionTransport) {
-    this.attachedBrowsers = new AttachedBrowserDeviceCollection(transport);
-    this.browsers = new BrowserSessionCollection(transport);
-    this.computers = new ComputerSessionCollection(transport);
-    this.identities = new BrowserIdentityCollection(transport);
+  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 +2103,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 {
@@ -1043,7 +2138,13 @@ export class BrowserSessionCollection {
   async currentOrOpen(options: CurrentOrOpenBrowserOptions): Promise<BrowserSessionResource> {
     const requestOptions = options.signal ? { signal: options.signal } : {};
     const listed = await this.list(options.workspaceId, requestOptions);
-    const current = newestRelevantBrowser(listed.sessions, options.associationSessionId);
+    const current = newestRelevantBrowser(
+      listed.sessions.filter(
+        (session) =>
+          browserSessionStorageMode(session) === (options.storageMode ?? "private_profile"),
+      ),
+      options.associationSessionId,
+    );
     if (current) {
       const resource = this.session(options.workspaceId, current.id);
       if (current.lifecycle === "suspended") {
@@ -1062,9 +2163,11 @@ export class BrowserSessionCollection {
         ...(options.name !== undefined ? { name: options.name } : {}),
         ...(options.initialUrl !== undefined ? { initialUrl: options.initialUrl } : {}),
         ...(options.headless !== undefined ? { headless: options.headless } : {}),
+        ...(options.storageMode !== undefined ? { storageMode: options.storageMode } : {}),
         ...(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 +2178,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 +2190,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;
   }
@@ -1099,6 +2208,49 @@ export class BrowserSessionResource {
     return await this.transport.observeBrowserTarget(this.workspaceId, this.id, targetId, options);
   }
 
+  async targetState(
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserTargetState> {
+    return await this.transport.getBrowserTargetState(this.workspaceId, this.id, targetId, options);
+  }
+
+  async readDom(
+    targetId: string,
+    request: BrowserDomReadRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserDomReadResponse> {
+    return await this.transport.readBrowserDom(
+      this.workspaceId,
+      this.id,
+      targetId,
+      request,
+      options,
+    );
+  }
+
+  async capture(
+    targetId: string,
+    options: OpenGeniRequestOptions = {},
+    captureOptions: BrowserScreenshotOptions = {},
+  ): Promise<BrowserFrame> {
+    return await this.transport.captureBrowserTarget(
+      this.workspaceId,
+      this.id,
+      targetId,
+      options,
+      captureOptions,
+    );
+  }
+
+  async screenshot(
+    targetId: string,
+    captureOptions: BrowserScreenshotOptions = {},
+    options: OpenGeniRequestOptions = {},
+  ): Promise<BrowserFrame> {
+    return await this.capture(targetId, options, captureOptions);
+  }
+
   async act(
     request: BrowserActionRequest,
     options: OpenGeniRequestOptions = {},
@@ -1176,6 +2328,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 +2434,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 +2443,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 +2515,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 +2524,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> {
@@ -1290,6 +2538,10 @@ export class ComputerSessionResource {
     return await this.transport.observeComputerTarget(this.workspaceId, this.id, targetId, options);
   }
 
+  async capture(targetId: string, options: OpenGeniRequestOptions = {}): Promise<ComputerFrame> {
+    return await this.transport.captureComputerTarget(this.workspaceId, this.id, targetId, options);
+  }
+
   async act(
     request: ComputerActionRequest,
     options: OpenGeniRequestOptions = {},
@@ -1316,6 +2568,13 @@ export class ComputerSessionResource {
     return await this.transport.attachComputerSession(this.workspaceId, this.id, request, options);
   }
 
+  async inputPosture(options: OpenGeniRequestOptions = {}): Promise<ComputerSessionInputPosture> {
+    if (!this.transport.getComputerInputPosture) {
+      throw new Error("Computer input posture requires a current interaction transport.");
+    }
+    return await this.transport.getComputerInputPosture(this.workspaceId, this.id, options);
+  }
+
   async heartbeat(options: OpenGeniRequestOptions = {}): Promise<ComputerSessionHeartbeatResponse> {
     return await this.transport.heartbeatComputerSession(this.workspaceId, this.id, options);
   }
@@ -1328,6 +2587,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,
@@ -1363,6 +2642,14 @@ export type BrowserFrameMetadata = {
 
 export type BrowserFrame = BrowserFrameMetadata & { data: Uint8Array };
 
+export type BrowserScreenshotOptions = {
+  /** Capture the document content instead of the visible viewport. */
+  fullPage?: boolean;
+  format?: "jpeg" | "png";
+  /** JPEG quality, from 1 to 100. Ignored for PNG. */
+  quality?: number;
+};
+
 export type ComputerFrameMetadata = {
   frameId: string;
   computerSessionId: string;
@@ -1395,6 +2682,7 @@ export function browserFrameSocketUrl(
   else if (url.protocol !== "ws:" && url.protocol !== "wss:") {
     throw new Error("browser frame attachment did not contain an HTTP or WebSocket URL");
   }
+  upgradeMixedContentWebSocket(url);
   if (options.format !== undefined) url.searchParams.set("format", options.format);
   setBoundedIntegerQuery(url, "quality", options.quality, 1, 100);
   setBoundedIntegerQuery(url, "maxWidth", options.maxWidth, 1, 4_096);
@@ -1417,6 +2705,7 @@ export function computerFrameSocketUrl(
   else if (url.protocol !== "ws:" && url.protocol !== "wss:") {
     throw new Error("computer frame attachment did not contain an HTTP or WebSocket URL");
   }
+  upgradeMixedContentWebSocket(url);
   if (options.format !== undefined) url.searchParams.set("format", options.format);
   setBoundedIntegerQuery(url, "quality", options.quality, 1, 100);
   setBoundedIntegerQuery(url, "maxWidth", options.maxWidth, 1, 4_096);
@@ -1657,6 +2946,28 @@ export function parseComputerFrameMetadata(value: unknown): ComputerFrameMetadat
   return metadata;
 }
 
+export function decodeComputerFrameMetadataHeader(value: string): ComputerFrameMetadata {
+  if (!value || value.length > 32 * 1024 || !/^[A-Za-z0-9_-]+$/u.test(value)) {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  const normalized = value.replace(/-/gu, "+").replace(/_/gu, "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  let decoded: string;
+  try {
+    decoded = atob(padded);
+  } catch {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  const bytes = Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+  let metadata: unknown;
+  try {
+    metadata = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new Error("computer frame metadata header is invalid");
+  }
+  return parseComputerFrameMetadata(metadata);
+}
+
 function newestRelevantBrowser(
   sessions: readonly BrowserSession[],
   associationSessionId: string,
@@ -1710,6 +3021,11 @@ function computerRelevance(session: ComputerSession, associationSessionId: strin
   return Math.max(association, Number.isFinite(used) ? used : 0);
 }
 
+function upgradeMixedContentWebSocket(url: URL): void {
+  const protocol = (globalThis as { location?: { protocol?: string } }).location?.protocol;
+  if (protocol === "https:" && url.protocol === "ws:") url.protocol = "wss:";
+}
+
 function setBoundedIntegerQuery(
   url: URL,
   name: string,