trodo-node 1.1.0 → 2.1.0

package/dist/cjs/otel/helpers.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+exports.trace = trace;
+exports.retrieval = retrieval;
+exports.llm = llm;
+exports.getTracer = getTracer;
+exports.trackLlmCall = trackLlmCall;
+exports.expressMiddleware = expressMiddleware;
+exports.propagationHeaders = propagationHeaders;
+/**
+ * Span helpers: `trace`, `tool`, `llm`, `retrieval` — typed function
+ * wrappers that auto-capture input/output/error. Plus `trackLlmCall` and
+ * Express middleware for cross-service run joining.
+ *
+ * These are the customer-facing surface for custom code: wrap once, get a
+ * span with args as input, return value as output, exception as error.
+ */
+const context_js_1 = require("./context.js");
+const wrapAgent_js_1 = require("./wrapAgent.js");
+function _input(args) {
+    if (args.length === 0)
+        return undefined;
+    if (args.length === 1)
+        return args[0];
+    return args;
+}
+function _wrap(name, fn, kind, options = {}, hooks) {
+    return async (...args) => {
+        return (0, wrapAgent_js_1.withSpan)(undefined, name, async (span) => {
+            if (kind === 'tool')
+                span.setTool(name);
+            hooks?.onEnter?.(span);
+            const result = await fn(...args);
+            try {
+                hooks?.onResult?.(span, result);
+            }
+            catch {
+                /* never break user code */
+            }
+            span.setOutput(result);
+            return result;
+        }, { kind, input: _input(args), ...options });
+    };
+}
+function tool(a, b) {
+    // name-first form: tool(name, fn)
+    if (typeof a === 'string' && typeof b === 'function') {
+        return _wrap(a, b, 'tool');
+    }
+    // fn-first form: tool(fn, options?)
+    const fn = a;
+    const options = (b || {});
+    const toolName = options.name || fn.name || 'anonymous-tool';
+    const kind = (options.kind || 'tool');
+    return _wrap(toolName, fn, kind);
+}
+/**
+ * Wrap a function as a generic span. Mirrors the uselemma `trace()` helper.
+ *
+ *   const prepare = trodo.trace('prepare', async (input) => { ... });
+ */
+function trace(name, fn, options = {}) {
+    return _wrap(name, fn, 'generic', options);
+}
+/** Wrap a retriever / vector search as a kind='retrieval' span. */
+function retrieval(name, fn, options = {}) {
+    return _wrap(name, fn, 'retrieval', options);
+}
+function _defaultExtractUsage(result) {
+    if (!result || typeof result !== 'object')
+        return {};
+    const r = result;
+    // OpenAI / OpenAI-compat: { usage: { prompt_tokens, completion_tokens } }
+    const usage = r.usage;
+    if (usage) {
+        if ('prompt_tokens' in usage || 'completion_tokens' in usage) {
+            return {
+                inputTokens: usage.prompt_tokens,
+                outputTokens: usage.completion_tokens,
+            };
+        }
+        // Anthropic: { usage: { input_tokens, output_tokens } }
+        if ('input_tokens' in usage || 'output_tokens' in usage) {
+            return {
+                inputTokens: usage.input_tokens,
+                outputTokens: usage.output_tokens,
+            };
+        }
+    }
+    // Gemini: { usageMetadata: { promptTokenCount, candidatesTokenCount } }
+    const meta = r.usageMetadata;
+    if (meta) {
+        return {
+            inputTokens: meta.promptTokenCount,
+            outputTokens: meta.candidatesTokenCount,
+        };
+    }
+    return {};
+}
+/**
+ * Wrap an LLM call — auto-extracts tokens from OpenAI/Anthropic/Gemini
+ * response shapes.
+ *
+ *   const answer = trodo.llm('answer', callOpenAI, {
+ *     model: 'gpt-4o-mini', provider: 'openai',
+ *   });
+ */
+function llm(name, fn, options = {}) {
+    const { model, provider, temperature, extractUsage, ...rest } = options;
+    const extractor = extractUsage || _defaultExtractUsage;
+    return _wrap(name, fn, 'llm', rest, {
+        onEnter: (s) => {
+            if (model || provider || temperature !== undefined) {
+                s.setLlm({ model, provider, temperature });
+            }
+        },
+        onResult: (s, result) => {
+            const { inputTokens, outputTokens } = extractor(result);
+            if (inputTokens !== undefined || outputTokens !== undefined) {
+                s.setLlm({
+                    model,
+                    provider,
+                    inputTokens,
+                    outputTokens,
+                    temperature,
+                });
+            }
+        },
+    });
+}
+/**
+ * Return a raw OTel tracer — the Trodo processor is already subscribed.
+ * Use for advanced cases where you want to emit spans with the raw OTel
+ * API; they flow through to Trodo like any other span.
+ */
+function getTracer(name = 'trodo') {
+    // Lazy import keeps @opentelemetry/api optional at runtime until used.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const api = require('@opentelemetry/api');
+    return api.trace.getTracer(name);
+}
+/**
+ * Record a one-shot LLM span for a raw-HTTP caller. Opens and immediately
+ * closes a span(kind='llm') populated with the model + token counts +
+ * prompt/completion. No-op outside an active run context.
+ *
+ * Usage:
+ *   const resp = await fetch(url, { body: JSON.stringify(body) }).then(r => r.json());
+ *   await trodo.trackLlmCall({
+ *     model: 'gemini-2.5-flash',
+ *     provider: 'google',
+ *     inputTokens: resp.usageMetadata.promptTokenCount,
+ *     outputTokens: resp.usageMetadata.candidatesTokenCount,
+ *     prompt: body,
+ *     completion: resp,
+ *   });
+ */
+async function trackLlmCall(params) {
+    if (!(0, context_js_1.getActiveContext)())
+        return;
+    const spanName = params.name || (params.model ? `llm.${params.provider}.${params.model}` : 'llm');
+    await (0, wrapAgent_js_1.withSpan)(undefined, spanName, async (span) => {
+        span.setLlm({
+            model: params.model,
+            provider: params.provider,
+            inputTokens: params.inputTokens,
+            outputTokens: params.outputTokens,
+            cost: params.cost,
+            temperature: params.temperature,
+        });
+        if (params.completion !== undefined) {
+            span.setOutput(params.completion);
+        }
+    }, {
+        kind: 'llm',
+        input: params.prompt,
+        attributes: params.metadata,
+    });
+}
+// ---------------------------------------------------------------------------
+// Express / Connect middleware for automatic cross-service run joining
+// ---------------------------------------------------------------------------
+const TRODO_RUN_HEADER = 'x-trodo-run-id';
+const TRODO_PARENT_SPAN_HEADER = 'x-trodo-parent-span-id';
+const TRODO_AGENT_HEADER = 'x-trodo-agent-name';
+/**
+ * Return an Express/Connect middleware that auto-joins inbound runs.
+ *
+ * If the inbound request has X-Trodo-Run-Id, every span created while
+ * handling the request nests under the caller's run. Otherwise the
+ * handler runs with no active context (no-op tracking).
+ *
+ * Usage:
+ *   import express from 'express';
+ *   import trodo from 'trodo-node';
+ *   trodo.init({ siteId: '...' });
+ *   const app = express();
+ *   app.use(trodo.expressMiddleware());
+ */
+function expressMiddleware(deps) {
+    const { processor, teamSiteId } = deps;
+    return (req, res, next) => {
+        const headers = req.headers || {};
+        const getHeader = (name) => {
+            const raw = headers[name] ?? headers[name.toLowerCase()];
+            if (!raw)
+                return undefined;
+            return Array.isArray(raw) ? raw[0] : raw;
+        };
+        const runId = getHeader(TRODO_RUN_HEADER);
+        if (!runId) {
+            next();
+            return;
+        }
+        const parentSpanId = getHeader(TRODO_PARENT_SPAN_HEADER) || null;
+        const agentHeader = getHeader(TRODO_AGENT_HEADER);
+        const name = agentHeader ||
+            `http.${(req.method || 'GET').toUpperCase()}.${req.path || req.url || ''}`;
+        const input = {
+            method: req.method,
+            path: req.path || req.url || req.originalUrl,
+        };
+        (0, wrapAgent_js_1.joinRun)(processor, teamSiteId, runId, parentSpanId, async (span) => {
+            await new Promise((resolve) => {
+                if (res.on) {
+                    res.on('finish', () => {
+                        span.setOutput({ status_code: res.statusCode });
+                        resolve();
+                    });
+                    res.on('close', () => resolve());
+                }
+                next();
+            });
+        }, { name, kind: 'agent', input }).catch(() => {
+            /* swallow — SDK never throws into user code */
+        });
+    };
+}
+/**
+ * Return HTTP headers carrying the current run/span context. Use when
+ * making outbound HTTP calls to downstream services so they can joinRun
+ * instead of creating their own runs.
+ */
+function propagationHeaders() {
+    const ctx = (0, context_js_1.getActiveContext)();
+    if (!ctx)
+        return {};
+    const headers = { 'X-Trodo-Run-Id': ctx.runId };
+    if (ctx.spanId)
+        headers['X-Trodo-Parent-Span-Id'] = ctx.spanId;
+    return headers;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cjs/otel/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/otel/helpers.ts"],"names":[],"mappings":"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"}

package/dist/cjs/otel/processor.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrodoSpanProcessor = void 0;
+class TrodoSpanProcessor {
+    constructor(opts) {
+        this.queue = [];
+        this.pendingByRun = new Map();
+        this.joinedRuns = new Set();
+        this.timer = null;
+        this.stopped = false;
+        this.apiClient = opts.apiClient;
+        this.maxBatchSize = opts.maxBatchSize ?? 64;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
+        this.maxSpansPerRun = opts.maxSpansPerRun ?? 1000;
+        this.startTimer();
+    }
+    startTimer() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => {
+            this.flushSpans().catch(() => { });
+        }, this.flushIntervalMs);
+        // Don't block Node from exiting because of our timer.
+        if (this.timer && typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+    /** Mark a run as joined — its spans flush immediately via append_spans. */
+    markJoined(runId) {
+        this.joinedRuns.add(runId);
+    }
+    unmarkJoined(runId) {
+        this.joinedRuns.delete(runId);
+        this.pendingByRun.delete(runId);
+    }
+    /** Read (without removing) the buffered spans for a run — used for run aggregation. */
+    getPending(runId) {
+        return (this.pendingByRun.get(runId) || []).slice();
+    }
+    /** Buffer a span for async flush. Called by wrapAgent/withSpan + OTel onEnd. */
+    enqueueSpan(span) {
+        if (this.joinedRuns.has(span.run_id)) {
+            // Owning service is remote — forward each span immediately.
+            this.apiClient
+                .postSpansAppend(span.run_id, [span])
+                .catch(() => { });
+            return;
+        }
+        this.queue.push(span);
+        const runBuf = this.pendingByRun.get(span.run_id) || [];
+        if (runBuf.length < this.maxSpansPerRun) {
+            runBuf.push(span);
+            this.pendingByRun.set(span.run_id, runBuf);
+        }
+        if (this.queue.length >= this.maxBatchSize) {
+            this.flushSpans().catch(() => { });
+        }
+    }
+    /** Stream spans for a long-running or joined run without finalising. */
+    async appendSpans(runId, spans) {
+        if (!spans.length)
+            return;
+        try {
+            await this.apiClient.postSpansAppend(runId, spans);
+        }
+        catch {
+            /* silent */
+        }
+    }
+    /** Fire-and-forget run+spans ingest, used when wrapAgent finalises. */
+    async ingestRun(run) {
+        const spans = this.pendingByRun.get(run.run_id) || [];
+        this.pendingByRun.delete(run.run_id);
+        this.queue = this.queue.filter((s) => s.run_id !== run.run_id);
+        try {
+            await this.apiClient.postRunIngest({
+                run: run,
+                spans: spans,
+            });
+        }
+        catch {
+            /* silent — SDK must never throw into user code */
+        }
+    }
+    async flushSpans() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0, this.maxBatchSize);
+        // Group pending-only spans by run_id and POST to /runs/:run_id/spans.
+        const byRun = new Map();
+        for (const span of batch) {
+            const arr = byRun.get(span.run_id) || [];
+            arr.push(span);
+            byRun.set(span.run_id, arr);
+        }
+        const tasks = [];
+        for (const [runId, spans] of byRun.entries()) {
+            tasks.push(this.apiClient
+                .postSpansAppend(runId, spans)
+                .catch(() => {
+                // Re-queue for next tick on failure.
+                this.queue.push(...spans);
+            }));
+        }
+        await Promise.all(tasks);
+    }
+    async forceFlush() {
+        await this.flushSpans();
+    }
+    async shutdown() {
+        this.stopped = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.forceFlush();
+    }
+    // ---------- OpenTelemetry SpanProcessor interface (subset) ----------
+    // Implemented so this can be registered with OTel SDK's addSpanProcessor().
+    // A thin adapter is in autoInstrument.ts.
+    onStart() {
+        /* noop — Trodo flushes on span end */
+    }
+    onEnd(span) {
+        this.enqueueSpan(span);
+    }
+}
+exports.TrodoSpanProcessor = TrodoSpanProcessor;
+//# sourceMappingURL=processor.js.map

package/dist/cjs/otel/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["../../../src/otel/processor.ts"],"names":[],"mappings":"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"}

package/dist/cjs/otel/uuid.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidv4 = uuidv4;
+/**
+ * RFC4122 v4 UUIDs — used for run_id, span_id, parent_span_id.
+ * Uses the runtime's crypto.randomUUID when available, falls back to a
+ * Math.random-based generator so we don't pull in a dependency for tests.
+ */
+function uuidv4() {
+    try {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID();
+    }
+    catch {
+        /* fall through */
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
+        const r = (Math.random() * 16) | 0;
+        const v = ch === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+//# sourceMappingURL=uuid.js.map

package/dist/cjs/otel/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../../src/otel/uuid.ts"],"names":[],"mappings":";;AAKA,wBAYC;AAjBD;;;;GAIG;AACH,SAAgB,MAAM;IACpB,IAAI,CAAC;QACH,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;QAC5E,IAAI,CAAC,EAAE,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE;QACpE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC3C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC"}