trickle-observe 0.2.96 → 0.2.98

package/dist/call-trace.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+export declare function traceCall(functionName: string, moduleName: string): number;
+/**
+ * Record a function return event with timing.
+ */
+export declare function traceReturn(callId: number, functionName: string, moduleName: string, durationMs: number, error?: string): void;
+export declare function initCallTrace(): void;

package/dist/call-trace.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+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.traceCall = traceCall;
+exports.traceReturn = traceReturn;
+exports.initCallTrace = initCallTrace;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let traceFile = null;
+let callCounter = 0;
+let currentCallId = 0; // 0 = top level
+const callStack = [0];
+const MAX_TRACE_EVENTS = 500;
+let eventCount = 0;
+function getTraceFile() {
+    if (traceFile)
+        return traceFile;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    traceFile = path.join(dir, 'calltrace.jsonl');
+    try {
+        fs.writeFileSync(traceFile, '');
+    }
+    catch { }
+    return traceFile;
+}
+function writeEvent(event) {
+    if (eventCount >= MAX_TRACE_EVENTS)
+        return;
+    eventCount++;
+    try {
+        fs.appendFileSync(getTraceFile(), JSON.stringify(event) + '\n');
+    }
+    catch { }
+}
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+function traceCall(functionName, moduleName) {
+    const id = ++callCounter;
+    const parentId = callStack[callStack.length - 1] || 0;
+    callStack.push(id);
+    // We record a placeholder — duration is filled in by traceReturn
+    return id;
+}
+/**
+ * Record a function return event with timing.
+ */
+function traceReturn(callId, functionName, moduleName, durationMs, error) {
+    const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
+    const depth = callStack.length - 1;
+    writeEvent({
+        kind: 'call',
+        function: functionName,
+        module: moduleName,
+        callId,
+        parentId,
+        depth,
+        timestamp: Date.now(),
+        durationMs: Math.round(durationMs * 100) / 100,
+        ...(error ? { error } : {}),
+    });
+    // Pop from stack
+    if (callStack[callStack.length - 1] === callId) {
+        callStack.pop();
+    }
+}
+function initCallTrace() {
+    // Ensure trace file is initialized
+    getTraceFile();
+}

package/dist/observe-register.js

@@ -1166,6 +1166,24 @@ if (enabled) {
             }
             catch { /* not critical */ }
         }
+        // WebSocket (ws)
+        if (request === 'ws' && !expressPatched.has('ws')) {
+            expressPatched.add('ws');
+            try {
+                const { patchWs } = require(path_1.default.join(__dirname, 'ws-observer.js'));
+                patchWs(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        // socket.io-client
+        if (request === 'socket.io-client' && !expressPatched.has('socket.io-client')) {
+            expressPatched.add('socket.io-client');
+            try {
+                const { patchSocketIo } = require(path_1.default.join(__dirname, 'ws-observer.js'));
+                patchSocketIo(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
         // Resolve to absolute path for dedup — do this FIRST since bundlers like
         // tsx/esbuild may use path aliases (e.g., @config/env) that don't start
         // with './' or '/'. We need the resolved path to decide if it's user code.

package/dist/wrap.js

@@ -6,6 +6,7 @@ const type_inference_1 = require("./type-inference");
 const type_hash_1 = require("./type-hash");
 const cache_1 = require("./cache");
 const transport_1 = require("./transport");
+const call_trace_1 = require("./call-trace");
 const typeCache = new cache_1.TypeCache();
 exports.typeCache = typeCache;
 /** Symbol to mark already-wrapped functions, preventing double-wrap. */
@@ -33,6 +34,7 @@ function wrapFunction(fn, opts) {
         let caughtError;
         const trackers = [];
         const startTime = performance.now();
+        const callId = (0, call_trace_1.traceCall)(opts.functionName, opts.module);
         try {
             // Always pass ORIGINAL args to the function — never proxied ones.
             // Proxied args can break framework internals (Express Router, DI containers, etc.)
@@ -45,6 +47,7 @@ function wrapFunction(fn, opts) {
             try {
                 const durationMs = performance.now() - startTime;
                 captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+                (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs, err?.message);
             }
             catch {
                 // Never let our instrumentation interfere
@@ -58,6 +61,7 @@ function wrapFunction(fn, opts) {
                 try {
                     const durationMs = performance.now() - startTime;
                     capturePayload(functionKey, opts, args, trackers, resolved, true, durationMs);
+                    (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs);
                 }
                 catch {
                     // Never let our instrumentation interfere
@@ -67,6 +71,7 @@ function wrapFunction(fn, opts) {
                 try {
                     const durationMs = performance.now() - startTime;
                     captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+                    (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs, err?.message);
                 }
                 catch {
                     // Never let our instrumentation interfere
@@ -79,6 +84,7 @@ function wrapFunction(fn, opts) {
         try {
             const durationMs = performance.now() - startTime;
             capturePayload(functionKey, opts, args, trackers, result, false, durationMs);
+            (0, call_trace_1.traceReturn)(callId, opts.functionName, opts.module, durationMs);
         }
         catch {
             // Never let our instrumentation interfere

package/dist/ws-observer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+export declare function patchWs(wsModule: any, debug: boolean): void;
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+export declare function patchSocketIo(ioModule: any, debug: boolean): void;

package/dist/ws-observer.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+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.patchWs = patchWs;
+exports.patchSocketIo = patchSocketIo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let wsFile = null;
+const MAX_EVENTS = 200;
+let eventCount = 0;
+const MAX_DATA_LENGTH = 500;
+function getWsFile() {
+    if (wsFile)
+        return wsFile;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    wsFile = path.join(dir, 'websocket.jsonl');
+    try {
+        fs.writeFileSync(wsFile, '');
+    }
+    catch { }
+    ;
+    return wsFile;
+}
+function writeWsEvent(event) {
+    if (eventCount >= MAX_EVENTS)
+        return;
+    eventCount++;
+    try {
+        fs.appendFileSync(getWsFile(), JSON.stringify(event) + '\n');
+    }
+    catch { }
+}
+function truncateData(data) {
+    if (data === undefined || data === null)
+        return data;
+    if (typeof data === 'string') {
+        return data.length > MAX_DATA_LENGTH ? data.substring(0, MAX_DATA_LENGTH) + '...' : data;
+    }
+    if (Buffer.isBuffer(data)) {
+        return `<Buffer(${data.length} bytes)>`;
+    }
+    if (typeof data === 'object') {
+        try {
+            const s = JSON.stringify(data);
+            return s.length > MAX_DATA_LENGTH ? JSON.parse(s.substring(0, MAX_DATA_LENGTH) + '..."}}') : data;
+        }
+        catch {
+            return String(data).substring(0, MAX_DATA_LENGTH);
+        }
+    }
+    return data;
+}
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+function patchWs(wsModule, debug) {
+    const WsClass = wsModule.WebSocket || wsModule;
+    if (!WsClass?.prototype || WsClass.prototype.__trickle_ws_patched)
+        return;
+    const origSend = WsClass.prototype.send;
+    if (origSend) {
+        WsClass.prototype.send = function patchedSend(data, ...args) {
+            writeWsEvent({
+                kind: 'ws',
+                event: 'message',
+                direction: 'out',
+                url: this.url || this._url,
+                data: truncateData(data),
+                timestamp: Date.now(),
+            });
+            return origSend.call(this, data, ...args);
+        };
+    }
+    // Patch 'on' to capture incoming messages
+    const origOn = WsClass.prototype.on;
+    if (origOn) {
+        WsClass.prototype.on = function patchedOn(event, listener, ...args) {
+            if (event === 'message') {
+                const wrappedListener = (data, ...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'message',
+                        direction: 'in',
+                        url: this.url || this._url,
+                        data: truncateData(data),
+                        timestamp: Date.now(),
+                    });
+                    return listener(data, ...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            if (event === 'open') {
+                const wrappedListener = (...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'connect',
+                        url: this.url || this._url,
+                        timestamp: Date.now(),
+                    });
+                    return listener(...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            if (event === 'close') {
+                const wrappedListener = (code, reason, ...rest) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'close',
+                        url: this.url || this._url,
+                        data: { code, reason: String(reason || '').substring(0, 100) },
+                        timestamp: Date.now(),
+                    });
+                    return listener(code, reason, ...rest);
+                };
+                return origOn.call(this, event, wrappedListener, ...args);
+            }
+            return origOn.call(this, event, listener, ...args);
+        };
+    }
+    WsClass.prototype.__trickle_ws_patched = true;
+    if (debug)
+        console.log('[trickle/ws] WebSocket tracing enabled');
+}
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+function patchSocketIo(ioModule, debug) {
+    // socket.io-client: the default export is a function that returns a Socket
+    const Socket = ioModule.Socket || (ioModule.io && ioModule.io.Socket);
+    if (!Socket?.prototype || Socket.prototype.__trickle_sio_patched)
+        return;
+    const origEmit = Socket.prototype.emit;
+    if (origEmit) {
+        Socket.prototype.emit = function patchedEmit(event, ...args) {
+            if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+                writeWsEvent({
+                    kind: 'ws',
+                    event: 'emit',
+                    direction: 'out',
+                    channel: event,
+                    data: truncateData(args[0]),
+                    timestamp: Date.now(),
+                });
+            }
+            return origEmit.call(this, event, ...args);
+        };
+    }
+    const origOn = Socket.prototype.on;
+    if (origOn) {
+        Socket.prototype.on = function patchedOn(event, listener, ...rest) {
+            if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+                const wrappedListener = (...args) => {
+                    writeWsEvent({
+                        kind: 'ws',
+                        event: 'emit',
+                        direction: 'in',
+                        channel: event,
+                        data: truncateData(args[0]),
+                        timestamp: Date.now(),
+                    });
+                    return listener(...args);
+                };
+                return origOn.call(this, event, wrappedListener, ...rest);
+            }
+            return origOn.call(this, event, listener, ...rest);
+        };
+    }
+    Socket.prototype.__trickle_sio_patched = true;
+    if (debug)
+        console.log('[trickle/ws] socket.io tracing enabled');
+}

package/package.json

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

package/src/call-trace.ts

@@ -0,0 +1,95 @@
+/**
+ * Call trace recorder — captures function call/return events with timing
+ * and parent-child relationships for building call graphs.
+ *
+ * Written to .trickle/calltrace.jsonl as:
+ *   { "kind": "call", "function": "createUser", "module": "api",
+ *     "parentId": 0, "callId": 1, "timestamp": 1710516000,
+ *     "durationMs": 2.5, "args": ["Alice"], "result": {...} }
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface CallEvent {
+  kind: 'call';
+  function: string;
+  module: string;
+  callId: number;
+  parentId: number;
+  depth: number;
+  timestamp: number;
+  durationMs: number;
+  error?: string;
+}
+
+let traceFile: string | null = null;
+let callCounter = 0;
+let currentCallId = 0; // 0 = top level
+const callStack: number[] = [0];
+const MAX_TRACE_EVENTS = 500;
+let eventCount = 0;
+
+function getTraceFile(): string {
+  if (traceFile) return traceFile;
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  traceFile = path.join(dir, 'calltrace.jsonl');
+  try { fs.writeFileSync(traceFile, ''); } catch {}
+  return traceFile;
+}
+
+function writeEvent(event: CallEvent): void {
+  if (eventCount >= MAX_TRACE_EVENTS) return;
+  eventCount++;
+  try {
+    fs.appendFileSync(getTraceFile(), JSON.stringify(event) + '\n');
+  } catch {}
+}
+
+/**
+ * Record a function call event. Returns the callId for pairing with traceReturn.
+ */
+export function traceCall(functionName: string, moduleName: string): number {
+  const id = ++callCounter;
+  const parentId = callStack[callStack.length - 1] || 0;
+  callStack.push(id);
+  // We record a placeholder — duration is filled in by traceReturn
+  return id;
+}
+
+/**
+ * Record a function return event with timing.
+ */
+export function traceReturn(
+  callId: number,
+  functionName: string,
+  moduleName: string,
+  durationMs: number,
+  error?: string,
+): void {
+  const parentId = callStack.length >= 2 ? callStack[callStack.length - 2] : 0;
+  const depth = callStack.length - 1;
+
+  writeEvent({
+    kind: 'call',
+    function: functionName,
+    module: moduleName,
+    callId,
+    parentId,
+    depth,
+    timestamp: Date.now(),
+    durationMs: Math.round(durationMs * 100) / 100,
+    ...(error ? { error } : {}),
+  });
+
+  // Pop from stack
+  if (callStack[callStack.length - 1] === callId) {
+    callStack.pop();
+  }
+}
+
+export function initCallTrace(): void {
+  // Ensure trace file is initialized
+  getTraceFile();
+}

package/src/observe-register.ts

@@ -1154,6 +1154,24 @@ if (enabled) {
       } catch { /* not critical */ }
     }
 
+    // WebSocket (ws)
+    if (request === 'ws' && !expressPatched.has('ws')) {
+      expressPatched.add('ws');
+      try {
+        const { patchWs } = require(path.join(__dirname, 'ws-observer.js'));
+        patchWs(exports, debug);
+      } catch { /* not critical */ }
+    }
+
+    // socket.io-client
+    if (request === 'socket.io-client' && !expressPatched.has('socket.io-client')) {
+      expressPatched.add('socket.io-client');
+      try {
+        const { patchSocketIo } = require(path.join(__dirname, 'ws-observer.js'));
+        patchSocketIo(exports, debug);
+      } catch { /* not critical */ }
+    }
+
     // Resolve to absolute path for dedup — do this FIRST since bundlers like
     // tsx/esbuild may use path aliases (e.g., @config/env) that don't start
     // with './' or '/'. We need the resolved path to decide if it's user code.

package/src/wrap.ts

@@ -4,6 +4,7 @@ import { hashType } from './type-hash';
 import { createTracker } from './proxy-tracker';
 import { TypeCache } from './cache';
 import { enqueue } from './transport';
+import { traceCall, traceReturn } from './call-trace';
 
 const typeCache = new TypeCache();
 
@@ -35,6 +36,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
     let caughtError: unknown;
     const trackers: Array<{ proxy: unknown; getAccessedPaths: () => Map<string, TypeNode> }> = [];
     const startTime = performance.now();
+    const callId = traceCall(opts.functionName, opts.module);
 
     try {
       // Always pass ORIGINAL args to the function — never proxied ones.
@@ -48,6 +50,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
       try {
         const durationMs = performance.now() - startTime;
         captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+        traceReturn(callId, opts.functionName, opts.module, durationMs, (err as Error)?.message);
       } catch {
         // Never let our instrumentation interfere
       }
@@ -63,6 +66,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
           try {
             const durationMs = performance.now() - startTime;
             capturePayload(functionKey, opts, args, trackers, resolved, true, durationMs);
+            traceReturn(callId, opts.functionName, opts.module, durationMs);
           } catch {
             // Never let our instrumentation interfere
           }
@@ -72,6 +76,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
           try {
             const durationMs = performance.now() - startTime;
             captureErrorPayload(functionKey, opts, args, trackers, err, durationMs);
+            traceReturn(callId, opts.functionName, opts.module, durationMs, (err as Error)?.message);
           } catch {
             // Never let our instrumentation interfere
           }
@@ -85,6 +90,7 @@ export function wrapFunction<T extends (...args: any[]) => any>(fn: T, opts: Wra
     try {
       const durationMs = performance.now() - startTime;
       capturePayload(functionKey, opts, args, trackers, result, false, durationMs);
+      traceReturn(callId, opts.functionName, opts.module, durationMs);
     } catch {
       // Never let our instrumentation interfere
     }

package/src/ws-observer.ts

@@ -0,0 +1,190 @@
+/**
+ * WebSocket observer — patches popular WebSocket libraries to capture
+ * message events, connection lifecycle, and timing.
+ *
+ * Supports:
+ *   - ws (most popular Node.js WebSocket library)
+ *   - Native WebSocket (browser/Deno/Bun)
+ *   - socket.io (real-time framework)
+ *
+ * Written to .trickle/websocket.jsonl as:
+ *   { "kind": "ws", "event": "message", "direction": "in",
+ *     "data": "...", "timestamp": 1710516000, "url": "ws://..." }
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface WsEvent {
+  kind: 'ws';
+  event: 'connect' | 'message' | 'close' | 'error' | 'emit';
+  direction?: 'in' | 'out';
+  url?: string;
+  data?: unknown;
+  channel?: string;
+  timestamp: number;
+}
+
+let wsFile: string | null = null;
+const MAX_EVENTS = 200;
+let eventCount = 0;
+const MAX_DATA_LENGTH = 500;
+
+function getWsFile(): string {
+  if (wsFile) return wsFile;
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  wsFile = path.join(dir, 'websocket.jsonl');
+  try { fs.writeFileSync(wsFile, ''); } catch {};
+  return wsFile;
+}
+
+function writeWsEvent(event: WsEvent): void {
+  if (eventCount >= MAX_EVENTS) return;
+  eventCount++;
+  try {
+    fs.appendFileSync(getWsFile(), JSON.stringify(event) + '\n');
+  } catch {}
+}
+
+function truncateData(data: unknown): unknown {
+  if (data === undefined || data === null) return data;
+  if (typeof data === 'string') {
+    return data.length > MAX_DATA_LENGTH ? data.substring(0, MAX_DATA_LENGTH) + '...' : data;
+  }
+  if (Buffer.isBuffer(data)) {
+    return `<Buffer(${data.length} bytes)>`;
+  }
+  if (typeof data === 'object') {
+    try {
+      const s = JSON.stringify(data);
+      return s.length > MAX_DATA_LENGTH ? JSON.parse(s.substring(0, MAX_DATA_LENGTH) + '..."}}') : data;
+    } catch {
+      return String(data).substring(0, MAX_DATA_LENGTH);
+    }
+  }
+  return data;
+}
+
+/**
+ * Patch ws (node WebSocket library) to capture messages.
+ */
+export function patchWs(wsModule: any, debug: boolean): void {
+  const WsClass = wsModule.WebSocket || wsModule;
+  if (!WsClass?.prototype || (WsClass.prototype as any).__trickle_ws_patched) return;
+
+  const origSend = WsClass.prototype.send;
+  if (origSend) {
+    WsClass.prototype.send = function patchedSend(data: any, ...args: any[]) {
+      writeWsEvent({
+        kind: 'ws',
+        event: 'message',
+        direction: 'out',
+        url: this.url || this._url,
+        data: truncateData(data),
+        timestamp: Date.now(),
+      });
+      return origSend.call(this, data, ...args);
+    };
+  }
+
+  // Patch 'on' to capture incoming messages
+  const origOn = WsClass.prototype.on;
+  if (origOn) {
+    WsClass.prototype.on = function patchedOn(event: string, listener: any, ...args: any[]) {
+      if (event === 'message') {
+        const wrappedListener = (data: any, ...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'message',
+            direction: 'in',
+            url: this.url || this._url,
+            data: truncateData(data),
+            timestamp: Date.now(),
+          });
+          return listener(data, ...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      if (event === 'open') {
+        const wrappedListener = (...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'connect',
+            url: this.url || this._url,
+            timestamp: Date.now(),
+          });
+          return listener(...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      if (event === 'close') {
+        const wrappedListener = (code: number, reason: string, ...rest: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'close',
+            url: this.url || this._url,
+            data: { code, reason: String(reason || '').substring(0, 100) },
+            timestamp: Date.now(),
+          });
+          return listener(code, reason, ...rest);
+        };
+        return origOn.call(this, event, wrappedListener, ...args);
+      }
+      return origOn.call(this, event, listener, ...args);
+    };
+  }
+
+  (WsClass.prototype as any).__trickle_ws_patched = true;
+  if (debug) console.log('[trickle/ws] WebSocket tracing enabled');
+}
+
+/**
+ * Patch socket.io client to capture emit/on events.
+ */
+export function patchSocketIo(ioModule: any, debug: boolean): void {
+  // socket.io-client: the default export is a function that returns a Socket
+  const Socket = ioModule.Socket || (ioModule.io && ioModule.io.Socket);
+  if (!Socket?.prototype || (Socket.prototype as any).__trickle_sio_patched) return;
+
+  const origEmit = Socket.prototype.emit;
+  if (origEmit) {
+    Socket.prototype.emit = function patchedEmit(event: string, ...args: any[]) {
+      if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+        writeWsEvent({
+          kind: 'ws',
+          event: 'emit',
+          direction: 'out',
+          channel: event,
+          data: truncateData(args[0]),
+          timestamp: Date.now(),
+        });
+      }
+      return origEmit.call(this, event, ...args);
+    };
+  }
+
+  const origOn = Socket.prototype.on;
+  if (origOn) {
+    Socket.prototype.on = function patchedOn(event: string, listener: any, ...rest: any[]) {
+      if (event !== 'connect' && event !== 'disconnect' && !event.startsWith('__')) {
+        const wrappedListener = (...args: any[]) => {
+          writeWsEvent({
+            kind: 'ws',
+            event: 'emit',
+            direction: 'in',
+            channel: event,
+            data: truncateData(args[0]),
+            timestamp: Date.now(),
+          });
+          return listener(...args);
+        };
+        return origOn.call(this, event, wrappedListener, ...rest);
+      }
+      return origOn.call(this, event, listener, ...rest);
+    };
+  }
+
+  (Socket.prototype as any).__trickle_sio_patched = true;
+  if (debug) console.log('[trickle/ws] socket.io tracing enabled');
+}