trickle-observe 0.2.105 → 0.2.107

package/dist/db-observer.d.ts

@@ -26,6 +26,23 @@ export declare function patchBetterSqlite3(dbConstructor: any, debug: boolean):
  * Called from observe-register when ioredis is required.
  */
 export declare function patchIoredis(ioredisModule: any, debug: boolean): void;
+/**
+ * Patch @prisma/client to capture queries.
+ * Prisma has its own query engine (Rust binary) so patching pg/mysql2 won't work.
+ * Instead, we hook into Prisma's $on('query') event and $use() middleware.
+ */
+export declare function patchPrisma(prismaModule: any, debug: boolean): void;
+/**
+ * Patch Drizzle ORM to capture queries.
+ * Drizzle exposes a logger option in its constructor.
+ * We patch the db object's execute method to capture queries.
+ */
+export declare function patchDrizzle(drizzleModule: any, debug: boolean): void;
+/**
+ * Patch Knex to capture queries.
+ * Knex emits 'query' and 'query-response' events on the knex instance.
+ */
+export declare function patchKnex(knexModule: any, debug: boolean): void;
 /**
  * Patch mongoose to capture MongoDB operations.
  * Called from observe-register when mongoose is required.

package/dist/db-observer.js

@@ -47,6 +47,9 @@ exports.patchPg = patchPg;
 exports.patchMysql2 = patchMysql2;
 exports.patchBetterSqlite3 = patchBetterSqlite3;
 exports.patchIoredis = patchIoredis;
+exports.patchPrisma = patchPrisma;
+exports.patchDrizzle = patchDrizzle;
+exports.patchKnex = patchKnex;
 exports.patchMongoose = patchMongoose;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -333,6 +336,193 @@ function patchIoredis(ioredisModule, debug) {
     if (debug)
         console.log('[trickle/db] Redis (ioredis) query tracing enabled');
 }
+/**
+ * Patch @prisma/client to capture queries.
+ * Prisma has its own query engine (Rust binary) so patching pg/mysql2 won't work.
+ * Instead, we hook into Prisma's $on('query') event and $use() middleware.
+ */
+function patchPrisma(prismaModule, debug) {
+    debugMode = debug;
+    const PrismaClient = prismaModule.PrismaClient;
+    if (!PrismaClient || PrismaClient.__trickle_patched)
+        return;
+    const originalConstructor = PrismaClient;
+    const OriginalPrototype = PrismaClient.prototype;
+    // Wrap the constructor to inject query logging
+    const patchedConstructor = function (opts = {}) {
+        // Enable query logging in Prisma
+        if (!opts.log)
+            opts.log = [];
+        const logEntries = Array.isArray(opts.log) ? opts.log : [];
+        // Add query event if not already present
+        const hasQueryLog = logEntries.some((entry) => (typeof entry === 'string' && entry === 'query') ||
+            (typeof entry === 'object' && entry.emit === 'event' && entry.level === 'query'));
+        if (!hasQueryLog) {
+            logEntries.push({ emit: 'event', level: 'query' });
+        }
+        opts.log = logEntries;
+        // Call original constructor
+        const instance = new originalConstructor(opts);
+        // Subscribe to query events
+        try {
+            instance.$on('query', (e) => {
+                const queryText = (e.query || '').substring(0, MAX_QUERY_LENGTH);
+                const params = e.params ? (() => { try {
+                    return JSON.parse(e.params).slice(0, 5);
+                }
+                catch {
+                    return undefined;
+                } })() : undefined;
+                writeQuery({
+                    kind: 'query',
+                    query: queryText,
+                    params,
+                    durationMs: e.duration || 0,
+                    rowCount: 0, // Prisma query events don't include row count
+                    timestamp: Date.now(),
+                });
+                if (debugMode) {
+                    console.log(`[trickle/db] Prisma: ${queryText.substring(0, 60)}... (${e.duration}ms)`);
+                }
+            });
+        }
+        catch { /* $on may not be available on all Prisma versions */ }
+        return instance;
+    };
+    // Copy prototype chain
+    patchedConstructor.prototype = OriginalPrototype;
+    Object.setPrototypeOf(patchedConstructor, originalConstructor);
+    // Copy static properties
+    for (const key of Object.getOwnPropertyNames(originalConstructor)) {
+        if (key !== 'prototype' && key !== 'length' && key !== 'name') {
+            try {
+                Object.defineProperty(patchedConstructor, key, Object.getOwnPropertyDescriptor(originalConstructor, key));
+            }
+            catch { }
+        }
+    }
+    prismaModule.PrismaClient = patchedConstructor;
+    prismaModule.PrismaClient.__trickle_patched = true;
+    if (debug)
+        console.log('[trickle/db] Prisma query tracing enabled');
+}
+/**
+ * Patch Drizzle ORM to capture queries.
+ * Drizzle exposes a logger option in its constructor.
+ * We patch the db object's execute method to capture queries.
+ */
+function patchDrizzle(drizzleModule, debug) {
+    debugMode = debug;
+    // drizzle-orm exports various dialect-specific functions
+    // The common pattern is drizzle(client, { logger: true })
+    // We patch by wrapping the module's default export or named exports
+    for (const key of Object.keys(drizzleModule)) {
+        const fn = drizzleModule[key];
+        if (typeof fn !== 'function')
+            continue;
+        if (fn.__trickle_patched)
+            continue;
+        // Only patch functions that look like drizzle constructors
+        // (they take a client + config object)
+        drizzleModule[key] = function patchedDrizzle(...args) {
+            // Inject a custom logger into the config
+            const config = args[1] && typeof args[1] === 'object' ? { ...args[1] } : (args.length > 1 ? args[1] : {});
+            if (typeof config === 'object' && config !== null) {
+                const origLogger = config.logger;
+                config.logger = {
+                    logQuery(query, params) {
+                        const startTime = performance.now();
+                        writeQuery({
+                            kind: 'query',
+                            query: query.substring(0, MAX_QUERY_LENGTH),
+                            params: Array.isArray(params) ? params.slice(0, 5) : undefined,
+                            durationMs: 0, // Drizzle logger doesn't provide timing
+                            rowCount: 0,
+                            timestamp: Date.now(),
+                        });
+                        // Call original logger if present
+                        if (origLogger && typeof origLogger === 'object' && 'logQuery' in origLogger) {
+                            origLogger.logQuery(query, params);
+                        }
+                    },
+                };
+                args[1] = config;
+            }
+            return fn.apply(this, args);
+        };
+        drizzleModule[key].__trickle_patched = true;
+    }
+    if (debug)
+        console.log('[trickle/db] Drizzle ORM query tracing enabled');
+}
+/**
+ * Patch Knex to capture queries.
+ * Knex emits 'query' and 'query-response' events on the knex instance.
+ */
+function patchKnex(knexModule, debug) {
+    debugMode = debug;
+    const origKnex = knexModule.default || knexModule;
+    if (typeof origKnex !== 'function' || origKnex.__trickle_patched)
+        return;
+    const wrapped = function patchedKnex(...args) {
+        const instance = origKnex.apply(this, args);
+        // Track query start times
+        const queryTimers = new Map();
+        try {
+            instance.on('query', (data) => {
+                queryTimers.set(data.__knexQueryUid || '', performance.now());
+            });
+            instance.on('query-response', (_response, data) => {
+                const startTime = queryTimers.get(data.__knexQueryUid || '');
+                const durationMs = startTime ? Math.round((performance.now() - startTime) * 100) / 100 : 0;
+                queryTimers.delete(data.__knexQueryUid || '');
+                writeQuery({
+                    kind: 'query',
+                    query: (data.sql || '').substring(0, MAX_QUERY_LENGTH),
+                    params: Array.isArray(data.bindings) ? data.bindings.slice(0, 5) : undefined,
+                    durationMs,
+                    rowCount: 0,
+                    timestamp: Date.now(),
+                });
+            });
+            instance.on('query-error', (error, data) => {
+                const startTime = queryTimers.get(data.__knexQueryUid || '');
+                const durationMs = startTime ? Math.round((performance.now() - startTime) * 100) / 100 : 0;
+                queryTimers.delete(data.__knexQueryUid || '');
+                writeQuery({
+                    kind: 'query',
+                    query: (data.sql || '').substring(0, MAX_QUERY_LENGTH),
+                    durationMs,
+                    rowCount: 0,
+                    error: error?.message?.substring(0, 200),
+                    timestamp: Date.now(),
+                });
+            });
+        }
+        catch { /* query events not available */ }
+        return instance;
+    };
+    // Copy properties
+    Object.setPrototypeOf(wrapped, origKnex);
+    for (const key of Object.getOwnPropertyNames(origKnex)) {
+        if (key !== 'length' && key !== 'name') {
+            try {
+                Object.defineProperty(wrapped, key, Object.getOwnPropertyDescriptor(origKnex, key));
+            }
+            catch { }
+        }
+    }
+    if (knexModule.default) {
+        knexModule.default = wrapped;
+    }
+    else {
+        // knex exports the function directly via module.exports
+        // We can't replace module.exports from here, but observe-register handles that
+    }
+    wrapped.__trickle_patched = true;
+    if (debug)
+        console.log('[trickle/db] Knex query tracing enabled');
+}
 /**
  * Patch mongoose to capture MongoDB operations.
  * Called from observe-register when mongoose is required.

package/dist/observe-register.js

@@ -1203,6 +1203,33 @@ if (enabled) {
             }
             catch { /* not critical */ }
         }
+        // Prisma ORM
+        if (request === '@prisma/client' && !expressPatched.has('@prisma/client')) {
+            expressPatched.add('@prisma/client');
+            try {
+                const { patchPrisma } = require(path_1.default.join(__dirname, 'db-observer.js'));
+                patchPrisma(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        // Drizzle ORM
+        if (request.startsWith('drizzle-orm') && !expressPatched.has('drizzle-orm')) {
+            expressPatched.add('drizzle-orm');
+            try {
+                const { patchDrizzle } = require(path_1.default.join(__dirname, 'db-observer.js'));
+                patchDrizzle(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        // Knex query builder
+        if (request === 'knex' && !expressPatched.has('knex')) {
+            expressPatched.add('knex');
+            try {
+                const { patchKnex } = require(path_1.default.join(__dirname, 'db-observer.js'));
+                patchKnex(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
         // Redis (ioredis)
         if (request === 'ioredis' && !expressPatched.has('ioredis')) {
             expressPatched.add('ioredis');

package/dist/transport.js

@@ -54,6 +54,13 @@ let localFilePath = '';
 let queue = [];
 let flushTimer = null;
 let isFlushing = false;
+// Cloud streaming: when TRICKLE_CLOUD_URL + TRICKLE_CLOUD_TOKEN are set,
+// observations are also streamed to the cloud backend in real-time.
+let cloudUrl = process.env.TRICKLE_CLOUD_URL || '';
+let cloudToken = process.env.TRICKLE_CLOUD_TOKEN || '';
+let cloudProject = '';
+let cloudBuffer = [];
+let cloudFlushTimer = null;
 /**
  * Configure the transport layer with global options.
  */
@@ -63,6 +70,34 @@ function configure(opts) {
     maxBatchSize = opts.maxBatchSize || DEFAULT_MAX_BATCH_SIZE;
     enabled = opts.enabled !== false;
     debug = opts.debug === true;
+    // Load cloud config from ~/.trickle/cloud.json if env vars not set
+    if (!cloudUrl || !cloudToken) {
+        try {
+            const configPath = pathMod.join(process.env.HOME || '~', '.trickle', 'cloud.json');
+            if (fs.existsSync(configPath)) {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                if (!cloudUrl && config.url)
+                    cloudUrl = config.url;
+                if (!cloudToken && config.token)
+                    cloudToken = config.token;
+            }
+        }
+        catch { }
+    }
+    cloudProject = process.env.TRICKLE_CLOUD_PROJECT || pathMod.basename(process.cwd());
+    // Start cloud streaming if configured
+    if (cloudUrl && cloudToken && !cloudFlushTimer) {
+        cloudFlushTimer = setInterval(() => {
+            flushCloud().catch(() => { });
+        }, 5000); // Flush to cloud every 5 seconds
+        if (cloudFlushTimer.unref)
+            cloudFlushTimer.unref();
+        if (debug) {
+            console.log(`[trickle] Cloud streaming enabled → ${cloudUrl}`);
+        }
+        // Flush cloud buffer on exit
+        process.on('beforeExit', () => { flushCloud().catch(() => { }); });
+    }
     // Check for local/file-based mode
     if (process.env.TRICKLE_LOCAL === '1') {
         localMode = true;
@@ -93,7 +128,12 @@ function enqueue(payload) {
     // Local file mode: append directly to JSONL file
     if (localMode && localFilePath) {
         try {
-            fs.appendFileSync(localFilePath, JSON.stringify(payload) + '\n');
+            const line = JSON.stringify(payload) + '\n';
+            fs.appendFileSync(localFilePath, line);
+            // Also buffer for cloud if configured
+            if (cloudUrl && cloudToken) {
+                cloudBuffer.push(line);
+            }
         }
         catch {
             // Never crash user's app
@@ -200,6 +240,32 @@ function stopTimer() {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Flush buffered observations to the cloud backend.
+ */
+async function flushCloud() {
+    if (cloudBuffer.length === 0 || !cloudUrl || !cloudToken)
+        return;
+    const lines = cloudBuffer.splice(0);
+    try {
+        await fetch(`${cloudUrl}/api/v1/ingest`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${cloudToken}`,
+            },
+            body: JSON.stringify({
+                project: cloudProject,
+                file: 'observations.jsonl',
+                lines: lines.join(''),
+            }),
+            signal: AbortSignal.timeout(10000),
+        });
+    }
+    catch {
+        // Silent — never crash user's app. Data is still saved locally.
+    }
+}
 function silentError() {
     // Intentionally empty — never crash user's app
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.105",
+  "version": "0.2.107",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/db-observer.ts

@@ -332,6 +332,207 @@ export function patchIoredis(ioredisModule: any, debug: boolean): void {
   if (debug) console.log('[trickle/db] Redis (ioredis) query tracing enabled');
 }
 
+/**
+ * Patch @prisma/client to capture queries.
+ * Prisma has its own query engine (Rust binary) so patching pg/mysql2 won't work.
+ * Instead, we hook into Prisma's $on('query') event and $use() middleware.
+ */
+export function patchPrisma(prismaModule: any, debug: boolean): void {
+  debugMode = debug;
+
+  const PrismaClient = prismaModule.PrismaClient;
+  if (!PrismaClient || (PrismaClient as any).__trickle_patched) return;
+
+  const originalConstructor = PrismaClient;
+  const OriginalPrototype = PrismaClient.prototype;
+
+  // Wrap the constructor to inject query logging
+  const patchedConstructor = function (this: any, opts: any = {}) {
+    // Enable query logging in Prisma
+    if (!opts.log) opts.log = [];
+    const logEntries = Array.isArray(opts.log) ? opts.log : [];
+
+    // Add query event if not already present
+    const hasQueryLog = logEntries.some((entry: any) =>
+      (typeof entry === 'string' && entry === 'query') ||
+      (typeof entry === 'object' && entry.emit === 'event' && entry.level === 'query')
+    );
+    if (!hasQueryLog) {
+      logEntries.push({ emit: 'event', level: 'query' });
+    }
+    opts.log = logEntries;
+
+    // Call original constructor
+    const instance = new originalConstructor(opts);
+
+    // Subscribe to query events
+    try {
+      instance.$on('query', (e: any) => {
+        const queryText = (e.query || '').substring(0, MAX_QUERY_LENGTH);
+        const params = e.params ? (() => { try { return JSON.parse(e.params).slice(0, 5); } catch { return undefined; } })() : undefined;
+        writeQuery({
+          kind: 'query',
+          query: queryText,
+          params,
+          durationMs: e.duration || 0,
+          rowCount: 0, // Prisma query events don't include row count
+          timestamp: Date.now(),
+        });
+        if (debugMode) {
+          console.log(`[trickle/db] Prisma: ${queryText.substring(0, 60)}... (${e.duration}ms)`);
+        }
+      });
+    } catch { /* $on may not be available on all Prisma versions */ }
+
+    return instance;
+  };
+
+  // Copy prototype chain
+  patchedConstructor.prototype = OriginalPrototype;
+  Object.setPrototypeOf(patchedConstructor, originalConstructor);
+
+  // Copy static properties
+  for (const key of Object.getOwnPropertyNames(originalConstructor)) {
+    if (key !== 'prototype' && key !== 'length' && key !== 'name') {
+      try {
+        Object.defineProperty(patchedConstructor, key, Object.getOwnPropertyDescriptor(originalConstructor, key)!);
+      } catch {}
+    }
+  }
+
+  prismaModule.PrismaClient = patchedConstructor;
+  (prismaModule.PrismaClient as any).__trickle_patched = true;
+
+  if (debug) console.log('[trickle/db] Prisma query tracing enabled');
+}
+
+/**
+ * Patch Drizzle ORM to capture queries.
+ * Drizzle exposes a logger option in its constructor.
+ * We patch the db object's execute method to capture queries.
+ */
+export function patchDrizzle(drizzleModule: any, debug: boolean): void {
+  debugMode = debug;
+
+  // drizzle-orm exports various dialect-specific functions
+  // The common pattern is drizzle(client, { logger: true })
+  // We patch by wrapping the module's default export or named exports
+
+  for (const key of Object.keys(drizzleModule)) {
+    const fn = drizzleModule[key];
+    if (typeof fn !== 'function') continue;
+    if ((fn as any).__trickle_patched) continue;
+
+    // Only patch functions that look like drizzle constructors
+    // (they take a client + config object)
+    drizzleModule[key] = function patchedDrizzle(...args: any[]): any {
+      // Inject a custom logger into the config
+      const config = args[1] && typeof args[1] === 'object' ? { ...args[1] } : (args.length > 1 ? args[1] : {});
+
+      if (typeof config === 'object' && config !== null) {
+        const origLogger = config.logger;
+        config.logger = {
+          logQuery(query: string, params: unknown[]): void {
+            const startTime = performance.now();
+            writeQuery({
+              kind: 'query',
+              query: query.substring(0, MAX_QUERY_LENGTH),
+              params: Array.isArray(params) ? params.slice(0, 5) : undefined,
+              durationMs: 0, // Drizzle logger doesn't provide timing
+              rowCount: 0,
+              timestamp: Date.now(),
+            });
+            // Call original logger if present
+            if (origLogger && typeof origLogger === 'object' && 'logQuery' in origLogger) {
+              (origLogger as any).logQuery(query, params);
+            }
+          },
+        };
+        args[1] = config;
+      }
+
+      return fn.apply(this, args);
+    };
+    (drizzleModule[key] as any).__trickle_patched = true;
+  }
+
+  if (debug) console.log('[trickle/db] Drizzle ORM query tracing enabled');
+}
+
+/**
+ * Patch Knex to capture queries.
+ * Knex emits 'query' and 'query-response' events on the knex instance.
+ */
+export function patchKnex(knexModule: any, debug: boolean): void {
+  debugMode = debug;
+
+  const origKnex = knexModule.default || knexModule;
+  if (typeof origKnex !== 'function' || (origKnex as any).__trickle_patched) return;
+
+  const wrapped = function patchedKnex(this: any, ...args: any[]): any {
+    const instance = origKnex.apply(this, args);
+
+    // Track query start times
+    const queryTimers = new Map<string, number>();
+
+    try {
+      instance.on('query', (data: any) => {
+        queryTimers.set(data.__knexQueryUid || '', performance.now());
+      });
+
+      instance.on('query-response', (_response: any, data: any) => {
+        const startTime = queryTimers.get(data.__knexQueryUid || '');
+        const durationMs = startTime ? Math.round((performance.now() - startTime) * 100) / 100 : 0;
+        queryTimers.delete(data.__knexQueryUid || '');
+
+        writeQuery({
+          kind: 'query',
+          query: (data.sql || '').substring(0, MAX_QUERY_LENGTH),
+          params: Array.isArray(data.bindings) ? data.bindings.slice(0, 5) : undefined,
+          durationMs,
+          rowCount: 0,
+          timestamp: Date.now(),
+        });
+      });
+
+      instance.on('query-error', (error: any, data: any) => {
+        const startTime = queryTimers.get(data.__knexQueryUid || '');
+        const durationMs = startTime ? Math.round((performance.now() - startTime) * 100) / 100 : 0;
+        queryTimers.delete(data.__knexQueryUid || '');
+
+        writeQuery({
+          kind: 'query',
+          query: (data.sql || '').substring(0, MAX_QUERY_LENGTH),
+          durationMs,
+          rowCount: 0,
+          error: error?.message?.substring(0, 200),
+          timestamp: Date.now(),
+        });
+      });
+    } catch { /* query events not available */ }
+
+    return instance;
+  };
+
+  // Copy properties
+  Object.setPrototypeOf(wrapped, origKnex);
+  for (const key of Object.getOwnPropertyNames(origKnex)) {
+    if (key !== 'length' && key !== 'name') {
+      try { Object.defineProperty(wrapped, key, Object.getOwnPropertyDescriptor(origKnex, key)!); } catch {}
+    }
+  }
+
+  if (knexModule.default) {
+    knexModule.default = wrapped;
+  } else {
+    // knex exports the function directly via module.exports
+    // We can't replace module.exports from here, but observe-register handles that
+  }
+
+  (wrapped as any).__trickle_patched = true;
+  if (debug) console.log('[trickle/db] Knex query tracing enabled');
+}
+
 /**
  * Patch mongoose to capture MongoDB operations.
  * Called from observe-register when mongoose is required.

package/src/observe-register.ts

@@ -1188,6 +1188,33 @@ if (enabled) {
       } catch { /* not critical */ }
     }
 
+    // Prisma ORM
+    if (request === '@prisma/client' && !expressPatched.has('@prisma/client')) {
+      expressPatched.add('@prisma/client');
+      try {
+        const { patchPrisma } = require(path.join(__dirname, 'db-observer.js'));
+        patchPrisma(exports, debug);
+      } catch { /* not critical */ }
+    }
+
+    // Drizzle ORM
+    if (request.startsWith('drizzle-orm') && !expressPatched.has('drizzle-orm')) {
+      expressPatched.add('drizzle-orm');
+      try {
+        const { patchDrizzle } = require(path.join(__dirname, 'db-observer.js'));
+        patchDrizzle(exports, debug);
+      } catch { /* not critical */ }
+    }
+
+    // Knex query builder
+    if (request === 'knex' && !expressPatched.has('knex')) {
+      expressPatched.add('knex');
+      try {
+        const { patchKnex } = require(path.join(__dirname, 'db-observer.js'));
+        patchKnex(exports, debug);
+      } catch { /* not critical */ }
+    }
+
     // Redis (ioredis)
     if (request === 'ioredis' && !expressPatched.has('ioredis')) {
       expressPatched.add('ioredis');

package/src/transport.ts

@@ -19,6 +19,14 @@ let queue: IngestPayload[] = [];
 let flushTimer: ReturnType<typeof setInterval> | null = null;
 let isFlushing = false;
 
+// Cloud streaming: when TRICKLE_CLOUD_URL + TRICKLE_CLOUD_TOKEN are set,
+// observations are also streamed to the cloud backend in real-time.
+let cloudUrl = process.env.TRICKLE_CLOUD_URL || '';
+let cloudToken = process.env.TRICKLE_CLOUD_TOKEN || '';
+let cloudProject = '';
+let cloudBuffer: string[] = [];
+let cloudFlushTimer: ReturnType<typeof setInterval> | null = null;
+
 /**
  * Configure the transport layer with global options.
  */
@@ -29,6 +37,33 @@ export function configure(opts: GlobalOpts): void {
   enabled = opts.enabled !== false;
   debug = opts.debug === true;
 
+  // Load cloud config from ~/.trickle/cloud.json if env vars not set
+  if (!cloudUrl || !cloudToken) {
+    try {
+      const configPath = pathMod.join(process.env.HOME || '~', '.trickle', 'cloud.json');
+      if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (!cloudUrl && config.url) cloudUrl = config.url;
+        if (!cloudToken && config.token) cloudToken = config.token;
+      }
+    } catch {}
+  }
+  cloudProject = process.env.TRICKLE_CLOUD_PROJECT || pathMod.basename(process.cwd());
+
+  // Start cloud streaming if configured
+  if (cloudUrl && cloudToken && !cloudFlushTimer) {
+    cloudFlushTimer = setInterval(() => {
+      flushCloud().catch(() => {});
+    }, 5000); // Flush to cloud every 5 seconds
+    if (cloudFlushTimer.unref) cloudFlushTimer.unref();
+    if (debug) {
+      console.log(`[trickle] Cloud streaming enabled → ${cloudUrl}`);
+    }
+
+    // Flush cloud buffer on exit
+    process.on('beforeExit', () => { flushCloud().catch(() => {}); });
+  }
+
   // Check for local/file-based mode
   if (process.env.TRICKLE_LOCAL === '1') {
     localMode = true;
@@ -58,7 +93,12 @@ export function enqueue(payload: IngestPayload): void {
   // Local file mode: append directly to JSONL file
   if (localMode && localFilePath) {
     try {
-      fs.appendFileSync(localFilePath, JSON.stringify(payload) + '\n');
+      const line = JSON.stringify(payload) + '\n';
+      fs.appendFileSync(localFilePath, line);
+      // Also buffer for cloud if configured
+      if (cloudUrl && cloudToken) {
+        cloudBuffer.push(line);
+      }
     } catch {
       // Never crash user's app
     }
@@ -175,6 +215,32 @@ function sleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Flush buffered observations to the cloud backend.
+ */
+async function flushCloud(): Promise<void> {
+  if (cloudBuffer.length === 0 || !cloudUrl || !cloudToken) return;
+
+  const lines = cloudBuffer.splice(0);
+  try {
+    await fetch(`${cloudUrl}/api/v1/ingest`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${cloudToken}`,
+      },
+      body: JSON.stringify({
+        project: cloudProject,
+        file: 'observations.jsonl',
+        lines: lines.join(''),
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch {
+    // Silent — never crash user's app. Data is still saved locally.
+  }
+}
+
 function silentError(): void {
   // Intentionally empty — never crash user's app
 }