sentienceapi 0.90.1

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

@@ -0,0 +1,74 @@
+/**
+ * CloudTraceSink - Enterprise Cloud Upload
+ *
+ * Implements "Local Write, Batch Upload" pattern for cloud tracing
+ *
+ * PRODUCTION HARDENING:
+ * - Uses persistent cache directory (~/.sentience/traces/pending/) to survive crashes
+ * - Supports non-blocking close() to avoid hanging user scripts
+ * - Preserves traces locally on upload failure
+ */
+import { TraceSink } from './sink';
+/**
+ * CloudTraceSink writes trace events to a local temp file,
+ * then uploads the complete trace to cloud storage on close()
+ *
+ * Architecture:
+ * 1. **Local Buffer**: Writes to temp file (zero latency, non-blocking)
+ * 2. **Pre-signed URL**: Uses secure pre-signed PUT URL from backend API
+ * 3. **Batch Upload**: Uploads complete file on close() or at intervals
+ * 4. **Zero Credential Exposure**: Never embeds cloud credentials in SDK
+ *
+ * This design ensures:
+ * - Fast agent performance (microseconds per emit, not milliseconds)
+ * - Security (credentials stay on backend)
+ * - Reliability (network issues don't crash the agent)
+ *
+ * Example:
+ *   const sink = new CloudTraceSink(uploadUrl);
+ *   const tracer = new Tracer(runId, sink);
+ *   tracer.emitRunStart('SentienceAgent');
+ *   await tracer.close(); // Uploads to cloud
+ */
+export declare class CloudTraceSink extends TraceSink {
+    private uploadUrl;
+    private tempFilePath;
+    private runId;
+    private writeStream;
+    private closed;
+    /**
+     * Create a new CloudTraceSink
+     *
+     * @param uploadUrl - Pre-signed PUT URL from Sentience API
+     * @param runId - Run ID for persistent cache naming
+     */
+    constructor(uploadUrl: string, runId?: string);
+    /**
+     * Emit a trace event to local temp file (fast, non-blocking)
+     *
+     * @param event - Event dictionary from TraceEvent
+     */
+    emit(event: Record<string, any>): void;
+    /**
+     * Upload data to cloud using Node's built-in https module
+     */
+    private _uploadToCloud;
+    /**
+     * Upload buffered trace to cloud via pre-signed URL
+     *
+     * @param blocking - If false, upload happens in background (default: true)
+     *
+     * PRODUCTION FIX: Non-blocking mode prevents hanging user scripts
+     * on slow uploads (Risk #2 from production hardening plan)
+     */
+    close(blocking?: boolean): Promise<void>;
+    /**
+     * Internal upload logic (called by both blocking and non-blocking close)
+     */
+    private _doUpload;
+    /**
+     * Get unique identifier for this sink
+     */
+    getSinkType(): string;
+}
+//# sourceMappingURL=cloud-sink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-sink.d.ts","sourceRoot":"","sources":["../../src/tracing/cloud-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAkBnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;;;OAKG;gBACS,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IA8B7C;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAkBtC;;OAEG;YACW,cAAc;IAwC5B;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BpD;;OAEG;YACW,SAAS;IA+CvB;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/tracing/cloud-sink.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * CloudTraceSink - Enterprise Cloud Upload
+ *
+ * Implements "Local Write, Batch Upload" pattern for cloud tracing
+ *
+ * PRODUCTION HARDENING:
+ * - Uses persistent cache directory (~/.sentience/traces/pending/) to survive crashes
+ * - Supports non-blocking close() to avoid hanging user scripts
+ * - Preserves traces locally on upload failure
+ */
+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.CloudTraceSink = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const zlib = __importStar(require("zlib"));
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const url_1 = require("url");
+const sink_1 = require("./sink");
+/**
+ * Get persistent cache directory for traces
+ * Uses ~/.sentience/traces/pending/ (survives process crashes)
+ */
+function getPersistentCacheDir() {
+    const homeDir = os.homedir();
+    const cacheDir = path.join(homeDir, '.sentience', 'traces', 'pending');
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+    }
+    return cacheDir;
+}
+/**
+ * CloudTraceSink writes trace events to a local temp file,
+ * then uploads the complete trace to cloud storage on close()
+ *
+ * Architecture:
+ * 1. **Local Buffer**: Writes to temp file (zero latency, non-blocking)
+ * 2. **Pre-signed URL**: Uses secure pre-signed PUT URL from backend API
+ * 3. **Batch Upload**: Uploads complete file on close() or at intervals
+ * 4. **Zero Credential Exposure**: Never embeds cloud credentials in SDK
+ *
+ * This design ensures:
+ * - Fast agent performance (microseconds per emit, not milliseconds)
+ * - Security (credentials stay on backend)
+ * - Reliability (network issues don't crash the agent)
+ *
+ * Example:
+ *   const sink = new CloudTraceSink(uploadUrl);
+ *   const tracer = new Tracer(runId, sink);
+ *   tracer.emitRunStart('SentienceAgent');
+ *   await tracer.close(); // Uploads to cloud
+ */
+class CloudTraceSink extends sink_1.TraceSink {
+    /**
+     * Create a new CloudTraceSink
+     *
+     * @param uploadUrl - Pre-signed PUT URL from Sentience API
+     * @param runId - Run ID for persistent cache naming
+     */
+    constructor(uploadUrl, runId) {
+        super();
+        this.writeStream = null;
+        this.closed = false;
+        this.uploadUrl = uploadUrl;
+        this.runId = runId || `trace-${Date.now()}`;
+        // PRODUCTION FIX: Use persistent cache directory instead of /tmp
+        // This ensures traces survive process crashes!
+        const cacheDir = getPersistentCacheDir();
+        this.tempFilePath = path.join(cacheDir, `${this.runId}.jsonl`);
+        try {
+            // Open file in append mode
+            this.writeStream = fs.createWriteStream(this.tempFilePath, {
+                flags: 'a',
+                encoding: 'utf-8',
+                autoClose: true,
+            });
+            // Handle stream errors (suppress if closed)
+            this.writeStream.on('error', (error) => {
+                if (!this.closed) {
+                    console.error('[CloudTraceSink] Stream error:', error);
+                }
+            });
+        }
+        catch (error) {
+            console.error('[CloudTraceSink] Failed to initialize sink:', error);
+            this.writeStream = null;
+        }
+    }
+    /**
+     * Emit a trace event to local temp file (fast, non-blocking)
+     *
+     * @param event - Event dictionary from TraceEvent
+     */
+    emit(event) {
+        if (this.closed) {
+            throw new Error('CloudTraceSink is closed');
+        }
+        if (!this.writeStream) {
+            console.error('[CloudTraceSink] Write stream not available');
+            return;
+        }
+        try {
+            const jsonStr = JSON.stringify(event);
+            this.writeStream.write(jsonStr + '\n');
+        }
+        catch (error) {
+            console.error('[CloudTraceSink] Write error:', error);
+        }
+    }
+    /**
+     * Upload data to cloud using Node's built-in https module
+     */
+    async _uploadToCloud(data) {
+        return new Promise((resolve, reject) => {
+            const url = new url_1.URL(this.uploadUrl);
+            const protocol = url.protocol === 'https:' ? https : http;
+            const options = {
+                hostname: url.hostname,
+                port: url.port || (url.protocol === 'https:' ? 443 : 80),
+                path: url.pathname + url.search,
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/x-gzip',
+                    'Content-Encoding': 'gzip',
+                    'Content-Length': data.length,
+                },
+                timeout: 60000, // 1 minute timeout
+            };
+            const req = protocol.request(options, (res) => {
+                // Consume response data (even if we don't use it)
+                res.on('data', () => { });
+                res.on('end', () => {
+                    resolve(res.statusCode || 500);
+                });
+            });
+            req.on('error', (error) => {
+                reject(error);
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Upload timeout'));
+            });
+            req.write(data);
+            req.end();
+        });
+    }
+    /**
+     * Upload buffered trace to cloud via pre-signed URL
+     *
+     * @param blocking - If false, upload happens in background (default: true)
+     *
+     * PRODUCTION FIX: Non-blocking mode prevents hanging user scripts
+     * on slow uploads (Risk #2 from production hardening plan)
+     */
+    async close(blocking = true) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        // Non-blocking mode: fire-and-forget background upload
+        if (!blocking) {
+            // Close the write stream synchronously
+            if (this.writeStream && !this.writeStream.destroyed) {
+                this.writeStream.end();
+            }
+            // Upload in background (don't await)
+            this._doUpload().catch((error) => {
+                console.error(`❌ [Sentience] Background upload failed: ${error.message}`);
+                console.error(`   Local trace preserved at: ${this.tempFilePath}`);
+            });
+            console.log('📤 [Sentience] Trace upload started in background');
+            return;
+        }
+        // Blocking mode: wait for upload to complete
+        await this._doUpload();
+    }
+    /**
+     * Internal upload logic (called by both blocking and non-blocking close)
+     */
+    async _doUpload() {
+        try {
+            // 1. Close write stream
+            if (this.writeStream && !this.writeStream.destroyed) {
+                const stream = this.writeStream;
+                stream.removeAllListeners('error');
+                await new Promise((resolve) => {
+                    stream.end(() => {
+                        resolve();
+                    });
+                });
+            }
+            // 2. Read and compress trace data
+            if (!fs.existsSync(this.tempFilePath)) {
+                console.warn('[CloudTraceSink] Temp file does not exist, skipping upload');
+                return;
+            }
+            const traceData = fs.readFileSync(this.tempFilePath);
+            const compressedData = zlib.gzipSync(traceData);
+            // 3. Upload to cloud via pre-signed URL
+            console.log(`📤 [Sentience] Uploading trace to cloud (${compressedData.length} bytes)...`);
+            const statusCode = await this._uploadToCloud(compressedData);
+            if (statusCode === 200) {
+                console.log('✅ [Sentience] Trace uploaded successfully');
+                // 4. Delete temp file on success
+                fs.unlinkSync(this.tempFilePath);
+            }
+            else {
+                console.error(`❌ [Sentience] Upload failed: HTTP ${statusCode}`);
+                console.error(`   Local trace preserved at: ${this.tempFilePath}`);
+            }
+        }
+        catch (error) {
+            console.error(`❌ [Sentience] Error uploading trace: ${error.message}`);
+            console.error(`   Local trace preserved at: ${this.tempFilePath}`);
+            // Don't throw - preserve trace locally even if upload fails
+        }
+    }
+    /**
+     * Get unique identifier for this sink
+     */
+    getSinkType() {
+        return `CloudTraceSink(${this.uploadUrl.substring(0, 50)}...)`;
+    }
+}
+exports.CloudTraceSink = CloudTraceSink;
+//# sourceMappingURL=cloud-sink.js.map

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

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

package/dist/tracing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tracing Module
+ *
+ * Exports all tracing functionality
+ */
+export * from './types';
+export * from './sink';
+export * from './jsonl-sink';
+export * from './cloud-sink';
+export * from './tracer';
+export * from './tracer-factory';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}

package/dist/tracing/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Tracing Module
+ *
+ * Exports all tracing functionality
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./sink"), exports);
+__exportStar(require("./jsonl-sink"), exports);
+__exportStar(require("./cloud-sink"), exports);
+__exportStar(require("./tracer"), exports);
+__exportStar(require("./tracer-factory"), exports);
+//# sourceMappingURL=index.js.map

package/dist/tracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,yCAAuB;AACvB,+CAA6B;AAC7B,+CAA6B;AAC7B,2CAAyB;AACzB,mDAAiC"}

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

@@ -0,0 +1,41 @@
+/**
+ * JSONL Trace Sink
+ *
+ * Writes trace events to a local JSONL (JSON Lines) file
+ */
+import { TraceSink } from './sink';
+/**
+ * JsonlTraceSink writes trace events to a JSONL file (one JSON object per line)
+ */
+export declare class JsonlTraceSink extends TraceSink {
+    private path;
+    private writeStream;
+    private closed;
+    /**
+     * Create a new JSONL trace sink
+     * @param filePath - Path to the JSONL file (will be created if doesn't exist)
+     */
+    constructor(filePath: string);
+    /**
+     * Emit a trace event (write as JSON line)
+     * @param event - Event dictionary
+     */
+    emit(event: Record<string, any>): void;
+    /**
+     * Close the sink and flush buffered data
+     */
+    close(): Promise<void>;
+    /**
+     * Get sink type identifier
+     */
+    getSinkType(): string;
+    /**
+     * Get file path
+     */
+    getPath(): string;
+    /**
+     * Check if sink is closed
+     */
+    isClosed(): boolean;
+}
+//# sourceMappingURL=jsonl-sink.d.ts.map

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

@@ -0,0 +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"}

package/dist/tracing/jsonl-sink.js

@@ -0,0 +1,168 @@
+"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 - Event dictionary
+     */
+    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) => {
+            stream.end((err) => {
+                if (err) {
+                    // Silently ignore close errors in production
+                    // (they're logged during stream lifetime if needed)
+                }
+                // Always resolve, don't reject on close errors
+                resolve();
+            });
+        });
+    }
+    /**
+     * 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;
+    }
+}
+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,24 @@
+/**
+ * TraceSink Abstract Class
+ *
+ * Defines the interface for trace event sinks (local files, cloud storage, etc.)
+ */
+/**
+ * Abstract base class for trace sinks
+ */
+export declare abstract class TraceSink {
+    /**
+     * Emit a trace event
+     * @param event - Event dictionary to emit
+     */
+    abstract emit(event: Record<string, any>): 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;;GAEG;AACH,8BAAsB,SAAS;IAC7B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAE/C;;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;;;AAEH;;GAEG;AACH,MAAsB,SAAS;CAgB9B;AAhBD,8BAgBC"}