trodo-node 1.2.0 → 2.2.0

package/dist/cjs/otel/wrapAgent.js

@@ -0,0 +1,460 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanHandle = exports.RunHandle = void 0;
+exports.currentRunId = currentRunId;
+exports.currentSpanId = currentSpanId;
+exports.startRun = startRun;
+exports.endRun = endRun;
+exports.wrapAgent = wrapAgent;
+exports.withSpan = withSpan;
+exports.joinRun = joinRun;
+/**
+ * wrapAgent / withSpan / joinRun — user-facing surface for agent tracking.
+ *
+ * Users never generate IDs. The SDK creates run_id on wrapAgent, threads a
+ * span_id through AsyncLocalStorage, and any nested withSpan (or OTel
+ * auto-instrumented span from Anthropic/OpenAI/Vercel AI SDK/LangChain)
+ * inherits the current span as its parent.
+ *
+ * joinRun is for downstream microservices: opens a SPAN (not a run) in the
+ * context of the caller's run_id, flushing each span to the backend via
+ * append_spans. The originating service owns run lifecycle.
+ */
+const uuid_js_1 = require("./uuid.js");
+const context_js_1 = require("./context.js");
+function nowIso() {
+    return new Date().toISOString();
+}
+function truncate(value, max = 64000) {
+    if (value == null)
+        return undefined;
+    const str = typeof value === 'string' ? value : safeJson(value);
+    return str.length > max ? str.slice(0, max) : str;
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** Return the currently active run_id, if any. */
+function currentRunId() {
+    return (0, context_js_1.getActiveContext)()?.runId ?? null;
+}
+/** Return the currently active span_id, if any. */
+function currentSpanId() {
+    return (0, context_js_1.getActiveContext)()?.spanId ?? null;
+}
+function aggregate(spans) {
+    let totalIn = 0;
+    let totalOut = 0;
+    let totalCost = 0;
+    let toolCount = 0;
+    let errorCount = 0;
+    for (const s of spans) {
+        if (s.input_tokens)
+            totalIn += Number(s.input_tokens);
+        if (s.output_tokens)
+            totalOut += Number(s.output_tokens);
+        if (s.cost)
+            totalCost += Number(s.cost);
+        if (s.kind === 'tool')
+            toolCount += 1;
+        if (s.status === 'error')
+            errorCount += 1;
+    }
+    return {
+        total_tokens_in: totalIn,
+        total_tokens_out: totalOut,
+        total_cost: totalCost ? Math.round(totalCost * 1e8) / 1e8 : 0,
+        span_count: spans.length,
+        tool_count: toolCount,
+        error_count: errorCount,
+    };
+}
+/**
+ * RunHandle — returned by wrapAgent so callers can set input/output after
+ * inspecting the arguments / result. Mirrors the Python RunHandle API.
+ */
+class RunHandle {
+    constructor(runId, agentName) {
+        this.metadata = {};
+        this.runId = runId;
+        this.agentName = agentName;
+    }
+    setInput(value) {
+        this.input = truncate(value);
+    }
+    setOutput(value) {
+        this.output = truncate(value);
+    }
+    setMetadata(extra) {
+        Object.assign(this.metadata, extra);
+    }
+}
+exports.RunHandle = RunHandle;
+/**
+ * SpanHandle — returned by withSpan / joinRun. Collect LLM model/token/cost
+ * info and tool name here; the processor picks them up at span close.
+ */
+class SpanHandle {
+    constructor(spanId, name) {
+        this.attributes = {};
+        this.spanId = spanId;
+        this.name = name;
+    }
+    setInput(value) {
+        this.input = truncate(value);
+    }
+    setOutput(value) {
+        this.output = truncate(value);
+    }
+    setAttribute(key, value) {
+        this.attributes[key] = value;
+    }
+    setLlm(opts) {
+        if (opts.model !== undefined)
+            this.model = opts.model;
+        if (opts.provider !== undefined)
+            this.provider = opts.provider;
+        if (opts.inputTokens !== undefined)
+            this.inputTokens = Number(opts.inputTokens);
+        if (opts.outputTokens !== undefined)
+            this.outputTokens = Number(opts.outputTokens);
+        if (opts.cost !== undefined)
+            this.cost = Number(opts.cost);
+        if (opts.temperature !== undefined)
+            this.temperature = Number(opts.temperature);
+    }
+    setTool(name) {
+        this.toolName = name;
+    }
+}
+exports.SpanHandle = SpanHandle;
+/**
+ * Open a Run record without holding a context manager.
+ *
+ * Pairs with {@link endRun} for sessions that span multiple processes or HTTP
+ * requests (e.g. an MCP server where ``initialize`` opens a run and later
+ * ``tools/call`` requests append spans before a final close).
+ *
+ * Returns the runId (caller-supplied or freshly minted). Between startRun and
+ * endRun any process can use ``joinRun(runId, ...)`` to add spans — they flush
+ * incrementally via append_spans.
+ */
+async function startRun(processor, agentName, options = {}) {
+    const runId = options.runId || (0, uuid_js_1.uuidv4)();
+    const run = {
+        run_id: runId,
+        agent_name: agentName,
+        distinct_id: options.distinctId ?? null,
+        conversation_id: options.conversationId ?? null,
+        parent_run_id: options.parentRunId ?? null,
+        status: 'running',
+        input: truncate(options.input),
+        started_at: nowIso(),
+        metadata: options.metadata,
+    };
+    processor.markJoined(runId);
+    await processor.startRun(run);
+    return runId;
+}
+/**
+ * Finalise a Run opened by {@link startRun}.
+ *
+ * Aggregates any locally-buffered spans for `runId`, POSTs to
+ * `/runs/{id}/end`, and unmarks the run as joined.
+ */
+async function endRun(processor, runId, options = {}) {
+    const pending = processor.getPending(runId);
+    const agg = aggregate(pending);
+    const payload = {
+        ended_at: nowIso(),
+        status: options.status ?? 'ok',
+        total_tokens_in: agg.total_tokens_in,
+        total_tokens_out: agg.total_tokens_out,
+        total_cost: agg.total_cost,
+        span_count: agg.span_count,
+        tool_count: agg.tool_count,
+        error_count: agg.error_count,
+    };
+    if (options.output !== undefined) {
+        payload.output = truncate(options.output);
+    }
+    if (options.errorSummary !== undefined) {
+        payload.error_summary = truncate(options.errorSummary, 4000);
+    }
+    if (options.metadata !== undefined) {
+        payload.metadata = options.metadata;
+    }
+    await processor.endRun(runId, payload);
+    processor.unmarkJoined(runId);
+}
+/**
+ * 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.
+ */
+async function wrapAgent(processor, teamSiteId, agentName, fn, options = {}) {
+    const runId = (0, uuid_js_1.uuidv4)();
+    const rootSpanId = (0, uuid_js_1.uuidv4)();
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const handle = new RunHandle(runId, agentName);
+    const ctx = {
+        runId,
+        spanId: rootSpanId,
+        parentSpanId: null,
+        teamSiteId,
+        processor,
+    };
+    let status = 'ok';
+    let output;
+    let errorSummary;
+    let result;
+    try {
+        result = await (0, context_js_1.runWithContextAsync)(ctx, async () => fn(handle));
+        output = handle.output ?? truncate(result);
+    }
+    catch (err) {
+        status = 'error';
+        errorSummary = truncate(err?.message ?? String(err), 4000);
+        const pending = processor.getPending(runId);
+        const agg = aggregate(pending);
+        const run = {
+            run_id: runId,
+            agent_name: agentName,
+            distinct_id: options.distinctId ?? null,
+            conversation_id: options.conversationId ?? null,
+            parent_run_id: options.parentRunId ?? null,
+            status,
+            input: handle.input,
+            started_at: startedAt,
+            ended_at: nowIso(),
+            duration_ms: Date.now() - startedMs,
+            error_summary: errorSummary,
+            metadata: { ...(options.metadata || {}), ...handle.metadata },
+            total_tokens_in: agg.total_tokens_in,
+            total_tokens_out: agg.total_tokens_out,
+            total_cost: agg.total_cost,
+            span_count: agg.span_count,
+            tool_count: agg.tool_count,
+            error_count: agg.error_count,
+        };
+        await processor.ingestRun(run);
+        throw err;
+    }
+    const pending = processor.getPending(runId);
+    const agg = aggregate(pending);
+    const run = {
+        run_id: runId,
+        agent_name: agentName,
+        distinct_id: options.distinctId ?? null,
+        conversation_id: options.conversationId ?? null,
+        parent_run_id: options.parentRunId ?? null,
+        status,
+        input: handle.input,
+        output,
+        started_at: startedAt,
+        ended_at: nowIso(),
+        duration_ms: Date.now() - startedMs,
+        metadata: { ...(options.metadata || {}), ...handle.metadata },
+        total_tokens_in: agg.total_tokens_in,
+        total_tokens_out: agg.total_tokens_out,
+        total_cost: agg.total_cost,
+        span_count: agg.span_count,
+        tool_count: agg.tool_count,
+        error_count: agg.error_count,
+    };
+    await processor.ingestRun(run);
+    return { result, runId };
+}
+/**
+ * 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.
+ */
+async function withSpan(_processor, name, fn, options = {}) {
+    const active = (0, context_js_1.getActiveContext)();
+    const spanId = (0, uuid_js_1.uuidv4)();
+    const handle = new SpanHandle(spanId, name);
+    if (options.input !== undefined)
+        handle.setInput(options.input);
+    if (options.attributes)
+        Object.assign(handle.attributes, options.attributes);
+    if (!active) {
+        // Outside of a run — execute but skip tracking (don't crash user code).
+        return Promise.resolve(fn(handle));
+    }
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const child = {
+        runId: active.runId,
+        spanId,
+        parentSpanId: active.spanId,
+        teamSiteId: active.teamSiteId,
+        processor: active.processor,
+    };
+    let status = 'ok';
+    let errorType;
+    let errorMessage;
+    try {
+        const result = await (0, context_js_1.runWithContextAsync)(child, async () => fn(handle));
+        if (handle.output === undefined)
+            handle.setOutput(result);
+        const span = {
+            span_id: spanId,
+            run_id: active.runId,
+            parent_span_id: active.spanId,
+            kind: options.kind || 'generic',
+            name,
+            status,
+            started_at: startedAt,
+            ended_at: nowIso(),
+            duration_ms: Date.now() - startedMs,
+            input: handle.input,
+            output: handle.output,
+            model: handle.model,
+            provider: handle.provider,
+            input_tokens: handle.inputTokens,
+            output_tokens: handle.outputTokens,
+            cost: handle.cost,
+            temperature: handle.temperature,
+            tool_name: handle.toolName,
+            attributes: Object.keys(handle.attributes).length ? handle.attributes : undefined,
+        };
+        active.processor.enqueueSpan(span);
+        return result;
+    }
+    catch (err) {
+        status = 'error';
+        errorType = err?.name || 'Error';
+        errorMessage = truncate(err?.message ?? String(err), 4000);
+        const span = {
+            span_id: spanId,
+            run_id: active.runId,
+            parent_span_id: active.spanId,
+            kind: options.kind || 'generic',
+            name,
+            status,
+            started_at: startedAt,
+            ended_at: nowIso(),
+            duration_ms: Date.now() - startedMs,
+            input: handle.input,
+            output: handle.output,
+            error_type: errorType,
+            error_message: errorMessage,
+            model: handle.model,
+            provider: handle.provider,
+            input_tokens: handle.inputTokens,
+            output_tokens: handle.outputTokens,
+            cost: handle.cost,
+            temperature: handle.temperature,
+            tool_name: handle.toolName,
+            attributes: Object.keys(handle.attributes).length ? handle.attributes : undefined,
+        };
+        active.processor.enqueueSpan(span);
+        throw err;
+    }
+}
+/**
+ * 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.
+ */
+async function joinRun(processor, teamSiteId, runId, parentSpanId, fn, options = {}) {
+    const spanId = (0, uuid_js_1.uuidv4)();
+    const name = options.name || 'remote.handler';
+    const kind = options.kind || 'agent';
+    const handle = new SpanHandle(spanId, name);
+    if (options.input !== undefined)
+        handle.setInput(options.input);
+    if (options.attributes)
+        Object.assign(handle.attributes, options.attributes);
+    processor.markJoined(runId);
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const ctx = {
+        runId,
+        spanId,
+        parentSpanId: parentSpanId ?? null,
+        teamSiteId,
+        processor,
+    };
+    let status = 'ok';
+    let errorType;
+    let errorMessage;
+    try {
+        const result = await (0, context_js_1.runWithContextAsync)(ctx, async () => fn(handle));
+        if (handle.output === undefined)
+            handle.setOutput(result);
+        const span = {
+            span_id: spanId,
+            run_id: runId,
+            parent_span_id: parentSpanId ?? null,
+            kind,
+            name,
+            status,
+            started_at: startedAt,
+            ended_at: nowIso(),
+            duration_ms: Date.now() - startedMs,
+            input: handle.input,
+            output: handle.output,
+            model: handle.model,
+            provider: handle.provider,
+            input_tokens: handle.inputTokens,
+            output_tokens: handle.outputTokens,
+            cost: handle.cost,
+            temperature: handle.temperature,
+            tool_name: handle.toolName,
+            attributes: Object.keys(handle.attributes).length ? handle.attributes : undefined,
+        };
+        await processor.appendSpans(runId, [span]);
+        return result;
+    }
+    catch (err) {
+        status = 'error';
+        errorType = err?.name || 'Error';
+        errorMessage = truncate(err?.message ?? String(err), 4000);
+        const span = {
+            span_id: spanId,
+            run_id: runId,
+            parent_span_id: parentSpanId ?? null,
+            kind,
+            name,
+            status,
+            started_at: startedAt,
+            ended_at: nowIso(),
+            duration_ms: Date.now() - startedMs,
+            input: handle.input,
+            output: handle.output,
+            error_type: errorType,
+            error_message: errorMessage,
+            model: handle.model,
+            provider: handle.provider,
+            input_tokens: handle.inputTokens,
+            output_tokens: handle.outputTokens,
+            cost: handle.cost,
+            temperature: handle.temperature,
+            tool_name: handle.toolName,
+            attributes: Object.keys(handle.attributes).length ? handle.attributes : undefined,
+        };
+        await processor.appendSpans(runId, [span]);
+        throw err;
+    }
+    finally {
+        processor.unmarkJoined(runId);
+    }
+}
+//# sourceMappingURL=wrapAgent.js.map

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

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

package/dist/esm/TrodoClient.d.ts

@@ -1,5 +1,7 @@
-import type { TrodoConfig, ForUserOptions, TrackOptions, WalletAddressResult, ResetResult, ApiResult, GroupProfile, AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps } from './types/index.js';
+import type { TrodoConfig, ForUserOptions, TrackOptions, WalletAddressResult, ResetResult, ApiResult, GroupProfile, FeedbackProps } from './types/index.js';
 import { UserContext } from './UserContext.js';
+import { type WrapAgentOptions, type WrapAgentResult, type WithSpanOptions, type JoinRunOptions, type StartRunOptions, type EndRunOptions, type RunHandle, type SpanHandle } from './otel/wrapAgent.js';
+import { expressMiddleware as expressMiddlewareImpl, type ToolOptions, type TrackLlmCallParams } from './otel/helpers.js';
 export declare class TrodoClient {
     readonly siteId: string;
     private readonly apiBase;
@@ -9,6 +11,7 @@ export declare class TrodoClient {
     private readonly batchFlusher;
     private readonly autoEventManager;
     private readonly userContextCache;
+    private readonly spanProcessor;
     readonly people: {
         set(distinctId: string, properties: Record<string, unknown>): Promise<ApiResult>;
         setOnce(distinctId: string, properties: Record<string, unknown>): Promise<ApiResult>;
@@ -35,15 +38,45 @@ export declare class TrodoClient {
     disableAutoEvents(): void;
     flush(): Promise<void>;
     shutdown(): Promise<void>;
-    /** Track an LLM invocation / inbound message. */
-    track_agent_call(props: AgentCallProps): Promise<void>;
-    /** Track a tool invocation within an agent turn. */
-    track_tool_use(props: ToolUseProps): Promise<void>;
-    /** Track an LLM response / completion. */
-    track_agent_response(props: AgentResponseProps): Promise<void>;
-    /** Track an error during an agent turn. */
-    track_agent_error(props: AgentErrorProps): Promise<void>;
-    /** Track a user feedback reaction (thumbs up/down) on an agent response. */
-    track_feedback(props: FeedbackProps): Promise<void>;
+    /**
+     * Wrap an async function as an agent run. Callback receives a RunHandle
+     * — call `handle.setInput(...)` / `handle.setOutput(...)` to populate the
+     * run's input/output fields. Every OTel-auto-instrumented LLM call or
+     * nested `withSpan` inside `fn` is captured as a child span.
+     * Returns { result, runId } — runId is used to attach feedback later.
+     */
+    wrapAgent<R>(agentName: string, fn: (handle: RunHandle) => Promise<R> | R, options?: WrapAgentOptions): Promise<WrapAgentResult<R>>;
+    /** Create a nested span inside the current run. */
+    withSpan<R>(name: string, fn: (handle: SpanHandle) => Promise<R> | R, options?: WithSpanOptions): Promise<R>;
+    /**
+     * Join an existing run owned by a remote service — opens a span (not a new
+     * run) in that run's context. Spans inside `fn` are streamed to the backend
+     * via append_spans. Used by the express middleware and for manual cross-
+     * service join on any request shape.
+     */
+    joinRun<R>(runId: string, parentSpanId: string | null, fn: (handle: SpanHandle) => Promise<R> | R, options?: JoinRunOptions): Promise<R>;
+    /**
+     * Open a Run record without holding a context manager. Returns the runId.
+     *
+     * Pairs with {@link endRun} for sessions that span multiple processes or
+     * HTTP requests (e.g. an MCP server). Between startRun and endRun any
+     * process can use ``joinRun(runId, ...)`` to add spans.
+     */
+    startRun(agentName: string, options?: StartRunOptions): Promise<string>;
+    /** Finalise a Run opened by {@link startRun}. */
+    endRun(runId: string, options?: EndRunOptions): Promise<void>;
+    /** Higher-order wrapper: decorate a tool-like function so each call becomes a span. */
+    tool<Args extends unknown[], R>(fn: (...args: Args) => Promise<R> | R, options?: ToolOptions): (...args: Args) => Promise<R>;
+    /** Record a one-shot LLM span for a raw-HTTP caller. */
+    trackLlmCall(params: TrackLlmCallParams): Promise<void>;
+    /** Return an Express/Connect middleware that auto-joins inbound runs. */
+    expressMiddleware(): ReturnType<typeof expressMiddlewareImpl>;
+    /** Outbound HTTP headers carrying the current run/span context. */
+    propagationHeaders(): Record<string, string>;
+    /** Expose current run/span ids for bespoke propagation needs. */
+    currentRunId(): string | null;
+    currentSpanId(): string | null;
+    /** Attach feedback to a completed run. Call with the runId returned from wrapAgent. */
+    feedback(runId: string, props: Omit<FeedbackProps, 'runId'>): Promise<ApiResult>;
 }
 //# sourceMappingURL=TrodoClient.d.ts.map

package/dist/esm/TrodoClient.d.ts.map

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