@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/dist/interaction.d.ts

@@ -1,4 +1,8 @@
-import type { OpenGeniRequestOptions } from "./client.js";
+import type { ComputerNativeCallRequest, ComputerNativeReceipt } from "@opengeni/contracts";
+export type { ComputerNativeCallRequest, ComputerNativeReceipt, ComputerOperationReceipt, } from "@opengeni/contracts";
+import type { InteractionSessionListOptions, OpenGeniRequestOptions } from "./client.js";
+import type { BrowserDomReadRequest, BrowserDomReadResponse, BrowserTargetState } from "@opengeni/contracts";
+export type { BrowserDomReadRequest, BrowserDomReadResponse, BrowserDomSafeAttribute, BrowserTargetState, } from "@opengeni/contracts";
 import type { RetainedArtifactReference } from "./types.js";
 /** Public Browser/Computer protocol version. Driver and provider details stay private. */
 export declare const INTERACTION_PROTOCOL_VERSION: 1;
@@ -31,7 +35,7 @@ export type InteractionControlFailure = {
     controlRequestId: string | undefined;
     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 declare function interactionControlFailureFromError(error: unknown): InteractionControlFailure | null;
 export type InteractionPlacement = {
@@ -234,29 +238,7 @@ export type NetworkRouteMutationResponse = {
     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;
@@ -340,17 +322,12 @@ export type AuthRun = {
     purpose: "authenticate" | "health_check" | "repair";
     methodId: string | null;
     authorityId: string | null;
-    state: "discovering" | "awaiting_choice" | "awaiting_secret" | "awaiting_external_action" | "working" | "verified" | "failed" | "cancelled";
+    state: "discovering" | "awaiting_choice" | "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;
@@ -389,40 +366,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;
@@ -691,6 +639,14 @@ 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;
@@ -747,6 +703,17 @@ 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;
@@ -765,6 +732,8 @@ export type BrowserAction = {
     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;
@@ -824,9 +793,10 @@ export type BrowserAction = {
 export type BrowserActionBatch = {
     type: "batch";
     actions: BrowserAction[];
+    fenceEachAction?: true | undefined;
 };
 export type InteractionError = {
-    code: "resource_not_found" | "resource_unavailable" | "controller_stale" | "target_not_found" | "target_stale" | "observation_stale" | "document_stale" | "frame_stale" | "locator_not_found" | "locator_ambiguous" | "unsupported" | "permission_denied" | "machine_locked" | "attempt_stale" | "operation_conflict" | "outcome_unknown" | "invalid_action" | "timeout" | "controller_lost" | "driver_failed";
+    code: "resource_not_found" | "resource_unavailable" | "controller_stale" | "target_not_found" | "target_stale" | "observation_stale" | "document_stale" | "frame_stale" | "locator_not_found" | "locator_ambiguous" | "unsupported" | "permission_denied" | "machine_locked" | "attempt_stale" | "operation_conflict" | "outcome_unknown" | "invalid_action" | "timeout" | "tab_not_responding" | "tab_crashed" | "controller_lost" | "driver_failed";
     message: string;
     retryable: boolean;
     details?: Record<string, InteractionJsonValue> | undefined;
@@ -850,6 +820,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;
@@ -864,10 +835,75 @@ export type BrowserSessionListResponse = {
 export type BrowserSessionMutationResponse = {
     session: BrowserSession;
     operation: InteractionLifecycleOperationReceipt;
+    /** Present only on a create that launched the browser in this request. */
+    initialView?: {
+        targets: BrowserTarget[];
+        observation: BrowserObservation;
+    } | undefined;
 };
 export type BrowserSessionLifecycleRequest = {
     operationId: string;
 };
+/** Why a browser's preserved working copy cannot be adopted as it is. */
+export type BrowserWorkingCopyRefusal = "unsupported_platform" | "unsupported_browser" | "browser_running" | "working_copy_invalid" | "receipt_not_adoptable" | "authority_changed" | "process_state_unknown" | "adoption_not_needed" | "adoption_unresolved";
+/** One adoption of a copied working directory, as its controller recorded it. */
+export type BrowserWorkingCopyAdoption = {
+    operationId: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    manifestDigest: string;
+    phase: "intent" | "copied" | "receipt" | "source_preserved" | "adopted" | "interrupted" | "failed" | "collision" | "reverting" | "reverted";
+    failureCode: string | null;
+    retainedDirectories: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+/** Evidence about a browser's preserved working copy after its controller lost
+ * it. Freshness is never machine-proven. */
+export type BrowserWorkingCopyInspection = {
+    browserSessionId: string;
+    controllerGeneration: string;
+    adoptable: boolean;
+    refusal: BrowserWorkingCopyRefusal | null;
+    explanation: string;
+    /** `excluded` lists the controller-owned derived entries left out of the
+     * copy (journal shared-memory indexes and the per-launch launcher folder). */
+    manifest: {
+        digest: string;
+        entries: number;
+        bytes: number;
+        excluded: string[];
+    } | null;
+    platformSupported: boolean;
+    profileIdentityMatches: boolean;
+    profileInUse: boolean | null;
+    receipt: {
+        operationId: string;
+        intent: "launch" | "suspend" | "retire" | "adopt";
+        state: string;
+        directoryLaunchAllowed: boolean;
+        authorityMatches: boolean;
+        launchedFromCheckpoint: boolean;
+        adoption: {
+            operationId: string;
+            manifestDigest: string;
+        } | null;
+    } | null;
+    freshness: {
+        status: "unknown";
+        latestCheckpointAt: string | null;
+    };
+    activeAdoption: BrowserWorkingCopyAdoption | null;
+};
+export type BrowserWorkingCopyAdoptionRequest = {
+    operationId: string;
+    manifestDigest: string;
+};
+export type BrowserWorkingCopyAdoptionResponse = {
+    inFlight: boolean;
+    adoption: BrowserWorkingCopyAdoption | null;
+    explanation: string;
+};
 export type BrowserOpenTargetRequest = {
     url?: string | undefined;
 };
@@ -896,12 +932,16 @@ 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;
 };
 export type BrowserSessionAttachmentRequest = {
@@ -912,10 +952,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;
 };
 export type BrowserActionReceipt = {
@@ -929,6 +974,19 @@ 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 = {
     browserSessionId: string;
@@ -943,9 +1001,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;
 };
 export type ComputerClipboard = {
@@ -1034,6 +1096,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";
@@ -1083,9 +1148,17 @@ 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;
@@ -1136,7 +1209,6 @@ export interface InteractionTransport {
     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>;
@@ -1151,7 +1223,7 @@ export interface InteractionTransport {
     createBrowserIdentity(workspaceId: string, request: CreateBrowserIdentityRequest, options?: OpenGeniRequestOptions): Promise<BrowserIdentityMutationResponse>;
     updateBrowserIdentity(workspaceId: string, identityId: string, request: UpdateBrowserIdentityRequest, options?: OpenGeniRequestOptions): Promise<BrowserIdentityMutationResponse>;
     listBrowserRevisions(workspaceId: string, identityId: string, options?: OpenGeniRequestOptions): Promise<BrowserRevisionListResponse>;
-    listBrowserSessions(workspaceId: string, options?: OpenGeniRequestOptions): Promise<BrowserSessionListResponse>;
+    listBrowserSessions(workspaceId: string, options?: OpenGeniRequestOptions | InteractionSessionListOptions): Promise<BrowserSessionListResponse>;
     getBrowserSession(workspaceId: string, browserSessionId: string, options?: OpenGeniRequestOptions): Promise<BrowserSession>;
     readBrowserClipboard(workspaceId: string, browserSessionId: string, options?: OpenGeniRequestOptions): Promise<BrowserClipboard>;
     listBrowserDownloads(workspaceId: string, browserSessionId: string, options?: OpenGeniRequestOptions): Promise<BrowserDownloadListResponse>;
@@ -1160,9 +1232,14 @@ export interface InteractionTransport {
     createBrowserSession(workspaceId: string, request: CreateBrowserSessionRequest, options?: OpenGeniRequestOptions): Promise<BrowserSessionMutationResponse>;
     listBrowserTargets(workspaceId: string, browserSessionId: string, options?: OpenGeniRequestOptions): Promise<BrowserTargetListResponse>;
     openBrowserTarget(workspaceId: string, browserSessionId: string, 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, targetId: string, options?: OpenGeniRequestOptions): Promise<BrowserObservation>;
     closeBrowserTarget(workspaceId: string, browserSessionId: string, targetId: string, options?: OpenGeniRequestOptions): Promise<BrowserTargetListResponse>;
     observeBrowserTarget(workspaceId: string, browserSessionId: string, 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, request: BrowserActionRequest, options?: OpenGeniRequestOptions): Promise<BrowserActionReceipt>;
     getBrowserActionReceipt(workspaceId: string, browserSessionId: string, operationId: string, options?: OpenGeniRequestOptions): Promise<BrowserActionReceipt>;
     listBrowserDiagnostics(workspaceId: string, browserSessionId: string, targetId: string, options?: BrowserDiagnosticsOptions): Promise<BrowserDiagnosticBatch>;
@@ -1172,14 +1249,17 @@ export interface InteractionTransport {
     suspendBrowserSession(workspaceId: string, browserSessionId: string, request: BrowserSessionLifecycleRequest, options?: OpenGeniRequestOptions): Promise<BrowserSessionMutationResponse>;
     resumeBrowserSession(workspaceId: string, browserSessionId: string, request: BrowserSessionLifecycleRequest, options?: OpenGeniRequestOptions): Promise<BrowserSessionMutationResponse>;
     endBrowserSession(workspaceId: string, browserSessionId: string, request: BrowserSessionLifecycleRequest, options?: OpenGeniRequestOptions): Promise<BrowserSessionMutationResponse>;
-    listComputerSessions(workspaceId: string, options?: OpenGeniRequestOptions): Promise<ComputerSessionListResponse>;
+    listComputerSessions(workspaceId: string, 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, options?: OpenGeniRequestOptions): Promise<ComputerClipboard>;
     createComputerSession(workspaceId: string, request: CreateComputerSessionRequest, options?: OpenGeniRequestOptions): Promise<ComputerSessionMutationResponse>;
     listComputerTargets(workspaceId: string, computerSessionId: string, options?: OpenGeniRequestOptions): Promise<ComputerTargetListResponse>;
     observeComputerTarget(workspaceId: string, computerSessionId: string, 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, operationId: string, options?: OpenGeniRequestOptions): Promise<ComputerActionReceipt>;
     attachComputerSession(workspaceId: string, computerSessionId: string, request: ComputerSessionAttachmentRequest, options?: OpenGeniRequestOptions): Promise<ComputerSessionAttachment>;
     heartbeatComputerSession(workspaceId: string, computerSessionId: string, options?: OpenGeniRequestOptions): Promise<ComputerSessionHeartbeatResponse>;
@@ -1220,6 +1300,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;
@@ -1301,7 +1382,6 @@ export declare class AuthRunResource {
     constructor(transport: BrowserInteractionTransport, workspaceId: string, browserSessionId: string, id: string);
     get(options?: OpenGeniRequestOptions): Promise<AuthRun>;
     report(request: ReportAuthRunRequest, options?: OpenGeniRequestOptions): Promise<AuthRunMutationResponse>;
-    protectedFill(request: ProtectedAuthFillRequest, options?: OpenGeniRequestOptions): Promise<ProtectedAuthFillResponse>;
     advanceExternal(request: ExternalAuthRunRequest, options?: OpenGeniRequestOptions): Promise<ExternalAuthRunResponse>;
     /** Human-session helper. Hosted provider URLs never appear in model tools. */
     openExternalFlow(request: ExternalAuthInteractiveRequest, options?: OpenGeniRequestOptions): Promise<ExternalAuthInteractiveResponse>;
@@ -1354,7 +1434,7 @@ export declare class BrowserIdentityResource {
 export declare class BrowserSessionCollection {
     private readonly transport;
     constructor(transport: BrowserInteractionTransport);
-    list(workspaceId: string, options?: OpenGeniRequestOptions): Promise<BrowserSessionListResponse>;
+    list(workspaceId: string, options?: OpenGeniRequestOptions | InteractionSessionListOptions): Promise<BrowserSessionListResponse>;
     session(workspaceId: string, browserSessionId: string): BrowserSessionResource;
     open(workspaceId: string, request: CreateBrowserSessionRequest, options?: OpenGeniRequestOptions): Promise<BrowserSessionResource>;
     currentOrOpen(options: CurrentOrOpenBrowserOptions): Promise<BrowserSessionResource>;
@@ -1372,6 +1452,10 @@ export declare class BrowserSessionResource {
     constructor(transport: BrowserInteractionTransport, workspaceId: string, id: string);
     get(options?: OpenGeniRequestOptions): Promise<BrowserSession>;
     observe(targetId: string, options?: OpenGeniRequestOptions): Promise<BrowserObservation>;
+    targetState(targetId: string, options?: OpenGeniRequestOptions): Promise<BrowserTargetState>;
+    readDom(targetId: string, request: BrowserDomReadRequest, options?: OpenGeniRequestOptions): Promise<BrowserDomReadResponse>;
+    capture(targetId: string, options?: OpenGeniRequestOptions, captureOptions?: BrowserScreenshotOptions): Promise<BrowserFrame>;
+    screenshot(targetId: string, captureOptions?: BrowserScreenshotOptions, options?: OpenGeniRequestOptions): Promise<BrowserFrame>;
     act(request: BrowserActionRequest, options?: OpenGeniRequestOptions): Promise<BrowserActionReceipt>;
     receipt(operationId: string, options?: OpenGeniRequestOptions): Promise<BrowserActionReceipt>;
     diagnostics(targetId: string, options?: BrowserDiagnosticsOptions): Promise<BrowserDiagnosticBatch>;
@@ -1422,7 +1506,7 @@ export declare class BrowserTargetCollection {
 export declare class ComputerSessionCollection {
     private readonly transport;
     constructor(transport: BrowserInteractionTransport);
-    list(workspaceId: string, options?: OpenGeniRequestOptions): Promise<ComputerSessionListResponse>;
+    list(workspaceId: string, options?: OpenGeniRequestOptions | InteractionSessionListOptions): Promise<ComputerSessionListResponse>;
     session(workspaceId: string, computerSessionId: string): ComputerSessionResource;
     open(workspaceId: string, request: CreateComputerSessionRequest, options?: OpenGeniRequestOptions): Promise<ComputerSessionResource>;
     currentOrOpen(options: CurrentOrOpenComputerOptions): Promise<ComputerSessionResource>;
@@ -1439,9 +1523,12 @@ export declare class ComputerSessionResource {
     get(options?: OpenGeniRequestOptions): Promise<ComputerSession>;
     observe(targetId: string, options?: OpenGeniRequestOptions): Promise<ComputerObservation>;
     capture(targetId: string, options?: OpenGeniRequestOptions): Promise<ComputerFrame>;
+    callNativeTool(request: ComputerNativeCallRequest, options?: OpenGeniRequestOptions): Promise<ComputerNativeReceipt>;
     act(request: ComputerActionRequest, options?: OpenGeniRequestOptions): Promise<ComputerActionReceipt>;
+    nativeReceipt(operationId: string, options?: OpenGeniRequestOptions): Promise<ComputerNativeReceipt>;
     receipt(operationId: string, options?: OpenGeniRequestOptions): Promise<ComputerActionReceipt>;
     attach(request: ComputerSessionAttachmentRequest, options?: OpenGeniRequestOptions): Promise<ComputerSessionAttachment>;
+    inputPosture(options?: OpenGeniRequestOptions): Promise<ComputerSessionInputPosture>;
     heartbeat(options?: OpenGeniRequestOptions): Promise<ComputerSessionHeartbeatResponse>;
     end(request?: ComputerSessionLifecycleRequest, options?: OpenGeniRequestOptions): Promise<ComputerSessionMutationResponse>;
 }
@@ -1478,6 +1565,13 @@ 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;

package/dist/interaction.js

@@ -39,8 +39,8 @@ import {
   interactionControlFailureFromError,
   parseBrowserFrameMetadata,
   parseComputerFrameMetadata
-} from "./chunk-QTBAMHEF.js";
-import "./chunk-OO5LPTO7.js";
+} from "./chunk-YJCHB7R3.js";
+import "./chunk-7EWT3PV6.js";
 export {
   AttachedBrowserDeviceCollection,
   AttachedBrowserDeviceResource,

package/dist/knowledge.d.ts

@@ -0,0 +1,7 @@
+export type { AgentLearningMode, AgentLearningCategory, AgentLearningDefaults, AgentLearningOverrides, AgentLearningContext, AgentLearningOverridePatch, AgentLearningSettingsRecord, AgentLearningOverrideRecord, SaveAgentLearningSettingsRequest, KnowledgeFilePreparationResult, KnowledgeSavePreparationRequest, KnowledgeSavePreparationResponse, KnowledgeOriginalFileDownload, KnowledgeEntryKind, KnowledgeEntryScope, KnowledgeIndexStatus, KnowledgeEntryContent, KnowledgeEntrySource, KnowledgeEntryEvidence, KnowledgeEntryRelationship, KnowledgeEntryRecord, KnowledgeEntrySummary, KnowledgeEntrySaveRequest, KnowledgeEntryReviewRequest, KnowledgeEntryBatchReviewRequest, KnowledgeEntryRestoreRequest, KnowledgeEntryWriteReceipt, KnowledgeEntryListRequest, KnowledgeEntryListResponse, KnowledgeReviewBatch, KnowledgeReviewBatchListRequest, KnowledgeReviewBatchListResponse, AgentInstructionReviewRequest, AgentInstructionReceipt, AgentInstructionReviewItem, AgentInstructionReviewListResponse, } from "@opengeni/contracts";
+import type { OpenGeniClient } from "./client.js";
+import type { KnowledgeSavePreparationRequest, KnowledgeSavePreparationResponse, KnowledgeFilePreparationResult } from "@opengeni/contracts";
+/** Agent-only source preparation is a focused transport surface, outside the browser client. */
+export declare function prepareKnowledgeFile(client: Pick<OpenGeniClient, "requestJson">, workspaceId: string, fileId: string, purpose?: "evidence" | "reference"): Promise<KnowledgeFilePreparationResult>;
+/** Read-only collection/duplicate discovery for a live selected agent or human Knowledge reviewer. */
+export declare function prepareKnowledgeSave(client: Pick<OpenGeniClient, "requestJson">, workspaceId: string, request: KnowledgeSavePreparationRequest): Promise<KnowledgeSavePreparationResponse>;

package/dist/knowledge.js

@@ -0,0 +1,20 @@
+// src/knowledge.ts
+async function prepareKnowledgeFile(client, workspaceId, fileId, purpose) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/files/${encodeURIComponent(fileId)}/prepare`,
+    purpose ? { purpose } : void 0
+  );
+}
+async function prepareKnowledgeSave(client, workspaceId, request) {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/entries/prepare-save`,
+    request
+  );
+}
+export {
+  prepareKnowledgeFile,
+  prepareKnowledgeSave
+};
+//# sourceMappingURL=knowledge.js.map

package/dist/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/knowledge.ts"],"sourcesContent":["export type {\n  AgentLearningMode,\n  AgentLearningCategory,\n  AgentLearningDefaults,\n  AgentLearningOverrides,\n  AgentLearningContext,\n  AgentLearningOverridePatch,\n  AgentLearningSettingsRecord,\n  AgentLearningOverrideRecord,\n  SaveAgentLearningSettingsRequest,\n  KnowledgeFilePreparationResult,\n  KnowledgeSavePreparationRequest,\n  KnowledgeSavePreparationResponse,\n  KnowledgeOriginalFileDownload,\n  KnowledgeEntryKind,\n  KnowledgeEntryScope,\n  KnowledgeIndexStatus,\n  KnowledgeEntryContent,\n  KnowledgeEntrySource,\n  KnowledgeEntryEvidence,\n  KnowledgeEntryRelationship,\n  KnowledgeEntryRecord,\n  KnowledgeEntrySummary,\n  KnowledgeEntrySaveRequest,\n  KnowledgeEntryReviewRequest,\n  KnowledgeEntryBatchReviewRequest,\n  KnowledgeEntryRestoreRequest,\n  KnowledgeEntryWriteReceipt,\n  KnowledgeEntryListRequest,\n  KnowledgeEntryListResponse,\n  KnowledgeReviewBatch,\n  KnowledgeReviewBatchListRequest,\n  KnowledgeReviewBatchListResponse,\n  AgentInstructionReviewRequest,\n  AgentInstructionReceipt,\n  AgentInstructionReviewItem,\n  AgentInstructionReviewListResponse,\n} from \"@opengeni/contracts\";\n\nimport type { OpenGeniClient } from \"./client\";\nimport type {\n  KnowledgeSavePreparationRequest,\n  KnowledgeSavePreparationResponse,\n  KnowledgeFilePreparationResult,\n} from \"@opengeni/contracts\";\n\n/** Agent-only source preparation is a focused transport surface, outside the browser client. */\nexport async function prepareKnowledgeFile(\n  client: Pick<OpenGeniClient, \"requestJson\">,\n  workspaceId: string,\n  fileId: string,\n  purpose?: \"evidence\" | \"reference\",\n): Promise<KnowledgeFilePreparationResult> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/files/${encodeURIComponent(fileId)}/prepare`,\n    purpose ? { purpose } : undefined,\n  );\n}\n\n/** Read-only collection/duplicate discovery for a live selected agent or human Knowledge reviewer. */\nexport async function prepareKnowledgeSave(\n  client: Pick<OpenGeniClient, \"requestJson\">,\n  workspaceId: string,\n  request: KnowledgeSavePreparationRequest,\n): Promise<KnowledgeSavePreparationResponse> {\n  return client.requestJson(\n    \"POST\",\n    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/entries/prepare-save`,\n    request,\n  );\n}\n"],"mappings":";AA+CA,eAAsB,qBACpB,QACA,aACA,QACA,SACyC;AACzC,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,kBAAkB,mBAAmB,WAAW,CAAC,oBAAoB,mBAAmB,MAAM,CAAC;AAAA,IAC/F,UAAU,EAAE,QAAQ,IAAI;AAAA,EAC1B;AACF;AAGA,eAAsB,qBACpB,QACA,aACA,SAC2C;AAC3C,SAAO,OAAO;AAAA,IACZ;AAAA,IACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,IACjD;AAAA,EACF;AACF;","names":[]}

package/dist/known-tools.d.ts

@@ -0,0 +1,4 @@
+import { type OpenGeniToolTransport, type OpenGeniWorkspaceTools } from "./tools.js";
+export declare const isToolDefinitionStale: (error: unknown) => boolean;
+/** Per-facade metadata only. Never coalesce invocations or retain credentials. */
+export declare function createKnownWorkspaceTools(transport: OpenGeniToolTransport, workspaceId: string, createLegacy: () => OpenGeniWorkspaceTools): OpenGeniWorkspaceTools;

package/dist/message-links.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Links an agent writes into chat Markdown that point at Opengeni-owned objects.
+ *
+ * Agents write these forms (tool receipts and bundled Skills teach them):
+ *
+ * - `artifact:<file uuid>` — a retained workspace file (exports, published files, images).
+ * - `sandbox:<path>[:<line>]` — a file in the session's sandbox or Connected Machine.
+ * - `/workspaces/<ws>/artifacts/editable/<32-hex id>` — a live editable document,
+ *   workbook, or presentation.
+ * - `/workspaces/<ws>/artifacts/<uuid>` — a saved Site / published HTML artifact.
+ * - `/workspaces/<ws>/artifacts/files/<uuid>` — a retained file (console path form).
+ *
+ * None of them is a URL a browser can navigate on its own: the `/workspaces/...`
+ * forms are Opengeni console routes, so inside another product they resolve
+ * against that product's origin and 404. Parse them with {@link parseOpenGeniLink}
+ * and route each target to the host's own UI (download, panel, page).
+ */
+export type OpenGeniLinkTarget = {
+    kind: "file";
+    fileId: string;
+    workspaceId: string | null;
+    fromSession?: string;
+} | {
+    kind: "editable-artifact";
+    artifactId: string;
+    workspaceId: string;
+    fromSession?: string;
+} | {
+    kind: "site";
+    artifactId: string;
+    workspaceId: string;
+    fromSession?: string;
+} | {
+    kind: "sandbox-file";
+    path: string;
+    line: number | null;
+};
+/** Application scheme names are case-insensitive, unlike their payloads. */
+export declare function openGeniLinkScheme(href: string | undefined): "artifact" | "sandbox" | null;
+/** Reserved references must never fall back to navigation on a host origin. */
+export declare function isReservedOpenGeniLink(href: string | undefined): boolean;
+/**
+ * Parse an Opengeni `sandbox:` href (plus the historical bare `/workspace/...`
+ * form). The decoded path is intentionally opaque: target selection, path
+ * policy, and filesystem authority belong to the session-aware host.
+ */
+export declare function parseSandboxLink(href: string | undefined): {
+    path: string;
+    line: number | null;
+} | null;
+/** Return the retained-file id of an exact `artifact:<uuid>` reference. */
+export declare function parseRetainedFileReference(href: string | undefined): string | null;
+/**
+ * Classify an agent-authored Markdown href. Returns `null` for ordinary links
+ * (`https://…`, `mailto:`, relative host links), which render as-is.
+ *
+ * Only root-relative console paths are recognized; an absolute URL is always an
+ * ordinary link, so a host's own `https://` routes are never reinterpreted.
+ * A validated `?fromSession=<uuid>` return hint is preserved.
+ */
+export declare function parseOpenGeniLink(href: string | undefined): OpenGeniLinkTarget | null;
+/** The Opengeni console route for a target (the form agents write). */
+export declare function openGeniConsolePath(target: OpenGeniLinkTarget, workspaceId: string): string | null;
+/**
+ * Request header naming the session an embedded artifact read belongs to.
+ * `createSessionProxyHandler` only serves artifacts Opengeni lists for it.
+ */
+export declare const SESSION_SCOPE_HEADER = "x-opengeni-session-id";

package/dist/model-context.d.ts

@@ -0,0 +1,68 @@
+export type ModelContextInstructionLayerId = "operational_contract" | "persona_and_core" | "workspace_governance" | "session_instructions" | "workspace_memory" | "skill_catalog" | "codemode" | "code_search" | "git_bindings" | "builtin_skills" | "genesis_title" | "sdk_capability_instructions" | "sandbox_preamble" | "sandbox_filesystem" | "sent_system_instructions" | "identity";
+/** Sections of a modular operational contract, in composition order. */
+export type AgentPromptModuleId = "base_behavior" | "runtime_mechanics" | "renderer_markdown" | "sandbox" | "connected_machine" | "repositories" | "workspace_environment" | "rig" | "artifacts" | "media" | "goals" | "subagents" | "knowledge" | "skills" | "secrets" | "admin" | "attachments";
+export type ModelContextInstructionModule = {
+    id: AgentPromptModuleId;
+    chars: number;
+};
+export type ModelContextInstructionLayer = {
+    id: ModelContextInstructionLayerId;
+    title: string;
+    content: string;
+    utf8Bytes: number;
+    estimatedTokens: number;
+    /** Present on the operational contract of sessions with an agent configuration. */
+    modules?: ModelContextInstructionModule[] | undefined;
+};
+export type ModelContextToolVisibility = "eager" | "searchable";
+export type ModelContextTool = {
+    name: string;
+    type: string;
+    visibility: ModelContextToolVisibility;
+    description?: string | undefined;
+    namespace?: string | undefined;
+    schema?: unknown | undefined;
+    utf8Bytes: number;
+    estimatedTokens: number;
+};
+export type ModelContextSkillKind = "preference_descriptor" | "runtime_skill" | "native_tool_skill";
+export type ModelContextSkill = {
+    kind: ModelContextSkillKind;
+    name: string;
+    description: string;
+    source?: string | undefined;
+    path?: string | undefined;
+};
+export type ModelContextTokenCounts = {
+    instructions: number;
+    tools: number;
+    prefix: number;
+};
+export type ModelContextSnapshot = {
+    providerRequest?: {
+        provider: string;
+        body: string | null;
+        unavailableReason?: string | undefined;
+        parts: {
+            key: string;
+            estimatedTokens: number | null;
+            utf8Bytes: number;
+            itemEstimatedTokens?: (number | null)[] | undefined;
+        }[];
+    } | undefined;
+    version: 1;
+    capturedAt: string;
+    source: "model_request";
+    requestIndex: number;
+    instructions: string;
+    layers: ModelContextInstructionLayer[];
+    tools: ModelContextTool[];
+    skills: ModelContextSkill[];
+    tokens: ModelContextTokenCounts;
+};
+export type SessionModelContextResponse = {
+    sessionId: string;
+    attemptId: string | null;
+    turnId: string | null;
+    snapshot: ModelContextSnapshot | null;
+};