stelo 1.0.1

package/dist/agent.d.ts

@@ -0,0 +1,870 @@
+/**
+ * Real-time Agent Control Module
+ *
+ * Designed for low-latency control of mouse and keyboard with:
+ * - Action batching (minimizes round-trips)
+ * - Visual verification (confirms actions had effect)
+ * - Async non-blocking movement (cursor moves visually in real-time)
+ * - Parallel action execution (multiple things at once)
+ * - Streaming cursor control (continuous, cancellable)
+ * - Velocity-based streaming control (continuous, low-latency)
+ * - Gesture recording and playback
+ *
+ * @module agent
+ */
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Result of a single action in a batch */
+export interface ActionResult {
+    /** Index of this action in the batch */
+    index: number;
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Time spent on this action in milliseconds */
+    durationMs: number;
+    /** Mouse position after mouse actions */
+    mousePosition?: {
+        x: number;
+        y: number;
+    };
+    /** Whether visual change was detected (for wait actions) */
+    changeDetected?: boolean;
+}
+/** Result of executing an action batch */
+export interface BatchResult {
+    /** Individual results for each action */
+    results: ActionResult[];
+    /** Total time spent in milliseconds */
+    totalDurationMs: number;
+    /** Number of successful actions */
+    successCount: number;
+    /** Number of failed actions */
+    failureCount: number;
+    /** Index of first failed action, or -1 if all succeeded */
+    firstFailureIndex: number;
+    /** Whether all actions succeeded */
+    allSucceeded: boolean;
+}
+/** Result of click/hotkey with verification */
+export interface VerifyResult {
+    /** Whether visual change was detected */
+    verified: boolean;
+    /** Percentage of pixels changed */
+    changePercentage: number;
+    /** Time spent in milliseconds */
+    durationMs: number;
+}
+/** A point in a recorded mouse trail */
+export interface TrailPoint {
+    /** Timestamp in milliseconds relative to start */
+    timestampMs: number;
+    /** X coordinate */
+    x: number;
+    /** Y coordinate */
+    y: number;
+}
+export type MouseButton = 'left' | 'right' | 'middle';
+/** All possible actions that can be batched */
+export type Action = {
+    type: 'mouseMove';
+    x: number;
+    y: number;
+} | {
+    type: 'mouseMoveRel';
+    dx: number;
+    dy: number;
+} | {
+    type: 'mouseMoveSmooth';
+    x: number;
+    y: number;
+    duration?: number;
+} | {
+    type: 'mouseClick';
+    button?: MouseButton;
+} | {
+    type: 'mouseClickAt';
+    x: number;
+    y: number;
+    button?: MouseButton;
+} | {
+    type: 'mouseDoubleClick';
+    button?: MouseButton;
+} | {
+    type: 'mouseDown';
+    button?: MouseButton;
+} | {
+    type: 'mouseUp';
+    button?: MouseButton;
+} | {
+    type: 'mouseScroll';
+    amount: number;
+    horizontal?: boolean;
+} | {
+    type: 'mouseDrag';
+    toX: number;
+    toY: number;
+    button?: MouseButton;
+} | {
+    type: 'type';
+    text: string;
+} | {
+    type: 'typeHumanized';
+    text: string;
+    minDelay?: number;
+    maxDelay?: number;
+} | {
+    type: 'keyPress';
+    key: string;
+} | {
+    type: 'keyDown';
+    key: string;
+} | {
+    type: 'keyUp';
+    key: string;
+} | {
+    type: 'hotkey';
+    keys: string[];
+} | {
+    type: 'delay';
+    ms: number;
+} | {
+    type: 'waitForChange';
+    threshold?: number;
+    timeout?: number;
+    region?: Region;
+} | {
+    type: 'waitForStable';
+    threshold?: number;
+    stableMs?: number;
+    timeout?: number;
+    region?: Region;
+};
+/**
+ * Execute multiple actions as an atomic batch.
+ *
+ * This is the primary way applications should interact with the system.
+ * All actions execute sequentially in a single native call,
+ * minimizing latency and round-trips.
+ *
+ * @example
+ * ```typescript
+ * // Click a button, wait for response, then type
+ * const result = await agent.executeBatch([
+ *   { type: 'mouseClickAt', x: 500, y: 300 },
+ *   { type: 'waitForStable', stableMs: 200 },
+ *   { type: 'type', text: 'Hello World' },
+ *   { type: 'keyPress', key: 'Enter' }
+ * ]);
+ *
+ * if (result.allSucceeded) {
+ *   console.log('All actions completed in', result.totalDurationMs, 'ms');
+ * }
+ * ```
+ *
+ * @param actions Array of actions to execute
+ * @param options Execution options
+ * @returns Batch result with per-action details
+ */
+export declare function executeBatch(actions: Action[], options?: {
+    stopOnError?: boolean;
+}): BatchResult;
+/**
+ * Click at a position and verify visual change occurred.
+ *
+ * Useful for confirming clicks had an effect.
+ * Captures screen before and after click, computes diff.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.clickAndVerify(500, 300);
+ * if (!result.verified) {
+ *   console.log('Click had no visual effect - may need retry');
+ * }
+ * ```
+ *
+ * @param x Target X coordinate
+ * @param y Target Y coordinate
+ * @param options Click options
+ * @returns Verification result
+ */
+export declare function clickAndVerify(x: number, y: number, options?: {
+    button?: MouseButton;
+    minChangePercent?: number;
+    timeoutMs?: number;
+    region?: Region;
+}): VerifyResult;
+/**
+ * Execute a hotkey combination and verify visual change.
+ *
+ * @example
+ * ```typescript
+ * // Open file dialog and verify it appeared
+ * const result = await agent.hotkeyAndVerify(['ctrl', 'o']);
+ * if (result.verified) {
+ *   console.log('Dialog opened');
+ * }
+ * ```
+ *
+ * @param keys Array of keys to press together
+ * @param options Verification options
+ * @returns Verification result
+ */
+export declare function hotkeyAndVerify(keys: string[], options?: {
+    minChangePercent?: number;
+    timeoutMs?: number;
+    region?: Region;
+}): VerifyResult;
+/**
+ * Move mouse relative to current position.
+ *
+ * @param dx Horizontal offset (positive = right)
+ * @param dy Vertical offset (positive = down)
+ * @returns New mouse position
+ */
+export declare function moveRelative(dx: number, dy: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Move mouse relative to current position with smooth animation.
+ *
+ * @param dx Horizontal offset
+ * @param dy Vertical offset
+ * @param durationMs Animation duration (default: 300ms)
+ * @returns New mouse position
+ */
+export declare function moveRelativeSmooth(dx: number, dy: number, durationMs?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Type text and wait for screen to stabilize.
+ *
+ * Useful for form input where you want to wait for
+ * autocomplete or validation to finish.
+ *
+ * @param text Text to type
+ * @param options Wait options
+ * @returns True if screen stabilized within timeout
+ */
+export declare function typeAndWaitStable(text: string, options?: {
+    stabilityThreshold?: number;
+    stableDurationMs?: number;
+    timeoutMs?: number;
+}): boolean;
+/**
+ * Record mouse movements for a duration.
+ *
+ * Captures mouse trail for gesture analysis or replay.
+ *
+ * @example
+ * ```typescript
+ * // Record 3 seconds of mouse movement
+ * const trail = agent.recordMouseTrail(3000);
+ * console.log(`Recorded ${trail.length} points`);
+ *
+ * // Replay at half speed
+ * agent.replayMouseTrail(trail, 0.5);
+ * ```
+ *
+ * @param durationMs How long to record
+ * @param sampleRateHz Sample rate (default: 60)
+ * @returns Array of trail points with timestamps
+ */
+export declare function recordMouseTrail(durationMs: number, sampleRateHz?: number): TrailPoint[];
+/**
+ * Replay a recorded mouse trail.
+ *
+ * @param trail Previously recorded trail
+ * @param speedMultiplier Playback speed (1.0 = normal, 0.5 = half speed)
+ */
+export declare function replayMouseTrail(trail: TrailPoint[], speedMultiplier?: number): void;
+/**
+ * Release all held modifier keys.
+ *
+ * Call this for error recovery when modifier keys might be stuck,
+ * or after complex keyboard sequences.
+ */
+export declare function releaseAllModifiers(): void;
+/**
+ * Fluent action builder for creating complex sequences.
+ *
+ * @example
+ * ```typescript
+ * const result = agent.sequence()
+ *   .click(500, 300)
+ *   .waitForStable()
+ *   .type('Hello World')
+ *   .press('Enter')
+ *   .waitForChange()
+ *   .execute();
+ * ```
+ */
+export declare class ActionSequence {
+    private actions;
+    /** Move mouse to absolute position */
+    moveTo(x: number, y: number): this;
+    /** Move mouse smoothly to absolute position */
+    moveToSmooth(x: number, y: number, duration?: number): this;
+    /** Move mouse relative to current position */
+    moveBy(dx: number, dy: number): this;
+    /** Click at current position */
+    click(button?: MouseButton): this;
+    /** Click at specific coordinates */
+    clickAt(x: number, y: number, button?: MouseButton): this;
+    /** Double click */
+    doubleClick(button?: MouseButton): this;
+    /** Press mouse button down */
+    mouseDown(button?: MouseButton): this;
+    /** Release mouse button */
+    mouseUp(button?: MouseButton): this;
+    /** Scroll wheel */
+    scroll(amount: number, horizontal?: boolean): this;
+    /** Drag from current position to target */
+    dragTo(toX: number, toY: number, button?: MouseButton): this;
+    /** Type text instantly */
+    type(text: string): this;
+    /** Type text with human-like delays */
+    typeHuman(text: string, minDelay?: number, maxDelay?: number): this;
+    /** Press and release a key */
+    press(key: string): this;
+    /** Press key down (remember to release!) */
+    keyDown(key: string): this;
+    /** Release key */
+    keyUp(key: string): this;
+    /** Press a hotkey combination */
+    hotkey(...keys: string[]): this;
+    /** Wait for specified duration */
+    delay(ms: number): this;
+    /** Alias for delay */
+    wait(ms: number): this;
+    /** Wait for visual change */
+    waitForChange(options?: {
+        threshold?: number;
+        timeout?: number;
+        region?: Region;
+    }): this;
+    /** Wait for screen to stabilize */
+    waitForStable(options?: {
+        threshold?: number;
+        stableMs?: number;
+        timeout?: number;
+        region?: Region;
+    }): this;
+    /** Get the built actions array */
+    build(): Action[];
+    /** Execute all queued actions */
+    execute(options?: {
+        stopOnError?: boolean;
+    }): BatchResult;
+    /** Execute all queued actions — non-blocking async version */
+    executeAsync(options?: {
+        stopOnError?: boolean;
+    }): Promise<BatchResult>;
+    /** Clear all queued actions */
+    clear(): this;
+}
+/**
+ * Create a new action sequence builder.
+ *
+ * @example
+ * ```typescript
+ * const result = agent.sequence()
+ *   .clickAt(500, 300)
+ *   .waitForStable()
+ *   .type('search query')
+ *   .press('Enter')
+ *   .execute();
+ * ```
+ */
+export declare function sequence(): ActionSequence;
+/**
+ * Simple click with optional wait for visual feedback.
+ * Combines click and waitForStable in one call.
+ *
+ * @param x Target X coordinate
+ * @param y Target Y coordinate
+ * @param options Click options
+ * @returns Batch result
+ */
+export declare function clickAndWait(x: number, y: number, options?: {
+    button?: MouseButton;
+    stableMs?: number;
+}): BatchResult;
+/**
+ * Type text followed by Enter key.
+ *
+ * @param text Text to type before pressing Enter
+ * @param options Type options
+ * @returns Batch result
+ */
+export declare function typeAndEnter(text: string, options?: {
+    humanized?: boolean;
+}): BatchResult;
+/** Result of a single parallel task */
+export interface ParallelTaskResult {
+    /** Task name/label */
+    name: string;
+    /** Whether it succeeded */
+    success: boolean;
+    /** Error if failed */
+    error?: string;
+    /** Duration in ms */
+    durationMs: number;
+    /** Return value */
+    value?: unknown;
+}
+/** Result of parallel execution */
+export interface ParallelResult {
+    /** Individual task results */
+    results: ParallelTaskResult[];
+    /** Total wall-clock time */
+    totalDurationMs: number;
+    /** Whether all tasks succeeded */
+    allSucceeded: boolean;
+}
+/**
+ * Execute multiple independent actions in parallel.
+ *
+ * This is the key primitive for AI agents that need to do multiple things
+ * simultaneously — e.g., move the mouse while monitoring the screen,
+ * or type while watching for visual changes.
+ *
+ * Each task is a named async function. All run concurrently via Promise.all.
+ *
+ * @example
+ * ```typescript
+ * // Move mouse and monitor screen simultaneously
+ * const result = await agent.parallel({
+ *   move: async () => {
+ *     // Non-blocking smooth movement
+ *     const handle = mouse.moveSmoothAsync(500, 300, { duration: 600 });
+ *     return handle.promise;
+ *   },
+ *   monitor: async () => {
+ *     // Capture screen while mouse is moving
+ *     await sleep(200);
+ *     return screen.capture();
+ *   },
+ * });
+ *
+ * // All done
+ * console.log(result.allSucceeded); // true
+ * ```
+ */
+export declare function parallel(tasks: Record<string, () => unknown | Promise<unknown>>): Promise<ParallelResult>;
+/** Handle for controlling a live cursor stream */
+export interface CursorStreamHandle {
+    /** Send a new target position — cursor will move towards it smoothly */
+    moveTo(x: number, y: number): void;
+    /** Teleport immediately */
+    jumpTo(x: number, y: number): void;
+    /** Set velocity (pixels per second) */
+    setVelocity(vx: number, vy: number): void;
+    /** Stop all movement */
+    stop(): void;
+    /** Destroy the stream and release resources */
+    destroy(): void;
+    /** Whether the stream is still active */
+    readonly active: boolean;
+    /** Current cursor position */
+    readonly position: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Create a real-time cursor control stream.
+ *
+ * Returns a handle that lets you continuously direct the cursor in real-time.
+ * The cursor moves smoothly towards targets with no blocking. Multiple
+ * `moveTo()` calls seamlessly redirect the cursor mid-flight.
+ *
+ * This is the preferred way for AI agents to control the cursor because:
+ * - Movement is always visible and smooth
+ * - Targets can be updated any time (no waiting for previous move to finish)
+ * - Velocity-based control for continuous steering
+ * - Zero blocking of the Node.js event loop
+ *
+ * @param updateRateHz How many times per second to update position (default: 120)
+ *
+ * @example
+ * ```typescript
+ * const cursor = agent.createCursorStream(120);
+ *
+ * // Smooth movement to target
+ * cursor.moveTo(500, 300);
+ *
+ * // Change target mid-flight — cursor redirects smoothly
+ * setTimeout(() => cursor.moveTo(800, 600), 200);
+ *
+ * // Velocity-based control (e.g., from joystick or AI output)
+ * cursor.setVelocity(200, -100); // 200px/s right, 100px/s up
+ *
+ * // When done
+ * cursor.destroy();
+ * ```
+ */
+export declare function createCursorStream(updateRateHz?: number): CursorStreamHandle;
+/**
+ * Move to a position smoothly, click, and verify — all non-blocking.
+ *
+ * The cursor visually moves to the target, clicks, then verifies
+ * that the screen changed. The entire operation is async.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.moveClickVerify(500, 300, {
+ *   moveDuration: 400,
+ *   button: 'left',
+ * });
+ * console.log(result.verified); // true if screen changed after click
+ * ```
+ */
+export declare function moveClickVerify(x: number, y: number, options?: {
+    moveDuration?: number;
+    button?: MouseButton;
+    minChangePercent?: number;
+    verifyTimeoutMs?: number;
+    region?: Region;
+}): Promise<VerifyResult & {
+    finalPosition: {
+        x: number;
+        y: number;
+    };
+}>;
+/**
+ * Execute a batch of actions with async wrapper.
+ *
+ * Same as `executeBatch()` but returns a Promise, so it can be used
+ * in `Promise.all()` with other async operations.
+ */
+export declare function executeBatchAsync(actions: Action[], options?: {
+    stopOnError?: boolean;
+}): Promise<BatchResult>;
+/**
+ * Convenience: smoothly move to position and click — async.
+ * The cursor is visible moving on screen the whole time.
+ */
+export declare function smoothClickAt(x: number, y: number, options?: {
+    duration?: number;
+    button?: MouseButton;
+}): Promise<void>;
+/**
+ * Convenience: smoothly move to a text field, click it, type text.
+ * Fully async and visually smooth.
+ */
+export declare function smoothClickAndType(x: number, y: number, text: string, options?: {
+    duration?: number;
+    typeDelay?: number;
+}): Promise<void>;
+/** An action group to execute on its own OS thread */
+export interface ActionGroup {
+    /** Unique group identifier */
+    groupId?: string;
+    /** Actions to execute sequentially within this group */
+    actions: Action[];
+    /** Stop this group on first error (default: true) */
+    stopOnError?: boolean;
+    /** Delay before starting this group (ms) — for interleaving */
+    startDelayMs?: number;
+}
+/** Result of a single parallel group */
+export interface NativeGroupResultTS {
+    groupId: string;
+    results: ActionResult[];
+    durationMs: number;
+    successCount: number;
+    failureCount: number;
+}
+/** Result of native parallel execution */
+export interface NativeParallelResultTS {
+    groups: NativeGroupResultTS[];
+    totalDurationMs: number;
+    totalActions: number;
+    totalSuccess: number;
+    totalFailures: number;
+    allSucceeded: boolean;
+}
+/**
+ * Execute multiple action groups in TRUE parallel on native OS threads.
+ *
+ * Each group runs on its own Rust thread. Within a group, actions execute
+ * sequentially. Groups start simultaneously (or with optional start delays).
+ *
+ * This is the core primitive that makes Stelo faster than any other SDK —
+ * true OS-level parallelism, not async pretend.
+ *
+ * @example
+ * ```typescript
+ * // Move mouse AND type AND capture screen — all at the same time
+ * const result = agent.nativeParallel([
+ *   {
+ *     groupId: 'mouse',
+ *     actions: [
+ *       { type: 'mouseMoveSmooth', x: 500, y: 300, duration: 500 },
+ *       { type: 'mouseClick' },
+ *     ],
+ *   },
+ *   {
+ *     groupId: 'keyboard',
+ *     actions: [
+ *       { type: 'delay', ms: 200 },  // Start typing 200ms after mouse starts
+ *       { type: 'type', text: 'hello world' },
+ *     ],
+ *   },
+ * ]);
+ * console.log(result.totalDurationMs); // ~500ms, not ~700ms sequential
+ * ```
+ */
+export declare function nativeParallel(groups: ActionGroup[]): NativeParallelResultTS;
+/** Timed action for interleaved execution */
+export type TimedAction = Action & {
+    /** When to start this action (ms from beginning). Actions with same time run in parallel. */
+    startAtMs: number;
+};
+/**
+ * Execute actions with interleaved timing — human-like overlapping input.
+ *
+ * Each action has a startAtMs offset. Actions with the same start time
+ * run in parallel on separate OS threads. This enables realistic
+ * overlapping mouse + keyboard behavior.
+ *
+ * @example
+ * ```typescript
+ * // Start moving mouse immediately, start typing while mouse still moving
+ * agent.interleave([
+ *   { startAtMs: 0, type: 'mouseMoveSmooth', x: 500, y: 300, duration: 500 },
+ *   { startAtMs: 150, type: 'type', text: 'hello' },  // starts while mouse moving
+ *   { startAtMs: 500, type: 'mouseClick' },             // after mouse arrives
+ * ]);
+ * ```
+ */
+export declare function interleave(timedActions: TimedAction[]): NativeParallelResultTS;
+/** A recognized word with its screen position */
+export interface OcrWord {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    confidence: number;
+    /** Center point of this word's bounding box */
+    center: {
+        x: number;
+        y: number;
+    };
+}
+/** A recognized line of text */
+export interface OcrLine {
+    text: string;
+    words: OcrWord[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Full OCR result */
+export interface OcrResult {
+    /** Complete recognized text */
+    text: string;
+    /** Lines with word-level detail */
+    lines: OcrLine[];
+    /** How long OCR took (ms) */
+    durationMs: number;
+}
+/**
+ * Perform OCR on a screen region. Returns recognized text with positions.
+ *
+ * @example
+ * ```typescript
+ * // OCR the entire screen
+ * const result = agent.ocr();
+ * console.log(result.text);
+ *
+ * // OCR a specific region
+ * const result = agent.ocr({ x: 100, y: 200, width: 400, height: 50 });
+ * for (const word of result.lines[0]?.words ?? []) {
+ *   console.log(`"${word.text}" at (${word.center.x}, ${word.center.y})`);
+ * }
+ * ```
+ */
+export declare function ocr(region?: Region): OcrResult;
+/**
+ * Find text on screen via OCR and return its position.
+ *
+ * @example
+ * ```typescript
+ * const submit = agent.findText('Submit');
+ * if (submit) {
+ *   mouse.clickAt(submit.center.x, submit.center.y);
+ * }
+ * ```
+ */
+export declare function findText(needle: string, region?: Region): OcrWord | null;
+/**
+ * Find text on screen and click its center. Game-changer for AI agents.
+ *
+ * @example
+ * ```typescript
+ * // Click the "Submit" button — no coordinates needed
+ * agent.clickText('Submit');
+ *
+ * // Click "Cancel" with right-click
+ * agent.clickText('Cancel', { button: 'right' });
+ * ```
+ *
+ * @throws Error if text not found on screen
+ */
+export declare function clickText(needle: string, options?: {
+    button?: MouseButton;
+    region?: Region;
+}): {
+    x: number;
+    y: number;
+};
+/**
+ * Wait until OCR detects the specified text on screen.
+ * Polls at a configurable interval. Returns the word position, or null on timeout.
+ *
+ * @example
+ * ```typescript
+ * // Wait up to 10s for "Loading complete" to appear
+ * const word = agent.waitForText('Loading complete', { timeout: 10000 });
+ * if (word) console.log('Found at', word.center);
+ * ```
+ */
+export declare function waitForText(needle: string, options?: {
+    timeout?: number;
+    interval?: number;
+    region?: Region;
+}): OcrWord | null;
+/**
+ * Wait for text to appear on screen, then click it.
+ * Combines waitForText + click in a single native call for lower latency.
+ *
+ * @example
+ * ```typescript
+ * // Wait for "Submit" button to appear, then click it
+ * const pos = agent.waitForTextAndClick('Submit', { timeout: 5000 });
+ * if (pos) console.log('Clicked at', pos);
+ * ```
+ */
+export declare function waitForTextAndClick(needle: string, options?: {
+    timeout?: number;
+    interval?: number;
+    button?: string;
+    region?: Region;
+}): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Watch a screen region and wait for it to change.
+ * Returns the change percentage when threshold is exceeded, or null on timeout.
+ *
+ * @example
+ * ```typescript
+ * // Watch a button area for any visual change
+ * const change = agent.watchRegion(
+ *   { x: 200, y: 300, width: 100, height: 40 },
+ *   { threshold: 2.0, timeout: 5000 }
+ * );
+ * if (change) console.log(`Region changed by ${change.toFixed(1)}%`);
+ * ```
+ */
+export declare function watchRegion(region: Region, options?: {
+    threshold?: number;
+    timeout?: number;
+    interval?: number;
+}): number | null;
+/**
+ * Continuously watch a screen region and call a handler when it changes.
+ * Returns a stop function.
+ *
+ * @example
+ * ```typescript
+ * const stop = agent.onRegionChange(
+ *   { x: 200, y: 300, width: 100, height: 40 },
+ *   (changePct) => console.log(`Changed: ${changePct}%`),
+ *   { threshold: 1.0, interval: 300 }
+ * );
+ * // Later...
+ * stop();
+ * ```
+ */
+export declare function onRegionChange(region: Region, handler: (changePercentage: number) => void, options?: {
+    threshold?: number;
+    interval?: number;
+}): () => void;
+/**
+ * Register a global hotkey handler. Starts listening for keyboard events
+ * and triggers the callback when the key combination is detected.
+ *
+ * @example
+ * ```typescript
+ * // Register Ctrl+Shift+A
+ * const unregister = agent.onHotkey('ctrl+shift+a', () => {
+ *   console.log('Hotkey triggered!');
+ * });
+ *
+ * // Later: stop listening
+ * unregister();
+ * ```
+ */
+export declare function onHotkey(combo: string, handler: () => void, options?: {
+    pollInterval?: number;
+}): () => void;
+/**
+ * Wait for a hotkey combo to be pressed. Returns a promise that resolves
+ * when the combo is detected, or rejects on timeout.
+ *
+ * @example
+ * ```typescript
+ * await agent.waitForHotkey('ctrl+shift+s', { timeout: 30000 });
+ * console.log('User pressed Ctrl+Shift+S!');
+ * ```
+ */
+export declare function waitForHotkey(combo: string, options?: {
+    timeout?: number;
+}): Promise<void>;
+export declare const agent: {
+    executeBatch: typeof executeBatch;
+    executeBatchAsync: typeof executeBatchAsync;
+    clickAndVerify: typeof clickAndVerify;
+    hotkeyAndVerify: typeof hotkeyAndVerify;
+    parallel: typeof parallel;
+    moveClickVerify: typeof moveClickVerify;
+    smoothClickAt: typeof smoothClickAt;
+    smoothClickAndType: typeof smoothClickAndType;
+    createCursorStream: typeof createCursorStream;
+    moveRelative: typeof moveRelative;
+    moveRelativeSmooth: typeof moveRelativeSmooth;
+    typeAndWaitStable: typeof typeAndWaitStable;
+    recordMouseTrail: typeof recordMouseTrail;
+    replayMouseTrail: typeof replayMouseTrail;
+    releaseAllModifiers: typeof releaseAllModifiers;
+    sequence: typeof sequence;
+    ActionSequence: typeof ActionSequence;
+    clickAndWait: typeof clickAndWait;
+    typeAndEnter: typeof typeAndEnter;
+    nativeParallel: typeof nativeParallel;
+    interleave: typeof interleave;
+    ocr: typeof ocr;
+    findText: typeof findText;
+    clickText: typeof clickText;
+    waitForText: typeof waitForText;
+    waitForTextAndClick: typeof waitForTextAndClick;
+    watchRegion: typeof watchRegion;
+    onRegionChange: typeof onRegionChange;
+    onHotkey: typeof onHotkey;
+    waitForHotkey: typeof waitForHotkey;
+};
+export default agent;
+//# sourceMappingURL=agent.d.ts.map