trodo-node 1.1.0 → 2.1.0

package/dist/esm/otel/helpers.js

@@ -0,0 +1,244 @@
+/**
+ * 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.
+ */
+import { getActiveContext } from './context.js';
+import { joinRun, withSpan, } from './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 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 });
+    };
+}
+export 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) => { ... });
+ */
+export function trace(name, fn, options = {}) {
+    return _wrap(name, fn, 'generic', options);
+}
+/** Wrap a retriever / vector search as a kind='retrieval' span. */
+export 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',
+ *   });
+ */
+export 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.
+ */
+export 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,
+ *   });
+ */
+export async function trackLlmCall(params) {
+    if (!getActiveContext())
+        return;
+    const spanName = params.name || (params.model ? `llm.${params.provider}.${params.model}` : 'llm');
+    await 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());
+ */
+export 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,
+        };
+        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.
+ */
+export function propagationHeaders() {
+    const ctx = 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/esm/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/esm/otel/processor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TrodoSpanProcessor — buffers completed spans and ships them to the Trodo
+ * backend in batches.
+ *
+ * Shape is compatible with OpenTelemetry's SpanProcessor (onStart / onEnd /
+ * shutdown / forceFlush) so users can register it with the OTel NodeSDK and
+ * have auto-instrumented spans (Anthropic/OpenAI/Vercel AI SDK/LangChain)
+ * flow through it into Trodo.
+ *
+ * Without a real OTel SDK, our wrapAgent/withSpan helpers call onStart/onEnd
+ * directly — so the processor handles both paths uniformly.
+ */
+import type { ApiClient } from '../api/ApiClient.js';
+export interface TrodoSpan {
+    span_id: string;
+    run_id: string;
+    parent_span_id: string | null;
+    kind: 'llm' | 'tool' | 'agent' | 'retrieval' | 'generic';
+    name: string;
+    status: 'ok' | 'error';
+    started_at: string;
+    ended_at?: string;
+    duration_ms?: number;
+    input?: string;
+    output?: string;
+    error_type?: string;
+    error_message?: string;
+    model?: string;
+    provider?: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    cost?: number;
+    temperature?: number;
+    tool_name?: string;
+    attributes?: Record<string, unknown>;
+}
+export interface TrodoRun {
+    run_id: string;
+    agent_name: string;
+    distinct_id?: string | null;
+    conversation_id?: string | null;
+    parent_run_id?: string | null;
+    status: 'running' | 'ok' | 'error';
+    input?: string;
+    output?: string;
+    error_summary?: string;
+    started_at: string;
+    ended_at?: string;
+    duration_ms?: number;
+    metadata?: Record<string, unknown>;
+    attributes?: Record<string, unknown>;
+    total_tokens_in?: number;
+    total_tokens_out?: number;
+    total_cost?: number;
+    span_count?: number;
+    tool_count?: number;
+    error_count?: number;
+}
+export interface ProcessorOptions {
+    apiClient: ApiClient;
+    maxBatchSize?: number;
+    flushIntervalMs?: number;
+    maxSpansPerRun?: number;
+}
+export declare class TrodoSpanProcessor {
+    private readonly apiClient;
+    private readonly maxBatchSize;
+    private readonly flushIntervalMs;
+    private readonly maxSpansPerRun;
+    private queue;
+    private pendingByRun;
+    private joinedRuns;
+    private timer;
+    private stopped;
+    constructor(opts: ProcessorOptions);
+    private startTimer;
+    /** Mark a run as joined — its spans flush immediately via append_spans. */
+    markJoined(runId: string): void;
+    unmarkJoined(runId: string): void;
+    /** Read (without removing) the buffered spans for a run — used for run aggregation. */
+    getPending(runId: string): TrodoSpan[];
+    /** Buffer a span for async flush. Called by wrapAgent/withSpan + OTel onEnd. */
+    enqueueSpan(span: TrodoSpan): void;
+    /** Stream spans for a long-running or joined run without finalising. */
+    appendSpans(runId: string, spans: TrodoSpan[]): Promise<void>;
+    /** Fire-and-forget run+spans ingest, used when wrapAgent finalises. */
+    ingestRun(run: TrodoRun): Promise<void>;
+    private flushSpans;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    onStart(): void;
+    onEnd(span: TrodoSpan): void;
+}
+//# sourceMappingURL=processor.d.ts.map

package/dist/esm/otel/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../../src/otel/processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAErC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,gBAAgB;IAQlC,OAAO,CAAC,UAAU;IAWlB,2EAA2E;IAC3E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI/B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKjC,uFAAuF;IACvF,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE;IAItC,gFAAgF;IAChF,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAmBlC,wEAAwE;IAClE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnE,uEAAuE;IACjE,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;YAc/B,UAAU;IAwBlB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAa/B,OAAO,IAAI,IAAI;IAIf,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;CAG7B"}

package/dist/esm/otel/processor.js

@@ -0,0 +1,125 @@
+export 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);
+    }
+}
+//# sourceMappingURL=processor.js.map

package/dist/esm/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/esm/otel/uuid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function uuidv4(): string;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/esm/otel/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../../src/otel/uuid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAY/B"}

package/dist/esm/otel/uuid.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export 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/esm/otel/uuid.js.map

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

package/dist/esm/otel/wrapAgent.d.ts

@@ -0,0 +1,100 @@
+import type { TrodoSpanProcessor, TrodoSpan } from './processor.js';
+export interface WrapAgentOptions {
+    distinctId?: string | null;
+    conversationId?: string | null;
+    parentRunId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface WrapAgentResult<R> {
+    result: R;
+    runId: string;
+}
+export interface WithSpanOptions {
+    kind?: TrodoSpan['kind'];
+    input?: unknown;
+    attributes?: Record<string, unknown>;
+}
+export interface JoinRunOptions {
+    name?: string;
+    kind?: TrodoSpan['kind'];
+    input?: unknown;
+    attributes?: Record<string, unknown>;
+}
+/** Return the currently active run_id, if any. */
+export declare function currentRunId(): string | null;
+/** Return the currently active span_id, if any. */
+export declare function currentSpanId(): string | null;
+/**
+ * RunHandle — returned by wrapAgent so callers can set input/output after
+ * inspecting the arguments / result. Mirrors the Python RunHandle API.
+ */
+export declare class RunHandle {
+    readonly runId: string;
+    readonly agentName: string;
+    input?: string;
+    output?: string;
+    metadata: Record<string, unknown>;
+    constructor(runId: string, agentName: string);
+    setInput(value: unknown): void;
+    setOutput(value: unknown): void;
+    setMetadata(extra: Record<string, unknown>): void;
+}
+/**
+ * SpanHandle — returned by withSpan / joinRun. Collect LLM model/token/cost
+ * info and tool name here; the processor picks them up at span close.
+ */
+export declare class SpanHandle {
+    readonly spanId: string;
+    readonly name: string;
+    input?: string;
+    output?: string;
+    attributes: Record<string, unknown>;
+    model?: string;
+    provider?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cost?: number;
+    temperature?: number;
+    toolName?: string;
+    constructor(spanId: string, name: string);
+    setInput(value: unknown): void;
+    setOutput(value: unknown): void;
+    setAttribute(key: string, value: unknown): void;
+    setLlm(opts: {
+        model?: string;
+        provider?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        cost?: number;
+        temperature?: number;
+    }): void;
+    setTool(name: string): void;
+}
+/**
+ * Wrap an async function as an agent run. Every OTel span (or withSpan call)
+ * created inside `fn` is auto-nested under the run via AsyncLocalStorage.
+ *
+ * The callback receives a RunHandle so it can call `handle.setInput(...)` /
+ * `handle.setOutput(...)`. Old-style callbacks (no arg) still work.
+ */
+export declare function wrapAgent<R>(processor: TrodoSpanProcessor, teamSiteId: string, agentName: string, fn: (handle: RunHandle) => Promise<R> | R, options?: WrapAgentOptions): Promise<WrapAgentResult<R>>;
+/**
+ * Create a nested span for non-auto-instrumented work (KB lookups, custom
+ * tools, computation). Requires an enclosing wrapAgent/joinRun.
+ *
+ * The callback receives a SpanHandle so the caller can record LLM tokens /
+ * tool name / output inside the function body.
+ */
+export declare function withSpan<R>(_processor: TrodoSpanProcessor, name: string, fn: (handle: SpanHandle) => Promise<R> | R, options?: WithSpanOptions): Promise<R>;
+/**
+ * Join an existing agent run owned by a remote service. Opens a SPAN (not a
+ * run) under ``parentSpanId``; every span produced inside ``fn`` — including
+ * OTel auto-instrumented LLM spans — flushes to the backend as a child of
+ * the caller's run via append_spans. We never ingest a run here.
+ *
+ * Typical use: Express/FastAPI middleware detects ``X-Trodo-Run-Id`` +
+ * ``X-Trodo-Parent-Span-Id`` on an inbound request and wraps the handler
+ * with joinRun so the handler's work nests under the caller's run.
+ */
+export declare function joinRun<R>(processor: TrodoSpanProcessor, teamSiteId: string, runId: string, parentSpanId: string | null, fn: (handle: SpanHandle) => Promise<R> | R, options?: JoinRunOptions): Promise<R>;
+//# sourceMappingURL=wrapAgent.d.ts.map

package/dist/esm/otel/wrapAgent.d.ts.map

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