kindred-tracer-node 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# kindred-tracer-node
+
+Kindred Tracer SDK for Node.js - Auto-instrumentation for AI agents.
+
+This package automatically intercepts HTTP/HTTPS requests from your AI agent, categorizes them as LLM calls or tool executions, and exports logs to the Kindred log-search system.
+
+## Installation
+
+```bash
+npm install kindred-tracer-node
+# or
+pnpm add kindred-tracer-node
+```
+
+## Usage
+
+### Basic Usage
+
+Just call `kindredTracer()` once at startup, and all HTTP requests will be automatically intercepted and logged:
+
+```typescript
+import { kindredTracer } from 'kindred-tracer-node';
+
+// At startup - initialize the tracer
+kindredTracer();
+
+// Your agent code here - no wrapping needed!
+// All HTTP requests will be automatically logged
+const response = await fetch('https://api.openai.com/v1/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ /* ... */ })
+});
+```
+
+## Configuration
+
+Set the following environment variables:
+
+- `KINDRED_API_KEY` (required) - Your Kindred API key for authentication
+- `KINDRED_API_URL` (optional) - Base URL for Kindred API, defaults to `https://api.usekindred.dev`
+- `KINDRED_SESSION_ID` (optional) - Session identifier. If not set, a UUID will be auto-generated
+- `KINDRED_AGENT_ID` (optional) - Agent identifier
+- `KINDRED_RUN_ID` (optional) - Run identifier
+
+You can also pass these values directly to `kindredTracer()`:
+
+```typescript
+import { kindredTracer } from 'kindred-tracer-node';
+
+// Initialize with explicit values
+kindredTracer('session-123', 'agent-456', 'run-789');
+```
+
+## How It Works
+
+1. **Simple Initialization**: Call `kindredTracer()` once at startup to set up global context and enable interception.
+
+2. **Auto-instrumentation**: The tracer automatically patches Node.js's `https.request` and `http.request` when initialized.
+
+3. **Global Context**: Uses a global context that applies to all HTTP requests after initialization.
+
+4. **Request Detection**:
+   - **LLM Calls**: Detected by hostname (e.g., `api.openai.com`, `api.anthropic.com`) → logged as `role: "agent"`
+   - **Tool Calls**: Any other hostname → logged as `role: "tool"`
+
+5. **Streaming Support**: Handles streaming responses correctly - chunks are passed through immediately (zero latency) while being buffered for logging.
+
+6. **Non-blocking Export**: Logs are batched and exported asynchronously to avoid slowing down your agent.
+
+## Log Format
+
+Logs are automatically formatted and sent to `${KINDRED_API_URL}/api/logs/ingest` with the following structure:
+
+```typescript
+{
+  session_id: string;
+  timestamp: string; // ISO 8601
+  role: "user" | "agent" | "tool" | "system";
+  content: string;
+  agent_id?: string;
+  run_id?: string;
+  meta?: {
+    type: "llm_generation" | "tool_execution";
+    request_id: string;
+    host: string;
+    method: string;
+    path: string;
+    request_headers: Record<string, unknown>;
+    request_body: string | null;
+    response_status: number;
+    response_headers: Record<string, unknown>;
+    response_body: string | null;
+    duration_ms: number;
+    tool_calls?: Array<{...}>; // Extracted from OpenAI responses
+  };
+}
+```
+
+## Flushing Logs
+
+Before shutting down your application, you can flush any pending logs:
+
+```typescript
+import { flushLogs } from 'kindred-tracer-node';
+
+// On shutdown
+await flushLogs();
+```
+
+## Security
+
+The tracer automatically sanitizes sensitive headers before logging:
+- `Authorization`
+- `x-api-key`
+- `api-key`
+- `x-auth-token`
+- `cookie`
+
+## Supported LLM Providers
+
+The tracer automatically detects requests to:
+- OpenAI (`api.openai.com`)
+- Anthropic (`api.anthropic.com`)
+- Google Gemini (`generativelanguage.googleapis.com`)
+- Cohere (`api.cohere.com`)
+- Mistral (`api.mistral.ai`)
+
+## Example
+
+Here's a complete example:
+
+```typescript
+import { kindredTracer, flushLogs } from 'kindred-tracer-node';
+
+// Set your API key
+process.env.KINDRED_API_KEY = 'your-api-key-here';
+
+// Initialize the tracer (reads sessionId from KINDRED_SESSION_ID env var, or auto-generates)
+kindredTracer();
+
+// Your agent code - all HTTP requests are automatically logged
+const response = await fetch('https://api.openai.com/v1/chat/completions', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }]
+  })
+});
+
+// Before shutdown, flush any pending logs
+await flushLogs();
+```
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Context management using global context for simple initialization pattern
+ */
+export interface TraceContext {
+    sessionId: string;
+    agentId?: string;
+    runId?: string;
+    traceId: string;
+}
+/**
+ * Get the current trace context
+ */
+export declare function getContext(): TraceContext | undefined;
+/**
+ * Set the global trace context
+ */
+export declare function setGlobalContext(sessionId: string, agentId?: string, runId?: string, traceId?: string): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;GAEG;AACH,wBAAgB,UAAU,IAAI,YAAY,GAAG,SAAS,CAErD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAON"}

package/dist/context.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Context management using global context for simple initialization pattern
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContext = getContext;
+exports.setGlobalContext = setGlobalContext;
+// Global context storage
+let globalContext = undefined;
+/**
+ * Get the current trace context
+ */
+function getContext() {
+    return globalContext;
+}
+/**
+ * Set the global trace context
+ */
+function setGlobalContext(sessionId, agentId, runId, traceId) {
+    globalContext = {
+        sessionId,
+        agentId,
+        runId,
+        traceId: traceId || sessionId, // Use sessionId as traceId if not provided
+    };
+}

package/dist/exporter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Non-blocking log exporter to Kindred API
+ */
+import type { LogEntry } from "./types";
+/**
+ * Add a log entry to the buffer
+ */
+export declare function addLog(log: LogEntry): void;
+/**
+ * Flush any remaining logs (call on shutdown)
+ * Waits for all pending logs to be sent
+ */
+export declare function flush(): Promise<void>;
+//# sourceMappingURL=exporter.d.ts.map

package/dist/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAcxC;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAgB1C;AA2KD;;;GAGG;AACH,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA6C3C"}

package/dist/exporter.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Non-blocking log exporter to Kindred API
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addLog = addLog;
+exports.flush = flush;
+const https_1 = __importDefault(require("https"));
+const http_1 = __importDefault(require("http"));
+const url_1 = require("url");
+const API_URL = process.env.KINDRED_API_URL || "https://api.usekindred.dev";
+const API_KEY = process.env.KINDRED_API_KEY;
+// In-memory buffer for batching logs
+const logBuffer = [];
+const BATCH_SIZE = 5; // Send logs in smaller batches to avoid payload size limits
+const FLUSH_INTERVAL_MS = 5000; // Flush every 5 seconds
+const MAX_PAYLOAD_SIZE = 100 * 1024; // 100KB max payload size
+let flushTimer = null;
+/**
+ * Add a log entry to the buffer
+ */
+function addLog(log) {
+    logBuffer.push(log);
+    // Flush if buffer is full
+    if (logBuffer.length >= BATCH_SIZE) {
+        flushLogs().catch((error) => {
+            console.error("[kindred-tracer] Failed to flush logs:", error);
+        });
+    }
+    else if (!flushTimer) {
+        // Start flush timer if not already running
+        flushTimer = setTimeout(() => {
+            flushLogs().catch((error) => {
+                console.error("[kindred-tracer] Failed to flush logs:", error);
+            });
+        }, FLUSH_INTERVAL_MS);
+    }
+}
+/**
+ * Truncate large strings in log metadata to prevent payload size issues
+ */
+function truncateLogEntry(log) {
+    const MAX_STRING_LENGTH = 10000; // 10KB max per string field
+    if (!log.meta) {
+        return log;
+    }
+    const truncatedMeta = { ...log.meta };
+    // Truncate large strings in metadata
+    const truncateString = (str) => {
+        if (!str || typeof str !== "string")
+            return str || null;
+        if (str.length <= MAX_STRING_LENGTH)
+            return str;
+        return str.substring(0, MAX_STRING_LENGTH) + `... [truncated ${str.length - MAX_STRING_LENGTH} chars]`;
+    };
+    if (typeof truncatedMeta.request_body === "string") {
+        truncatedMeta.request_body = truncateString(truncatedMeta.request_body);
+    }
+    if (typeof truncatedMeta.response_body === "string") {
+        truncatedMeta.response_body = truncateString(truncatedMeta.response_body);
+    }
+    return {
+        ...log,
+        meta: truncatedMeta,
+    };
+}
+/**
+ * Flush logs to the API (non-blocking)
+ */
+function flushLogs() {
+    if (logBuffer.length === 0) {
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+        }
+        return Promise.resolve();
+    }
+    // Copy and clear buffer
+    const logsToSend = [...logBuffer];
+    logBuffer.length = 0;
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    // Truncate large payloads
+    const truncatedLogs = logsToSend.map(truncateLogEntry);
+    // Send and return promise so caller can wait
+    return sendLogs(truncatedLogs).catch((error) => {
+        // Log error but don't throw - we don't want to break the agent
+        console.error("[kindred-tracer] Failed to send logs:", error);
+    });
+}
+/**
+ * Send logs to Kindred API
+ */
+async function sendLogs(logs) {
+    if (!API_KEY) {
+        console.warn("[kindred-tracer] KINDRED_API_KEY not set, skipping log export");
+        return;
+    }
+    if (logs.length === 0) {
+        return;
+    }
+    const ingestUrl = new url_1.URL(`${API_URL}/api/logs/ingest`);
+    const isHttps = ingestUrl.protocol === "https:";
+    const client = isHttps ? https_1.default : http_1.default;
+    // Try to stringify, but split into smaller batches if too large
+    let postData;
+    let logsToSend = logs;
+    try {
+        postData = JSON.stringify({ logs });
+        // If payload is too large, split into smaller batches
+        if (postData.length > MAX_PAYLOAD_SIZE && logs.length > 1) {
+            const batchSize = Math.max(1, Math.floor(logs.length / 2));
+            const firstBatch = logs.slice(0, batchSize);
+            const secondBatch = logs.slice(batchSize);
+            // Send first batch
+            await sendLogs(firstBatch);
+            // Send second batch
+            await sendLogs(secondBatch);
+            return;
+        }
+    }
+    catch (error) {
+        // If stringify fails (too large), try sending fewer logs
+        if (logs.length > 1) {
+            const half = Math.floor(logs.length / 2);
+            await sendLogs(logs.slice(0, half));
+            await sendLogs(logs.slice(half));
+            return;
+        }
+        // If even one log is too large, skip it
+        console.error("[kindred-tracer] Log entry too large to serialize, skipping");
+        return;
+    }
+    const options = {
+        hostname: ingestUrl.hostname,
+        port: ingestUrl.port || (isHttps ? 443 : 80),
+        path: ingestUrl.pathname,
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Content-Length": Buffer.byteLength(postData),
+            Authorization: `Bearer ${API_KEY}`,
+        },
+        timeout: 10000, // 10 second timeout
+    };
+    return new Promise((resolve, reject) => {
+        const req = client.request(options, (res) => {
+            let responseData = "";
+            res.on("data", (chunk) => {
+                responseData += chunk;
+            });
+            res.on("end", () => {
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    if (process.env.KINDRED_TRACER_VERBOSE) {
+                        console.log(`[kindred-tracer] Successfully sent ${logs.length} log(s) to API`);
+                    }
+                    resolve();
+                }
+                else {
+                    const errorMsg = `API returned ${res.statusCode}: ${responseData || "unknown error"}`;
+                    console.error(`[kindred-tracer] ${errorMsg}`);
+                    reject(new Error(errorMsg));
+                }
+            });
+            res.on("error", (error) => {
+                reject(error);
+            });
+        });
+        req.on("error", (error) => {
+            reject(error);
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("Request timeout"));
+        });
+        req.write(postData);
+        req.end();
+    });
+}
+/**
+ * Flush any remaining logs (call on shutdown)
+ * Waits for all pending logs to be sent
+ */
+async function flush() {
+    // Clear any pending timer
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    // Send all logs currently in buffer (don't wait for new ones)
+    if (logBuffer.length === 0) {
+        if (process.env.KINDRED_TRACER_VERBOSE) {
+            console.log("[kindred-tracer] No logs to flush");
+        }
+        return;
+    }
+    // Copy buffer and clear it immediately
+    const logsToSend = [...logBuffer];
+    logBuffer.length = 0;
+    if (process.env.KINDRED_TRACER_VERBOSE) {
+        console.log(`[kindred-tracer] Flushing ${logsToSend.length} log(s)`);
+    }
+    if (logsToSend.length > 0) {
+        // Truncate and send with timeout
+        const truncatedLogs = logsToSend.map(truncateLogEntry);
+        try {
+            // Add a timeout wrapper to prevent hanging
+            await Promise.race([
+                sendLogs(truncatedLogs),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Flush timeout after 15 seconds")), 15000)),
+            ]);
+            if (process.env.KINDRED_TRACER_VERBOSE) {
+                console.log("[kindred-tracer] Flush completed successfully");
+            }
+        }
+        catch (error) {
+            console.error("[kindred-tracer] Failed to send logs during flush:", error.message || error);
+            // Don't throw - we want flush to complete even if send fails
+        }
+    }
+    // Give a moment for the HTTP request to complete
+    await new Promise((resolve) => setTimeout(resolve, 500));
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Kindred Tracer SDK for Node.js
+ * Auto-instrumentation for AI agents
+ */
+/**
+ * Initialize the Kindred tracer.
+ *
+ * Reads sessionId, agentId, and runId from environment variables or parameters.
+ * Auto-generates sessionId if not provided.
+ *
+ * @param sessionId - Session identifier. If not provided, reads from KINDRED_SESSION_ID env var.
+ *                    If still not set, auto-generates a UUID.
+ * @param agentId - Agent identifier. If not provided, reads from KINDRED_AGENT_ID env var.
+ * @param runId - Run identifier. If not provided, reads from KINDRED_RUN_ID env var.
+ *
+ * @example
+ * ```typescript
+ * import { kindredTracer } from 'kindred-tracer-node';
+ *
+ * // At startup - reads from environment variables
+ * kindredTracer();
+ *
+ * // Or specify explicitly
+ * kindredTracer('session-123', 'agent-456');
+ * ```
+ */
+export declare function kindredTracer(sessionId?: string, agentId?: string, runId?: string): void;
+/**
+ * Flush any pending logs to the API.
+ * Call this before shutting down your application.
+ */
+export declare function flushLogs(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Kindred Tracer SDK for Node.js
+ * Auto-instrumentation for AI agents
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kindredTracer = kindredTracer;
+exports.flushLogs = flushLogs;
+const uuid_1 = require("uuid");
+const context_1 = require("./context");
+const interceptor_1 = require("./interceptor");
+const exporter_1 = require("./exporter");
+// Track if interceptor has been initialized
+let isInterceptorInitialized = false;
+/**
+ * Initialize the Kindred tracer.
+ *
+ * Reads sessionId, agentId, and runId from environment variables or parameters.
+ * Auto-generates sessionId if not provided.
+ *
+ * @param sessionId - Session identifier. If not provided, reads from KINDRED_SESSION_ID env var.
+ *                    If still not set, auto-generates a UUID.
+ * @param agentId - Agent identifier. If not provided, reads from KINDRED_AGENT_ID env var.
+ * @param runId - Run identifier. If not provided, reads from KINDRED_RUN_ID env var.
+ *
+ * @example
+ * ```typescript
+ * import { kindredTracer } from 'kindred-tracer-node';
+ *
+ * // At startup - reads from environment variables
+ * kindredTracer();
+ *
+ * // Or specify explicitly
+ * kindredTracer('session-123', 'agent-456');
+ * ```
+ */
+function kindredTracer(sessionId, agentId, runId) {
+    // Read from parameters or environment variables
+    const finalSessionId = sessionId || process.env.KINDRED_SESSION_ID || (0, uuid_1.v4)();
+    const finalAgentId = agentId || process.env.KINDRED_AGENT_ID;
+    const finalRunId = runId || process.env.KINDRED_RUN_ID;
+    // Set global context
+    (0, context_1.setGlobalContext)(finalSessionId, finalAgentId, finalRunId);
+    // Initialize interceptor if not already done
+    if (!isInterceptorInitialized) {
+        (0, interceptor_1.initializeInterceptor)();
+        isInterceptorInitialized = true;
+    }
+}
+/**
+ * Flush any pending logs to the API.
+ * Call this before shutting down your application.
+ */
+async function flushLogs() {
+    return (0, exporter_1.flush)();
+}

package/dist/interceptor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP/HTTPS request interceptor
+ * Handles streaming responses correctly: passes through chunks immediately while buffering for logging
+ */
+/**
+ * Initialize the HTTP interceptor
+ */
+export declare function initializeInterceptor(): void;
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4EH;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAsB5C"}

package/dist/interceptor.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * HTTP/HTTPS request interceptor
+ * Handles streaming responses correctly: passes through chunks immediately while buffering for logging
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeInterceptor = initializeInterceptor;
+const https_1 = __importDefault(require("https"));
+const http_1 = __importDefault(require("http"));
+const url_1 = require("url");
+const context_1 = require("./context");
+const exporter_1 = require("./exporter");
+const parser_1 = require("./parser");
+const types_1 = require("./types");
+const uuid_1 = require("uuid");
+// Store original request functions
+const originalHttpsRequest = https_1.default.request;
+const originalHttpRequest = http_1.default.request;
+// Track if we've already patched
+let isPatched = false;
+/**
+ * Sanitize headers by removing sensitive information
+ */
+function sanitizeHeaders(headers) {
+    const sanitized = { ...headers };
+    const sensitiveKeys = [
+        "authorization",
+        "x-api-key",
+        "api-key",
+        "x-auth-token",
+        "cookie",
+    ];
+    for (const key of sensitiveKeys) {
+        const lowerKey = key.toLowerCase();
+        for (const headerKey of Object.keys(sanitized)) {
+            if (headerKey.toLowerCase() === lowerKey) {
+                delete sanitized[headerKey];
+            }
+        }
+    }
+    return sanitized;
+}
+/**
+ * Extract request body from options or data
+ */
+async function extractRequestBody(options, data) {
+    if (data !== undefined) {
+        if (typeof data === "string") {
+            return data;
+        }
+        if (Buffer.isBuffer(data)) {
+            return data.toString("utf-8");
+        }
+        return JSON.stringify(data);
+    }
+    // If body is in options, try to extract it
+    if ("body" in options && options.body !== undefined) {
+        if (typeof options.body === "string") {
+            return options.body;
+        }
+        if (Buffer.isBuffer(options.body)) {
+            return options.body.toString("utf-8");
+        }
+        return JSON.stringify(options.body);
+    }
+    return null;
+}
+/**
+ * Initialize the HTTP interceptor
+ */
+function initializeInterceptor() {
+    if (isPatched) {
+        return;
+    }
+    isPatched = true;
+    // Patch https.request
+    https_1.default.request = function (options, callback) {
+        return interceptRequest(originalHttpsRequest, options, callback, true);
+    };
+    // Patch http.request
+    http_1.default.request = function (options, callback) {
+        return interceptRequest(originalHttpRequest, options, callback, false);
+    };
+}
+/**
+ * Intercept HTTP/HTTPS requests
+ */
+function interceptRequest(originalRequest, options, callback, isHttps = true) {
+    const context = (0, context_1.getContext)();
+    // If no context, just pass through
+    if (!context) {
+        if (typeof options === "string" || options instanceof url_1.URL) {
+            return originalRequest(options, callback);
+        }
+        return originalRequest(options, callback);
+    }
+    // Normalize options
+    let normalizedOptions;
+    if (typeof options === "string" || options instanceof url_1.URL) {
+        const url = new url_1.URL(options.toString());
+        normalizedOptions = {
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            protocol: url.protocol,
+        };
+    }
+    else {
+        normalizedOptions = { ...options };
+    }
+    const hostname = normalizedOptions.hostname ||
+        (normalizedOptions.host ? normalizedOptions.host.split(":")[0] : null);
+    if (!hostname) {
+        // Can't determine host, pass through
+        return originalRequest(normalizedOptions, callback);
+    }
+    // Determine if this is an LLM call or tool call
+    const isLLM = (0, types_1.isLLMHost)(hostname);
+    const role = isLLM ? "agent" : "tool";
+    // Extract request data
+    const requestId = (0, uuid_1.v4)();
+    const startTime = Date.now();
+    let requestBody = null;
+    const requestHeaders = sanitizeHeaders(normalizedOptions.headers || {});
+    // Create the request
+    const req = originalRequest(normalizedOptions, (res) => {
+        // Buffer for response body (for logging) - accumulates chunks
+        const responseChunks = [];
+        // Intercept data events to buffer while passing through immediately
+        // This ensures zero latency - chunks go to user immediately
+        const originalEmit = res.emit.bind(res);
+        res.emit = function (event, ...args) {
+            // Buffer data chunks for logging
+            if (event === "data" && args[0] instanceof Buffer) {
+                responseChunks.push(args[0]);
+            }
+            // Always emit the event (pass through) - this is critical for zero latency
+            return originalEmit(event, ...args);
+        };
+        // When response ends, log it
+        res.once("end", () => {
+            // Reconstruct response body from buffered chunks
+            // Truncate to prevent huge payloads (max 50KB per response)
+            const MAX_RESPONSE_BODY_SIZE = 50 * 1024; // 50KB
+            let responseBody = null;
+            if (responseChunks.length > 0) {
+                const fullBody = Buffer.concat(responseChunks).toString("utf-8");
+                if (fullBody.length > MAX_RESPONSE_BODY_SIZE) {
+                    responseBody =
+                        fullBody.substring(0, MAX_RESPONSE_BODY_SIZE) +
+                            `... [truncated ${fullBody.length - MAX_RESPONSE_BODY_SIZE} chars]`;
+                }
+                else {
+                    responseBody = fullBody;
+                }
+            }
+            // Parse response if it's JSON
+            let parsedResponse = null;
+            let toolCalls = null;
+            if (responseBody) {
+                try {
+                    parsedResponse = JSON.parse(responseBody);
+                    if (isLLM) {
+                        const parsed = (0, parser_1.parseOpenAIResponse)(parsedResponse);
+                        if (parsed.toolCalls) {
+                            toolCalls = parsed.toolCalls;
+                        }
+                    }
+                }
+                catch {
+                    // Not JSON, ignore
+                }
+            }
+            const endTime = Date.now();
+            const duration = endTime - startTime;
+            // Build log entry
+            const logEntry = {
+                session_id: context.sessionId,
+                timestamp: new Date(startTime).toISOString(),
+                role,
+                content: isLLM
+                    ? `LLM request to ${hostname}${normalizedOptions.path || ""}`
+                    : `Tool request to ${hostname}${normalizedOptions.path || ""}`,
+                agent_id: context.agentId,
+                run_id: context.runId,
+                meta: {
+                    type: isLLM ? "llm_generation" : "tool_execution",
+                    request_id: requestId,
+                    host: hostname,
+                    method: normalizedOptions.method || "GET",
+                    path: normalizedOptions.path || "",
+                    request_headers: requestHeaders,
+                    request_body: requestBody,
+                    response_status: res.statusCode,
+                    response_headers: sanitizeHeaders(res.headers || {}),
+                    response_body: responseBody,
+                    duration_ms: duration,
+                    ...(toolCalls ? { tool_calls: toolCalls } : {}),
+                },
+            };
+            // Export log (non-blocking)
+            (0, exporter_1.addLog)(logEntry);
+        });
+        // Call original callback if provided
+        if (callback) {
+            callback(res);
+        }
+    });
+    // Intercept request body if data is written
+    // Accumulate request body chunks (with size limit)
+    const requestChunks = [];
+    const MAX_REQUEST_BODY_SIZE = 50 * 1024; // 50KB
+    let requestBodySize = 0;
+    const originalWrite = req.write.bind(req);
+    const originalEnd = req.end.bind(req);
+    req.write = function (chunk, encoding, cb) {
+        // Buffer request body chunks (up to size limit)
+        if (requestBodySize < MAX_REQUEST_BODY_SIZE) {
+            let chunkBuffer;
+            if (typeof chunk === "string") {
+                const enc = typeof encoding === "string" ? encoding : undefined;
+                chunkBuffer = Buffer.from(chunk, enc);
+            }
+            else if (Buffer.isBuffer(chunk)) {
+                chunkBuffer = chunk;
+            }
+            else {
+                return originalWrite(chunk, encoding, cb);
+            }
+            if (requestBodySize + chunkBuffer.length <= MAX_REQUEST_BODY_SIZE) {
+                requestChunks.push(chunkBuffer);
+                requestBodySize += chunkBuffer.length;
+            }
+            else {
+                // Truncate at limit
+                const remaining = MAX_REQUEST_BODY_SIZE - requestBodySize;
+                requestChunks.push(chunkBuffer.subarray(0, remaining));
+                requestBodySize = MAX_REQUEST_BODY_SIZE;
+            }
+        }
+        return originalWrite(chunk, encoding, cb);
+    };
+    req.end = function (chunk, encoding, cb) {
+        // Buffer final chunk if present and under limit
+        if (chunk !== undefined && requestBodySize < MAX_REQUEST_BODY_SIZE) {
+            let chunkBuffer;
+            if (typeof chunk === "string") {
+                const enc = typeof encoding === "string" ? encoding : undefined;
+                chunkBuffer = Buffer.from(chunk, enc);
+            }
+            else if (Buffer.isBuffer(chunk)) {
+                chunkBuffer = chunk;
+            }
+            else {
+                return originalEnd(chunk, encoding, cb);
+            }
+            if (requestBodySize + chunkBuffer.length <= MAX_REQUEST_BODY_SIZE) {
+                requestChunks.push(chunkBuffer);
+                requestBodySize += chunkBuffer.length;
+            }
+            else {
+                const remaining = MAX_REQUEST_BODY_SIZE - requestBodySize;
+                requestChunks.push(chunkBuffer.subarray(0, remaining));
+                requestBodySize = MAX_REQUEST_BODY_SIZE;
+            }
+        }
+        // Reconstruct request body (may be truncated)
+        if (requestChunks.length > 0) {
+            requestBody = Buffer.concat(requestChunks).toString("utf-8");
+            if (requestBodySize >= MAX_REQUEST_BODY_SIZE) {
+                requestBody += "... [truncated]";
+            }
+        }
+        return originalEnd(chunk, encoding, cb);
+    };
+    return req;
+}

package/dist/parser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Response parser for extracting structured data from LLM responses
+ */
+export interface ToolCall {
+    id?: string;
+    type: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ParsedResponse {
+    toolCalls?: ToolCall[];
+    content?: string;
+    role?: string;
+}
+/**
+ * Parse OpenAI JSON response and extract tool calls
+ */
+export declare function parseOpenAIResponse(body: unknown): ParsedResponse;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CA4CjE"}

package/dist/parser.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Response parser for extracting structured data from LLM responses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOpenAIResponse = parseOpenAIResponse;
+/**
+ * Parse OpenAI JSON response and extract tool calls
+ */
+function parseOpenAIResponse(body) {
+    const result = {};
+    if (typeof body !== "object" || body === null) {
+        return result;
+    }
+    const obj = body;
+    // Handle chat completion response
+    if (Array.isArray(obj.choices)) {
+        const firstChoice = obj.choices[0];
+        if (firstChoice?.message) {
+            const message = firstChoice.message;
+            // Extract tool calls
+            if (Array.isArray(message.tool_calls)) {
+                result.toolCalls = message.tool_calls.map((tc) => {
+                    const toolCall = tc;
+                    const fn = toolCall.function;
+                    return {
+                        id: typeof toolCall.id === "string" ? toolCall.id : undefined,
+                        type: typeof toolCall.type === "string" ? toolCall.type : "function",
+                        function: {
+                            name: typeof fn?.name === "string" ? fn.name : "",
+                            arguments: typeof fn?.arguments === "string" ? fn.arguments : "{}",
+                        },
+                    };
+                });
+            }
+            // Extract content
+            if (typeof message.content === "string") {
+                result.content = message.content;
+            }
+            // Extract role
+            if (typeof message.role === "string") {
+                result.role = message.role;
+            }
+        }
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Type definitions for kindred-tracer
+ */
+export interface LogEntry {
+    session_id: string;
+    timestamp: string;
+    role: "user" | "agent" | "tool" | "system";
+    content: string;
+    agent_id?: string;
+    run_id?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * LLM provider hosts
+ */
+export declare const LLM_HOSTS: Set<string>;
+/**
+ * Check if a host is an LLM provider
+ */
+export declare function isLLMHost(host: string): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,aAMpB,CAAC;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C"}

package/dist/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Type definitions for kindred-tracer
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_HOSTS = void 0;
+exports.isLLMHost = isLLMHost;
+/**
+ * LLM provider hosts
+ */
+exports.LLM_HOSTS = new Set([
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com", // Google Gemini
+    "api.cohere.com",
+    "api.mistral.ai",
+]);
+/**
+ * Check if a host is an LLM provider
+ */
+function isLLMHost(host) {
+    return exports.LLM_HOSTS.has(host.toLowerCase());
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "kindred-tracer-node",
+  "version": "1.0.0",
+  "description": "Kindred Tracer SDK for Node.js - Auto-instrumentation for AI agents",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aryanmundre/Kindred.git",
+    "directory": "packages/kindred-tracer/node"
+  },
+  "homepage": "https://github.com/aryanmundre/Kindred#readme",
+  "bugs": {
+    "url": "https://github.com/aryanmundre/Kindred/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true}); require('fs').rmSync('tsconfig.tsbuildinfo', {force: true});\"",
+    "prebuild": "pnpm run clean",
+    "build": "tsc --build",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.6",
+    "@types/uuid": "^9.0.7",
+    "typescript": "^5.3.0"
+  },
+  "keywords": ["kindred", "tracer", "instrumentation", "ai", "agent"],
+  "license": "MIT"
+}