trickle-observe 0.2.60 → 0.2.61

package/dist/lambda.d.ts

@@ -0,0 +1,61 @@
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+import './observe-register';
+export type LambdaEvent = Record<string, unknown>;
+export type LambdaContext = {
+    functionName: string;
+    functionVersion: string;
+    invokedFunctionArn: string;
+    awsRequestId: string;
+    remainingTimeInMillis?: () => number;
+    [key: string]: unknown;
+};
+export type LambdaHandler<E = LambdaEvent, R = unknown> = (event: E, context: LambdaContext) => Promise<R>;
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+export declare function wrapLambda<E = LambdaEvent, R = unknown>(handler: LambdaHandler<E, R>): LambdaHandler<E, R>;
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+export declare function printObservations(): void;

package/dist/lambda.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+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.wrapLambda = wrapLambda;
+exports.printObservations = printObservations;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const transport_1 = require("./transport");
+const trace_var_1 = require("./trace-var");
+// Install Module._compile and Module._load hooks for auto-instrumentation
+require("./observe-register");
+let initialized = false;
+function initOnce() {
+    if (initialized)
+        return;
+    initialized = true;
+    const debug = process.env.TRICKLE_DEBUG === '1';
+    const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+    // Ensure /tmp/.trickle exists (writable in Lambda, unlike /var/task)
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    if (process.env.TRICKLE_BACKEND_URL) {
+        // HTTP mode: send to developer's backend (e.g. via ngrok)
+        (0, transport_1.configure)({
+            backendUrl: process.env.TRICKLE_BACKEND_URL,
+            batchIntervalMs: 100, // aggressive batching for Lambda
+            enabled: true,
+            debug,
+            environment: 'node',
+        });
+        if (debug)
+            console.log(`[trickle/lambda] HTTP mode → ${process.env.TRICKLE_BACKEND_URL}`);
+    }
+    else {
+        // Local file mode: write to /tmp/.trickle/observations.jsonl
+        process.env.TRICKLE_LOCAL = '1';
+        process.env.TRICKLE_LOCAL_DIR = dir;
+        (0, transport_1.configure)({ backendUrl: 'http://localhost:4888', batchIntervalMs: 2000, enabled: true, debug, environment: 'node' });
+        if (debug)
+            console.log(`[trickle/lambda] Local mode → ${dir}/observations.jsonl`);
+    }
+    // Initialize variable tracer (writes to variables.jsonl)
+    (0, trace_var_1.initVarTracer)({ debug });
+}
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+function wrapLambda(handler) {
+    return async (event, context) => {
+        initOnce();
+        const debug = process.env.TRICKLE_DEBUG === '1';
+        const startMs = Date.now();
+        try {
+            const result = await handler(event, context);
+            // Flush pending HTTP observations before Lambda freezes the process.
+            // File-mode writes are already synchronous, so no flush needed there.
+            if (process.env.TRICKLE_BACKEND_URL) {
+                await (0, transport_1.flush)();
+            }
+            if (debug) {
+                const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+                const elapsed = Date.now() - startMs;
+                const varsFile = path.join(dir, 'variables.jsonl');
+                try {
+                    const size = fs.statSync(varsFile).size;
+                    console.log(`[trickle/lambda] Flushed in ${elapsed}ms, observations: ${varsFile} (${size}b)`);
+                }
+                catch { }
+            }
+            return result;
+        }
+        catch (err) {
+            // Flush even on errors so partial observations are captured
+            if (process.env.TRICKLE_BACKEND_URL) {
+                await (0, transport_1.flush)().catch(() => { });
+            }
+            throw err;
+        }
+    };
+}
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+function printObservations() {
+    const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+    for (const file of ['variables.jsonl', 'observations.jsonl']) {
+        const filePath = path.join(dir, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8').trim();
+            if (content) {
+                for (const line of content.split('\n')) {
+                    if (line.trim()) {
+                        // Prefix so trickle CLI can grep from CloudWatch Logs
+                        console.log(`[trickle] ${line}`);
+                    }
+                }
+            }
+        }
+        catch { /* file may not exist yet */ }
+    }
+}

package/dist/trace-var.js

@@ -70,7 +70,10 @@ const MAX_BUFFER_SIZE = 100;
  */
 function initVarTracer(opts = {}) {
     debugMode = opts.debug === true;
-    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+    const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+    const defaultDir = isLambda ? '/tmp/.trickle' : path.join(process.cwd(), '.trickle');
+    const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
     try {
         fs.mkdirSync(dir, { recursive: true });
     }

package/dist/transport.js

@@ -66,7 +66,10 @@ function configure(opts) {
     // Check for local/file-based mode
     if (process.env.TRICKLE_LOCAL === '1') {
         localMode = true;
-        const dir = process.env.TRICKLE_LOCAL_DIR || pathMod.join(process.cwd(), '.trickle');
+        // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+        const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+        const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+        const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
         try {
             fs.mkdirSync(dir, { recursive: true });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.60",
+  "version": "0.2.61",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,11 +16,12 @@
       "import": "./dist-esm/vite-plugin.js",
       "require": "./dist/vite-plugin.js"
     },
-    "./trace-var": "./dist/trace-var.js"
+    "./trace-var": "./dist/trace-var.js",
+    "./lambda": "./dist/lambda.js"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts",
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {

package/src/lambda.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for wrapLambda and printObservations.
+ *
+ * Run with: node --experimental-strip-types --test src/lambda.test.ts
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ── wrapLambda ────────────────────────────────────────────────────────────────
+
+describe('wrapLambda', () => {
+  const makeContext = () => ({
+    functionName: 'test-fn',
+    functionVersion: '$LATEST',
+    invokedFunctionArn: 'arn:aws:lambda:us-east-1:123:function:test-fn',
+    awsRequestId: 'req-1',
+  });
+
+  let tmpDir: string;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-lambda-test-'));
+    process.env.TRICKLE_LOCAL_DIR = tmpDir;
+  });
+
+  after(() => {
+    delete process.env.TRICKLE_LOCAL_DIR;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns the handler result unchanged', async () => {
+    // Import fresh to avoid module cache issues with env vars
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async (_event: unknown, _ctx: unknown) => ({ statusCode: 200, body: 'ok' });
+    const wrapped = wrapLambda(handler);
+    const result = await wrapped({ orderId: '123' }, makeContext());
+    assert.deepEqual(result, { statusCode: 200, body: 'ok' });
+  });
+
+  it('passes event and context to the handler', async () => {
+    const { wrapLambda } = await import('../dist/lambda.js');
+    let receivedEvent: unknown;
+    let receivedCtx: unknown;
+    const handler = async (event: unknown, ctx: unknown) => {
+      receivedEvent = event;
+      receivedCtx = ctx;
+      return 'done';
+    };
+    const wrapped = wrapLambda(handler);
+    const ctx = makeContext();
+    await wrapped({ hello: 'world' }, ctx);
+    assert.deepEqual(receivedEvent, { hello: 'world' });
+    assert.equal((receivedCtx as typeof ctx).awsRequestId, 'req-1');
+  });
+
+  it('re-throws errors from the handler', async () => {
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async () => { throw new Error('Lambda error'); };
+    const wrapped = wrapLambda(handler);
+    await assert.rejects(() => wrapped({}, makeContext()), /Lambda error/);
+  });
+
+  it('does not throw if TRICKLE_BACKEND_URL is not set', async () => {
+    delete process.env.TRICKLE_BACKEND_URL;
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async () => 42;
+    const wrapped = wrapLambda(handler);
+    const result = await wrapped({}, makeContext());
+    assert.equal(result, 42);
+  });
+});
+
+// ── printObservations ─────────────────────────────────────────────────────────
+
+describe('printObservations', () => {
+  let tmpDir: string;
+  let originalDir: string | undefined;
+  let logged: string[];
+  let origLog: typeof console.log;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-print-test-'));
+    originalDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = tmpDir;
+    // Capture console.log output
+    origLog = console.log;
+    logged = [];
+    console.log = (...args: unknown[]) => { logged.push(args.join(' ')); };
+  });
+
+  after(() => {
+    console.log = origLog;
+    if (originalDir !== undefined) {
+      process.env.TRICKLE_LOCAL_DIR = originalDir;
+    } else {
+      delete process.env.TRICKLE_LOCAL_DIR;
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('prints [trickle] prefixed JSON lines from variables.jsonl', async () => {
+    const record = JSON.stringify({ kind: 'var', name: 'x', value: 1 });
+    fs.writeFileSync(path.join(tmpDir, 'variables.jsonl'), record + '\n');
+
+    const { printObservations } = await import('../dist/lambda.js');
+    logged = [];
+    printObservations();
+
+    assert.ok(logged.some(l => l.startsWith('[trickle]')), 'should prefix with [trickle]');
+    assert.ok(logged.some(l => l.includes('"kind"')), 'should include JSON content');
+  });
+
+  it('does not crash when no files exist', async () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-empty-'));
+    const prevDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = emptyDir;
+    try {
+      const { printObservations } = await import('../dist/lambda.js');
+      assert.doesNotThrow(() => printObservations());
+    } finally {
+      process.env.TRICKLE_LOCAL_DIR = prevDir;
+      fs.rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it('prints observations from both variables.jsonl and observations.jsonl', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-both-'));
+    const prevDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = dir;
+    try {
+      fs.writeFileSync(path.join(dir, 'variables.jsonl'), JSON.stringify({ kind: 'var' }) + '\n');
+      fs.writeFileSync(path.join(dir, 'observations.jsonl'), JSON.stringify({ kind: 'obs' }) + '\n');
+
+      const { printObservations } = await import('../dist/lambda.js');
+      logged = [];
+      printObservations();
+      const count = logged.filter(l => l.startsWith('[trickle]')).length;
+      assert.ok(count >= 2, `should print at least 2 [trickle] lines, got ${count}`);
+    } finally {
+      process.env.TRICKLE_LOCAL_DIR = prevDir;
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/lambda.ts

@@ -0,0 +1,160 @@
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { configure, flush } from './transport';
+import { initVarTracer } from './trace-var';
+// Install Module._compile and Module._load hooks for auto-instrumentation
+import './observe-register';
+
+export type LambdaEvent = Record<string, unknown>;
+export type LambdaContext = {
+  functionName: string;
+  functionVersion: string;
+  invokedFunctionArn: string;
+  awsRequestId: string;
+  remainingTimeInMillis?: () => number;
+  [key: string]: unknown;
+};
+export type LambdaHandler<E = LambdaEvent, R = unknown> = (
+  event: E,
+  context: LambdaContext,
+) => Promise<R>;
+
+let initialized = false;
+
+function initOnce() {
+  if (initialized) return;
+  initialized = true;
+
+  const debug = process.env.TRICKLE_DEBUG === '1';
+  const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+
+  // Ensure /tmp/.trickle exists (writable in Lambda, unlike /var/task)
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+
+  if (process.env.TRICKLE_BACKEND_URL) {
+    // HTTP mode: send to developer's backend (e.g. via ngrok)
+    configure({
+      backendUrl: process.env.TRICKLE_BACKEND_URL,
+      batchIntervalMs: 100,    // aggressive batching for Lambda
+      enabled: true,
+      debug,
+      environment: 'node',
+    });
+    if (debug) console.log(`[trickle/lambda] HTTP mode → ${process.env.TRICKLE_BACKEND_URL}`);
+  } else {
+    // Local file mode: write to /tmp/.trickle/observations.jsonl
+    process.env.TRICKLE_LOCAL = '1';
+    process.env.TRICKLE_LOCAL_DIR = dir;
+    configure({ backendUrl: 'http://localhost:4888', batchIntervalMs: 2000, enabled: true, debug, environment: 'node' });
+    if (debug) console.log(`[trickle/lambda] Local mode → ${dir}/observations.jsonl`);
+  }
+
+  // Initialize variable tracer (writes to variables.jsonl)
+  initVarTracer({ debug });
+}
+
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+export function wrapLambda<E = LambdaEvent, R = unknown>(
+  handler: LambdaHandler<E, R>,
+): LambdaHandler<E, R> {
+  return async (event: E, context: LambdaContext): Promise<R> => {
+    initOnce();
+
+    const debug = process.env.TRICKLE_DEBUG === '1';
+    const startMs = Date.now();
+
+    try {
+      const result = await handler(event, context);
+
+      // Flush pending HTTP observations before Lambda freezes the process.
+      // File-mode writes are already synchronous, so no flush needed there.
+      if (process.env.TRICKLE_BACKEND_URL) {
+        await flush();
+      }
+
+      if (debug) {
+        const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+        const elapsed = Date.now() - startMs;
+        const varsFile = path.join(dir, 'variables.jsonl');
+        try {
+          const size = fs.statSync(varsFile).size;
+          console.log(`[trickle/lambda] Flushed in ${elapsed}ms, observations: ${varsFile} (${size}b)`);
+        } catch {}
+      }
+
+      return result;
+    } catch (err) {
+      // Flush even on errors so partial observations are captured
+      if (process.env.TRICKLE_BACKEND_URL) {
+        await flush().catch(() => {});
+      }
+      throw err;
+    }
+  };
+}
+
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+export function printObservations(): void {
+  const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+  for (const file of ['variables.jsonl', 'observations.jsonl']) {
+    const filePath = path.join(dir, file);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+      if (content) {
+        for (const line of content.split('\n')) {
+          if (line.trim()) {
+            // Prefix so trickle CLI can grep from CloudWatch Logs
+            console.log(`[trickle] ${line}`);
+          }
+        }
+      }
+    } catch { /* file may not exist yet */ }
+  }
+}

package/src/trace-var.ts

@@ -50,7 +50,10 @@ export interface VariableObservation {
  */
 export function initVarTracer(opts: { debug?: boolean } = {}): void {
   debugMode = opts.debug === true;
-  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+  const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+  const defaultDir = isLambda ? '/tmp/.trickle' : path.join(process.cwd(), '.trickle');
+  const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   varsFilePath = path.join(dir, 'variables.jsonl');
 

package/src/transport.ts

@@ -32,7 +32,10 @@ export function configure(opts: GlobalOpts): void {
   // Check for local/file-based mode
   if (process.env.TRICKLE_LOCAL === '1') {
     localMode = true;
-    const dir = process.env.TRICKLE_LOCAL_DIR || pathMod.join(process.cwd(), '.trickle');
+    // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+    const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+    const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+    const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
     try { fs.mkdirSync(dir, { recursive: true }); } catch {}
     localFilePath = pathMod.join(dir, 'observations.jsonl');
     if (debug) {