sentienceapi 0.90.6 → 0.90.11

package/dist/tracing/index-schema.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Type definitions for trace index schema using concrete classes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceIndex = exports.StepIndex = exports.StepCounters = exports.ActionInfo = exports.SnapshotInfo = exports.TraceSummary = exports.TraceFileInfo = void 0;
+class TraceFileInfo {
+    constructor(path, size_bytes, sha256) {
+        this.path = path;
+        this.size_bytes = size_bytes;
+        this.sha256 = sha256;
+    }
+    toJSON() {
+        return {
+            path: this.path,
+            size_bytes: this.size_bytes,
+            sha256: this.sha256,
+        };
+    }
+}
+exports.TraceFileInfo = TraceFileInfo;
+class TraceSummary {
+    constructor(first_ts, last_ts, event_count, step_count, error_count, final_url) {
+        this.first_ts = first_ts;
+        this.last_ts = last_ts;
+        this.event_count = event_count;
+        this.step_count = step_count;
+        this.error_count = error_count;
+        this.final_url = final_url;
+    }
+    toJSON() {
+        return {
+            first_ts: this.first_ts,
+            last_ts: this.last_ts,
+            event_count: this.event_count,
+            step_count: this.step_count,
+            error_count: this.error_count,
+            final_url: this.final_url,
+        };
+    }
+}
+exports.TraceSummary = TraceSummary;
+class SnapshotInfo {
+    constructor(snapshot_id = null, digest = null, url = null) {
+        this.snapshot_id = snapshot_id;
+        this.digest = digest;
+        this.url = url;
+    }
+    toJSON() {
+        return {
+            snapshot_id: this.snapshot_id,
+            digest: this.digest,
+            url: this.url,
+        };
+    }
+}
+exports.SnapshotInfo = SnapshotInfo;
+class ActionInfo {
+    constructor(type = null, target_element_id = null, args_digest = null, success = null) {
+        this.type = type;
+        this.target_element_id = target_element_id;
+        this.args_digest = args_digest;
+        this.success = success;
+    }
+    toJSON() {
+        return {
+            type: this.type,
+            target_element_id: this.target_element_id,
+            args_digest: this.args_digest,
+            success: this.success,
+        };
+    }
+}
+exports.ActionInfo = ActionInfo;
+class StepCounters {
+    constructor(events = 0, snapshots = 0, actions = 0, llm_calls = 0) {
+        this.events = events;
+        this.snapshots = snapshots;
+        this.actions = actions;
+        this.llm_calls = llm_calls;
+    }
+    toJSON() {
+        return {
+            events: this.events,
+            snapshots: this.snapshots,
+            actions: this.actions,
+            llm_calls: this.llm_calls,
+        };
+    }
+}
+exports.StepCounters = StepCounters;
+class StepIndex {
+    constructor(step_index, step_id, goal, status, ts_start, ts_end, offset_start, offset_end, url_before, url_after, snapshot_before, snapshot_after, action, counters) {
+        this.step_index = step_index;
+        this.step_id = step_id;
+        this.goal = goal;
+        this.status = status;
+        this.ts_start = ts_start;
+        this.ts_end = ts_end;
+        this.offset_start = offset_start;
+        this.offset_end = offset_end;
+        this.url_before = url_before;
+        this.url_after = url_after;
+        this.snapshot_before = snapshot_before;
+        this.snapshot_after = snapshot_after;
+        this.action = action;
+        this.counters = counters;
+    }
+    toJSON() {
+        return {
+            step_index: this.step_index,
+            step_id: this.step_id,
+            goal: this.goal,
+            status: this.status,
+            ts_start: this.ts_start,
+            ts_end: this.ts_end,
+            offset_start: this.offset_start,
+            offset_end: this.offset_end,
+            url_before: this.url_before,
+            url_after: this.url_after,
+            snapshot_before: this.snapshot_before.toJSON(),
+            snapshot_after: this.snapshot_after.toJSON(),
+            action: this.action.toJSON(),
+            counters: this.counters.toJSON(),
+        };
+    }
+}
+exports.StepIndex = StepIndex;
+class TraceIndex {
+    constructor(version, run_id, created_at, trace_file, summary, steps = []) {
+        this.version = version;
+        this.run_id = run_id;
+        this.created_at = created_at;
+        this.trace_file = trace_file;
+        this.summary = summary;
+        this.steps = steps;
+    }
+    toJSON() {
+        return {
+            version: this.version,
+            run_id: this.run_id,
+            created_at: this.created_at,
+            trace_file: this.trace_file.toJSON(),
+            summary: this.summary.toJSON(),
+            steps: this.steps.map((s) => s.toJSON()),
+        };
+    }
+}
+exports.TraceIndex = TraceIndex;
+//# sourceMappingURL=index-schema.js.map

package/dist/tracing/index-schema.js.map

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

package/dist/tracing/indexer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Trace indexing for fast timeline rendering and step drill-down.
+ */
+import { TraceIndex } from './index-schema';
+/**
+ * Build trace index from JSONL file in single streaming pass
+ */
+export declare function buildTraceIndex(tracePath: string): TraceIndex;
+/**
+ * Build index and write to file
+ */
+export declare function writeTraceIndex(tracePath: string, indexPath?: string): string;
+/**
+ * Read events for a specific step using byte offsets from index
+ */
+export declare function readStepEvents(tracePath: string, offsetStart: number, offsetEnd: number): any[];
+//# sourceMappingURL=indexer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../src/tracing/indexer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EACL,UAAU,EAQX,MAAM,gBAAgB,CAAC;AA6GxB;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CA+J7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAU7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,GAAG,EAAE,CA0BP"}

package/dist/tracing/indexer.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Trace indexing for fast timeline rendering and step drill-down.
+ */
+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.buildTraceIndex = buildTraceIndex;
+exports.writeTraceIndex = writeTraceIndex;
+exports.readStepEvents = readStepEvents;
+const fs = __importStar(require("fs"));
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+const index_schema_1 = require("./index-schema");
+/**
+ * Normalize text for digest: trim, collapse whitespace, lowercase, cap length
+ */
+function normalizeText(text, maxLen = 80) {
+    if (!text)
+        return '';
+    // Trim and collapse whitespace
+    let normalized = text.split(/\s+/).join(' ').trim();
+    // Lowercase
+    normalized = normalized.toLowerCase();
+    // Cap length
+    if (normalized.length > maxLen) {
+        normalized = normalized.substring(0, maxLen);
+    }
+    return normalized;
+}
+/**
+ * Round bbox coordinates to reduce noise (default: 2px precision)
+ */
+function roundBBox(bbox, precision = 2) {
+    return {
+        x: Math.round((bbox.x || 0) / precision) * precision,
+        y: Math.round((bbox.y || 0) / precision) * precision,
+        width: Math.round((bbox.width || 0) / precision) * precision,
+        height: Math.round((bbox.height || 0) / precision) * precision,
+    };
+}
+/**
+ * Compute stable digest of snapshot for diffing
+ */
+function computeSnapshotDigest(snapshotData) {
+    const url = snapshotData.url || '';
+    const viewport = snapshotData.viewport || {};
+    const elements = snapshotData.elements || [];
+    // Canonicalize elements
+    const canonicalElements = elements.map((elem) => ({
+        id: elem.id,
+        role: elem.role || '',
+        text_norm: normalizeText(elem.text),
+        bbox: roundBBox(elem.bbox || { x: 0, y: 0, width: 0, height: 0 }),
+        is_primary: elem.is_primary || false,
+        is_clickable: elem.is_clickable || false,
+    }));
+    // Sort by element id for determinism
+    canonicalElements.sort((a, b) => (a.id || 0) - (b.id || 0));
+    // Build canonical object
+    const canonical = {
+        url,
+        viewport: {
+            width: viewport.width || 0,
+            height: viewport.height || 0,
+        },
+        elements: canonicalElements,
+    };
+    // Hash
+    const canonicalJson = JSON.stringify(canonical);
+    const hash = crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+    return `sha256:${hash}`;
+}
+/**
+ * Compute digest of action args for privacy + determinism
+ */
+function computeActionDigest(actionData) {
+    const actionType = actionData.type || '';
+    const targetId = actionData.target_element_id;
+    const canonical = {
+        type: actionType,
+        target_element_id: targetId,
+    };
+    // Type-specific canonicalization
+    if (actionType === 'TYPE') {
+        const text = actionData.text || '';
+        canonical.text_len = text.length;
+        canonical.text_sha256 = crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+    }
+    else if (actionType === 'PRESS') {
+        canonical.key = actionData.key || '';
+    }
+    // CLICK has no extra args
+    // Hash
+    const canonicalJson = JSON.stringify(canonical);
+    const hash = crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+    return `sha256:${hash}`;
+}
+/**
+ * Compute SHA256 hash of entire file
+ */
+function computeFileSha256(filePath) {
+    const hash = crypto.createHash('sha256');
+    const data = fs.readFileSync(filePath);
+    hash.update(data);
+    return hash.digest('hex');
+}
+/**
+ * Build trace index from JSONL file in single streaming pass
+ */
+function buildTraceIndex(tracePath) {
+    if (!fs.existsSync(tracePath)) {
+        throw new Error(`Trace file not found: ${tracePath}`);
+    }
+    // Extract run_id from filename
+    const runId = path.basename(tracePath, '.jsonl');
+    // Initialize summary
+    let firstTs = '';
+    let lastTs = '';
+    let eventCount = 0;
+    let errorCount = 0;
+    let finalUrl = null;
+    const stepsById = new Map();
+    const stepOrder = [];
+    // Stream through file, tracking byte offsets
+    const fileBuffer = fs.readFileSync(tracePath);
+    let byteOffset = 0;
+    const lines = fileBuffer.toString('utf-8').split('\n');
+    for (const line of lines) {
+        const lineBytes = Buffer.byteLength(line + '\n', 'utf-8');
+        if (!line.trim()) {
+            byteOffset += lineBytes;
+            continue;
+        }
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch (e) {
+            // Skip malformed lines
+            byteOffset += lineBytes;
+            continue;
+        }
+        // Extract event metadata
+        const eventType = event.type || '';
+        const ts = event.ts || event.timestamp || '';
+        const stepId = event.step_id || 'step-0';
+        const data = event.data || {};
+        // Update summary
+        eventCount++;
+        if (!firstTs) {
+            firstTs = ts;
+        }
+        lastTs = ts;
+        if (eventType === 'error') {
+            errorCount++;
+        }
+        // Initialize step if first time seeing this step_id
+        if (!stepsById.has(stepId)) {
+            stepOrder.push(stepId);
+            stepsById.set(stepId, new index_schema_1.StepIndex(stepOrder.length, stepId, null, 'partial', ts, ts, byteOffset, byteOffset + lineBytes, null, null, new index_schema_1.SnapshotInfo(), new index_schema_1.SnapshotInfo(), new index_schema_1.ActionInfo(), new index_schema_1.StepCounters()));
+        }
+        const step = stepsById.get(stepId);
+        // Update step metadata
+        step.ts_end = ts;
+        step.offset_end = byteOffset + lineBytes;
+        step.counters.events++;
+        // Handle specific event types
+        if (eventType === 'step_start') {
+            step.goal = data.goal;
+            step.url_before = data.pre_url;
+        }
+        else if (eventType === 'snapshot') {
+            const snapshotId = data.snapshot_id;
+            const url = data.url;
+            const digest = computeSnapshotDigest(data);
+            // First snapshot = before, last snapshot = after
+            if (!step.snapshot_before.snapshot_id) {
+                step.snapshot_before = new index_schema_1.SnapshotInfo(snapshotId, digest, url);
+                step.url_before = step.url_before || url;
+            }
+            step.snapshot_after = new index_schema_1.SnapshotInfo(snapshotId, digest, url);
+            step.url_after = url;
+            step.counters.snapshots++;
+            finalUrl = url;
+        }
+        else if (eventType === 'action') {
+            step.action = new index_schema_1.ActionInfo(data.type, data.target_element_id, computeActionDigest(data), data.success !== false);
+            step.counters.actions++;
+        }
+        else if (eventType === 'llm_response') {
+            step.counters.llm_calls++;
+        }
+        else if (eventType === 'error') {
+            step.status = 'error';
+        }
+        else if (eventType === 'step_end') {
+            if (step.status !== 'error') {
+                step.status = 'ok';
+            }
+        }
+        byteOffset += lineBytes;
+    }
+    // Build summary
+    const summary = new index_schema_1.TraceSummary(firstTs, lastTs, eventCount, stepsById.size, errorCount, finalUrl);
+    // Build steps list in order
+    const stepsList = stepOrder.map((sid) => stepsById.get(sid));
+    // Build trace file info
+    const traceFile = new index_schema_1.TraceFileInfo(tracePath, fs.statSync(tracePath).size, computeFileSha256(tracePath));
+    // Build final index
+    const index = new index_schema_1.TraceIndex(1, runId, new Date().toISOString(), traceFile, summary, stepsList);
+    return index;
+}
+/**
+ * Build index and write to file
+ */
+function writeTraceIndex(tracePath, indexPath) {
+    if (!indexPath) {
+        indexPath = tracePath.replace(/\.jsonl$/, '.index.json');
+    }
+    const index = buildTraceIndex(tracePath);
+    fs.writeFileSync(indexPath, JSON.stringify(index.toJSON(), null, 2));
+    return indexPath;
+}
+/**
+ * Read events for a specific step using byte offsets from index
+ */
+function readStepEvents(tracePath, offsetStart, offsetEnd) {
+    const events = [];
+    const fd = fs.openSync(tracePath, 'r');
+    const bytesToRead = offsetEnd - offsetStart;
+    const buffer = Buffer.alloc(bytesToRead);
+    fs.readSync(fd, buffer, 0, bytesToRead, offsetStart);
+    fs.closeSync(fd);
+    // Parse lines
+    const chunk = buffer.toString('utf-8');
+    const lines = chunk.split('\n');
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            events.push(event);
+        }
+        catch (e) {
+            // Skip malformed lines
+        }
+    }
+    return events;
+}
+//# sourceMappingURL=indexer.js.map

package/dist/tracing/indexer.js.map

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

package/dist/tracing/jsonl-sink.d.ts

@@ -25,6 +25,10 @@ export declare class JsonlTraceSink extends TraceSink {
      * Close the sink and flush buffered data
      */
     close(): Promise<void>;
+    /**
+     * Generate trace index file (automatic on close)
+     */
+    private generateIndex;
     /**
      * Get sink type identifier
      */

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

@@ -1 +1 @@
-{"version":3,"file":"jsonl-sink.d.ts","sourceRoot":"","sources":["../../src/tracing/jsonl-sink.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;OAGG;gBACS,QAAQ,EAAE,MAAM;IAiC5B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAoCtC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B5B;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGpB"}
+{"version":3,"file":"jsonl-sink.d.ts","sourceRoot":"","sources":["../../src/tracing/jsonl-sink.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;OAGG;gBACS,QAAQ,EAAE,MAAM;IAiC5B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAoCtC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;OAEG;IACH,QAAQ,IAAI,OAAO;CAGpB"}

package/dist/tracing/jsonl-sink.js

@@ -140,11 +140,26 @@ class JsonlTraceSink extends sink_1.TraceSink {
                     // Silently ignore close errors in production
                     // (they're logged during stream lifetime if needed)
                 }
+                // Generate index after closing file
+                this.generateIndex();
                 // Always resolve, don't reject on close errors
                 resolve();
             });
         });
     }
+    /**
+     * Generate trace index file (automatic on close)
+     */
+    generateIndex() {
+        try {
+            const { writeTraceIndex } = require('./indexer');
+            writeTraceIndex(this.path);
+        }
+        catch (error) {
+            // Non-fatal: log but don't crash
+            console.log(`⚠️  Failed to generate trace index: ${error.message}`);
+        }
+    }
     /**
      * Get sink type identifier
      */

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

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

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

@@ -17,22 +17,27 @@ export declare const SENTIENCE_API_URL = "https://api.sentienceapi.com";
  * Create tracer with automatic tier detection
  *
  * Tier Detection:
- * - If apiKey is provided: Try to initialize CloudTraceSink (Pro/Enterprise)
- * - If cloud init fails or no apiKey: Fall back to JsonlTraceSink (Free tier)
+ * - 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)
  * @returns Tracer configured with appropriate sink
  *
  * @example
  * ```typescript
- * // Pro tier user
- * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo" });
+ * // Pro tier user with cloud upload
+ * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo", uploadTrace: true });
  * // Returns: Tracer with CloudTraceSink
  *
+ * // 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)
+ *
  * // Free tier user
  * const tracer = await createTracer({ runId: "demo" });
  * // Returns: Tracer with JsonlTraceSink (local-only)
@@ -40,7 +45,7 @@ export declare const SENTIENCE_API_URL = "https://api.sentienceapi.com";
  * // Use with agent
  * const agent = new SentienceAgent(browser, llm, 50, true, tracer);
  * await agent.act("Click search");
- * await tracer.close(); // Uploads to cloud if Pro tier
+ * await tracer.close(); // Uploads to cloud if uploadTrace: true and Pro tier
  * ```
  */
 export declare function createTracer(options: {
@@ -48,6 +53,7 @@ export declare function createTracer(options: {
     runId?: string;
     apiUrl?: string;
     logger?: SentienceLogger;
+    uploadTrace?: boolean;
 }): Promise<Tracer>;
 /**
  * Synchronous version of createTracer for non-async contexts

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

@@ -1 +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;AAG/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AA2IhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;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;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgElB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAYxD"}
+{"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;AAG/D;;GAEG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AA2IhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoElB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAYxD"}

package/dist/tracing/tracer-factory.js

@@ -174,22 +174,27 @@ function httpPost(url, data, headers) {
  * Create tracer with automatic tier detection
  *
  * Tier Detection:
- * - If apiKey is provided: Try to initialize CloudTraceSink (Pro/Enterprise)
- * - If cloud init fails or no apiKey: Fall back to JsonlTraceSink (Free tier)
+ * - 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)
  * @returns Tracer configured with appropriate sink
  *
  * @example
  * ```typescript
- * // Pro tier user
- * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo" });
+ * // Pro tier user with cloud upload
+ * const tracer = await createTracer({ apiKey: "sk_pro_xyz", runId: "demo", uploadTrace: true });
  * // Returns: Tracer with CloudTraceSink
  *
+ * // 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)
+ *
  * // Free tier user
  * const tracer = await createTracer({ runId: "demo" });
  * // Returns: Tracer with JsonlTraceSink (local-only)
@@ -197,23 +202,27 @@ function httpPost(url, data, headers) {
  * // Use with agent
  * const agent = new SentienceAgent(browser, llm, 50, true, tracer);
  * await agent.act("Click search");
- * await tracer.close(); // Uploads to cloud if Pro tier
+ * await tracer.close(); // Uploads to cloud if uploadTrace: true and Pro tier
  * ```
  */
 async function createTracer(options) {
     const runId = options.runId || (0, crypto_1.randomUUID)();
     const apiUrl = options.apiUrl || exports.SENTIENCE_API_URL;
+    // Default uploadTrace to true for backward compatibility
+    const uploadTrace = options.uploadTrace !== false;
     // PRODUCTION FIX: Recover orphaned traces from previous crashes
     // Note: This is skipped in test environments (see recoverOrphanedTraces function)
     // Run in background to avoid blocking tracer creation
-    if (options.apiKey) {
+    // Only recover if uploadTrace is enabled
+    if (options.apiKey && uploadTrace) {
         // Don't await - run in background to avoid blocking
         recoverOrphanedTraces(options.apiKey, apiUrl).catch(() => {
             // Silently fail - orphan recovery should not block tracer creation
         });
     }
     // 1. Try to initialize Cloud Sink (Pro/Enterprise tier)
-    if (options.apiKey) {
+    // Only attempt cloud init if uploadTrace is enabled
+    if (options.apiKey && uploadTrace) {
         try {
             // Request pre-signed upload URL from backend
             const response = await httpPost(`${apiUrl}/v1/traces/init`, { run_id: runId }, { Authorization: `Bearer ${options.apiKey}` });