@opengeni/sdk 3.1.0 → 3.1.2

package/src/insights-usage.ts

@@ -0,0 +1,61 @@
+// Type-only references keep this opt-in SDK leaf free of zod/root contracts.
+import type {
+  OrganizationInsightsUsageQueryInput,
+  OrganizationInsightsCallsQueryInput,
+  InsightsUsageRange,
+  InsightsUsagePayer,
+  InsightsUsageSource,
+} from "@opengeni/contracts/insights-usage";
+
+export type {
+  InsightsUsageRange,
+  InsightsUsageGroupBy,
+  InsightsUsagePayer,
+  InsightsUsageSource,
+  InsightsUsageTokens,
+  InsightsUsageClassMicros,
+  InsightsUsageMeasures,
+  InsightsUsageScope,
+  InsightsUsageGroup,
+  InsightsUsageSeriesPoint,
+  InsightsUsageFacets,
+  InsightsUsageResponse,
+  InsightsCall,
+  InsightsCallsResponse,
+} from "@opengeni/contracts/insights-usage";
+
+/** Custom selections require both inclusive UTC calendar days. */
+export type InsightsUsageWindowOptions =
+  | { range?: Exclude<InsightsUsageRange, "custom">; from?: never; to?: never }
+  | { range: "custom"; from: string; to: string };
+
+type FilterOptions<T> = Omit<T, "range" | "from" | "to" | "limit" | "payer" | "source"> &
+  InsightsUsageWindowOptions & {
+    limit?: number;
+    payer?: InsightsUsagePayer | InsightsUsagePayer[];
+    source?: InsightsUsageSource | InsightsUsageSource[];
+  };
+
+export type OrganizationInsightsUsageOptions = FilterOptions<
+  Omit<OrganizationInsightsUsageQueryInput, "seriesGroups">
+> & { seriesGroups?: boolean };
+/** workspaceId is intersected with the path workspace by the existing server gate. */
+export type WorkspaceInsightsUsageOptions = OrganizationInsightsUsageOptions;
+export type OrganizationInsightsCallsOptions = FilterOptions<OrganizationInsightsCallsQueryInput>;
+export type WorkspaceInsightsCallsOptions = OrganizationInsightsCallsOptions;
+export type InsightsCallsScope =
+  | { kind: "workspace"; workspaceId: string }
+  | { kind: "organization"; accountId: string };
+
+/** Arrays repeat; comma strings, false and opaque values round-trip unchanged. */
+export function insightsUsageQueryString(
+  options: OrganizationInsightsUsageOptions | OrganizationInsightsCallsOptions,
+): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined) continue;
+    for (const item of Array.isArray(value) ? value : [value]) params.append(key, String(item));
+  }
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}

package/src/interaction.ts

@@ -1,4 +1,22 @@
-import type { OpenGeniRequestOptions } from "./client";
+import type { ComputerNativeCallRequest, ComputerNativeReceipt } from "@opengeni/contracts";
+export type {
+  ComputerNativeCallRequest,
+  ComputerNativeReceipt,
+  ComputerOperationReceipt,
+} from "@opengeni/contracts";
+import type { InteractionSessionListOptions, 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";
 
@@ -54,7 +72,7 @@ export type InteractionControlFailure = {
   message: string;
 };
 
-/** Decodes the bounded typed control-failure details emitted by OpenGeni. Raw
+/** 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,
@@ -318,36 +336,14 @@ export type NetworkRouteMutationResponse = {
   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 SiteAuthAuthority = {
+  id: string;
+  kind: "external_provider";
+  label: string;
+  adapterId: string;
+  connectionId: string;
+  credential: InteractionCredentialAuthorityRef | null;
+};
 
 export type SiteAuthMethod = {
   id: string;
@@ -433,14 +429,12 @@ export type AuthRun = {
   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;
@@ -474,37 +468,11 @@ export type ReportAuthRunRequest = {
   expectedVersion: number;
   methodId?: string | undefined;
   authorityId?: string | undefined;
-  state:
-    | "awaiting_choice"
-    | "awaiting_secret"
-    | "awaiting_external_action"
-    | "working"
-    | "failed"
-    | "cancelled";
+  state: "awaiting_choice" | "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;
@@ -802,6 +770,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;
@@ -863,6 +842,15 @@ 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;
@@ -871,7 +859,13 @@ export type BrowserAction =
   | { type: "double_click"; locator: BrowserLocator }
   | { type: "hover"; locator: BrowserLocator }
   | { type: "fill"; locator: BrowserLocator; value: string }
-  | { type: "type"; locator?: BrowserLocator | undefined; text: string }
+  | {
+      type: "type";
+      locator?: BrowserLocator | undefined;
+      text: string;
+      /** `keys` sends one key press per character (split one-time-code boxes). */
+      mode?: "insert" | "keys" | undefined;
+    }
   | { type: "press"; locator?: BrowserLocator | undefined; key: string }
   | { type: "select"; locator: BrowserLocator; values: string[] }
   | { type: "check"; locator: BrowserLocator; checked: boolean }
@@ -919,7 +913,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:
@@ -941,6 +939,8 @@ export type InteractionError = {
     | "outcome_unknown"
     | "invalid_action"
     | "timeout"
+    | "tab_not_responding"
+    | "tab_crashed"
     | "controller_lost"
     | "driver_failed";
   message: string;
@@ -974,6 +974,7 @@ 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;
@@ -1018,13 +1019,16 @@ export type InteractionFrameStreamAttachment<RelayKind extends 3 | 4 = 3 | 4> =
 
 export type ComputerFrameStreamAttachment =
   | InteractionFrameStreamAttachment<4>
-  | { kind: "direct_rfb"; url: string; protocols: string[] };
+  | { 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;
 };
 
@@ -1037,10 +1041,15 @@ export type BrowserSessionAttachmentRequest = {
 export type BrowserActionRequest = {
   operationId: string;
   targetId: string;
-  expectedTargetGeneration: string;
-  expectedDocumentGeneration: string | null;
-  expectedFrameId: string | null;
-  observationMode?: "full" | "none" | undefined;
+  /** Omit the three fences to act on the target's current state; the API reads
+   * them from the live controller in the same request. */
+  expectedTargetGeneration?: string | undefined;
+  expectedDocumentGeneration?: string | null | undefined;
+  expectedFrameId?: string | null | undefined;
+  /** `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;
 };
 
@@ -1055,6 +1064,17 @@ export type BrowserActionReceipt = {
   settledAt: string | null;
   observation: BrowserObservation | null;
   error: InteractionError | null;
+  /** Elements the action's locators resolved to, in dispatch order. */
+  targets?: BrowserActionResolvedTarget[] | undefined;
+};
+
+export type BrowserActionResolvedTarget = {
+  actionIndex: number;
+  ref: string | null;
+  role: string;
+  name: string | null;
+  /** Nearest dialog, landmark, menu or toolbar around the element. */
+  container: { role: string; name: string | null } | null;
 };
 
 export type BrowserSessionHeartbeatResponse = {
@@ -1071,9 +1091,13 @@ export type ComputerSessionCapabilities = {
   screenCapture: boolean;
   semanticActions: boolean;
   pointerInput: boolean;
+  /** Causal count-2 input requires its exact confirmed first operation. Absent means unsupported. */
+  pointerClickContinuation?: boolean | undefined;
   keyboardInput: boolean;
   clipboard: boolean;
   backgroundActions: boolean;
+  /** Raw window input stays in the background. Absent means foreground-only. */
+  backgroundInput?: boolean | undefined;
   parallelApps: boolean;
 };
 
@@ -1172,6 +1196,9 @@ export type ComputerAction =
       deltaX?: number | undefined;
       deltaY?: number | undefined;
       button?: "left" | "right" | "middle" | undefined;
+      /** Click only; 2 delivers one second click pair after a completed first click. */
+      clickCount?: 1 | 2 | undefined;
+      continuationOfOperationId?: string | undefined;
     }
   | { type: "keyboard"; action: "type" | "press"; value: string }
   | {
@@ -1221,10 +1248,19 @@ export type ComputerSessionAttachment = {
   computerSessionId: string;
   controllerGeneration: string;
   targetId: string;
+  /** 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;
@@ -1327,13 +1363,6 @@ export interface InteractionTransport {
     request: ReportAuthRunRequest,
     options?: OpenGeniRequestOptions,
   ): Promise<AuthRunMutationResponse>;
-  protectedBrowserAuthFill(
-    workspaceId: string,
-    browserSessionId: string,
-    authRunId: string,
-    request: ProtectedAuthFillRequest,
-    options?: OpenGeniRequestOptions,
-  ): Promise<ProtectedAuthFillResponse>;
   advanceExternalBrowserAuthRun(
     workspaceId: string,
     browserSessionId: string,
@@ -1411,7 +1440,7 @@ export interface InteractionTransport {
   ): Promise<BrowserRevisionListResponse>;
   listBrowserSessions(
     workspaceId: string,
-    options?: OpenGeniRequestOptions,
+    options?: OpenGeniRequestOptions | InteractionSessionListOptions,
   ): Promise<BrowserSessionListResponse>;
   getBrowserSession(
     workspaceId: string,
@@ -1457,6 +1486,13 @@ export interface InteractionTransport {
     request?: BrowserOpenTargetRequest,
     options?: OpenGeniRequestOptions,
   ): Promise<BrowserObservation>;
+  /** Optional for custom transports predating metadata-only tab opening. */
+  openBrowserTargetWithInventory?(
+    workspaceId: string,
+    browserSessionId: string,
+    request?: BrowserOpenTargetRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<BrowserTargetListResponse>;
   selectBrowserTarget(
     workspaceId: string,
     browserSessionId: string,
@@ -1475,6 +1511,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,
@@ -1530,13 +1586,18 @@ export interface InteractionTransport {
   ): Promise<BrowserSessionMutationResponse>;
   listComputerSessions(
     workspaceId: string,
-    options?: OpenGeniRequestOptions,
+    options?: OpenGeniRequestOptions | InteractionSessionListOptions,
   ): Promise<ComputerSessionListResponse>;
   getComputerSession(
     workspaceId: string,
     computerSessionId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerSession>;
+  getComputerInputPosture?(
+    workspaceId: string,
+    computerSessionId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerSessionInputPosture>;
   readComputerClipboard(
     workspaceId: string,
     computerSessionId: string,
@@ -1558,12 +1619,30 @@ export interface InteractionTransport {
     targetId: string,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerObservation>;
+  captureComputerTarget(
+    workspaceId: string,
+    computerSessionId: string,
+    targetId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerFrame>;
+  callNativeComputerTool?(
+    workspaceId: string,
+    computerSessionId: string,
+    request: ComputerNativeCallRequest,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerNativeReceipt>;
   actInComputer(
     workspaceId: string,
     computerSessionId: string,
     request: ComputerActionRequest,
     options?: OpenGeniRequestOptions,
   ): Promise<ComputerActionReceipt>;
+  getNativeComputerToolReceipt?(
+    workspaceId: string,
+    computerSessionId: string,
+    operationId: string,
+    options?: OpenGeniRequestOptions,
+  ): Promise<ComputerNativeReceipt>;
   getComputerActionReceipt(
     workspaceId: string,
     computerSessionId: string,
@@ -1632,6 +1711,7 @@ export type CurrentOrOpenBrowserOptions = {
   name?: string | undefined;
   initialUrl?: string | undefined;
   headless?: boolean | undefined;
+  storageMode?: "private_profile" | "ephemeral_context" | undefined;
   placement?: InteractionPlacement | undefined;
   identityId?: string | undefined;
   baseRevisionId?: string | undefined;
@@ -1846,19 +1926,6 @@ export class AuthRunResource {
     );
   }
 
-  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 = {},
@@ -2031,7 +2098,7 @@ export class BrowserSessionCollection {
 
   async list(
     workspaceId: string,
-    options: OpenGeniRequestOptions = {},
+    options: OpenGeniRequestOptions | InteractionSessionListOptions = {},
   ): Promise<BrowserSessionListResponse> {
     return await this.transport.listBrowserSessions(workspaceId, options);
   }
@@ -2052,7 +2119,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") {
@@ -2071,6 +2144,7 @@ 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 } : {}),
@@ -2115,6 +2189,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 = {},
@@ -2337,7 +2454,7 @@ export class ComputerSessionCollection {
 
   async list(
     workspaceId: string,
-    options: OpenGeniRequestOptions = {},
+    options: OpenGeniRequestOptions | InteractionSessionListOptions = {},
   ): Promise<ComputerSessionListResponse> {
     return await this.transport.listComputerSessions(workspaceId, options);
   }
@@ -2402,6 +2519,19 @@ 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 callNativeTool(
+    request: ComputerNativeCallRequest,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerNativeReceipt> {
+    if (!this.transport.callNativeComputerTool)
+      throw new Error("Native CUA tools require a current interaction transport");
+    return await this.transport.callNativeComputerTool(this.workspaceId, this.id, request, options);
+  }
+
   async act(
     request: ComputerActionRequest,
     options: OpenGeniRequestOptions = {},
@@ -2409,6 +2539,20 @@ export class ComputerSessionResource {
     return await this.transport.actInComputer(this.workspaceId, this.id, request, options);
   }
 
+  async nativeReceipt(
+    operationId: string,
+    options: OpenGeniRequestOptions = {},
+  ): Promise<ComputerNativeReceipt> {
+    if (!this.transport.getNativeComputerToolReceipt)
+      throw new Error("Native CUA receipts require a current interaction transport");
+    return await this.transport.getNativeComputerToolReceipt(
+      this.workspaceId,
+      this.id,
+      operationId,
+      options,
+    );
+  }
+
   async receipt(
     operationId: string,
     options: OpenGeniRequestOptions = {},
@@ -2428,6 +2572,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);
   }
@@ -2495,6 +2646,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;
@@ -2791,6 +2950,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,