@predicatelabs/sdk 0.99.9

package/dist/tracing/tracer.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Tracer Class
+ *
+ * High-level API for emitting trace events with automatic sequencing and timestamps
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tracer = void 0;
+/**
+ * Tracer provides a high-level API for recording agent execution traces
+ */
+class Tracer {
+    /**
+     * Create a new Tracer
+     * @param runId - Unique run identifier (UUID)
+     * @param sink - TraceSink implementation (e.g., JsonlTraceSink)
+     * @param screenshotProcessor - Optional function to process screenshots before emission.
+     *                             Takes base64 string, returns processed base64 string.
+     *                             Useful for PII redaction or custom image processing.
+     *
+     * @example
+     * // Basic usage
+     * const sink = new JsonlTraceSink('trace.jsonl');
+     * const tracer = new Tracer('run-123', sink);
+     *
+     * @example
+     * // With screenshot processor for PII redaction
+     * const redactPII = (screenshot: string): string => {
+     *   // Your custom redaction logic
+     *   return redactedScreenshot;
+     * };
+     * const tracer = new Tracer('run-123', sink, redactPII);
+     */
+    constructor(runId, sink, screenshotProcessor) {
+        // Stats tracking
+        this.totalSteps = 0;
+        this.totalEvents = 0;
+        this.startedAt = null;
+        this.endedAt = null;
+        this.finalStatus = 'unknown';
+        // Track step outcomes for automatic status inference
+        this.stepSuccesses = 0;
+        this.stepFailures = 0;
+        this.hasErrors = false;
+        this.runId = runId;
+        this.sink = sink;
+        this.seq = 0;
+        this.screenshotProcessor = screenshotProcessor;
+    }
+    /**
+     * Emit a trace event
+     * @param eventType - Type of event (e.g., 'run_start', 'snapshot')
+     * @param data - Event-specific payload
+     * @param stepId - Optional step UUID
+     */
+    emit(eventType, data, stepId) {
+        this.seq += 1;
+        this.totalEvents += 1;
+        // Apply screenshot processor if configured and screenshot is present
+        if (this.screenshotProcessor && data.screenshot_base64) {
+            const processedScreenshot = this.screenshotProcessor(data.screenshot_base64);
+            data = { ...data, screenshot_base64: processedScreenshot }; // Don't modify the original object
+        }
+        // Generate timestamps
+        const tsMs = Date.now();
+        const ts = new Date(tsMs).toISOString();
+        const event = {
+            v: 1,
+            type: eventType,
+            ts,
+            ts_ms: tsMs,
+            run_id: this.runId,
+            seq: this.seq,
+            data,
+        };
+        if (stepId) {
+            event.step_id = stepId;
+        }
+        this.sink.emit(event);
+        // Track step outcomes for automatic status inference
+        if (eventType === 'step_end') {
+            const success = data.success || false;
+            if (success) {
+                this.stepSuccesses += 1;
+            }
+            else {
+                this.stepFailures += 1;
+            }
+        }
+        else if (eventType === 'error') {
+            this.hasErrors = true;
+        }
+    }
+    /**
+     * Emit run_start event
+     * @param agent - Agent type (e.g., 'SentienceAgent')
+     * @param llmModel - Optional LLM model name
+     * @param config - Optional configuration
+     */
+    emitRunStart(agent, llmModel, config) {
+        // Track start time
+        this.startedAt = new Date();
+        const data = { agent };
+        if (llmModel)
+            data.llm_model = llmModel;
+        if (config)
+            data.config = config;
+        this.emit('run_start', data);
+    }
+    /**
+     * Emit step_start event
+     * @param stepId - Step UUID
+     * @param stepIndex - Step number (1-indexed)
+     * @param goal - Goal description
+     * @param attempt - Retry attempt number (0 = first try)
+     * @param preUrl - Optional URL before step execution
+     */
+    emitStepStart(stepId, stepIndex, goal, attempt = 0, preUrl) {
+        // Track step count (only count first attempt of each step)
+        if (attempt === 0) {
+            this.totalSteps = Math.max(this.totalSteps, stepIndex);
+        }
+        const data = {
+            step_id: stepId,
+            step_index: stepIndex,
+            goal,
+            attempt,
+        };
+        if (preUrl) {
+            data.url = preUrl;
+        }
+        this.emit('step_start', data, stepId);
+    }
+    /**
+     * Emit run_end event
+     * @param steps - Total number of steps executed
+     * @param status - Optional final status ("success", "failure", "partial", "unknown")
+     *                 If not provided, infers from tracked outcomes or uses this.finalStatus
+     */
+    emitRunEnd(steps, status) {
+        // Track end time
+        this.endedAt = new Date();
+        // Auto-infer status if not provided and not explicitly set
+        if (status === undefined && this.finalStatus === 'unknown') {
+            this._inferFinalStatus();
+        }
+        // Use provided status or fallback to this.finalStatus
+        const finalStatus = status || this.finalStatus;
+        // Ensure totalSteps is at least the provided steps value
+        this.totalSteps = Math.max(this.totalSteps, steps);
+        // Ensure finalStatus is a valid status value
+        const validStatus = finalStatus === 'success' ||
+            finalStatus === 'failure' ||
+            finalStatus === 'partial' ||
+            finalStatus === 'unknown'
+            ? finalStatus
+            : 'unknown';
+        this.emit('run_end', { steps, status: validStatus });
+    }
+    /**
+     * Emit error event
+     * @param stepId - Step UUID where error occurred
+     * @param error - Error message
+     * @param attempt - Retry attempt number
+     */
+    emitError(stepId, error, attempt = 0) {
+        this.emit('error', { step_id: stepId, error, attempt }, stepId);
+    }
+    /**
+     * Emit snapshot event with screenshot for Studio visualization.
+     *
+     * This method builds and emits a 'snapshot' trace event that includes:
+     * - Page URL and element data
+     * - Screenshot (if present in snapshot)
+     * - Step correlation info
+     *
+     * Use this when you want screenshots to appear in the Sentience Studio timeline.
+     *
+     * @param snapshot - Snapshot object (must have 'screenshot' property for images)
+     * @param stepId - Step UUID (for correlating snapshot with a step)
+     * @param stepIndex - Step index (0-based) for Studio timeline ordering
+     * @param screenshotFormat - Format of screenshot ("jpeg" or "png", default: "jpeg")
+     *
+     * @example
+     * // After taking a snapshot with AgentRuntime
+     * const snapshot = await runtime.snapshot();
+     * tracer.emitSnapshot(snapshot, runtime.getStepId(), runtime.getStepIndex());
+     *
+     * // Or use auto-emit (default in AgentRuntime.snapshot())
+     * const snapshot = await runtime.snapshot();  // Auto-emits snapshot event
+     */
+    emitSnapshot(snapshot, stepId, stepIndex, screenshotFormat = 'jpeg') {
+        if (!snapshot) {
+            return;
+        }
+        try {
+            // Build the snapshot event data
+            const data = {
+                url: snapshot.url,
+                element_count: snapshot.elements?.length || 0,
+                timestamp: snapshot.timestamp,
+            };
+            // Include step_index if provided (required for UUID step_ids)
+            if (stepIndex !== undefined) {
+                data.step_index = stepIndex;
+            }
+            // Include elements data (simplified for trace)
+            if (snapshot.elements && snapshot.elements.length > 0) {
+                // Normalize importance values to importance_score (0-1 range)
+                const importanceValues = snapshot.elements.map((el) => el.importance || 0);
+                const minImportance = Math.min(...importanceValues);
+                const maxImportance = Math.max(...importanceValues);
+                const importanceRange = maxImportance - minImportance;
+                data.elements = snapshot.elements.map((el) => {
+                    const importanceScore = importanceRange > 0 ? (el.importance - minImportance) / importanceRange : 0.5;
+                    return {
+                        ...el,
+                        importance_score: importanceScore,
+                    };
+                });
+            }
+            // Extract and add screenshot if present
+            const screenshotRaw = snapshot.screenshot;
+            if (screenshotRaw) {
+                // Extract base64 string from data URL if needed
+                // Format: "data:image/jpeg;base64,{base64_string}"
+                let screenshotBase64;
+                if (typeof screenshotRaw === 'string' && screenshotRaw.startsWith('data:image')) {
+                    const commaIndex = screenshotRaw.indexOf(',');
+                    screenshotBase64 =
+                        commaIndex !== -1 ? screenshotRaw.slice(commaIndex + 1) : screenshotRaw;
+                }
+                else {
+                    screenshotBase64 = screenshotRaw;
+                }
+                data.screenshot_base64 = screenshotBase64;
+                data.screenshot_format = screenshotFormat;
+            }
+            this.emit('snapshot', data, stepId);
+        }
+        catch {
+            // Best-effort: don't let trace emission errors break the caller
+        }
+    }
+    /**
+     * Automatically infer finalStatus from tracked step outcomes if not explicitly set.
+     * This is called automatically in close() if finalStatus is still "unknown".
+     */
+    _inferFinalStatus() {
+        if (this.finalStatus !== 'unknown') {
+            // Status already set explicitly, don't override
+            return;
+        }
+        // Infer from tracked outcomes
+        if (this.hasErrors) {
+            // Has errors - check if there were successful steps too
+            if (this.stepSuccesses > 0) {
+                this.finalStatus = 'partial';
+            }
+            else {
+                this.finalStatus = 'failure';
+            }
+        }
+        else if (this.stepSuccesses > 0) {
+            // Has successful steps and no errors
+            this.finalStatus = 'success';
+        }
+        // Otherwise stays "unknown" (no steps executed or no clear outcome)
+    }
+    /**
+     * Close the underlying sink (flush buffered data)
+     * @param blocking - If false, upload happens in background (default: true). Only applies to CloudTraceSink.
+     */
+    async close(blocking = true) {
+        // Auto-infer finalStatus if not explicitly set and we have step outcomes
+        if (this.finalStatus === 'unknown' &&
+            (this.stepSuccesses > 0 || this.stepFailures > 0 || this.hasErrors)) {
+            this._inferFinalStatus();
+        }
+        // Check if sink has a close method that accepts blocking parameter
+        if (typeof this.sink.close === 'function' && this.sink.close.length > 0) {
+            await this.sink.close(blocking);
+        }
+        else {
+            await this.sink.close();
+        }
+    }
+    /**
+     * Get run ID
+     */
+    getRunId() {
+        return this.runId;
+    }
+    /**
+     * Get current sequence number
+     */
+    getSeq() {
+        return this.seq;
+    }
+    /**
+     * Get sink type (for debugging)
+     */
+    getSinkType() {
+        return this.sink.getSinkType();
+    }
+    /**
+     * Set the final status of the trace run
+     * @param status - Final status ("success", "failure", "partial", "unknown")
+     */
+    setFinalStatus(status) {
+        if (!['success', 'failure', 'partial', 'unknown'].includes(status)) {
+            throw new Error(`Invalid status: ${status}. Must be one of: success, failure, partial, unknown`);
+        }
+        this.finalStatus = status;
+    }
+    /**
+     * Get execution statistics for trace completion
+     * @returns Dictionary with stats fields for /v1/traces/complete
+     */
+    getStats() {
+        let durationMs = null;
+        if (this.startedAt && this.endedAt) {
+            durationMs = this.endedAt.getTime() - this.startedAt.getTime();
+        }
+        return {
+            total_steps: this.totalSteps,
+            total_events: this.totalEvents,
+            duration_ms: durationMs,
+            final_status: this.finalStatus,
+            started_at: this.startedAt ? this.startedAt.toISOString() : null,
+            ended_at: this.endedAt ? this.endedAt.toISOString() : null,
+        };
+    }
+}
+exports.Tracer = Tracer;
+//# sourceMappingURL=tracer.js.map

package/dist/tracing/tracer.js.map

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

package/dist/tracing/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Tracing Types
+ *
+ * Schema v1 - Compatible with Python SDK
+ */
+/**
+ * TraceStats represents execution statistics extracted from a trace
+ */
+export interface TraceStats {
+    total_steps: number;
+    total_events: number;
+    duration_ms: number | null;
+    final_status: 'success' | 'failure' | 'partial' | 'unknown';
+    started_at: string | null;
+    ended_at: string | null;
+}
+/**
+ * Visual cues structure (matches Element.visual_cues)
+ */
+export interface TraceVisualCues {
+    is_primary: boolean;
+    background_color_name: string | null;
+    is_clickable: boolean;
+}
+/**
+ * Element data structure for snapshot events
+ */
+export interface TraceElement {
+    id: number;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    role: string;
+    text?: string | null;
+    importance?: number;
+    importance_score?: number;
+    visual_cues?: TraceVisualCues;
+    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';
+}
+/**
+ * Pre/post snapshot info for step_end events
+ */
+export interface SnapshotInfo {
+    url?: string;
+    snapshot_digest?: string;
+    elements?: TraceElement[];
+}
+/**
+ * LLM usage data for step_end events
+ */
+export interface LLMUsageData {
+    model?: string;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    response_text?: string;
+    response_hash?: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Execution data for step_end events
+ */
+export interface ExecutionData {
+    success: boolean;
+    action?: string;
+    outcome?: string;
+    duration_ms?: number;
+    element_id?: number;
+    bounding_box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    text?: string;
+    key?: string;
+    error?: string;
+    /** Optional action metadata (e.g., human-like cursor movement path) */
+    cursor?: Record<string, any>;
+}
+/**
+ * Element found info for verify signals
+ */
+export interface ElementFound {
+    label: string;
+    bounding_box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Assertion result for verification events
+ */
+export interface AssertionResult {
+    label: string;
+    passed: boolean;
+    required?: boolean;
+    reason?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Verify signals for step_end events
+ */
+export interface VerifySignals {
+    url_changed?: boolean;
+    error?: string;
+    elements_found?: ElementFound[];
+    assertions?: AssertionResult[];
+    task_done?: boolean;
+    task_done_label?: string;
+}
+/**
+ * Verify data for step_end events
+ */
+export interface VerifyData {
+    passed: boolean;
+    signals: VerifySignals;
+}
+/**
+ * TraceEventData contains fields for event payloads
+ * All fields are optional since different event types use different subsets
+ */
+export interface TraceEventData {
+    goal?: string;
+    step_index?: number;
+    attempt?: number;
+    step_id?: string;
+    url?: string;
+    element_count?: number;
+    timestamp?: string;
+    elements?: TraceElement[];
+    screenshot_base64?: string;
+    screenshot_format?: string;
+    model?: string;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+    response_text?: string;
+    action_type?: string;
+    action?: string;
+    element_id?: number;
+    text?: string;
+    key?: string;
+    success?: boolean;
+    /** Optional action metadata (e.g., human-like cursor movement path) */
+    cursor?: Record<string, any>;
+    error?: string;
+    agent?: string;
+    llm_model?: string;
+    config?: Record<string, unknown>;
+    steps?: number;
+    status?: 'success' | 'failure' | 'partial' | 'unknown';
+    v?: number;
+    pre?: SnapshotInfo;
+    llm?: LLMUsageData;
+    exec?: ExecutionData;
+    post?: SnapshotInfo;
+    verify?: VerifyData;
+    kind?: 'assert' | 'task_done' | 'captcha';
+    label?: string;
+    passed?: boolean;
+    required?: boolean;
+    reason?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * TraceEvent represents a single event in an agent execution trace
+ */
+export interface TraceEvent {
+    /** Schema version (always 1 for now) */
+    v: number;
+    /** Event type (e.g., 'run_start', 'snapshot', 'action') */
+    type: string;
+    /** ISO 8601 timestamp */
+    ts: string;
+    /** Run UUID */
+    run_id: string;
+    /** Sequence number (monotonically increasing) */
+    seq: number;
+    /** Event-specific payload */
+    data: TraceEventData;
+    /** Optional step UUID (for step-scoped events) */
+    step_id?: string;
+    /** Optional Unix timestamp in milliseconds */
+    ts_ms?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tracing/types.d.ts.map

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

package/dist/tracing/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Tracing Types
+ *
+ * Schema v1 - Compatible with Python SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/tracing/types.js.map

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