@trycua/cua-driver 0.12.5 → 0.14.0

package/README.md

@@ -32,8 +32,10 @@ agent SDK.
 import {
   CaptureScope,
   CuaDriver,
+  CursorReducedMotion,
   EndSessionInput,
   GetDesktopStateInput,
+  SetAgentCursorThemeInput,
   StartSessionInput,
 } from "@trycua/cua-driver"
 
@@ -46,6 +48,13 @@ await driver.startSession(
 )
 
 try {
+  await driver.setAgentCursorTheme(
+    SetAgentCursorThemeInput.new({
+      session: "demo",
+      themeId: "cua.default",
+      reducedMotion: CursorReducedMotion.Auto,
+    }),
+  )
   const desktop = await driver.getDesktopState(
     GetDesktopStateInput.new({ session: "demo" }),
   )
@@ -64,6 +73,30 @@ images, verification/error metadata, and `structuredJson` / `rawJson` for
 platform-extensible results. Session lifecycle calls return dedicated generated
 records.
 
+The agent cursor is session-owned. Its default theme and custom dotLottie
+authoring workflow are documented in
+[`docs/cursor-themes.md`](../docs/cursor-themes.md). Custom source is compiled
+and installed with the local CLI; SDK and MCP tools select only an installed
+theme ID. The built-in cursor shows the sanitized public session name in a
+badge below the pointer.
+
+## Authorization integrations
+
+`standard` is promptless for normal automation. An application that needs to
+authorize attachment to an existing logged-in Chromium profile can construct a
+configured runtime with
+`CuaDriver.createConfiguredWithAuthorizationHost(options, host)`. Implement
+the `DriverAuthorizationHost` interface in trusted application code and return
+the request's exact digest with `Allow`, `Deny`, or `Cancel`.
+
+`CuaDriver.createConfiguredWithActivityObserver(options, observer)` emits
+content-free action, refusal, grant, and session events. The observer cannot
+change authorization or tool results. Use
+`createConfiguredWithHostIntegrations` when the application needs both.
+
+See the [SDK reference](https://cua.ai/docs/reference/cua-driver/sdk-reference)
+for complete examples and the callback trust rules.
+
 `CuaDriver.connect(socketPath)` remains available while existing applications
 migrate. It exposes the same methods over the installed daemon, but it does not
 provide a second SDK contract.

package/dist/index.js

@@ -9,6 +9,11 @@ import { CuaDriver, SdkClientKind } from "./native/cua_driver_sdk.js";
 // both the canonical same-process constructor and the temporary daemon
 // compatibility constructor with the importing runtime.
 CuaDriver.create = (options) => CuaDriver.createWithClientKind(options, SdkClientKind.Typescript);
+CuaDriver.createConfigured = (options) => CuaDriver.createConfiguredWithClientKind(options, SdkClientKind.Typescript);
+CuaDriver.createConfiguredWithAuthorizationHost = (options, host) => CuaDriver.createConfiguredWithAuthorizationHostAndClientKind(options, host, SdkClientKind.Typescript);
+CuaDriver.createConfiguredWithActivityObserver = (options, observer) => CuaDriver.createConfiguredWithActivityObserverAndClientKind(options, observer, SdkClientKind.Typescript);
+CuaDriver.createConfiguredWithHostIntegrations = (options, host, observer) => CuaDriver.createConfiguredWithHostIntegrationsAndClientKind(options, host, observer, SdkClientKind.Typescript);
+CuaDriver.createPrivateWorker = (options) => CuaDriver.createPrivateWorkerWithClientKind(options, SdkClientKind.Typescript);
 CuaDriver.connect = (socketPath) => CuaDriver.connectWithClientKind(socketPath, SdkClientKind.Typescript);
 export * from "./native/index.js";
 export { default } from "./native/index.js";

package/dist/native/cua_driver_contract.d.ts

@@ -26,6 +26,99 @@ export declare const ClickInput: Readonly<{
     new: (partial: Partial<ClickInput> & Required<Omit<ClickInput, "session" | "button" | "count">>) => ClickInput;
     defaults: () => Partial<ClickInput>;
 }>;
+export type CursorMotionOutput = {
+    startHandle: number;
+    endHandle: number;
+    arcSize: number;
+    arcFlow: number;
+    spring: number;
+    glideDurationMs: number;
+    dwellAfterClickMs: number;
+    idleHideMs: number;
+    turnRadius: number;
+};
+/**
+ * Generated factory for {@link CursorMotionOutput} record objects.
+ */
+export declare const CursorMotionOutput: Readonly<{
+    create: (partial: Partial<CursorMotionOutput> & Required<Omit<CursorMotionOutput, never>>) => CursorMotionOutput;
+    new: (partial: Partial<CursorMotionOutput> & Required<Omit<CursorMotionOutput, never>>) => CursorMotionOutput;
+    defaults: () => Partial<CursorMotionOutput>;
+}>;
+export type CursorPointOutput = {
+    x: number;
+    y: number;
+};
+/**
+ * Generated factory for {@link CursorPointOutput} record objects.
+ */
+export declare const CursorPointOutput: Readonly<{
+    create: (partial: Partial<CursorPointOutput> & Required<Omit<CursorPointOutput, never>>) => CursorPointOutput;
+    new: (partial: Partial<CursorPointOutput> & Required<Omit<CursorPointOutput, never>>) => CursorPointOutput;
+    defaults: () => Partial<CursorPointOutput>;
+}>;
+export declare enum CursorReducedMotion {
+    Auto = 0,
+    On = 1,
+    Off = 2
+}
+export type CursorThemeOutput = {
+    id: string;
+    version: string;
+    profile: string;
+    reducedMotion: CursorReducedMotion;
+    fallback?: string;
+};
+/**
+ * Generated factory for {@link CursorThemeOutput} record objects.
+ */
+export declare const CursorThemeOutput: Readonly<{
+    create: (partial: Partial<CursorThemeOutput> & Required<Omit<CursorThemeOutput, "fallback">>) => CursorThemeOutput;
+    new: (partial: Partial<CursorThemeOutput> & Required<Omit<CursorThemeOutput, "fallback">>) => CursorThemeOutput;
+    defaults: () => Partial<CursorThemeOutput>;
+}>;
+export type CursorThemeSelection = {
+    themeId: string;
+    reducedMotion: CursorReducedMotion;
+};
+/**
+ * Generated factory for {@link CursorThemeSelection} record objects.
+ */
+export declare const CursorThemeSelection: Readonly<{
+    create: (partial: Partial<CursorThemeSelection> & Required<Omit<CursorThemeSelection, never>>) => CursorThemeSelection;
+    new: (partial: Partial<CursorThemeSelection> & Required<Omit<CursorThemeSelection, never>>) => CursorThemeSelection;
+    defaults: () => Partial<CursorThemeSelection>;
+}>;
+export declare enum CursorAction {
+    Idle = 0,
+    Observe = 1,
+    Click = 2,
+    Drag = 3,
+    Scroll = 4,
+    Text = 5,
+    Key = 6,
+    Navigate = 7,
+    App = 8,
+    Transfer = 9,
+    Record = 10,
+    System = 11
+}
+export type CursorVisualOutput = {
+    requestedAction: CursorAction;
+    resolvedAction: CursorAction;
+    modifiers: Array<string>;
+    phase: string;
+    frame: bigint;
+    preemptedCount: bigint;
+};
+/**
+ * Generated factory for {@link CursorVisualOutput} record objects.
+ */
+export declare const CursorVisualOutput: Readonly<{
+    create: (partial: Partial<CursorVisualOutput> & Required<Omit<CursorVisualOutput, never>>) => CursorVisualOutput;
+    new: (partial: Partial<CursorVisualOutput> & Required<Omit<CursorVisualOutput, never>>) => CursorVisualOutput;
+    defaults: () => Partial<CursorVisualOutput>;
+}>;
 export type DragInput = {
     fromX: number;
     fromY: number;
@@ -101,6 +194,33 @@ export declare const EscalateSessionInput: Readonly<{
     new: (partial: Partial<EscalateSessionInput> & Required<Omit<EscalateSessionInput, "detail">>) => EscalateSessionInput;
     defaults: () => Partial<EscalateSessionInput>;
 }>;
+export type GetAgentCursorStateInput = {
+    session: string;
+};
+/**
+ * Generated factory for {@link GetAgentCursorStateInput} record objects.
+ */
+export declare const GetAgentCursorStateInput: Readonly<{
+    create: (partial: Partial<GetAgentCursorStateInput> & Required<Omit<GetAgentCursorStateInput, never>>) => GetAgentCursorStateInput;
+    new: (partial: Partial<GetAgentCursorStateInput> & Required<Omit<GetAgentCursorStateInput, never>>) => GetAgentCursorStateInput;
+    defaults: () => Partial<GetAgentCursorStateInput>;
+}>;
+export type GetAgentCursorStateOutput = {
+    session: string;
+    enabled: boolean;
+    position?: CursorPointOutput;
+    theme: CursorThemeOutput;
+    visualState: CursorVisualOutput;
+    motion: CursorMotionOutput;
+};
+/**
+ * Generated factory for {@link GetAgentCursorStateOutput} record objects.
+ */
+export declare const GetAgentCursorStateOutput: Readonly<{
+    create: (partial: Partial<GetAgentCursorStateOutput> & Required<Omit<GetAgentCursorStateOutput, "position">>) => GetAgentCursorStateOutput;
+    new: (partial: Partial<GetAgentCursorStateOutput> & Required<Omit<GetAgentCursorStateOutput, "position">>) => GetAgentCursorStateOutput;
+    defaults: () => Partial<GetAgentCursorStateOutput>;
+}>;
 export type GetCursorPositionInput = {
     /**
      * Optional session id.
@@ -266,6 +386,87 @@ export declare const SessionStateOutput: Readonly<{
     new: (partial: Partial<SessionStateOutput> & Required<Omit<SessionStateOutput, "escalationReason" | "escalationDetail">>) => SessionStateOutput;
     defaults: () => Partial<SessionStateOutput>;
 }>;
+export type SetAgentCursorEnabledInput = {
+    session: string;
+    enabled: boolean;
+};
+/**
+ * Generated factory for {@link SetAgentCursorEnabledInput} record objects.
+ */
+export declare const SetAgentCursorEnabledInput: Readonly<{
+    create: (partial: Partial<SetAgentCursorEnabledInput> & Required<Omit<SetAgentCursorEnabledInput, never>>) => SetAgentCursorEnabledInput;
+    new: (partial: Partial<SetAgentCursorEnabledInput> & Required<Omit<SetAgentCursorEnabledInput, never>>) => SetAgentCursorEnabledInput;
+    defaults: () => Partial<SetAgentCursorEnabledInput>;
+}>;
+export type SetAgentCursorEnabledOutput = {
+    session: string;
+    enabled: boolean;
+};
+/**
+ * Generated factory for {@link SetAgentCursorEnabledOutput} record objects.
+ */
+export declare const SetAgentCursorEnabledOutput: Readonly<{
+    create: (partial: Partial<SetAgentCursorEnabledOutput> & Required<Omit<SetAgentCursorEnabledOutput, never>>) => SetAgentCursorEnabledOutput;
+    new: (partial: Partial<SetAgentCursorEnabledOutput> & Required<Omit<SetAgentCursorEnabledOutput, never>>) => SetAgentCursorEnabledOutput;
+    defaults: () => Partial<SetAgentCursorEnabledOutput>;
+}>;
+export type SetAgentCursorMotionInput = {
+    session: string;
+    startHandle?: number;
+    endHandle?: number;
+    arcSize?: number;
+    arcFlow?: number;
+    spring?: number;
+    glideDurationMs?: number;
+    dwellAfterClickMs?: number;
+    idleHideMs?: number;
+    turnRadius?: number;
+};
+/**
+ * Generated factory for {@link SetAgentCursorMotionInput} record objects.
+ */
+export declare const SetAgentCursorMotionInput: Readonly<{
+    create: (partial: Partial<SetAgentCursorMotionInput> & Required<Omit<SetAgentCursorMotionInput, "startHandle" | "endHandle" | "arcSize" | "arcFlow" | "spring" | "glideDurationMs" | "dwellAfterClickMs" | "idleHideMs" | "turnRadius">>) => SetAgentCursorMotionInput;
+    new: (partial: Partial<SetAgentCursorMotionInput> & Required<Omit<SetAgentCursorMotionInput, "startHandle" | "endHandle" | "arcSize" | "arcFlow" | "spring" | "glideDurationMs" | "dwellAfterClickMs" | "idleHideMs" | "turnRadius">>) => SetAgentCursorMotionInput;
+    defaults: () => Partial<SetAgentCursorMotionInput>;
+}>;
+export type SetAgentCursorMotionOutput = {
+    session: string;
+    motion: CursorMotionOutput;
+};
+/**
+ * Generated factory for {@link SetAgentCursorMotionOutput} record objects.
+ */
+export declare const SetAgentCursorMotionOutput: Readonly<{
+    create: (partial: Partial<SetAgentCursorMotionOutput> & Required<Omit<SetAgentCursorMotionOutput, never>>) => SetAgentCursorMotionOutput;
+    new: (partial: Partial<SetAgentCursorMotionOutput> & Required<Omit<SetAgentCursorMotionOutput, never>>) => SetAgentCursorMotionOutput;
+    defaults: () => Partial<SetAgentCursorMotionOutput>;
+}>;
+export type SetAgentCursorThemeInput = {
+    session: string;
+    themeId: string;
+    reducedMotion: CursorReducedMotion;
+};
+/**
+ * Generated factory for {@link SetAgentCursorThemeInput} record objects.
+ */
+export declare const SetAgentCursorThemeInput: Readonly<{
+    create: (partial: Partial<SetAgentCursorThemeInput> & Required<Omit<SetAgentCursorThemeInput, never>>) => SetAgentCursorThemeInput;
+    new: (partial: Partial<SetAgentCursorThemeInput> & Required<Omit<SetAgentCursorThemeInput, never>>) => SetAgentCursorThemeInput;
+    defaults: () => Partial<SetAgentCursorThemeInput>;
+}>;
+export type SetAgentCursorThemeOutput = {
+    session: string;
+    theme: CursorThemeOutput;
+};
+/**
+ * Generated factory for {@link SetAgentCursorThemeOutput} record objects.
+ */
+export declare const SetAgentCursorThemeOutput: Readonly<{
+    create: (partial: Partial<SetAgentCursorThemeOutput> & Required<Omit<SetAgentCursorThemeOutput, never>>) => SetAgentCursorThemeOutput;
+    new: (partial: Partial<SetAgentCursorThemeOutput> & Required<Omit<SetAgentCursorThemeOutput, never>>) => SetAgentCursorThemeOutput;
+    defaults: () => Partial<SetAgentCursorThemeOutput>;
+}>;
 export type StartSessionInput = {
     /**
      * Stable session id for this run (e.g. "research-run-1").
@@ -275,13 +476,18 @@ export type StartSessionInput = {
      * Per-session perception/action modality. auto starts window-only and requires explicit escalation before desktop tools; window and desktop are strict. Immutable for the live session.
      */
     captureScope?: CaptureScope;
+    /**
+     * Optional initial cursor theme. The host applies it before the cursor is
+     * first made visible, avoiding a flash of the default theme.
+     */
+    cursorTheme?: CursorThemeSelection;
 };
 /**
  * Generated factory for {@link StartSessionInput} record objects.
  */
 export declare const StartSessionInput: Readonly<{
-    create: (partial: Partial<StartSessionInput> & Required<Omit<StartSessionInput, "captureScope">>) => StartSessionInput;
-    new: (partial: Partial<StartSessionInput> & Required<Omit<StartSessionInput, "captureScope">>) => StartSessionInput;
+    create: (partial: Partial<StartSessionInput> & Required<Omit<StartSessionInput, "captureScope" | "cursorTheme">>) => StartSessionInput;
+    new: (partial: Partial<StartSessionInput> & Required<Omit<StartSessionInput, "captureScope" | "cursorTheme">>) => StartSessionInput;
     defaults: () => Partial<StartSessionInput>;
 }>;
 /**
@@ -356,6 +562,55 @@ declare const _default: Readonly<{
             lift(value: UniffiByteArray): ClickInput;
             lower(value: ClickInput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
         };
+        FfiConverterTypeCursorAction: {
+            read(from: RustBuffer): CursorAction;
+            write(value: CursorAction, into: RustBuffer): void;
+            allocationSize(value: CursorAction): number;
+            lift(value: UniffiByteArray): CursorAction;
+            lower(value: CursorAction, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorMotionOutput: {
+            read(from: RustBuffer): CursorMotionOutput;
+            write(value: CursorMotionOutput, into: RustBuffer): void;
+            allocationSize(value: CursorMotionOutput): number;
+            lift(value: UniffiByteArray): CursorMotionOutput;
+            lower(value: CursorMotionOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorPointOutput: {
+            read(from: RustBuffer): CursorPointOutput;
+            write(value: CursorPointOutput, into: RustBuffer): void;
+            allocationSize(value: CursorPointOutput): number;
+            lift(value: UniffiByteArray): CursorPointOutput;
+            lower(value: CursorPointOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorReducedMotion: {
+            read(from: RustBuffer): CursorReducedMotion;
+            write(value: CursorReducedMotion, into: RustBuffer): void;
+            allocationSize(value: CursorReducedMotion): number;
+            lift(value: UniffiByteArray): CursorReducedMotion;
+            lower(value: CursorReducedMotion, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorThemeOutput: {
+            read(from: RustBuffer): CursorThemeOutput;
+            write(value: CursorThemeOutput, into: RustBuffer): void;
+            allocationSize(value: CursorThemeOutput): number;
+            lift(value: UniffiByteArray): CursorThemeOutput;
+            lower(value: CursorThemeOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorThemeSelection: {
+            read(from: RustBuffer): CursorThemeSelection;
+            write(value: CursorThemeSelection, into: RustBuffer): void;
+            allocationSize(value: CursorThemeSelection): number;
+            lift(value: UniffiByteArray): CursorThemeSelection;
+            lower(value: CursorThemeSelection, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeCursorVisualOutput: {
+            read(from: RustBuffer): CursorVisualOutput;
+            write(value: CursorVisualOutput, into: RustBuffer): void;
+            allocationSize(value: CursorVisualOutput): number;
+            lift(value: UniffiByteArray): CursorVisualOutput;
+            lower(value: CursorVisualOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
         FfiConverterTypeDesktopScope: {
             read(from: RustBuffer): DesktopScope;
             write(value: DesktopScope, into: RustBuffer): void;
@@ -405,6 +660,20 @@ declare const _default: Readonly<{
             lift(value: UniffiByteArray): EscalationReason;
             lower(value: EscalationReason, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
         };
+        FfiConverterTypeGetAgentCursorStateInput: {
+            read(from: RustBuffer): GetAgentCursorStateInput;
+            write(value: GetAgentCursorStateInput, into: RustBuffer): void;
+            allocationSize(value: GetAgentCursorStateInput): number;
+            lift(value: UniffiByteArray): GetAgentCursorStateInput;
+            lower(value: GetAgentCursorStateInput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeGetAgentCursorStateOutput: {
+            read(from: RustBuffer): GetAgentCursorStateOutput;
+            write(value: GetAgentCursorStateOutput, into: RustBuffer): void;
+            allocationSize(value: GetAgentCursorStateOutput): number;
+            lift(value: UniffiByteArray): GetAgentCursorStateOutput;
+            lower(value: GetAgentCursorStateOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
         FfiConverterTypeGetCursorPositionInput: {
             read(from: RustBuffer): GetCursorPositionInput;
             write(value: GetCursorPositionInput, into: RustBuffer): void;
@@ -489,6 +758,48 @@ declare const _default: Readonly<{
             lift(value: UniffiByteArray): SessionStateOutput;
             lower(value: SessionStateOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
         };
+        FfiConverterTypeSetAgentCursorEnabledInput: {
+            read(from: RustBuffer): SetAgentCursorEnabledInput;
+            write(value: SetAgentCursorEnabledInput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorEnabledInput): number;
+            lift(value: UniffiByteArray): SetAgentCursorEnabledInput;
+            lower(value: SetAgentCursorEnabledInput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeSetAgentCursorEnabledOutput: {
+            read(from: RustBuffer): SetAgentCursorEnabledOutput;
+            write(value: SetAgentCursorEnabledOutput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorEnabledOutput): number;
+            lift(value: UniffiByteArray): SetAgentCursorEnabledOutput;
+            lower(value: SetAgentCursorEnabledOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeSetAgentCursorMotionInput: {
+            read(from: RustBuffer): SetAgentCursorMotionInput;
+            write(value: SetAgentCursorMotionInput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorMotionInput): number;
+            lift(value: UniffiByteArray): SetAgentCursorMotionInput;
+            lower(value: SetAgentCursorMotionInput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeSetAgentCursorMotionOutput: {
+            read(from: RustBuffer): SetAgentCursorMotionOutput;
+            write(value: SetAgentCursorMotionOutput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorMotionOutput): number;
+            lift(value: UniffiByteArray): SetAgentCursorMotionOutput;
+            lower(value: SetAgentCursorMotionOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeSetAgentCursorThemeInput: {
+            read(from: RustBuffer): SetAgentCursorThemeInput;
+            write(value: SetAgentCursorThemeInput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorThemeInput): number;
+            lift(value: UniffiByteArray): SetAgentCursorThemeInput;
+            lower(value: SetAgentCursorThemeInput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
+        FfiConverterTypeSetAgentCursorThemeOutput: {
+            read(from: RustBuffer): SetAgentCursorThemeOutput;
+            write(value: SetAgentCursorThemeOutput, into: RustBuffer): void;
+            allocationSize(value: SetAgentCursorThemeOutput): number;
+            lift(value: UniffiByteArray): SetAgentCursorThemeOutput;
+            lower(value: SetAgentCursorThemeOutput, alloc: import("@ubjs/core").RustBufferAllocator): UniffiByteArray;
+        };
         FfiConverterTypeStartSessionInput: {
             read(from: RustBuffer): StartSessionInput;
             write(value: StartSessionInput, into: RustBuffer): void;