@visibe.ai/node 0.1.4

package/dist/esm/client.js

@@ -0,0 +1,238 @@
+import { randomUUID } from 'node:crypto';
+import { APIClient, SpanBatcher } from './api';
+import { activeGroupTraceStorage } from './integrations/group-context';
+import { calculateCost, detectProvider, truncate, LLM_CONTENT_LIMIT } from './utils';
+export class Visibe {
+    constructor(options) {
+        // Map of instrumented clients to their cleanup functions.
+        this._instrumented = new Map();
+        const apiKey = options.apiKey ?? process.env['VISIBE_API_KEY'];
+        const apiUrl = options.apiUrl ?? process.env['VISIBE_API_URL'];
+        const debug = options.debug ?? process.env['VISIBE_DEBUG'] === '1';
+        const limit = options.contentLimit
+            ?? (process.env['VISIBE_CONTENT_LIMIT'] ? Number(process.env['VISIBE_CONTENT_LIMIT']) : undefined)
+            ?? LLM_CONTENT_LIMIT;
+        this.contentLimit = limit;
+        this.sessionId = options.sessionId;
+        this.debug = debug;
+        this.apiClient = new APIClient({ apiKey, apiUrl });
+        this.batcher = new SpanBatcher(this.apiClient);
+    }
+    // ---------------------------------------------------------------------------
+    // instrument() — wrap a client so each call creates its own trace.
+    // ---------------------------------------------------------------------------
+    instrument(client, options) {
+        if (this._instrumented.has(client))
+            return; // already patched
+        const name = options?.name ?? 'agent';
+        // Detect which kind of client this is and apply the right integration.
+        // Integrations are resolved lazily here to avoid circular imports at module load.
+        const restore = applyIntegration(client, name, this);
+        if (restore) {
+            this._instrumented.set(client, restore);
+        }
+    }
+    uninstrument(client) {
+        const restore = this._instrumented.get(client);
+        if (restore) {
+            restore();
+            this._instrumented.delete(client);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // track() — group multiple LLM calls into a single named trace.
+    //
+    // Instruments the client if not already done, then runs fn() inside an
+    // AsyncLocalStorage context so all integrations automatically route their
+    // spans into the shared traceId and report token/cost totals back here.
+    // ---------------------------------------------------------------------------
+    async track(client, name, fn) {
+        const traceId = randomUUID();
+        const startedAt = new Date().toISOString();
+        const startMs = Date.now();
+        await this.apiClient.createTrace({
+            trace_id: traceId,
+            name,
+            framework: detectFrameworkName(client),
+            started_at: startedAt,
+            ...(this.sessionId ? { session_id: this.sessionId } : {}),
+        });
+        // Accumulators updated by the group context callbacks (called from integrations).
+        let llmCallCount = 0;
+        let toolCallCount = 0;
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalCost = 0;
+        const groupCtx = {
+            traceId,
+            onLLMSpan: (inputTokens, outputTokens, cost) => {
+                llmCallCount++;
+                totalInput += inputTokens;
+                totalOutput += outputTokens;
+                totalCost += cost;
+            },
+            onToolSpan: () => { toolCallCount++; },
+        };
+        // Temporarily instrument client if not already done so that the integration
+        // patch is in place for the duration of fn().
+        const wasInstrumented = this._instrumented.has(client);
+        if (!wasInstrumented) {
+            this.instrument(client, { name });
+        }
+        // Run fn() inside the group ALS context.  All instrumented integrations
+        // check activeGroupTraceStorage.getStore() — when set they skip their own
+        // createTrace/completeTrace calls and route spans into the shared traceId.
+        return activeGroupTraceStorage.run(groupCtx, async () => {
+            let status = 'completed';
+            try {
+                return await fn();
+            }
+            catch (err) {
+                status = 'failed';
+                throw err;
+            }
+            finally {
+                if (!wasInstrumented) {
+                    this.uninstrument(client);
+                }
+                const durationMs = Date.now() - startMs;
+                // CRITICAL ORDER: flush spans first, then complete the trace.
+                // The backend computes all breakdowns from spans at read time.
+                this.batcher.flush();
+                const sent = await this.apiClient.completeTrace(traceId, {
+                    status,
+                    ended_at: new Date().toISOString(),
+                    duration_ms: durationMs,
+                    llm_call_count: llmCallCount,
+                    total_cost: parseFloat(totalCost.toFixed(6)),
+                    total_tokens: totalInput + totalOutput,
+                    total_input_tokens: totalInput,
+                    total_output_tokens: totalOutput,
+                });
+                printTraceSummary({
+                    name,
+                    llmCallCount,
+                    toolCallCount,
+                    totalTokens: totalInput + totalOutput,
+                    totalCost,
+                    durationMs,
+                    status,
+                }, sent);
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // flushSpans() — called by shutdown() in index.ts.
+    // ---------------------------------------------------------------------------
+    flushSpans() {
+        this.batcher.flush();
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers used by integrations.
+    // ---------------------------------------------------------------------------
+    buildLLMSpan(opts) {
+        const cost = calculateCost(opts.model, opts.inputTokens, opts.outputTokens);
+        return {
+            span_id: opts.spanId,
+            ...(opts.parentSpanId ? { parent_span_id: opts.parentSpanId } : {}),
+            type: 'llm_call',
+            timestamp: new Date().toISOString(),
+            agent_name: opts.agentName,
+            model: opts.model,
+            provider: detectProvider(opts.model),
+            status: opts.status,
+            description: `LLM Call using ${opts.model}`,
+            input_tokens: opts.inputTokens,
+            output_tokens: opts.outputTokens,
+            cost,
+            duration_ms: opts.durationMs,
+            input_text: truncate(opts.inputText, this.contentLimit),
+            output_text: truncate(opts.outputText, this.contentLimit),
+        };
+    }
+    buildToolSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            ...(opts.parentSpanId ? { parent_span_id: opts.parentSpanId } : {}),
+            type: 'tool_call',
+            timestamp: new Date().toISOString(),
+            tool_name: opts.toolName,
+            agent_name: opts.agentName,
+            status: opts.status,
+            duration_ms: opts.durationMs,
+            input_text: truncate(opts.inputText, 500),
+            output_text: truncate(opts.outputText, 500),
+        };
+    }
+    buildErrorSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            type: 'error',
+            timestamp: new Date().toISOString(),
+            description: `Error: ${opts.errorType}`,
+            error_type: opts.errorType,
+            error_message: truncate(opts.errorMessage, 500),
+            duration_ms: opts.durationMs ?? 10,
+        };
+    }
+    buildAgentStartSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            type: 'agent_start', // EXACT string — backend validates this
+            timestamp: new Date().toISOString(),
+            agent_name: opts.agentName,
+            description: `Agent started: ${opts.agentName}`,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers (module-private)
+// ---------------------------------------------------------------------------
+function printTraceSummary(summary, sent) {
+    const durationSec = (summary.durationMs / 1000).toFixed(1);
+    const tokens = summary.totalTokens.toLocaleString();
+    const cost = `$${summary.totalCost.toFixed(6)}`;
+    const sentStr = sent ? 'OK' : 'FAILED';
+    console.log(`[Visibe] Trace: ${summary.name} | ${summary.llmCallCount} LLM calls | ${tokens} tokens | ${cost} | ${durationSec}s | ${summary.toolCallCount} tool calls | status: ${summary.status} | sent: ${sentStr}`);
+}
+// Detect a human-readable framework name from a client instance.
+// Used in createTrace() payload. Integrations can refine this later.
+function detectFrameworkName(client) {
+    const name = client?.constructor?.name ?? '';
+    if (name === 'OpenAI')
+        return 'openai';
+    if (name === 'Anthropic')
+        return 'anthropic';
+    if (name === 'BedrockRuntimeClient')
+        return 'bedrock';
+    return 'unknown';
+}
+// Apply the correct integration for a given client instance.
+// Returns a restore function, or null if the client type is unrecognised.
+function applyIntegration(client, name, visibe) {
+    // Integrations are loaded lazily to avoid import errors when the peer
+    // dependency is not installed.  Each integration module exports a
+    // `patchClient(client, name, visibe)` that returns a restore function.
+    const constructorName = client?.constructor?.name ?? '';
+    try {
+        if (constructorName === 'OpenAI') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchOpenAIClient } = require('./integrations/openai');
+            return patchOpenAIClient(client, name, visibe);
+        }
+        if (constructorName === 'Anthropic') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchAnthropicClient } = require('./integrations/anthropic');
+            return patchAnthropicClient(client, name, visibe);
+        }
+        if (constructorName === 'BedrockRuntimeClient') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchBedrockClient } = require('./integrations/bedrock');
+            return patchBedrockClient(client, name, visibe);
+        }
+    }
+    catch {
+        // Integration module not available or patch threw — never crash user code.
+    }
+    return null;
+}

package/dist/esm/index.js

@@ -0,0 +1,209 @@
+import { Visibe } from './client';
+// ---------------------------------------------------------------------------
+// Global state
+// ---------------------------------------------------------------------------
+let _globalClient = null;
+let _shutdownRegistered = false;
+// Saved original constructors so shutdown() can restore them.
+// Each is typed as `any` because we need to reassign imported class bindings.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _originalOpenAI = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _originalBedrockClient = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _originalCompiledStateGraph = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _originalAnthropic = null;
+let _vercelAIRestore = null;
+// ---------------------------------------------------------------------------
+// detectFrameworks()
+// ---------------------------------------------------------------------------
+function tryRequire(pkg) {
+    try {
+        require(pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectFrameworks() {
+    return {
+        openai: tryRequire('openai'),
+        langchain: tryRequire('@langchain/core'),
+        langgraph: tryRequire('@langchain/langgraph'),
+        bedrock: tryRequire('@aws-sdk/client-bedrock-runtime'),
+        vercel_ai: tryRequire('ai'),
+        anthropic: tryRequire('@anthropic-ai/sdk'),
+        // crewai and autogen are Python-only — no Node.js equivalent
+    };
+}
+// ---------------------------------------------------------------------------
+// patchFramework() — auto-instruments a framework at the constructor level
+// ---------------------------------------------------------------------------
+function patchFramework(framework, client) {
+    try {
+        switch (framework) {
+            case 'openai': {
+                const openaiModule = require('openai');
+                _originalOpenAI = openaiModule.OpenAI;
+                openaiModule.OpenAI = class extends _originalOpenAI {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    constructor(...args) {
+                        super(...args);
+                        try {
+                            client.instrument(this);
+                        }
+                        catch { /* never crash new OpenAI() */ }
+                    }
+                };
+                break;
+            }
+            case 'anthropic': {
+                const anthropicModule = require('@anthropic-ai/sdk');
+                _originalAnthropic = anthropicModule.Anthropic;
+                anthropicModule.Anthropic = class extends _originalAnthropic {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    constructor(...args) {
+                        super(...args);
+                        try {
+                            client.instrument(this);
+                        }
+                        catch { /* never crash new Anthropic() */ }
+                    }
+                };
+                break;
+            }
+            case 'bedrock': {
+                const bedrockModule = require('@aws-sdk/client-bedrock-runtime');
+                _originalBedrockClient = bedrockModule.BedrockRuntimeClient;
+                bedrockModule.BedrockRuntimeClient = class extends _originalBedrockClient {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    constructor(...args) {
+                        super(...args);
+                        try {
+                            client.instrument(this);
+                        }
+                        catch { /* never crash new BedrockRuntimeClient() */ }
+                    }
+                };
+                break;
+            }
+            case 'langgraph': {
+                const lgModule = require('@langchain/langgraph');
+                _originalCompiledStateGraph = lgModule.CompiledStateGraph;
+                // LangGraph instrumentation is applied via LangChainCallback at the class level.
+                // The actual patching happens inside the langgraph integration module.
+                const { patchCompiledStateGraph } = require('./integrations/langgraph');
+                patchCompiledStateGraph(lgModule, client);
+                break;
+            }
+            case 'langchain': {
+                // LangChain is instrumented via RunnableSequence constructor patching.
+                const { patchRunnableSequence } = require('./integrations/langchain');
+                const lcModule = require('@langchain/core/runnables');
+                patchRunnableSequence(lcModule, client);
+                break;
+            }
+            case 'vercel_ai': {
+                const { patchVercelAI } = require('./integrations/vercel-ai');
+                const aiModule = require('ai');
+                _vercelAIRestore = patchVercelAI(aiModule, client);
+                break;
+            }
+        }
+        // Record which frameworks were successfully patched for the startup log.
+        _autoPatchedFrameworks.push(framework);
+    }
+    catch {
+        // Package not installed or patch failed — skip silently.
+    }
+}
+let _autoPatchedFrameworks = [];
+// ---------------------------------------------------------------------------
+// init()
+// ---------------------------------------------------------------------------
+export function init(options) {
+    if (_globalClient !== null) {
+        process.emitWarning('[Visibe] Already initialized — call shutdown() first to re-init', { type: 'VisibleSDKWarning' });
+        return _globalClient;
+    }
+    _globalClient = new Visibe(options ?? {});
+    const detected = detectFrameworks();
+    const toInstrument = options?.frameworks
+        ?? Object.keys(detected).filter(k => detected[k]);
+    for (const fw of toInstrument) {
+        patchFramework(fw, _globalClient);
+    }
+    // Register graceful shutdown handlers.
+    // NOTE: process.on('exit') fires synchronously — async HTTP requests cannot
+    // complete there.  SIGTERM is what Docker/Kubernetes send before killing a
+    // container; without handling it all buffered spans are lost.
+    // We await shutdown() so the batcher's 300 ms window completes before exit.
+    if (!_shutdownRegistered) {
+        const graceful = async () => { await shutdown(); process.exit(0); };
+        process.on('SIGTERM', graceful);
+        process.on('SIGINT', graceful);
+        process.on('beforeExit', () => { shutdown().catch(() => { }); });
+        _shutdownRegistered = true;
+    }
+    if (_autoPatchedFrameworks.length > 0) {
+        console.log(`[Visibe] Auto-instrumented: ${_autoPatchedFrameworks.join(', ')}`);
+    }
+    return _globalClient;
+}
+// ---------------------------------------------------------------------------
+// shutdown()
+// ---------------------------------------------------------------------------
+export async function shutdown() {
+    if (_globalClient === null)
+        return;
+    // Capture the client reference and clear global state immediately so that
+    // re-init() calls work without needing to await this function.
+    const client = _globalClient;
+    _globalClient = null;
+    _autoPatchedFrameworks = [];
+    // Restore patched constructors so the SDK leaves no trace after shutdown.
+    try {
+        if (_originalOpenAI) {
+            require('openai').OpenAI = _originalOpenAI;
+            _originalOpenAI = null;
+        }
+    }
+    catch { /* package may have been unloaded */ }
+    try {
+        if (_originalAnthropic) {
+            require('@anthropic-ai/sdk').Anthropic = _originalAnthropic;
+            _originalAnthropic = null;
+        }
+    }
+    catch { /* package may have been unloaded */ }
+    try {
+        if (_originalBedrockClient) {
+            require('@aws-sdk/client-bedrock-runtime').BedrockRuntimeClient = _originalBedrockClient;
+            _originalBedrockClient = null;
+        }
+    }
+    catch { /* package may have been unloaded */ }
+    try {
+        if (_originalCompiledStateGraph) {
+            require('@langchain/langgraph').CompiledStateGraph = _originalCompiledStateGraph;
+            _originalCompiledStateGraph = null;
+        }
+    }
+    catch { /* package may have been unloaded */ }
+    try {
+        if (_vercelAIRestore) {
+            _vercelAIRestore();
+            _vercelAIRestore = null;
+        }
+    }
+    catch { /* package may have been unloaded */ }
+    // Flush buffered spans and wait up to 300 ms for in-flight HTTP requests to
+    // complete.  This prevents spans from being lost on SIGTERM.
+    await client.batcher.shutdown();
+}
+// ---------------------------------------------------------------------------
+// Re-export public surface
+// ---------------------------------------------------------------------------
+export { Visibe } from './client';