@predicatelabs/sdk 0.99.9

package/dist/tracing/jsonl-sink.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * JSONL Trace Sink
+ *
+ * Writes trace events to a local JSONL (JSON Lines) file
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonlTraceSink = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const sink_1 = require("./sink");
+/**
+ * JsonlTraceSink writes trace events to a JSONL file (one JSON object per line)
+ */
+class JsonlTraceSink extends sink_1.TraceSink {
+    /**
+     * Create a new JSONL trace sink
+     * @param filePath - Path to the JSONL file (will be created if doesn't exist)
+     */
+    constructor(filePath) {
+        super();
+        this.writeStream = null;
+        this.closed = false;
+        this.path = filePath;
+        // Create parent directories if needed (synchronously)
+        const dir = path.dirname(filePath);
+        try {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Verify directory is writable
+            fs.accessSync(dir, fs.constants.W_OK);
+            // Open file in append mode with line buffering
+            this.writeStream = fs.createWriteStream(filePath, {
+                flags: 'a',
+                encoding: 'utf-8',
+                autoClose: true,
+            });
+            // Handle stream errors (suppress logging if stream is closed)
+            this.writeStream.on('error', error => {
+                if (!this.closed) {
+                    console.error('[JsonlTraceSink] Stream error:', error);
+                }
+            });
+        }
+        catch (error) {
+            console.error('[JsonlTraceSink] Failed to initialize sink:', error);
+            this.writeStream = null;
+        }
+    }
+    /**
+     * Emit a trace event (write as JSON line)
+     * @param event - Trace event to emit
+     */
+    emit(event) {
+        if (this.closed) {
+            // Only warn in non-test environments to avoid test noise
+            const isTestEnv = process.env.CI === 'true' ||
+                process.env.NODE_ENV === 'test' ||
+                process.env.JEST_WORKER_ID !== undefined ||
+                (typeof global !== 'undefined' && global.__JEST__);
+            if (!isTestEnv) {
+                console.warn('[JsonlTraceSink] Attempted to emit after close()');
+            }
+            return;
+        }
+        if (!this.writeStream) {
+            console.error('[JsonlTraceSink] Write stream not available');
+            return;
+        }
+        try {
+            const jsonLine = JSON.stringify(event) + '\n';
+            const written = this.writeStream.write(jsonLine);
+            // If write returns false, the stream is backpressured
+            // We don't need to wait, but we could add a drain listener if needed
+            if (!written) {
+                // Stream is backpressured - wait for drain
+                this.writeStream.once('drain', () => {
+                    // Stream is ready again
+                });
+            }
+        }
+        catch (error) {
+            // Log error but don't crash agent execution
+            console.error('[JsonlTraceSink] Failed to write event:', error);
+        }
+    }
+    /**
+     * Close the sink and flush buffered data
+     */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        // Check if stream exists and is writable
+        if (!this.writeStream || this.writeStream.destroyed) {
+            return;
+        }
+        // Store reference to satisfy TypeScript null checks
+        const stream = this.writeStream;
+        // Remove error listener to prevent late errors
+        stream.removeAllListeners('error');
+        return new Promise(resolve => {
+            // Check if stream is already closed
+            if (stream.destroyed || !stream.writable) {
+                // Stream already closed, generate index and resolve immediately
+                this.generateIndex();
+                resolve();
+                return;
+            }
+            let resolved = false;
+            const doResolve = () => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    // Generate index after closing file
+                    this.generateIndex();
+                    resolve();
+                }
+            };
+            // Fallback timeout in case 'close' event doesn't fire (shouldn't happen, but safety)
+            const timeout = setTimeout(() => {
+                if (!resolved) {
+                    doResolve();
+                }
+            }, 500);
+            // Wait for stream to fully close (Windows needs this)
+            // The 'close' event fires after all data is flushed and file handle is released
+            stream.once('close', doResolve);
+            stream.end((err) => {
+                if (err) {
+                    // Silently ignore close errors in production
+                    // (they're logged during stream lifetime if needed)
+                }
+                // Note: 'close' event will fire after end() completes
+                // Don't resolve here - wait for 'close' event
+            });
+        });
+    }
+    /**
+     * Generate trace index file (automatic on close)
+     */
+    generateIndex() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { writeTraceIndex } = require('./indexer');
+            // Use frontend format to ensure 'step' field is present (1-based)
+            // Frontend derives sequence from step.step - 1, so step must be valid
+            const indexPath = this.path.replace(/\.jsonl$/, '.index.json');
+            writeTraceIndex(this.path, indexPath, true);
+        }
+        catch (error) {
+            // Non-fatal: log but don't crash
+            console.log(`⚠️  Failed to generate trace index: ${error.message}`);
+        }
+    }
+    /**
+     * Get sink type identifier
+     */
+    getSinkType() {
+        return `JsonlTraceSink(${this.path})`;
+    }
+    /**
+     * Get file path
+     */
+    getPath() {
+        return this.path;
+    }
+    /**
+     * Check if sink is closed
+     */
+    isClosed() {
+        return this.closed;
+    }
+    /**
+     * Extract execution statistics from trace file (for local traces).
+     * @returns Trace statistics
+     */
+    getStats() {
+        try {
+            // Read trace file to extract stats
+            const traceContent = fs.readFileSync(this.path, 'utf-8');
+            const lines = traceContent.split('\n').filter(line => line.trim());
+            const events = [];
+            for (const line of lines) {
+                try {
+                    const event = JSON.parse(line);
+                    events.push(event);
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (events.length === 0) {
+                return {
+                    total_steps: 0,
+                    total_events: 0,
+                    duration_ms: null,
+                    final_status: 'unknown',
+                    started_at: null,
+                    ended_at: null,
+                };
+            }
+            // Find run_start and run_end events
+            const runStart = events.find(e => e.type === 'run_start');
+            const runEnd = events.find(e => e.type === 'run_end');
+            // Extract timestamps
+            const startedAt = runStart?.ts || null;
+            const endedAt = runEnd?.ts || null;
+            // Calculate duration
+            let durationMs = null;
+            if (startedAt && endedAt) {
+                try {
+                    const startDt = new Date(startedAt);
+                    const endDt = new Date(endedAt);
+                    durationMs = endDt.getTime() - startDt.getTime();
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+            // Count steps (from step_start events, only first attempt)
+            const stepIndices = new Set();
+            for (const event of events) {
+                if (event.type === 'step_start') {
+                    const stepIndex = event.data?.step_index;
+                    if (stepIndex !== undefined) {
+                        stepIndices.add(stepIndex);
+                    }
+                }
+            }
+            let totalSteps = stepIndices.size;
+            // If run_end has steps count, use that (more accurate)
+            if (runEnd) {
+                const stepsFromEnd = runEnd.data?.steps;
+                if (stepsFromEnd !== undefined) {
+                    totalSteps = Math.max(totalSteps, stepsFromEnd);
+                }
+            }
+            // Count total events
+            const totalEvents = events.length;
+            // Infer final status
+            let finalStatus = 'unknown';
+            // Check for run_end event with status
+            if (runEnd) {
+                const status = runEnd.data?.status;
+                if (status === 'success' ||
+                    status === 'failure' ||
+                    status === 'partial' ||
+                    status === 'unknown') {
+                    finalStatus = status;
+                }
+            }
+            else {
+                // Infer from error events
+                const hasErrors = events.some(e => e.type === 'error');
+                if (hasErrors) {
+                    const stepEnds = events.filter(e => e.type === 'step_end');
+                    if (stepEnds.length > 0) {
+                        finalStatus = 'partial';
+                    }
+                    else {
+                        finalStatus = 'failure';
+                    }
+                }
+                else {
+                    const stepEnds = events.filter(e => e.type === 'step_end');
+                    if (stepEnds.length > 0) {
+                        finalStatus = 'success';
+                    }
+                }
+            }
+            return {
+                total_steps: totalSteps,
+                total_events: totalEvents,
+                duration_ms: durationMs,
+                final_status: finalStatus,
+                started_at: startedAt,
+                ended_at: endedAt,
+            };
+        }
+        catch {
+            return {
+                total_steps: 0,
+                total_events: 0,
+                duration_ms: null,
+                final_status: 'unknown',
+                started_at: null,
+                ended_at: null,
+            };
+        }
+    }
+}
+exports.JsonlTraceSink = JsonlTraceSink;
+//# sourceMappingURL=jsonl-sink.js.map

package/dist/tracing/jsonl-sink.js.map

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

package/dist/tracing/sink.d.ts

@@ -0,0 +1,25 @@
+/**
+ * TraceSink Abstract Class
+ *
+ * Defines the interface for trace event sinks (local files, cloud storage, etc.)
+ */
+import { TraceEvent } from './types';
+/**
+ * Abstract base class for trace sinks
+ */
+export declare abstract class TraceSink {
+    /**
+     * Emit a trace event
+     * @param event - Trace event to emit
+     */
+    abstract emit(event: TraceEvent): void;
+    /**
+     * Close the sink and flush buffered data
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Get unique identifier for this sink (for debugging)
+     */
+    abstract getSinkType(): string;
+}
+//# sourceMappingURL=sink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/tracing/sink.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,8BAAsB,SAAS;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAEtC;;OAEG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,WAAW,IAAI,MAAM;CAC/B"}

package/dist/tracing/sink.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * TraceSink Abstract Class
+ *
+ * Defines the interface for trace event sinks (local files, cloud storage, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceSink = void 0;
+/**
+ * Abstract base class for trace sinks
+ */
+class TraceSink {
+}
+exports.TraceSink = TraceSink;
+//# sourceMappingURL=sink.js.map

package/dist/tracing/sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.js","sourceRoot":"","sources":["../../src/tracing/sink.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH;;GAEG;AACH,MAAsB,SAAS;CAgB9B;AAhBD,8BAgBC"}

package/dist/tracing/tracer-factory.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Tracer Factory with Automatic Tier Detection
+ *
+ * Provides convenient factory function for creating tracers with cloud upload support
+ *
+ * PRODUCTION HARDENING:
+ * - Recovers orphaned traces from previous crashes on SDK init (Risk #3)
+ * - Passes runId to CloudTraceSink for persistent cache naming (Risk #1)
+ */
+import { Tracer } from './tracer';
+import { SentienceLogger } from './cloud-sink';
+/**
+ * Sentience API base URL (constant)
+ */
+export declare const SENTIENCE_API_URL = "https://api.sentienceapi.com";
+/**
+ * Create tracer with automatic tier detection
+ *
+ * Tier Detection:
+ * - If apiKey is provided AND uploadTrace is true: Try to initialize CloudTraceSink (Pro/Enterprise)
+ * - If cloud init fails, no apiKey, or uploadTrace is false: Fall back to JsonlTraceSink (Free tier)
+ *
+ * @param options - Configuration options
+ * @param options.apiKey - Sentience API key (e.g., "sk_pro_xxxxx")
+ * @param options.runId - Unique identifier for this agent run (generates UUID if not provided)
+ * @param options.apiUrl - Sentience API base URL (default: https://api.sentienceapi.com)
+ * @param options.logger - Optional logger instance for logging file sizes and errors
+ * @param options.uploadTrace - Enable cloud trace upload (default: true for backward compatibility)
+ * @param options.goal - User's goal/objective for this trace run. This will be displayed as the trace name in the frontend. Should be descriptive and action-oriented. Example: "Add wireless headphones to cart on Amazon"
+ * @param options.agentType - Type of agent running (e.g., "SentienceAgent", "CustomAgent")
+ * @param options.llmModel - LLM model used (e.g., "gpt-4-turbo", "claude-3-5-sonnet")
+ * @param options.startUrl - Starting URL of the agent run (e.g., "https://amazon.com")
+ * @param options.screenshotProcessor - Optional function to process screenshots before upload. Takes base64 string, returns processed base64 string. Useful for PII redaction or custom image processing.
+ * @param options.autoEmitRunStart - If true (default), automatically emit run_start event with provided metadata. This ensures traces have complete structure for Studio visualization.
+ * @returns Tracer configured with appropriate sink
+ *
+ * @example
+ * ```typescript
+ * // Pro tier user with goal and metadata
+ * const tracer = await createTracer({
+ *   apiKey: "sk_pro_xyz",
+ *   runId: "demo",
+ *   goal: "Add headphones to cart",
+ *   agentType: "SentienceAgent",
+ *   llmModel: "gpt-4-turbo",
+ *   startUrl: "https://amazon.com",
+ *   uploadTrace: true
+ * });
+ * // Returns: Tracer with CloudTraceSink
+ * // run_start event is automatically emitted
+ *
+ * // With screenshot processor for PII redaction
+ * const redactPII = (screenshot: string): string => {
+ *   // Your custom redaction logic
+ *   return redactedScreenshot;
+ * };
+ * const tracer = await createTracer({
+ *   apiKey: "sk_pro_xyz",
+ *   screenshotProcessor: redactPII
+ * });
+ * // Screenshots will be processed before upload
+ *
+ * // Pro tier user with local-only tracing
+ * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo", uploadTrace: false });
+ * // Returns: Tracer with JsonlTraceSink (local-only)
+ *
+ * // Disable auto-emit for manual control
+ * const tracer = await createTracer({ runId: "demo", autoEmitRunStart: false });
+ * tracer.emitRunStart("MyAgent", "gpt-4o"); // Manual emit
+ *
+ * // Free tier user
+ * const tracer = await createTracer({ runId: "demo" });
+ * // Returns: Tracer with JsonlTraceSink (local-only)
+ *
+ * // Use with agent
+ * const agent = new SentienceAgent(browser, llm, 50, true, tracer);
+ * await agent.act("Click search");
+ * await tracer.close(); // Uploads to cloud if uploadTrace: true and Pro tier
+ * ```
+ */
+export declare function createTracer(options: {
+    apiKey?: string;
+    runId?: string;
+    apiUrl?: string;
+    logger?: SentienceLogger;
+    uploadTrace?: boolean;
+    goal?: string;
+    agentType?: string;
+    llmModel?: string;
+    startUrl?: string;
+    screenshotProcessor?: (screenshot: string) => string;
+    autoEmitRunStart?: boolean;
+}): Promise<Tracer>;
+/**
+ * Synchronous version of createTracer for non-async contexts
+ * Always returns local JsonlTraceSink (no cloud upload)
+ *
+ * @param runId - Unique identifier for this agent run (generates UUID if not provided)
+ * @returns Tracer with JsonlTraceSink
+ */
+export declare function createLocalTracer(runId?: string): Tracer;
+//# sourceMappingURL=tracer-factory.d.ts.map

package/dist/tracing/tracer-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-factory.d.ts","sourceRoot":"","sources":["../../src/tracing/tracer-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAgC/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AA8JhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuGlB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAYxD"}