trodo-node 1.1.0 → 2.1.0

package/dist/cjs/otel/wrapAgent.js

@@ -0,0 +1,399 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanHandle = exports.RunHandle = void 0;
+exports.currentRunId = currentRunId;
+exports.currentSpanId = currentSpanId;
+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;
+/**
+ * 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/cjs/queue/BatchFlusher.js

@@ -28,7 +28,7 @@ class BatchFlusher {
         const events = this.queue.drain();
         if (events.length === 0)
             return;
-        await this.apiClient.postBulkEvents(events);
+        await Promise.all(events.map((e) => this.apiClient.postEvent(e)));
     }
 }
 exports.BatchFlusher = BatchFlusher;

package/dist/cjs/queue/BatchFlusher.js.map

@@ -1 +1 @@
-{"version":3,"file":"BatchFlusher.js","sourceRoot":"","sources":["../../../src/queue/BatchFlusher.ts"],"names":[],"mappings":";;;AAGA,MAAa,YAAY;IAGvB,YACmB,KAAiB,EACjB,SAAoB,EACpB,eAAuB;QAFvB,UAAK,GAAL,KAAK,CAAY;QACjB,cAAS,GAAT,SAAS,CAAW;QACpB,oBAAe,GAAf,eAAe,CAAQ;QALlC,UAAK,GAA0C,IAAI,CAAC;IAMzD,CAAC;IAEJ,KAAK;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACzB,gEAAgE;QAChE,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;CACF;AA9BD,oCA8BC"}
+{"version":3,"file":"BatchFlusher.js","sourceRoot":"","sources":["../../../src/queue/BatchFlusher.ts"],"names":[],"mappings":";;;AAGA,MAAa,YAAY;IAGvB,YACmB,KAAiB,EACjB,SAAoB,EACpB,eAAuB;QAFvB,UAAK,GAAL,KAAK,CAAY;QACjB,cAAS,GAAT,SAAS,CAAW;QACpB,oBAAe,GAAf,eAAe,CAAQ;QALlC,UAAK,GAA0C,IAAI,CAAC;IAMzD,CAAC;IAEJ,KAAK;QACH,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACzB,gEAAgE;QAChE,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;CACF;AA9BD,oCA8BC"}

package/dist/esm/TrodoClient.d.ts

@@ -1,5 +1,7 @@
-import type { TrodoConfig, ForUserOptions, TrackOptions, WalletAddressResult, ResetResult, ApiResult, GroupProfile } 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 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,5 +38,35 @@ export declare class TrodoClient {
     disableAutoEvents(): void;
     flush(): Promise<void>;
     shutdown(): 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>;
+    /** 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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"}

package/dist/esm/TrodoClient.js

@@ -4,6 +4,10 @@ import { EventQueue } from './queue/EventQueue.js';
 import { BatchFlusher } from './queue/BatchFlusher.js';
 import { AutoEventManager } from './auto/AutoEventManager.js';
 import { UserContext } from './UserContext.js';
+import { TrodoSpanProcessor } from './otel/processor.js';
+import { wrapAgent as wrapAgentImpl, withSpan as withSpanImpl, joinRun as joinRunImpl, currentRunId, currentSpanId, } from './otel/wrapAgent.js';
+import { tool as toolImpl, trackLlmCall as trackLlmCallImpl, propagationHeaders, expressMiddleware as expressMiddlewareImpl, } from './otel/helpers.js';
+import { enableAutoInstrument } from './otel/autoInstrument.js';
 const DEFAULT_API_BASE = 'https://sdkapi.trodo.ai';
 export class TrodoClient {
     constructor(config) {
@@ -27,7 +31,11 @@ export class TrodoClient {
         if (config.autoEvents) {
             this.autoEventManager.enable();
         }
-        // Wire up direct-call-pattern people helpers
+        this.spanProcessor = new TrodoSpanProcessor({ apiClient: this.apiClient });
+        // Default ON — matches Python SDK. Opt out with autoInstrument: false.
+        if (config.autoInstrument !== false) {
+            enableAutoInstrument({ processor: this.spanProcessor });
+        }
         const client = this;
         this.people = {
             set: (d, p) => client.forUser(d).people.set(p),
@@ -46,17 +54,13 @@ export class TrodoClient {
     // Primary pattern: forUser()
     // --------------------------------------------------------------------------
     forUser(distinctId, options) {
-        const key = distinctId;
-        const cached = this.userContextCache.get(key);
+        const cached = this.userContextCache.get(distinctId);
         if (cached)
             return cached;
         const ctx = new UserContext(distinctId, this.siteId, this.apiClient, this.sessionManager, this.eventQueue, this.batchFlusher, this.autoEventManager, options);
-        this.userContextCache.set(key, ctx);
+        this.userContextCache.set(distinctId, ctx);
         return ctx;
     }
-    // --------------------------------------------------------------------------
-    // Direct-call pattern (distinctId as first param)
-    // --------------------------------------------------------------------------
     async track(distinctId, eventName, properties, options) {
         return this.forUser(distinctId).track(eventName, properties, options);
     }
@@ -87,21 +91,12 @@ export class TrodoClient {
     get_group(distinctId, groupKey, groupId) {
         return this.forUser(distinctId).get_group(groupKey, groupId);
     }
-    // --------------------------------------------------------------------------
-    // Auto events
-    // --------------------------------------------------------------------------
-    enableAutoEvents() {
-        this.autoEventManager.enable();
-    }
-    disableAutoEvents() {
-        this.autoEventManager.disable();
-    }
-    // --------------------------------------------------------------------------
-    // Lifecycle
-    // --------------------------------------------------------------------------
+    enableAutoEvents() { this.autoEventManager.enable(); }
+    disableAutoEvents() { this.autoEventManager.disable(); }
     async flush() {
         if (this.batchFlusher)
             await this.batchFlusher.flush();
+        await this.spanProcessor.forceFlush();
     }
     async shutdown() {
         this.autoEventManager.disable();
@@ -109,6 +104,69 @@ export class TrodoClient {
             this.batchFlusher.stop();
             await this.batchFlusher.flush();
         }
+        await this.spanProcessor.shutdown();
+    }
+    // --------------------------------------------------------------------------
+    // Agent Runs — unified surface
+    // --------------------------------------------------------------------------
+    /**
+     * 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(agentName, fn, options = {}) {
+        return wrapAgentImpl(this.spanProcessor, this.siteId, agentName, fn, options);
+    }
+    /** Create a nested span inside the current run. */
+    withSpan(name, fn, options = {}) {
+        return withSpanImpl(this.spanProcessor, name, fn, options);
+    }
+    /**
+     * 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(runId, parentSpanId, fn, options = {}) {
+        return joinRunImpl(this.spanProcessor, this.siteId, runId, parentSpanId, fn, options);
+    }
+    /** Higher-order wrapper: decorate a tool-like function so each call becomes a span. */
+    tool(fn, options = {}) {
+        return toolImpl(fn, options);
+    }
+    /** Record a one-shot LLM span for a raw-HTTP caller. */
+    trackLlmCall(params) {
+        return trackLlmCallImpl(params);
+    }
+    /** Return an Express/Connect middleware that auto-joins inbound runs. */
+    expressMiddleware() {
+        return expressMiddlewareImpl({
+            processor: this.spanProcessor,
+            teamSiteId: this.siteId,
+        });
+    }
+    /** Outbound HTTP headers carrying the current run/span context. */
+    propagationHeaders() {
+        return propagationHeaders();
+    }
+    /** Expose current run/span ids for bespoke propagation needs. */
+    currentRunId() {
+        return currentRunId();
+    }
+    currentSpanId() {
+        return currentSpanId();
+    }
+    /** Attach feedback to a completed run. Call with the runId returned from wrapAgent. */
+    async feedback(runId, props) {
+        return this.apiClient.postRunFeedback(runId, {
+            satisfaction: props.satisfaction ?? null,
+            rating: props.rating ?? null,
+            comment: props.comment ?? props.feedback ?? null,
+            distinct_id: props.distinctId ?? null,
+            attributes: props.metadata ?? {},
+        });
     }
 }
 //# sourceMappingURL=TrodoClient.js.map