lightrace 0.1.1 → 0.1.3

package/dist/integrations/langchain.js

@@ -3,7 +3,7 @@
  *
  * Extends `BaseCallbackHandler` from `@langchain/core` to automatically
  * capture chains, LLM calls, tool invocations, and retriever operations
- * as Lightrace trace observations.
+ * as Lightrace trace observations via OpenTelemetry spans.
  *
  * @example
  * ```ts
@@ -16,6 +16,7 @@
  */
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 import { generateId, jsonSerializable } from "../utils.js";
+import * as attrs from "../otel-exporter.js";
 import { Lightrace } from "../client.js";
 export class LightraceCallbackHandler extends BaseCallbackHandler {
     name = "lightrace";
@@ -30,8 +31,10 @@ export class LightraceCallbackHandler extends BaseCallbackHandler {
     sessionId;
     traceName;
     rootMetadata;
-    // Exporter
-    exporter = null;
+    // OTel exporter
+    otelExporter = null;
+    /** Root span for the current trace. */
+    rootSpan = null;
     /** The trace ID from the most recently completed root run. */
     lastTraceId = null;
     constructor(opts) {
@@ -41,23 +44,43 @@ export class LightraceCallbackHandler extends BaseCallbackHandler {
         this.traceName = opts?.traceName;
         this.rootMetadata = opts?.metadata;
         const client = opts?.client ?? Lightrace.getInstance();
-        this.exporter = client?.getExporter() ?? null;
+        this.otelExporter = client?.getOtelExporter() ?? null;
     }
-    // ── helpers ──────────────────────────────────────────────────────────
+    // -- helpers ----------------------------------------------------------------
     getParentObservationId(observationId) {
         return this.runParents.get(observationId) ?? null;
     }
-    emit(event) {
-        this.exporter?.enqueue(event);
+    /**
+     * Normalize IO data by converting BaseMessage-like objects to plain
+     * {role, content, tool_calls?} objects. Recurses into arrays and plain objects.
+     */
+    normalizeIO(data) {
+        if (data === null || data === undefined)
+            return data;
+        if (Array.isArray(data))
+            return data.map((d) => this.normalizeIO(d));
+        if (typeof data === "object") {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const obj = data;
+            // Detect BaseMessage-like objects
+            if ("content" in obj && ("type" in obj || "_getType" in obj)) {
+                const role = typeof obj._getType === "function" ? obj._getType() : (obj.type ?? "unknown");
+                return {
+                    role,
+                    content: obj.content,
+                    ...(obj.tool_calls?.length ? { tool_calls: obj.tool_calls } : {}),
+                };
+            }
+            // Recurse into plain objects
+            const result = {};
+            for (const [k, v] of Object.entries(obj)) {
+                result[k] = this.normalizeIO(v);
+            }
+            return result;
+        }
+        return data;
     }
-    emitObservation(run, endTime, output, level, statusMessage, extra) {
-        const eventTypeMap = {
-            span: "span-create",
-            generation: "generation-create",
-            event: "event-create",
-            tool: "tool-create",
-            chain: "chain-create",
-        };
+    endObservationSpan(run, output, level, statusMessage, extra) {
         const obsTypeMap = {
             span: "SPAN",
             generation: "GENERATION",
@@ -65,62 +88,116 @@ export class LightraceCallbackHandler extends BaseCallbackHandler {
             tool: "TOOL",
             chain: "CHAIN",
         };
-        const body = {
-            id: run.observationId,
-            traceId: this._traceId,
-            type: obsTypeMap[run.type] ?? run.type,
-            name: run.name,
-            startTime: run.startTime.toISOString(),
-            endTime: endTime.toISOString(),
-            input: jsonSerializable(run.input),
-            output: jsonSerializable(output),
-            metadata: run.metadata ?? null,
-            model: run.model ?? null,
-            level,
-            statusMessage,
-            parentObservationId: this.getParentObservationId(run.observationId) ?? null,
-            ...extra,
-        };
-        this.emit({
-            id: generateId(),
-            type: eventTypeMap[run.type] ?? "span-create",
-            timestamp: run.startTime.toISOString(),
-            body,
-        });
+        const span = run.span;
+        span.setAttribute(attrs.OBSERVATION_TYPE, obsTypeMap[run.type] ?? run.type);
+        span.setAttribute(attrs.OBSERVATION_INPUT, attrs.safeJson(jsonSerializable(run.input)));
+        span.setAttribute(attrs.OBSERVATION_OUTPUT, attrs.safeJson(jsonSerializable(output)));
+        span.setAttribute(attrs.OBSERVATION_LEVEL, level);
+        if (run.metadata) {
+            span.setAttribute(attrs.OBSERVATION_METADATA, attrs.safeJson(run.metadata));
+        }
+        if (run.model) {
+            span.setAttribute(attrs.OBSERVATION_MODEL, run.model);
+        }
+        if (statusMessage) {
+            span.setAttribute(attrs.OBSERVATION_STATUS_MESSAGE, statusMessage);
+        }
+        if (run.modelParameters && Object.keys(run.modelParameters).length > 0) {
+            span.setAttribute(attrs.OBSERVATION_MODEL_PARAMETERS, attrs.safeJson(run.modelParameters));
+        }
+        if (extra) {
+            // Usage details from extra (promptTokens, completionTokens, totalTokens)
+            const usageDetails = {};
+            if (extra.promptTokens !== undefined)
+                usageDetails.promptTokens = extra.promptTokens;
+            if (extra.completionTokens !== undefined)
+                usageDetails.completionTokens = extra.completionTokens;
+            if (extra.totalTokens !== undefined)
+                usageDetails.totalTokens = extra.totalTokens;
+            if (Object.keys(usageDetails).length > 0) {
+                span.setAttribute(attrs.OBSERVATION_USAGE_DETAILS, attrs.safeJson(usageDetails));
+            }
+        }
+        span.end();
     }
     extractModelName(serialized) {
+        if (!serialized)
+            return undefined;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const s = serialized;
         return (s?.kwargs?.model_name ?? s?.kwargs?.model ?? s?.kwargs?.modelName ?? s?.name ?? undefined);
     }
+    extractModelParameters(extraParams) {
+        const invocationParams = extraParams?.["invocation_params"];
+        const modelParameters = {};
+        for (const key of [
+            "temperature",
+            "max_tokens",
+            "top_p",
+            "frequency_penalty",
+            "presence_penalty",
+        ]) {
+            const val = invocationParams?.[key];
+            if (val !== undefined && val !== null)
+                modelParameters[key] = val;
+        }
+        return modelParameters;
+    }
     isAgent(serialized) {
+        if (!serialized)
+            return false;
         const name = (serialized.id?.join("/") ?? "").toLowerCase();
         const sName = (serialized.name ?? "").toLowerCase();
         return name.includes("agent") || sName.includes("agent");
     }
     registerRun(runId, parentRunId, info) {
+        const tracer = this.otelExporter?.tracer;
         const isRoot = !this.rootRunId;
         if (isRoot) {
             this.rootRunId = runId;
             this._traceId = generateId();
-            // Emit root trace-create event
-            this.emit({
-                id: generateId(),
-                type: "trace-create",
-                timestamp: info.startTime.toISOString(),
-                body: {
-                    id: this._traceId,
-                    name: this.traceName ?? info.name,
-                    timestamp: info.startTime.toISOString(),
-                    userId: this.userId,
-                    sessionId: this.sessionId,
-                    metadata: this.rootMetadata ?? null,
-                    input: jsonSerializable(info.input),
-                },
-            });
+            // Create root span representing the trace
+            if (tracer) {
+                this.rootSpan = tracer.startSpan(this.traceName ?? info.name, {
+                    startTime: info.startTime,
+                });
+                this.rootSpan.setAttribute(attrs.AS_ROOT, "true");
+                this.rootSpan.setAttribute(attrs.TRACE_NAME, this.traceName ?? info.name);
+                this.rootSpan.setAttribute(attrs.TRACE_INPUT, attrs.safeJson(jsonSerializable(info.input)));
+                if (this.userId)
+                    this.rootSpan.setAttribute(attrs.TRACE_USER_ID, this.userId);
+                if (this.sessionId)
+                    this.rootSpan.setAttribute(attrs.TRACE_SESSION_ID, this.sessionId);
+                if (this.rootMetadata) {
+                    this.rootSpan.setAttribute(attrs.TRACE_METADATA, attrs.safeJson(this.rootMetadata));
+                }
+            }
         }
         const observationId = generateId();
-        const runInfo = { ...info, observationId, parentRunId };
+        // Create an OTel span for this observation
+        let span;
+        if (tracer) {
+            span = tracer.startSpan(info.name, { startTime: info.startTime });
+        }
+        else {
+            // Dummy span if no tracer -- will be a no-op
+            span = {
+                setAttribute: () => span,
+                setAttributes: () => span,
+                addEvent: () => span,
+                setStatus: () => span,
+                end: () => { },
+                isRecording: () => false,
+                recordException: () => { },
+                spanContext: () => ({
+                    traceId: "",
+                    spanId: "",
+                    traceFlags: 0,
+                }),
+                updateName: () => span,
+            };
+        }
+        const runInfo = { ...info, observationId, parentRunId, span };
         this.runs.set(runId, runInfo);
         this.runParents.set(observationId, parentRunId ? this.runs.get(parentRunId)?.observationId : undefined);
         return runInfo;
@@ -129,25 +206,14 @@ export class LightraceCallbackHandler extends BaseCallbackHandler {
         const run = this.runs.get(runId);
         if (!run)
             return;
-        const endTime = new Date();
-        this.emitObservation(run, endTime, output, level, statusMessage, extra);
-        // If this is the root run completing, update the trace and reset
+        this.endObservationSpan(run, output, level, statusMessage, extra);
+        // If this is the root run completing, end the root span and reset
         if (runId === this.rootRunId) {
-            // Emit trace-create with output (update)
-            this.emit({
-                id: generateId(),
-                type: "trace-create",
-                timestamp: run.startTime.toISOString(),
-                body: {
-                    id: this._traceId,
-                    name: this.traceName ?? run.name,
-                    timestamp: run.startTime.toISOString(),
-                    output: jsonSerializable(output),
-                    userId: this.userId,
-                    sessionId: this.sessionId,
-                    metadata: this.rootMetadata ?? null,
-                },
-            });
+            if (this.rootSpan) {
+                this.rootSpan.setAttribute(attrs.TRACE_OUTPUT, attrs.safeJson(jsonSerializable(output)));
+                this.rootSpan.end();
+                this.rootSpan = null;
+            }
             this.lastTraceId = this._traceId;
             this.rootRunId = null;
             this._traceId = null;
@@ -159,176 +225,314 @@ export class LightraceCallbackHandler extends BaseCallbackHandler {
             this.runs.delete(runId);
         }
     }
-    // ── Chain callbacks ──────────────────────────────────────────────────
-    async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata) {
-        const name = chain.name ??
-            chain.id?.[chain.id.length - 1] ??
-            "Chain";
-        const type = this.isAgent(chain) ? "chain" : "chain";
-        const mergedMetadata = { ...metadata, ...(tags?.length ? { tags } : {}) };
-        this.registerRun(runId, parentRunId, {
-            type,
-            name,
-            startTime: new Date(),
-            input: inputs,
-            metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
-        });
+    // -- Chain callbacks --------------------------------------------------------
+    async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata, _runType, name) {
+        try {
+            const resolvedName = name ??
+                chain?.name ??
+                chain?.id?.[chain.id.length - 1] ??
+                "Chain";
+            const type = this.isAgent(chain) ? "chain" : "chain";
+            const mergedMetadata = { ...metadata, ...(tags?.length ? { tags } : {}) };
+            this.registerRun(runId, parentRunId, {
+                type,
+                name: resolvedName,
+                startTime: new Date(),
+                input: this.normalizeIO(inputs ?? {}),
+                metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
+            });
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleChainStart:", e);
+        }
     }
     async handleChainEnd(outputs, runId, _parentRunId) {
-        this.endRun(runId, outputs);
+        try {
+            this.endRun(runId, this.normalizeIO(outputs ?? null));
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleChainEnd:", e);
+        }
     }
     async handleChainError(error, runId, _parentRunId) {
-        // LangGraph GraphBubbleUp is a control flow error, not an actual error
-        if (error?.constructor?.name === "GraphBubbleUp" || error?.name === "GraphBubbleUp") {
-            this.endRun(runId, null, "DEFAULT", null);
-            return;
+        try {
+            // LangGraph GraphBubbleUp is a control flow error, not an actual error
+            if (error?.constructor?.name === "GraphBubbleUp" || error?.name === "GraphBubbleUp") {
+                this.endRun(runId, null, "DEFAULT", null);
+                return;
+            }
+            this.endRun(runId, null, "ERROR", error?.message ?? String(error));
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleChainError:", e);
         }
-        this.endRun(runId, null, "ERROR", error.message ?? String(error));
     }
-    // ── LLM callbacks ───────────────────────────────────────────────────
-    async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, _tags, metadata) {
-        const model = this.extractModelName(llm);
-        const name = model ??
-            llm.name ??
-            llm.id?.[llm.id.length - 1] ??
-            "LLM";
-        this.registerRun(runId, parentRunId, {
-            type: "generation",
-            name,
-            startTime: new Date(),
-            input: prompts.length === 1 ? prompts[0] : prompts,
-            model,
-            metadata,
-        });
+    // -- LLM callbacks ----------------------------------------------------------
+    async handleLLMStart(llm, prompts, runId, parentRunId, extraParams, _tags, metadata, name) {
+        try {
+            const model = this.extractModelName(llm);
+            const resolvedName = name ??
+                model ??
+                llm?.name ??
+                llm?.id?.[llm.id.length - 1] ??
+                "LLM";
+            const modelParameters = this.extractModelParameters(extraParams);
+            this.registerRun(runId, parentRunId, {
+                type: "generation",
+                name: resolvedName,
+                startTime: new Date(),
+                input: prompts?.length === 1 ? prompts[0] : (prompts ?? []),
+                model,
+                metadata,
+                modelParameters,
+            });
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleLLMStart:", e);
+        }
     }
-    async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, _tags, metadata) {
-        const model = this.extractModelName(llm);
-        const name = model ??
-            llm.name ??
-            llm.id?.[llm.id.length - 1] ??
-            "ChatModel";
-        // Convert messages to a simpler role/content format
-        const formattedMessages = messages.map((msgGroup) => msgGroup.map((msg) => ({
-            role: msg._getType(),
-            content: msg.content,
-            ...(msg.name ? { name: msg.name } : {}),
-        })));
-        this.registerRun(runId, parentRunId, {
-            type: "generation",
-            name,
-            startTime: new Date(),
-            input: formattedMessages.length === 1 ? formattedMessages[0] : formattedMessages,
-            model,
-            metadata,
-        });
+    async handleChatModelStart(llm, messages, runId, parentRunId, extraParams, _tags, metadata, name) {
+        try {
+            const model = this.extractModelName(llm);
+            const resolvedName = name ??
+                model ??
+                llm?.name ??
+                llm?.id?.[llm.id.length - 1] ??
+                "ChatModel";
+            const modelParameters = this.extractModelParameters(extraParams);
+            // Convert messages to a simpler role/content format
+            const formattedMessages = (messages ?? []).map((msgGroup) => (msgGroup ?? []).map((msg) => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const msgAny = msg;
+                const role = typeof msgAny?._getType === "function"
+                    ? msgAny._getType()
+                    : (msgAny?.type ?? "unknown");
+                return {
+                    role,
+                    content: msg?.content,
+                    ...(msg?.name ? { name: msg.name } : {}),
+                    ...(msgAny?.tool_calls?.length ? { tool_calls: msgAny.tool_calls } : {}),
+                };
+            }));
+            this.registerRun(runId, parentRunId, {
+                type: "generation",
+                name: resolvedName,
+                startTime: new Date(),
+                input: formattedMessages.length === 1 ? formattedMessages[0] : formattedMessages,
+                model,
+                metadata,
+                modelParameters,
+            });
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleChatModelStart:", e);
+        }
     }
     async handleLLMEnd(output, runId, _parentRunId) {
-        const extra = {};
-        // Extract token usage
-        const usage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokens ?? null;
-        if (usage) {
-            if (usage.promptTokens !== undefined)
-                extra.promptTokens = usage.promptTokens;
-            if (usage.completionTokens !== undefined)
-                extra.completionTokens = usage.completionTokens;
-            if (usage.totalTokens !== undefined)
-                extra.totalTokens = usage.totalTokens;
-        }
-        // Add TTFT if we have it
-        const ttftStart = this.completionStartTimes.get(runId);
-        const run = this.runs.get(runId);
-        if (ttftStart && run) {
-            const ttft = ttftStart.getTime() - run.startTime.getTime();
-            if (!run.metadata)
-                run.metadata = {};
-            run.metadata.timeToFirstToken = ttft;
-        }
-        // Extract output text
-        const generations = output.generations;
-        let outputText;
-        if (generations.length === 1 && generations[0].length === 1) {
-            const gen = generations[0][0];
-            // ChatGeneration has a `message` field, base Generation only has `text`
-            const genAny = gen;
-            outputText = genAny.message ?? gen.text;
+        try {
+            const extra = {};
+            const run = this.runs.get(runId);
+            // Extract token usage from multiple sources
+            const llmUsage = output?.llmOutput?.tokenUsage ?? output?.llmOutput?.usage ?? null;
+            // Also check generation-level usage_metadata (e.g. Anthropic, Google)
+            const lastGen = output?.generations?.at(-1)?.at(-1);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const msgUsage = lastGen?.message?.usage_metadata;
+            const usage = llmUsage ?? msgUsage;
+            if (usage) {
+                const promptTokens = usage.promptTokens ?? usage.prompt_tokens ?? usage.input_tokens ?? undefined;
+                const completionTokens = usage.completionTokens ?? usage.completion_tokens ?? usage.output_tokens ?? undefined;
+                const totalTokens = usage.totalTokens ?? usage.total_tokens ?? undefined;
+                if (promptTokens !== undefined)
+                    extra.promptTokens = promptTokens;
+                if (completionTokens !== undefined)
+                    extra.completionTokens = completionTokens;
+                if (totalTokens !== undefined)
+                    extra.totalTokens = totalTokens;
+                else if (promptTokens !== undefined && completionTokens !== undefined)
+                    extra.totalTokens = promptTokens + completionTokens;
+            }
+            // Extract model name from response if not set at start
+            if (run && !run.model) {
+                const modelFromResponse = output?.llmOutput?.model_name ?? output?.llmOutput?.model ?? undefined;
+                if (modelFromResponse) {
+                    run.model = modelFromResponse;
+                    // Also update name if it was a default
+                    if (run.name === "LLM" || run.name === "ChatModel") {
+                        run.name = modelFromResponse;
+                    }
+                }
+            }
+            // Add TTFT if we have it
+            const ttftStart = this.completionStartTimes.get(runId);
+            if (ttftStart && run) {
+                const ttft = ttftStart.getTime() - run.startTime.getTime();
+                if (!run.metadata)
+                    run.metadata = {};
+                run.metadata.timeToFirstToken = ttft;
+            }
+            // Extract output -- handle ChatGeneration (has .message) vs Generation (only .text)
+            let outputData;
+            const generations = output?.generations;
+            if (generations && generations.length > 0) {
+                const singleGen = generations.length === 1 && generations[0].length === 1;
+                if (singleGen) {
+                    const gen = generations[0][0];
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const genAny = gen;
+                    if (genAny?.message) {
+                        const msg = genAny.message;
+                        const role = typeof msg._getType === "function" ? msg._getType() : (msg.type ?? "assistant");
+                        outputData = {
+                            role,
+                            content: msg.content,
+                            ...(msg.tool_calls?.length ? { tool_calls: msg.tool_calls } : {}),
+                        };
+                    }
+                    else {
+                        outputData = gen?.text;
+                    }
+                }
+                else {
+                    outputData = generations.map((g) => g.map((gg) => {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const ggAny = gg;
+                        if (ggAny?.message) {
+                            const msg = ggAny.message;
+                            const role = typeof msg._getType === "function" ? msg._getType() : (msg.type ?? "assistant");
+                            return {
+                                role,
+                                content: msg.content,
+                                ...(msg.tool_calls?.length ? { tool_calls: msg.tool_calls } : {}),
+                            };
+                        }
+                        return gg?.text;
+                    }));
+                }
+            }
+            else {
+                outputData = null;
+            }
+            this.endRun(runId, outputData, "DEFAULT", null, extra);
+            this.completionStartTimes.delete(runId);
         }
-        else {
-            outputText = generations.map((g) => g.map((gg) => {
-                const ggAny = gg;
-                return ggAny.message ?? gg.text;
-            }));
+        catch (e) {
+            console.warn("[lightrace] Error in handleLLMEnd:", e);
         }
-        this.endRun(runId, outputText, "DEFAULT", null, extra);
-        this.completionStartTimes.delete(runId);
     }
     async handleLLMNewToken(_token, _idx, runId) {
-        if (!this.completionStartTimes.has(runId)) {
-            this.completionStartTimes.set(runId, new Date());
+        try {
+            if (!this.completionStartTimes.has(runId)) {
+                this.completionStartTimes.set(runId, new Date());
+            }
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleLLMNewToken:", e);
         }
     }
     async handleLLMError(error, runId, _parentRunId) {
-        this.endRun(runId, null, "ERROR", error.message ?? String(error));
-        this.completionStartTimes.delete(runId);
+        try {
+            this.endRun(runId, null, "ERROR", error?.message ?? String(error));
+            this.completionStartTimes.delete(runId);
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleLLMError:", e);
+        }
     }
-    // ── Tool callbacks ──────────────────────────────────────────────────
-    async handleToolStart(tool, input, runId, parentRunId, _tags, metadata) {
-        const name = tool.name ??
-            tool.id?.[tool.id.length - 1] ??
-            "Tool";
-        // Try to parse input as JSON
-        let parsedInput = input;
+    // -- Tool callbacks ---------------------------------------------------------
+    async handleToolStart(tool, input, runId, parentRunId, _tags, metadata, name) {
         try {
-            parsedInput = JSON.parse(input);
-        }
-        catch {
-            // keep as string
-        }
-        this.registerRun(runId, parentRunId, {
-            type: "tool",
-            name,
-            startTime: new Date(),
-            input: parsedInput,
-            metadata,
-        });
+            const resolvedName = name ??
+                tool?.name ??
+                tool?.id?.[tool.id.length - 1] ??
+                "Tool";
+            // Try to parse input as JSON
+            let parsedInput = input;
+            if (typeof input === "string") {
+                try {
+                    parsedInput = JSON.parse(input);
+                }
+                catch {
+                    // keep as string
+                }
+            }
+            this.registerRun(runId, parentRunId, {
+                type: "tool",
+                name: resolvedName,
+                startTime: new Date(),
+                input: parsedInput,
+                metadata,
+            });
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleToolStart:", e);
+        }
     }
     async handleToolEnd(output, runId, _parentRunId) {
-        // Try to parse output as JSON
-        let parsedOutput = output;
         try {
-            parsedOutput = JSON.parse(output);
+            // Try to parse output as JSON
+            let parsedOutput = output;
+            if (typeof output === "string") {
+                try {
+                    parsedOutput = JSON.parse(output);
+                }
+                catch {
+                    // keep as string
+                }
+            }
+            this.endRun(runId, parsedOutput);
         }
-        catch {
-            // keep as string
+        catch (e) {
+            console.warn("[lightrace] Error in handleToolEnd:", e);
         }
-        this.endRun(runId, parsedOutput);
     }
     async handleToolError(error, runId, _parentRunId) {
-        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+        try {
+            this.endRun(runId, null, "ERROR", error?.message ?? String(error));
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleToolError:", e);
+        }
     }
-    // ── Retriever callbacks ─────────────────────────────────────────────
+    // -- Retriever callbacks ----------------------------------------------------
     async handleRetrieverStart(retriever, query, runId, parentRunId, _tags, metadata) {
-        const name = retriever.name ??
-            retriever.id?.[retriever.id.length - 1] ??
-            "Retriever";
-        this.registerRun(runId, parentRunId, {
-            type: "span",
-            name,
-            startTime: new Date(),
-            input: query,
-            metadata,
-        });
+        try {
+            const name = retriever?.name ??
+                retriever?.id?.[retriever.id.length - 1] ??
+                "Retriever";
+            this.registerRun(runId, parentRunId, {
+                type: "span",
+                name,
+                startTime: new Date(),
+                input: query,
+                metadata,
+            });
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleRetrieverStart:", e);
+        }
     }
     async handleRetrieverEnd(documents, runId, _parentRunId) {
-        const output = documents.map((doc) => ({
-            pageContent: doc.pageContent,
-            metadata: doc.metadata,
-        }));
-        this.endRun(runId, output);
+        try {
+            const output = (documents ?? []).map((doc) => ({
+                pageContent: doc?.pageContent,
+                metadata: doc?.metadata,
+            }));
+            this.endRun(runId, output);
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleRetrieverEnd:", e);
+        }
     }
     async handleRetrieverError(error, runId, _parentRunId) {
-        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+        try {
+            this.endRun(runId, null, "ERROR", error?.message ?? String(error));
+        }
+        catch (e) {
+            console.warn("[lightrace] Error in handleRetrieverError:", e);
+        }
     }
-    // ── Accessors ───────────────────────────────────────────────────────
+    // -- Accessors --------------------------------------------------------------
     /** Get the current active trace ID (null if no run is active). */
     get traceId() {
         return this._traceId;