@predicatelabs/sdk 0.99.9

package/dist/types.d.ts

@@ -0,0 +1,422 @@
+/**
+ * TypeScript type definitions - matches spec/sdk-types.md
+ */
+export interface BBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface VisualCues {
+    is_primary: boolean;
+    background_color_name: string | null;
+    fallback_background_color_name?: string | null;
+    is_clickable: boolean;
+}
+export interface Element {
+    id: number;
+    role: string;
+    text: string | null;
+    importance: number;
+    bbox: BBox;
+    visual_cues: VisualCues;
+    in_viewport: boolean;
+    is_occluded: boolean;
+    z_index: number;
+    fused_rank_index?: number;
+    heuristic_index?: number;
+    ml_probability?: number;
+    ml_score?: number;
+    diff_status?: 'ADDED' | 'REMOVED' | 'MODIFIED' | 'MOVED';
+    center_x?: number;
+    center_y?: number;
+    doc_y?: number;
+    group_key?: string;
+    group_index?: number;
+    href?: string;
+    /** Nearby static text (best-effort, usually only for top-ranked elements) */
+    nearby_text?: string | null;
+    /** Best-effort accessible name/label for controls (distinct from visible text) */
+    name?: string | null;
+    /** Current value for inputs/textarea/select (PII-aware: may be omitted/redacted) */
+    value?: string | null;
+    /** Input type (e.g., "text", "email", "password") */
+    input_type?: string | null;
+    /** Whether value was redacted for privacy */
+    value_redacted?: boolean | null;
+    /** Normalized boolean states (best-effort) */
+    checked?: boolean | null;
+    disabled?: boolean | null;
+    expanded?: boolean | null;
+    /** Raw ARIA state strings (tri-state / debugging) */
+    aria_checked?: string | null;
+    aria_disabled?: string | null;
+    aria_expanded?: string | null;
+    in_dominant_group?: boolean;
+    layout?: LayoutHints;
+}
+export interface GridPosition {
+    /** 0-based row index */
+    row_index: number;
+    /** 0-based column index */
+    col_index: number;
+    /** ID of the row cluster (for distinguishing separate grids) */
+    cluster_id: number;
+}
+export interface LayoutHints {
+    /** Grid ID (maps to GridInfo.grid_id) - distinguishes multiple grids on same page */
+    /** Per feedback: Add grid_id to distinguish main feed + sidebar lists + nav links */
+    grid_id?: number | null;
+    /** Grid position within the grid (row_index, col_index) */
+    grid_pos?: GridPosition | null;
+    /** Inferred parent index in the original elements slice */
+    parent_index?: number | null;
+    /** Indices of children elements (optional to avoid payload bloat - container elements can have hundreds) */
+    /** Per feedback: Make optional/capped to prevent serializing large arrays */
+    children_indices?: number[] | null;
+    /** Confidence score for grid position assignment (0.0-1.0) */
+    grid_confidence: number;
+    /** Confidence score for parent-child containment (0.0-1.0) */
+    parent_confidence: number;
+    /** Optional: Page region (header/nav/main/aside/footer) - killer signal for ordinality + dominant group */
+    /** Per feedback: Optional but very useful for region detection */
+    region?: 'header' | 'nav' | 'main' | 'aside' | 'footer' | null;
+    /** Confidence score for region assignment (0.0-1.0) */
+    region_confidence: number;
+}
+export interface GridInfo {
+    /** The grid ID (matches grid_id in LayoutHints) */
+    grid_id: number;
+    /** Bounding box: x, y, width, height (document coordinates) */
+    bbox: BBox;
+    /** Number of rows in the grid */
+    row_count: number;
+    /** Number of columns in the grid */
+    col_count: number;
+    /** Total number of items in the grid */
+    item_count: number;
+    /** Confidence score (currently 1.0) */
+    confidence: number;
+    /** Optional inferred label (e.g., "product_grid", "search_results", "navigation") - best-effort heuristic, may be null */
+    label?: string | null;
+    /** Whether this grid is the dominant group (main content area) */
+    is_dominant?: boolean;
+    /** Z-index of this grid (max among elements in this grid) */
+    z_index?: number;
+    /** Global max z-index across ALL grids (for comparison) */
+    z_index_max?: number;
+    /** Whether this grid blocks interaction with content behind it */
+    blocks_interaction?: boolean;
+    /** Ratio of grid area to viewport area (0.0-1.0) */
+    viewport_coverage?: number;
+}
+export interface MlRerankTags {
+    repeated: boolean;
+    sponsored_ish: boolean;
+    non_sponsored: boolean;
+    pos: boolean;
+    occ: boolean;
+    vocc: boolean;
+    short: boolean;
+    action_ish: boolean;
+    nav_ish: boolean;
+}
+export interface MlRerankInfo {
+    enabled: boolean;
+    applied: boolean;
+    reason?: string | null;
+    candidate_count?: number | null;
+    top_probability?: number | null;
+    min_confidence?: number | null;
+    is_high_confidence?: boolean | null;
+    tags?: MlRerankTags | null;
+    error?: string | null;
+}
+export interface Snapshot {
+    status: 'success' | 'error';
+    timestamp?: string;
+    url: string;
+    viewport?: Viewport;
+    elements: Element[];
+    screenshot?: string;
+    screenshot_format?: 'png' | 'jpeg';
+    error?: string;
+    requires_license?: boolean;
+    dominant_group_key?: string;
+    diagnostics?: SnapshotDiagnostics;
+    /** True if a modal/overlay grid was detected */
+    modal_detected?: boolean;
+    /** Array of GridInfo for detected modal grids */
+    modal_grids?: GridInfo[];
+    /** ML rerank metadata (optional) */
+    ml_rerank?: MlRerankInfo;
+}
+export interface StepHookContext {
+    stepId: string;
+    stepIndex: number;
+    goal: string;
+    attempt: number;
+    url?: string | null;
+    success?: boolean;
+    outcome?: string | null;
+    error?: string | null;
+}
+export interface SnapshotDiagnosticsMetrics {
+    ready_state?: string | null;
+    quiet_ms?: number | null;
+    node_count?: number | null;
+    interactive_count?: number | null;
+    raw_elements_count?: number | null;
+}
+export interface CaptchaEvidence {
+    text_hits: string[];
+    selector_hits: string[];
+    iframe_src_hits: string[];
+    url_hits: string[];
+}
+export interface CaptchaDiagnostics {
+    detected: boolean;
+    provider_hint?: 'recaptcha' | 'hcaptcha' | 'turnstile' | 'arkose' | 'awswaf' | 'unknown' | null;
+    confidence: number;
+    evidence: CaptchaEvidence;
+}
+export interface SnapshotDiagnostics {
+    confidence?: number | null;
+    reasons?: string[];
+    metrics?: SnapshotDiagnosticsMetrics;
+    captcha?: CaptchaDiagnostics;
+    /** P1-01: forward-compatible vision recommendation signal (optional) */
+    requires_vision?: boolean | null;
+    requires_vision_reason?: string | null;
+}
+/**
+ * Metadata for a stored screenshot.
+ * Used by CloudTraceSink to track screenshots before upload.
+ */
+export interface ScreenshotMetadata {
+    sequence: number;
+    format: 'png' | 'jpeg';
+    sizeBytes: number;
+    stepId: string | null;
+    filepath: string;
+}
+export interface ActionResult {
+    success: boolean;
+    duration_ms: number;
+    outcome?: 'navigated' | 'dom_updated' | 'no_change' | 'error';
+    url_changed?: boolean;
+    snapshot_after?: Snapshot;
+    /** Optional: action metadata (e.g., human-like cursor movement path) */
+    cursor?: Record<string, any>;
+    error?: {
+        code: string;
+        reason: string;
+        recovery_hint?: string;
+    };
+}
+export interface TabInfo {
+    tab_id: string;
+    url?: string | null;
+    title?: string | null;
+    is_active: boolean;
+}
+export interface TabListResult {
+    ok: boolean;
+    tabs: TabInfo[];
+    error?: string | null;
+}
+export interface TabOperationResult {
+    ok: boolean;
+    tab?: TabInfo | null;
+    error?: string | null;
+}
+export interface BackendCapabilities {
+    tabs: boolean;
+    evaluate_js: boolean;
+    downloads: boolean;
+    filesystem_tools: boolean;
+    keyboard: boolean;
+    permissions: boolean;
+}
+export interface EvaluateJsRequest {
+    code: string;
+    max_output_chars?: number;
+    truncate?: boolean;
+}
+export interface EvaluateJsResult {
+    ok: boolean;
+    value?: any;
+    text?: string | null;
+    truncated?: boolean;
+    error?: string | null;
+}
+export interface WaitResult {
+    found: boolean;
+    element?: Element;
+    duration_ms: number;
+    timeout: boolean;
+}
+export interface ExtractResult {
+    ok: boolean;
+    data?: any;
+    raw?: string | null;
+    error?: string | null;
+}
+export interface QuerySelectorObject {
+    role?: string;
+    text?: string;
+    name?: string;
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    expanded?: boolean;
+    clickable?: boolean;
+    isPrimary?: boolean;
+    importance?: number | {
+        min?: number;
+        max?: number;
+    };
+}
+export type QuerySelector = string | QuerySelectorObject;
+/**
+ * Cookie definition for storage state injection.
+ * Matches Playwright's cookie format for storage_state.
+ */
+export interface Cookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * LocalStorage item for a specific origin.
+ * Playwright stores localStorage as an array of {name, value} objects.
+ */
+export interface LocalStorageItem {
+    name: string;
+    value: string;
+}
+/**
+ * Storage state for a specific origin (localStorage).
+ * Represents localStorage data for a single domain.
+ */
+export interface OriginStorage {
+    origin: string;
+    localStorage: LocalStorageItem[];
+}
+/**
+ * Complete browser storage state (cookies + localStorage).
+ * This is the format used by Playwright's storage_state() method.
+ * Can be saved to/loaded from JSON files for session injection.
+ */
+export interface StorageState {
+    cookies: Cookie[];
+    origins: OriginStorage[];
+}
+/**
+ * Rectangle coordinates for text occurrence.
+ * Includes both absolute (page) and viewport-relative coordinates.
+ */
+export interface TextRect {
+    /** Absolute X coordinate (page coordinate with scroll offset) */
+    x: number;
+    /** Absolute Y coordinate (page coordinate with scroll offset) */
+    y: number;
+    /** Rectangle width in pixels */
+    width: number;
+    /** Rectangle height in pixels */
+    height: number;
+    /** Absolute left position (same as x) */
+    left: number;
+    /** Absolute top position (same as y) */
+    top: number;
+    /** Absolute right position (x + width) */
+    right: number;
+    /** Absolute bottom position (y + height) */
+    bottom: number;
+}
+/**
+ * Viewport-relative rectangle coordinates (without scroll offset)
+ */
+export interface ViewportRect {
+    /** Viewport-relative X coordinate */
+    x: number;
+    /** Viewport-relative Y coordinate */
+    y: number;
+    /** Rectangle width in pixels */
+    width: number;
+    /** Rectangle height in pixels */
+    height: number;
+}
+/**
+ * Context text surrounding a match
+ */
+export interface TextContext {
+    /** Text before the match (up to 20 chars) */
+    before: string;
+    /** Text after the match (up to 20 chars) */
+    after: string;
+}
+/**
+ * A single text match with its rectangle and context
+ */
+export interface TextMatch {
+    /** The matched text */
+    text: string;
+    /** Absolute rectangle coordinates (with scroll offset) */
+    rect: TextRect;
+    /** Viewport-relative rectangle (without scroll offset) */
+    viewport_rect: ViewportRect;
+    /** Surrounding text context */
+    context: TextContext;
+    /** Whether the match is currently visible in viewport */
+    in_viewport: boolean;
+}
+/**
+ * Result of findTextRect operation.
+ * Returns all occurrences of text on the page with their exact pixel coordinates.
+ */
+export interface TextRectSearchResult {
+    status: 'success' | 'error';
+    /** The search text that was queried */
+    query?: string;
+    /** Whether search was case-sensitive */
+    case_sensitive?: boolean;
+    /** Whether whole-word matching was used */
+    whole_word?: boolean;
+    /** Number of matches found */
+    matches?: number;
+    /** List of text matches with coordinates */
+    results?: TextMatch[];
+    /** Current viewport dimensions */
+    viewport?: Viewport & {
+        scroll_x: number;
+        scroll_y: number;
+    };
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Options for findTextRect operation
+ */
+export interface FindTextRectOptions {
+    /** Text to search for (required) */
+    text: string;
+    /** Container element to search within (default: document.body) */
+    containerElement?: Element;
+    /** Case-sensitive search (default: false) */
+    caseSensitive?: boolean;
+    /** Match whole words only (default: false) */
+    wholeWord?: boolean;
+    /** Maximum number of results to return (default: 10) */
+    maxResults?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * TypeScript type definitions - matches spec/sdk-types.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/utils/action-executor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ActionExecutor - Executes actions and handles retries
+ *
+ * Extracted from SentienceAgent to improve separation of concerns
+ */
+import { IBrowser } from '../protocols/browser-protocol';
+import { Snapshot } from '../types';
+import { AgentActResult } from '../agent';
+/**
+ * ActionExecutor handles action parsing and execution
+ */
+export declare class ActionExecutor {
+    private browser;
+    private verbose;
+    constructor(browser: IBrowser, verbose?: boolean);
+    /**
+     * Execute an action string (e.g., "CLICK(42)", "TYPE(5, \"text\")")
+     *
+     * @param actionStr - Action string to parse and execute
+     * @param snap - Current snapshot for element lookup
+     * @returns Action result
+     */
+    executeAction(actionStr: string, snap: Snapshot): Promise<AgentActResult>;
+}
+//# sourceMappingURL=action-executor.d.ts.map

package/dist/utils/action-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-executor.d.ts","sourceRoot":"","sources":["../../src/utils/action-executor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;gBADP,OAAO,EAAE,QAAQ,EACjB,OAAO,GAAE,OAAc;IAGjC;;;;;;OAMG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;CA+GhF"}

package/dist/utils/action-executor.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * ActionExecutor - Executes actions and handles retries
+ *
+ * Extracted from SentienceAgent to improve separation of concerns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionExecutor = void 0;
+const actions_1 = require("../actions");
+/**
+ * ActionExecutor handles action parsing and execution
+ */
+class ActionExecutor {
+    constructor(browser, verbose = true) {
+        this.browser = browser;
+        this.verbose = verbose;
+    }
+    /**
+     * Execute an action string (e.g., "CLICK(42)", "TYPE(5, \"text\")")
+     *
+     * @param actionStr - Action string to parse and execute
+     * @param snap - Current snapshot for element lookup
+     * @returns Action result
+     */
+    async executeAction(actionStr, snap) {
+        // Parse action string
+        const actionMatch = actionStr.match(/^(\w+)\((.*)\)$/);
+        if (!actionMatch) {
+            throw new Error(`Unknown action format: ${actionStr}\n` +
+                `Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()`);
+        }
+        const [, action, argsStr] = actionMatch;
+        const actionUpper = action.toUpperCase();
+        if (actionUpper === 'FINISH') {
+            return {
+                success: true,
+                action: 'finish',
+                outcome: 'Task completed',
+                durationMs: 0,
+                attempt: 0,
+                goal: '',
+                urlChanged: false,
+            };
+        }
+        if (actionUpper === 'CLICK') {
+            const elementId = parseInt(argsStr.trim(), 10);
+            if (isNaN(elementId)) {
+                throw new Error(`Invalid element ID in CLICK action: ${argsStr}`);
+            }
+            // Verify element exists
+            const element = snap.elements.find(el => el.id === elementId);
+            if (!element) {
+                throw new Error(`Element ${elementId} not found in snapshot`);
+            }
+            const result = await (0, actions_1.click)(this.browser, elementId);
+            return {
+                success: result.success,
+                action: 'click',
+                elementId,
+                cursor: result.cursor,
+                outcome: result.outcome || (result.success ? 'Clicked successfully' : 'Click failed'),
+                durationMs: result.duration_ms,
+                attempt: 0,
+                goal: '',
+                urlChanged: result.url_changed || false,
+                error: result.error?.reason,
+            };
+        }
+        if (actionUpper === 'TYPE') {
+            // Parse TYPE(id, "text") - support both single and double quotes, and flexible whitespace
+            const typeMatch = argsStr.match(/^(\d+)\s*,\s*["']([^"']+)["']$/);
+            if (!typeMatch) {
+                throw new Error(`Invalid TYPE format. Expected: TYPE(id, "text")`);
+            }
+            const [, elementIdStr, text] = typeMatch;
+            const elementId = parseInt(elementIdStr, 10);
+            // Verify element exists
+            const element = snap.elements.find(el => el.id === elementId);
+            if (!element) {
+                throw new Error(`Element ${elementId} not found in snapshot`);
+            }
+            const result = await (0, actions_1.typeText)(this.browser, elementId, text);
+            return {
+                success: result.success,
+                action: 'type',
+                elementId,
+                text,
+                outcome: result.outcome || (result.success ? 'Typed successfully' : 'Type failed'),
+                durationMs: result.duration_ms,
+                attempt: 0,
+                goal: '',
+                urlChanged: result.url_changed || false,
+                error: result.error?.reason,
+            };
+        }
+        if (actionUpper === 'PRESS') {
+            // Parse PRESS("key") - support both single and double quotes
+            const keyMatch = argsStr.match(/^["']([^"']+)["']$/);
+            if (!keyMatch) {
+                throw new Error(`Invalid PRESS format. Expected: PRESS("key")`);
+            }
+            const [, key] = keyMatch;
+            const result = await (0, actions_1.press)(this.browser, key);
+            return {
+                success: result.success,
+                action: 'press',
+                key,
+                outcome: result.outcome || (result.success ? 'Key pressed successfully' : 'Press failed'),
+                durationMs: result.duration_ms,
+                attempt: 0,
+                goal: '',
+                urlChanged: result.url_changed || false,
+                error: result.error?.reason,
+            };
+        }
+        throw new Error(`Unknown action: ${actionUpper}\n` +
+            `Expected: CLICK(id), TYPE(id, "text"), PRESS("key"), or FINISH()`);
+    }
+}
+exports.ActionExecutor = ActionExecutor;
+//# sourceMappingURL=action-executor.js.map

package/dist/utils/action-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-executor.js","sourceRoot":"","sources":["../../src/utils/action-executor.ts"],"names":[],"mappings":"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"}

package/dist/utils/browser-evaluator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * BrowserEvaluator - Common browser evaluation patterns with standardized error handling
+ *
+ * This utility class extracts common page.evaluate() patterns to reduce code duplication
+ * and provide consistent error handling across snapshot, actions, wait, and read modules.
+ */
+import { Page } from 'playwright';
+export interface EvaluationOptions {
+    timeout?: number;
+    retries?: number;
+    onError?: (error: Error) => void;
+}
+/**
+ * BrowserEvaluator provides static methods for common browser evaluation patterns
+ */
+export declare class BrowserEvaluator {
+    /**
+     * Execute a browser evaluation script with standardized error handling
+     *
+     * @param page - Playwright Page instance
+     * @param script - Function to execute in browser context
+     * @param args - Arguments to pass to the script
+     * @param options - Evaluation options (timeout, retries, error handler)
+     * @returns Promise resolving to the evaluation result
+     *
+     * @example
+     * ```typescript
+     * const result = await BrowserEvaluator.evaluate(
+     *   page,
+     *   (opts) => (window as any).sentience.snapshot(opts),
+     *   { limit: 50 }
+     * );
+     * ```
+     */
+    static evaluate<T>(page: Page, script: (args: any) => T | Promise<T>, args?: any, options?: EvaluationOptions): Promise<T>;
+    /**
+     * Execute a browser evaluation with navigation-aware error handling
+     * Navigation may destroy the context, so we handle that gracefully
+     *
+     * @param page - Playwright Page instance
+     * @param script - Function to execute in browser context
+     * @param args - Arguments to pass to the script
+     * @param fallbackValue - Value to return if evaluation fails due to navigation
+     * @returns Promise resolving to the evaluation result or fallback value
+     *
+     * @example
+     * ```typescript
+     * const success = await BrowserEvaluator.evaluateWithNavigationFallback(
+     *   page,
+     *   (id) => (window as any).sentience.click(id),
+     *   elementId,
+     *   true // Assume success if navigation destroyed context
+     * );
+     * ```
+     */
+    static evaluateWithNavigationFallback<T>(page: Page, script: (args: any) => T | Promise<T>, args?: any, fallbackValue?: T): Promise<T>;
+    /**
+     * Wait for a condition in the browser context with timeout
+     *
+     * @param page - Playwright Page instance
+     * @param condition - Function that returns a truthy value when condition is met
+     * @param timeout - Maximum time to wait in milliseconds
+     * @returns Promise resolving when condition is met
+     *
+     * @example
+     * ```typescript
+     * await BrowserEvaluator.waitForCondition(
+     *   page,
+     *   () => typeof (window as any).sentience !== 'undefined',
+     *   5000
+     * );
+     * ```
+     */
+    static waitForCondition(page: Page, condition: () => boolean | Promise<boolean>, timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=browser-evaluator.d.ts.map