@mtharrison/loupe 1.2.0 → 1.3.0

package/README.md

@@ -125,9 +125,28 @@ Supported demo environment variables: `OPENAI_MODEL`, `LLM_TRACE_PORT`, `LOUPE_O
 
 The script tries to open the dashboard automatically and prints the local URL either way. Set `LOUPE_OPEN_BROWSER=0` if you want to suppress the browser launch.
 
+### Runnable Nested Tool-Call Demo
+
+`examples/nested-tool-call.js` is a credential-free demo that:
+
+- starts the Loupe dashboard eagerly
+- wraps a root assistant model and a nested tool model
+- invokes the nested tool model from inside the parent model call
+- shows parent/child spans linked on the same trace
+
+Run it with:
+
+```bash
+npm install
+export LLM_TRACE_ENABLED=1
+node examples/nested-tool-call.js
+```
+
 ## Low-Level Lifecycle API
 
-If you need full control over trace boundaries, Loupe also exposes the lower-level `record*` lifecycle functions.
+If you need full control over trace boundaries, Loupe exposes a lower-level span lifecycle API modeled on OpenTelemetry concepts: start a span, add events, end it, and record exceptions.
+
+Loupe stores GenAI span attributes using the OpenTelemetry semantic convention names where they apply, including `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.system`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.conversation.id`.
 
 Start the dashboard during app startup, then instrument a model call:
 
@@ -135,9 +154,9 @@ Start the dashboard during app startup, then instrument a model call:
 import {
   getLocalLLMTracer,
   isTraceEnabled,
-  recordError,
-  recordInvokeFinish,
-  recordInvokeStart,
+  endSpan,
+  recordException,
+  startSpan,
   type TraceContext,
 } from '@mtharrison/loupe';
 
@@ -166,51 +185,63 @@ const request = {
   options: {},
 };
 
-const traceId = recordInvokeStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'invoke',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   const response = await model.invoke(request.input, request.options);
-  recordInvokeFinish(traceId, response);
+  endSpan(spanId, response);
   return response;
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
 ### Streaming
 
-Streaming works the same way. Loupe records each chunk event, first-chunk latency, and the reconstructed final response.
+Streaming works the same way. Loupe records each span event, first-chunk latency, and the reconstructed final response.
 
 ```ts
 import {
-  recordError,
-  recordStreamChunk,
-  recordStreamFinish,
-  recordStreamStart,
+  addSpanEvent,
+  endSpan,
+  recordException,
+  startSpan,
 } from '@mtharrison/loupe';
 
-const traceId = recordStreamStart(context, request);
+const spanId = startSpan(context, {
+  mode: 'stream',
+  name: 'openai.chat.completions',
+  request,
+});
 
 try {
   for await (const chunk of model.stream(request.input, request.options)) {
     if (chunk?.type === 'finish') {
-      recordStreamFinish(traceId, chunk);
+      endSpan(spanId, chunk);
     } else {
-      recordStreamChunk(traceId, chunk);
+      addSpanEvent(spanId, {
+        name: `stream.${chunk?.type || 'event'}`,
+        attributes: chunk,
+        payload: chunk,
+      });
     }
 
     yield chunk;
   }
 } catch (error) {
-  recordError(traceId, error);
+  recordException(spanId, error);
   throw error;
 }
 ```
 
 ## Trace Context
 
-Loupe gets its hierarchy and filters from the context you pass to `recordInvokeStart()` and `recordStreamStart()`.
+Loupe gets its hierarchy and filters from the context you pass to `startSpan()`.
 
 ### Generic context fields
 
@@ -322,7 +353,7 @@ Programmatic configuration is also available through `getLocalLLMTracer(config)`
 
 ## API
 
-Loupe exposes both low-level lifecycle functions and lightweight wrappers.
+Loupe exposes both low-level span lifecycle functions and lightweight wrappers.
 
 ### `isTraceEnabled()`
 
@@ -340,29 +371,21 @@ Returns the singleton tracer instance. This is useful if you want to:
 
 Starts the local dashboard server eagerly instead of waiting for the first trace.
 
-### `recordInvokeStart(context, request, config?)`
-
-Creates an `invoke` trace and returns a `traceId`.
-
-### `recordInvokeFinish(traceId, response, config?)`
-
-Marks an `invoke` trace as complete and stores the response payload.
-
-### `recordStreamStart(context, request, config?)`
+### `startSpan(context, options?, config?)`
 
-Creates a `stream` trace and returns a `traceId`.
+Creates a span and returns its Loupe `spanId`. Pass `mode`, `name`, and `request` in `options` to describe the operation. Nested spans are linked automatically when wrapped calls invoke other wrapped calls in the same async flow.
 
-### `recordStreamChunk(traceId, chunk, config?)`
+### `addSpanEvent(spanId, event, config?)`
 
-Appends a non-final stream chunk to an existing trace.
+Appends an event to an existing span. For streaming traces, pass the raw chunk as `event.payload` to preserve chunk reconstruction in the UI.
 
-### `recordStreamFinish(traceId, chunk, config?)`
+### `endSpan(spanId, response, config?)`
 
-Stores the final stream payload and marks the trace complete.
+Marks a span as complete and stores the final response payload.
 
-### `recordError(traceId, error, config?)`
+### `recordException(spanId, error, config?)`
 
-Marks a trace as failed and stores a serialized error payload.
+Marks a span as failed and stores a serialized exception payload.
 
 All of these functions forward to the singleton tracer returned by `getLocalLLMTracer()`.
 

package/dist/client/app.js

@@ -21395,34 +21395,36 @@ function App() {
   });
   const handleSseMessage = (0, import_react3.useEffectEvent)((data2) => {
     const payload = parseEvent(data2);
+    const nextTrace = payload?.span;
+    const nextTraceId = payload?.spanId;
     if (payload?.type === "ui:reload") {
       window.location.reload();
       return;
     }
-    if (payload?.trace && selectedTraceId && payload.traceId === selectedTraceId) {
-      (0, import_react3.startTransition)(() => setDetail(payload.trace));
+    if (nextTrace && selectedTraceId && nextTraceId === selectedTraceId) {
+      (0, import_react3.startTransition)(() => setDetail(nextTrace));
     }
     if (!queryString) {
-      if (payload?.type === "trace:update" && payload.trace) {
-        applyIncrementalTraceUpdate(payload.trace);
+      if ((payload?.type === "span:update" || payload?.type === "span:end") && nextTrace) {
+        applyIncrementalTraceUpdate(nextTrace);
         return;
       }
-      if (payload?.type === "trace:add" && payload.trace) {
-        applyIncrementalTraceAdd(payload.trace);
+      if (payload?.type === "span:start" && nextTrace) {
+        applyIncrementalTraceAdd(nextTrace);
         scheduleRefresh(180);
         return;
       }
-      if (payload?.type === "trace:evict") {
-        applyIncrementalTraceEvict(payload.traceId);
+      if (payload?.type === "span:evict") {
+        applyIncrementalTraceEvict(nextTraceId);
         scheduleRefresh(180);
         return;
       }
-      if (payload?.type === "trace:clear") {
+      if (payload?.type === "span:clear") {
         clearIncrementalState();
         return;
       }
     }
-    scheduleRefresh(payload?.type === "trace:update" ? 700 : 180);
+    scheduleRefresh(payload?.type === "span:update" || payload?.type === "span:end" ? 700 : 180);
   });
   (0, import_react3.useEffect)(() => {
     const events = new EventSource("/api/events");

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { type ChatModelLike, type LocalLLMTracer, type OpenAIChatCompletionCreateParamsLike, type OpenAIClientLike, type TraceConfig, type TraceContext, type TraceRequest } from './types';
-export type { ChatModelLike, HierarchyNode, HierarchyResponse, LocalLLMTracer, NormalizedTraceContext, OpenAIChatCompletionCreateParamsLike, OpenAIChatCompletionStreamLike, OpenAIClientLike, TraceConfig, TraceContext, TraceEvent, TraceFilters, TraceHierarchy, TraceListResponse, TraceMode, TraceRecord, TraceRequest, TraceServer, TraceStatus, TraceSummary, TraceTags, UIReloadEvent, } from './types';
+import { type ChatModelLike, type LocalLLMTracer, type OpenAIChatCompletionCreateParamsLike, type OpenAIClientLike, type SpanEventInput, type SpanStartOptions, type TraceConfig, type TraceContext } from './types';
+export type { ChatModelLike, HierarchyNode, HierarchyResponse, LocalLLMTracer, NormalizedTraceContext, OpenAIChatCompletionCreateParamsLike, OpenAIChatCompletionStreamLike, OpenAIClientLike, SpanAttributes, SpanContext, SpanEvent, SpanEventInput, SpanKind, SpanStartOptions, SpanStatus, SpanStatusCode, TraceConfig, TraceContext, TraceEvent, TraceFilters, TraceHierarchy, TraceListResponse, TraceMode, TraceRecord, TraceRequest, TraceServer, TraceStatus, TraceSummary, TraceTags, UIReloadEvent, } from './types';
 export declare function isTraceEnabled(): boolean;
 export declare function getLocalLLMTracer(config?: TraceConfig): LocalLLMTracer;
 export declare function startTraceServer(config?: TraceConfig): Promise<{
@@ -7,12 +7,10 @@ export declare function startTraceServer(config?: TraceConfig): Promise<{
     port: number;
     url: string;
 }>;
-export declare function recordInvokeStart(context: TraceContext, request: TraceRequest, config?: TraceConfig): string;
-export declare function recordInvokeFinish(traceId: string, response: unknown, config?: TraceConfig): void;
-export declare function recordStreamStart(context: TraceContext, request: TraceRequest, config?: TraceConfig): string;
-export declare function recordStreamChunk(traceId: string, chunk: unknown, config?: TraceConfig): void;
-export declare function recordStreamFinish(traceId: string, chunk: unknown, config?: TraceConfig): void;
-export declare function recordError(traceId: string, error: unknown, config?: TraceConfig): void;
+export declare function startSpan(context: TraceContext, options?: SpanStartOptions, config?: TraceConfig): string;
+export declare function endSpan(spanId: string, response: unknown, config?: TraceConfig): void;
+export declare function addSpanEvent(spanId: string, event: SpanEventInput, config?: TraceConfig): void;
+export declare function recordException(spanId: string, error: unknown, config?: TraceConfig): void;
 export declare function __resetLocalLLMTracerForTests(): void;
 export declare function wrapChatModel<TModel extends ChatModelLike<TInput, TOptions, TValue, TChunk>, TInput = any, TOptions = any, TValue = any, TChunk = any>(model: TModel, getContext: () => TraceContext, config?: TraceConfig): TModel;
 export declare function wrapOpenAIClient<TClient extends OpenAIClientLike<TParams, TOptions, TResponse, TChunk>, TParams extends OpenAIChatCompletionCreateParamsLike = OpenAIChatCompletionCreateParamsLike, TOptions = Record<string, any>, TResponse = any, TChunk = any>(client: TClient, getContext: () => TraceContext, config?: TraceConfig): TClient;

package/dist/index.js

@@ -3,21 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTraceEnabled = isTraceEnabled;
 exports.getLocalLLMTracer = getLocalLLMTracer;
 exports.startTraceServer = startTraceServer;
-exports.recordInvokeStart = recordInvokeStart;
-exports.recordInvokeFinish = recordInvokeFinish;
-exports.recordStreamStart = recordStreamStart;
-exports.recordStreamChunk = recordStreamChunk;
-exports.recordStreamFinish = recordStreamFinish;
-exports.recordError = recordError;
+exports.startSpan = startSpan;
+exports.endSpan = endSpan;
+exports.addSpanEvent = addSpanEvent;
+exports.recordException = recordException;
 exports.__resetLocalLLMTracerForTests = __resetLocalLLMTracerForTests;
 exports.wrapChatModel = wrapChatModel;
 exports.wrapOpenAIClient = wrapOpenAIClient;
+const node_async_hooks_1 = require("node:async_hooks");
 const server_1 = require("./server");
 const store_1 = require("./store");
 const ui_build_1 = require("./ui-build");
 const utils_1 = require("./utils");
 let singleton = null;
 const DEFAULT_TRACE_PORT = 4319;
+const activeSpanStorage = new node_async_hooks_1.AsyncLocalStorage();
 function isTraceEnabled() {
     return (0, utils_1.envFlag)('LLM_TRACE_ENABLED');
 }
@@ -33,23 +33,17 @@ function getLocalLLMTracer(config = {}) {
 function startTraceServer(config = {}) {
     return getLocalLLMTracer(config).startServer();
 }
-function recordInvokeStart(context, request, config = {}) {
-    return getLocalLLMTracer(config).recordInvokeStart(context, request);
+function startSpan(context, options = {}, config = {}) {
+    return getLocalLLMTracer(config).startSpan(context, options);
 }
-function recordInvokeFinish(traceId, response, config = {}) {
-    getLocalLLMTracer(config).recordInvokeFinish(traceId, response);
+function endSpan(spanId, response, config = {}) {
+    getLocalLLMTracer(config).endSpan(spanId, response);
 }
-function recordStreamStart(context, request, config = {}) {
-    return getLocalLLMTracer(config).recordStreamStart(context, request);
+function addSpanEvent(spanId, event, config = {}) {
+    getLocalLLMTracer(config).addSpanEvent(spanId, event);
 }
-function recordStreamChunk(traceId, chunk, config = {}) {
-    getLocalLLMTracer(config).recordStreamChunk(traceId, chunk);
-}
-function recordStreamFinish(traceId, chunk, config = {}) {
-    getLocalLLMTracer(config).recordStreamFinish(traceId, chunk);
-}
-function recordError(traceId, error, config = {}) {
-    getLocalLLMTracer(config).recordError(traceId, error);
+function recordException(spanId, error, config = {}) {
+    getLocalLLMTracer(config).recordException(spanId, error);
 }
 function __resetLocalLLMTracerForTests() {
     if (singleton?.uiWatcher) {
@@ -70,14 +64,19 @@ function wrapChatModel(model, getContext, config) {
             if (!tracer.isEnabled()) {
                 return model.invoke(input, options);
             }
-            const traceId = tracer.recordInvokeStart(getContext ? getContext() : {}, { input: input, options: options });
+            const traceId = tracer.startSpan(getContext ? getContext() : {}, {
+                attributes: { 'gen_ai.operation.name': 'chat' },
+                mode: 'invoke',
+                name: 'llm.invoke',
+                request: { input: input, options: options },
+            });
             try {
-                const response = await model.invoke(input, options);
-                tracer.recordInvokeFinish(traceId, response);
+                const response = await tracer.runWithActiveSpan(traceId, () => model.invoke(input, options));
+                tracer.endSpan(traceId, response);
                 return response;
             }
             catch (error) {
-                tracer.recordError(traceId, error);
+                tracer.recordException(traceId, error);
                 throw error;
             }
         },
@@ -87,21 +86,26 @@ function wrapChatModel(model, getContext, config) {
                 yield* model.stream(input, options);
                 return;
             }
-            const traceId = tracer.recordStreamStart(getContext ? getContext() : {}, { input: input, options: options });
+            const traceId = tracer.startSpan(getContext ? getContext() : {}, {
+                attributes: { 'gen_ai.operation.name': 'chat' },
+                mode: 'stream',
+                name: 'llm.stream',
+                request: { input: input, options: options },
+            });
             try {
-                const stream = model.stream(input, options);
+                const stream = tracer.runWithActiveSpan(traceId, () => model.stream(input, options));
                 for await (const chunk of stream) {
                     if (chunk?.type === 'finish') {
-                        tracer.recordStreamFinish(traceId, chunk);
+                        tracer.endSpan(traceId, chunk);
                     }
                     else {
-                        tracer.recordStreamChunk(traceId, chunk);
+                        tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)(chunk));
                     }
                     yield chunk;
                 }
             }
             catch (error) {
-                tracer.recordError(traceId, error);
+                tracer.recordException(traceId, error);
                 throw error;
             }
         },
@@ -121,24 +125,34 @@ function wrapOpenAIClient(client, getContext, config) {
                     }
                     const context = withOpenAITraceContext(getContext ? getContext() : {}, params);
                     if (params?.stream) {
-                        const traceId = tracer.recordStreamStart(context, { input: params, options: options });
+                        const traceId = tracer.startSpan(context, {
+                            attributes: { 'gen_ai.operation.name': 'chat' },
+                            mode: 'stream',
+                            name: 'openai.chat.completions',
+                            request: { input: params, options: options },
+                        });
                         try {
-                            const stream = await target.create.call(target, params, options);
+                            const stream = await tracer.runWithActiveSpan(traceId, () => target.create.call(target, params, options));
                             return wrapOpenAIChatCompletionsStream(stream, tracer, traceId);
                         }
                         catch (error) {
-                            tracer.recordError(traceId, error);
+                            tracer.recordException(traceId, error);
                             throw error;
                         }
                     }
-                    const traceId = tracer.recordInvokeStart(context, { input: params, options: options });
+                    const traceId = tracer.startSpan(context, {
+                        attributes: { 'gen_ai.operation.name': 'chat' },
+                        mode: 'invoke',
+                        name: 'openai.chat.completions',
+                        request: { input: params, options: options },
+                    });
                     try {
-                        const response = await target.create.call(target, params, options);
-                        tracer.recordInvokeFinish(traceId, normalizeOpenAIChatCompletionResponse(response));
+                        const response = await tracer.runWithActiveSpan(traceId, () => target.create.call(target, params, options));
+                        tracer.endSpan(traceId, normalizeOpenAIChatCompletionResponse(response));
                         return response;
                     }
                     catch (error) {
-                        tracer.recordError(traceId, error);
+                        tracer.recordException(traceId, error);
                         throw error;
                     }
                 };
@@ -213,6 +227,27 @@ class LocalLLMTracerImpl {
     isEnabled() {
         return isTraceEnabled();
     }
+    startSpan(context, options = {}) {
+        void this.startServer();
+        const parentSpanId = options.parentSpanId || activeSpanStorage.getStore() || null;
+        return this.store.startSpan(context, {
+            ...options,
+            parentSpanId,
+            request: normaliseRequest(options.request || {}),
+        });
+    }
+    runWithActiveSpan(spanId, callback) {
+        return activeSpanStorage.run(spanId, callback);
+    }
+    addSpanEvent(spanId, event) {
+        this.store.addSpanEvent(spanId, (0, utils_1.safeClone)(event));
+    }
+    endSpan(spanId, response) {
+        this.store.endSpan(spanId, (0, utils_1.safeClone)(response));
+    }
+    recordException(spanId, error) {
+        this.store.recordException(spanId, error);
+    }
     startServer() {
         if (!this.isEnabled() || this.serverFailed) {
             return Promise.resolve(this.serverInfo);
@@ -234,7 +269,7 @@ class LocalLLMTracerImpl {
                     this.uiWatcher = await (0, ui_build_1.maybeStartUIWatcher)(() => {
                         this.server?.broadcast({
                             timestamp: new Date().toISOString(),
-                            traceId: null,
+                            spanId: null,
                             type: 'ui:reload',
                         });
                     }, this.config.uiHotReload);
@@ -256,26 +291,6 @@ class LocalLLMTracerImpl {
         })();
         return this.serverStartPromise;
     }
-    recordInvokeStart(context, request) {
-        void this.startServer();
-        return this.store.recordInvokeStart(context, normaliseRequest(request));
-    }
-    recordInvokeFinish(traceId, response) {
-        this.store.recordInvokeFinish(traceId, (0, utils_1.safeClone)(response));
-    }
-    recordStreamStart(context, request) {
-        void this.startServer();
-        return this.store.recordStreamStart(context, normaliseRequest(request));
-    }
-    recordStreamChunk(traceId, chunk) {
-        this.store.recordStreamChunk(traceId, (0, utils_1.safeClone)(chunk));
-    }
-    recordStreamFinish(traceId, chunk) {
-        this.store.recordStreamFinish(traceId, (0, utils_1.safeClone)(chunk));
-    }
-    recordError(traceId, error) {
-        this.store.recordError(traceId, error);
-    }
 }
 function normaliseRequest(request) {
     return {
@@ -322,7 +337,7 @@ function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
         state.began = true;
         const nextRole = role || state.role || 'assistant';
         state.role = nextRole;
-        tracer.recordStreamChunk(traceId, { type: 'begin', role: nextRole });
+        tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({ type: 'begin', role: nextRole }));
     };
     const emitFinish = () => {
         if (state.finished) {
@@ -330,7 +345,7 @@ function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
         }
         emitBegin(state.role);
         state.finished = true;
-        tracer.recordStreamFinish(traceId, {
+        tracer.endSpan(traceId, {
             type: 'finish',
             finish_reasons: state.finishReasons,
             message: {
@@ -382,23 +397,23 @@ function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
             emitBegin(state.role);
         }
         if (contentParts.length > 0) {
-            tracer.recordStreamChunk(traceId, {
+            tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({
                 type: 'chunk',
                 content: contentParts.join(''),
                 finish_reasons: [...finishReasons],
                 raw,
                 tool_calls: chunkToolCalls,
                 usage,
-            });
+            }));
             return;
         }
-        tracer.recordStreamChunk(traceId, {
+        tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({
             type: 'event',
             finish_reasons: [...finishReasons],
             raw,
             tool_calls: chunkToolCalls,
             usage,
-        });
+        }));
     };
     const createWrappedIterator = (iterator) => ({
         async next(...args) {
@@ -412,7 +427,7 @@ function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
                 return result;
             }
             catch (error) {
-                tracer.recordError(traceId, error);
+                tracer.recordException(traceId, error);
                 throw error;
             }
         },
@@ -428,12 +443,12 @@ function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
                 return result;
             }
             catch (error) {
-                tracer.recordError(traceId, error);
+                tracer.recordException(traceId, error);
                 throw error;
             }
         },
         async throw(error) {
-            tracer.recordError(traceId, error);
+            tracer.recordException(traceId, error);
             if (typeof iterator.throw === 'function') {
                 return iterator.throw(error);
             }

package/dist/store.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import { type HierarchyResponse, type NormalizedTraceContext, type TraceFilters, type TraceListResponse, type TraceRecord, type TraceRequest } from './types';
+import { type HierarchyResponse, type NormalizedTraceContext, type SpanEventInput, type SpanStartOptions, type TraceFilters, type TraceListResponse, type TraceRecord } from './types';
 export declare class TraceStore extends EventEmitter {
     maxTraces: number;
     order: string[];
@@ -7,12 +7,11 @@ export declare class TraceStore extends EventEmitter {
     constructor(options?: {
         maxTraces?: number;
     });
-    recordInvokeStart(context: NormalizedTraceContext | undefined, request: TraceRequest): string;
-    recordInvokeFinish(traceId: string, response: any): void;
-    recordStreamStart(context: NormalizedTraceContext | undefined, request: TraceRequest): string;
-    recordStreamChunk(traceId: string, chunk: any): void;
-    recordStreamFinish(traceId: string, chunk: any): void;
-    recordError(traceId: string, error: unknown): void;
+    startSpan(context: NormalizedTraceContext | undefined, options?: SpanStartOptions): string;
+    addSpanEvent(spanId: string, event: SpanEventInput): void;
+    endSpan(spanId: string, response: any): void;
+    recordException(spanId: string, error: unknown): void;
+    private applyStreamPayload;
     list(filters?: TraceFilters): TraceListResponse;
     get(traceId: string): TraceRecord | null;
     clear(): void;

package/dist/store.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TraceStore = void 0;
+const node_crypto_1 = require("node:crypto");
 const node_events_1 = require("node:events");
 const utils_1 = require("./utils");
+const STREAM_EVENT_NAME_PREFIX = 'stream.';
 class TraceStore extends node_events_1.EventEmitter {
     maxTraces;
     order;
@@ -13,72 +15,100 @@ class TraceStore extends node_events_1.EventEmitter {
         this.order = [];
         this.traces = new Map();
     }
-    recordInvokeStart(context, request) {
-        return this.recordStart('invoke', context, request);
+    startSpan(context, options = {}) {
+        return this.recordStart(options.mode || 'invoke', context, options.request || {}, options);
     }
-    recordInvokeFinish(traceId, response) {
-        const trace = this.traces.get(traceId);
+    addSpanEvent(spanId, event) {
+        // Loupe returns its own stable span handle from startSpan(). That handle is used to
+        // look up mutable in-memory records here, while trace.spanContext.spanId stores the
+        // OpenTelemetry span ID exposed on the resulting span data.
+        const trace = this.traces.get(spanId);
         if (!trace) {
             return;
         }
-        trace.response = (0, utils_1.safeClone)(response);
-        trace.usage = (0, utils_1.safeClone)(response?.usage);
+        const spanEvent = normalizeSpanEvent(event);
+        trace.events.push(spanEvent);
+        this.applyStreamPayload(trace, event.payload, spanEvent);
+        this.publish('span:update', spanId, { trace: this.cloneTrace(trace) });
+    }
+    endSpan(spanId, response) {
+        const trace = this.traces.get(spanId);
+        if (!trace) {
+            return;
+        }
+        const clone = (0, utils_1.safeClone)(response);
+        if (trace.mode === 'stream') {
+            const finishEvent = normalizeSpanEvent((0, utils_1.toSpanEventInputFromChunk)(clone));
+            trace.events.push(finishEvent);
+            this.applyStreamPayload(trace, clone, finishEvent);
+            trace.response = clone;
+            trace.usage = (0, utils_1.safeClone)(clone?.usage);
+        }
+        else {
+            trace.response = clone;
+            trace.usage = (0, utils_1.safeClone)(clone?.usage);
+        }
+        applyResponseAttributes(trace, clone);
         trace.status = 'ok';
+        trace.spanStatus = { code: 'OK' };
         trace.endedAt = new Date().toISOString();
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
+        this.publish('span:end', spanId, { trace: this.cloneTrace(trace) });
     }
-    recordStreamStart(context, request) {
-        return this.recordStart('stream', context, request);
+    recordException(spanId, error) {
+        const trace = this.traces.get(spanId);
+        if (!trace) {
+            return;
+        }
+        const payload = (0, utils_1.toErrorPayload)(error);
+        trace.error = payload;
+        trace.events.push({
+            attributes: payload || {},
+            name: 'exception',
+            timestamp: new Date().toISOString(),
+        });
+        trace.status = 'error';
+        trace.spanStatus = {
+            code: 'ERROR',
+            message: payload?.message,
+        };
+        if (payload?.name || payload?.type || payload?.code || payload?.status) {
+            trace.attributes['error.type'] = String(payload.name || payload.type || payload.code || payload.status);
+        }
+        trace.endedAt = new Date().toISOString();
+        this.publish('span:end', spanId, { trace: this.cloneTrace(trace) });
     }
-    recordStreamChunk(traceId, chunk) {
-        const trace = this.traces.get(traceId);
-        if (!trace || !trace.stream) {
+    applyStreamPayload(trace, payload, spanEvent) {
+        if (!trace.stream) {
             return;
         }
-        const clone = (0, utils_1.safeClone)(chunk);
+        const clone = toStreamPayload(payload, spanEvent);
         if (clone && typeof clone === 'object') {
             clone.offsetMs = Math.max(0, Date.now() - Date.parse(trace.startedAt));
         }
         trace.stream.events.push(clone);
-        if (chunk?.type === 'chunk') {
+        if (clone?.type === 'chunk') {
             trace.stream.chunkCount += 1;
             if (trace.stream.firstChunkMs === null) {
                 trace.stream.firstChunkMs = Date.now() - Date.parse(trace.startedAt);
             }
-            if (typeof chunk.content === 'string') {
-                trace.stream.reconstructed.message.content = `${trace.stream.reconstructed.message.content || ''}${chunk.content}`;
+            if (typeof clone.content === 'string') {
+                trace.stream.reconstructed.message.content = `${trace.stream.reconstructed.message.content || ''}${clone.content}`;
             }
         }
-        if (chunk?.type === 'begin') {
-            trace.stream.reconstructed.message.role = chunk.role;
+        if (clone?.type === 'begin') {
+            trace.stream.reconstructed.message.role = clone.role;
         }
-        if (chunk?.type === 'finish') {
+        if (clone?.type === 'finish') {
             trace.response = clone;
-            trace.usage = (0, utils_1.safeClone)(chunk.usage);
+            trace.usage = (0, utils_1.safeClone)(clone.usage);
             trace.stream.reconstructed.message = {
-                ...((0, utils_1.safeClone)(chunk.message) || {}),
+                ...((0, utils_1.safeClone)(clone.message) || {}),
                 content: trace.stream.reconstructed.message.content ||
-                    (typeof chunk.message?.content === 'string' ? chunk.message.content : chunk.message?.content ?? null),
+                    (typeof clone.message?.content === 'string' ? clone.message.content : clone.message?.content ?? null),
             };
-            trace.stream.reconstructed.tool_calls = (0, utils_1.safeClone)(chunk.tool_calls || []);
-            trace.stream.reconstructed.usage = (0, utils_1.safeClone)(chunk.usage || null);
-            trace.status = 'ok';
-            trace.endedAt = new Date().toISOString();
-        }
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
-    }
-    recordStreamFinish(traceId, chunk) {
-        this.recordStreamChunk(traceId, chunk);
-    }
-    recordError(traceId, error) {
-        const trace = this.traces.get(traceId);
-        if (!trace) {
-            return;
+            trace.stream.reconstructed.tool_calls = (0, utils_1.safeClone)(clone.tool_calls || []);
+            trace.stream.reconstructed.usage = (0, utils_1.safeClone)(clone.usage || null);
         }
-        trace.error = (0, utils_1.toErrorPayload)(error);
-        trace.status = 'error';
-        trace.endedAt = new Date().toISOString();
-        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
     }
     list(filters = {}) {
         const items = this.filteredTraces(filters).map(utils_1.toSummary);
@@ -99,7 +129,7 @@ class TraceStore extends node_events_1.EventEmitter {
     clear() {
         this.order = [];
         this.traces.clear();
-        this.publish('trace:clear', null, {});
+        this.publish('span:clear', null, {});
     }
     hierarchy(filters = {}) {
         const traces = this.filteredTraces(filters);
@@ -164,19 +194,24 @@ class TraceStore extends node_events_1.EventEmitter {
             rootNodes: [...roots.values()].map(serialiseNode),
         };
     }
-    recordStart(mode, context, request) {
+    recordStart(mode, context, request, options = {}) {
         const traceContext = (0, utils_1.normalizeTraceContext)(context, mode);
         const traceId = randomId();
+        const parentSpan = options.parentSpanId ? this.traces.get(options.parentSpanId) : null;
         const startedAt = new Date().toISOString();
         const trace = {
+            attributes: buildSpanAttributes(traceContext, mode, request, options.attributes),
             context: traceContext,
             endedAt: null,
             error: null,
+            events: [],
             hierarchy: traceContext.hierarchy,
             id: traceId,
             kind: traceContext.kind,
             mode,
             model: traceContext.model,
+            name: options.name || getDefaultSpanName(traceContext, mode),
+            parentSpanId: parentSpan?.spanContext.spanId || options.parentSpanId || null,
             provider: traceContext.provider,
             request: {
                 input: (0, utils_1.safeClone)(request?.input),
@@ -187,6 +222,15 @@ class TraceStore extends node_events_1.EventEmitter {
             },
             response: null,
             startedAt,
+            spanContext: {
+                // The returned Loupe span handle (trace.id) is used for local mutation and SSE updates.
+                // spanContext contains the OpenTelemetry trace/span identifiers that are attached to
+                // the exported span payload and inherited by child spans.
+                spanId: randomHexId(16),
+                traceId: parentSpan?.spanContext.traceId || randomHexId(32),
+            },
+            spanKind: options.kind || 'CLIENT',
+            spanStatus: { code: 'UNSET' },
             status: 'pending',
             stream: mode === 'stream'
                 ? {
@@ -206,7 +250,7 @@ class TraceStore extends node_events_1.EventEmitter {
         this.order.push(traceId);
         this.traces.set(traceId, trace);
         this.evictIfNeeded();
-        this.publish('trace:add', traceId, { trace: this.cloneTrace(trace) });
+        this.publish('span:start', traceId, { trace: this.cloneTrace(trace) });
         return traceId;
     }
     evictIfNeeded() {
@@ -216,7 +260,7 @@ class TraceStore extends node_events_1.EventEmitter {
             if (oldest) {
                 this.traces.delete(oldest);
             }
-            this.publish('trace:evict', oldest || null, removed ? { trace: this.cloneTrace(removed) } : {});
+            this.publish('span:evict', oldest || null, removed ? { trace: this.cloneTrace(removed) } : {});
         }
     }
     cloneTrace(trace) {
@@ -273,8 +317,9 @@ class TraceStore extends node_events_1.EventEmitter {
     }
     publish(type, traceId, payload) {
         const event = {
+            span: payload.trace,
+            spanId: traceId,
             type,
-            traceId,
             timestamp: new Date().toISOString(),
             ...payload,
         };
@@ -378,3 +423,116 @@ function buildGroupHierarchy(traces, groupBy) {
 function randomId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+function randomHexId(length) {
+    if (length % 2 !== 0) {
+        throw new RangeError(`OpenTelemetry hex IDs must have an even length. Received: ${length}`);
+    }
+    return (0, node_crypto_1.randomBytes)(Math.ceil(length / 2)).toString('hex').slice(0, length);
+}
+function normalizeSpanEvent(event) {
+    const attributes = (0, utils_1.safeClone)(event.attributes || {});
+    if (event.name === 'stream.finish') {
+        attributes['gen_ai.message.status'] = attributes['gen_ai.message.status'] || 'completed';
+    }
+    else if (event.name.startsWith(STREAM_EVENT_NAME_PREFIX)) {
+        attributes['gen_ai.message.status'] = attributes['gen_ai.message.status'] || 'in_progress';
+    }
+    if (attributes.finish_reasons && attributes['gen_ai.response.finish_reasons'] === undefined) {
+        attributes['gen_ai.response.finish_reasons'] = (0, utils_1.safeClone)(attributes.finish_reasons);
+    }
+    if (attributes.message && attributes['gen_ai.output.messages'] === undefined) {
+        attributes['gen_ai.output.messages'] = [(0, utils_1.safeClone)(attributes.message)];
+    }
+    return {
+        attributes,
+        name: event.name,
+        timestamp: new Date().toISOString(),
+    };
+}
+function toStreamPayload(payload, spanEvent) {
+    if (payload && typeof payload === 'object') {
+        return (0, utils_1.safeClone)(payload);
+    }
+    // Generic addSpanEvent() callers may only provide an OpenTelemetry-style event name
+    // plus attributes. Reconstruct the minimal legacy stream payload shape from that data
+    // so the existing dashboard stream timeline can continue to render incrementally.
+    const suffix = spanEvent.name.startsWith(STREAM_EVENT_NAME_PREFIX)
+        ? spanEvent.name.slice(STREAM_EVENT_NAME_PREFIX.length)
+        : spanEvent.name;
+    const eventType = suffix || 'event';
+    return {
+        ...(0, utils_1.safeClone)(spanEvent.attributes || {}),
+        type: eventType,
+    };
+}
+function getDefaultSpanName(context, mode) {
+    const prefix = context.provider || 'llm';
+    return `${prefix}.${mode}`;
+}
+function buildSpanAttributes(context, mode, request, extraAttributes) {
+    const base = {
+        'gen_ai.conversation.id': context.sessionId || undefined,
+        'gen_ai.input.messages': Array.isArray(request?.input?.messages) ? (0, utils_1.safeClone)(request.input.messages) : undefined,
+        'gen_ai.operation.name': inferGenAIOperationName(request, mode),
+        'gen_ai.provider.name': context.provider || undefined,
+        'gen_ai.request.choice.count': typeof request?.input?.n === 'number' ? request.input.n : undefined,
+        'gen_ai.request.model': (typeof request?.input?.model === 'string' && request.input.model) || context.model || undefined,
+        'gen_ai.system': context.provider || undefined,
+        'loupe.actor.id': context.actorId || undefined,
+        'loupe.actor.type': context.actorType || undefined,
+        'loupe.guardrail.phase': context.guardrailPhase || undefined,
+        'loupe.guardrail.type': context.guardrailType || undefined,
+        'loupe.root_actor.id': context.rootActorId || undefined,
+        'loupe.root_session.id': context.rootSessionId || undefined,
+        'loupe.session.id': context.sessionId || undefined,
+        'loupe.stage': context.stage || undefined,
+        'loupe.tenant.id': context.tenantId || undefined,
+        'loupe.user.id': context.userId || undefined,
+    };
+    for (const [key, value] of Object.entries(context.tags || {})) {
+        base[`loupe.tag.${key}`] = value;
+    }
+    return Object.fromEntries(Object.entries({
+        ...base,
+        ...(extraAttributes || {}),
+    }).filter(([, value]) => value !== undefined && value !== null));
+}
+function applyResponseAttributes(trace, response) {
+    const finishReasons = Array.isArray(response?.finish_reasons)
+        ? response.finish_reasons
+        : response?.finish_reason
+            ? [response.finish_reason]
+            : [];
+    const usage = response?.usage;
+    if (typeof response?.model === 'string' && response.model) {
+        trace.attributes['gen_ai.response.model'] = response.model;
+    }
+    if (usage?.tokens?.prompt !== undefined) {
+        trace.attributes['gen_ai.usage.input_tokens'] = usage.tokens.prompt;
+    }
+    if (usage?.tokens?.completion !== undefined) {
+        trace.attributes['gen_ai.usage.output_tokens'] = usage.tokens.completion;
+    }
+    if (finishReasons.length > 0) {
+        trace.attributes['gen_ai.response.finish_reasons'] = (0, utils_1.safeClone)(finishReasons);
+    }
+    if (response?.message) {
+        trace.attributes['gen_ai.output.messages'] = [(0, utils_1.safeClone)(response.message)];
+        trace.attributes['gen_ai.output.type'] = inferGenAIOutputType(response.message.content);
+    }
+}
+function inferGenAIOperationName(request, mode) {
+    if (Array.isArray(request?.input?.messages) && request.input.messages.length > 0) {
+        return 'chat';
+    }
+    return mode;
+}
+function inferGenAIOutputType(content) {
+    if (typeof content === 'string' || Array.isArray(content)) {
+        return 'text';
+    }
+    if (content && typeof content === 'object') {
+        return 'json';
+    }
+    return 'unknown';
+}

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 export type TraceMode = 'invoke' | 'stream';
 export type TraceStatus = 'pending' | 'ok' | 'error';
+export type SpanKind = 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+export type SpanStatusCode = 'UNSET' | 'OK' | 'ERROR';
 export type TraceConfig = {
     host?: string;
     maxTraces?: number;
@@ -7,6 +9,20 @@ export type TraceConfig = {
     uiHotReload?: boolean;
 };
 export type TraceTags = Record<string, string>;
+export type SpanAttributes = Record<string, any>;
+export type SpanContext = {
+    spanId: string;
+    traceId: string;
+};
+export type SpanEvent = {
+    attributes: SpanAttributes;
+    name: string;
+    timestamp: string;
+};
+export type SpanStatus = {
+    code: SpanStatusCode;
+    message?: string;
+};
 export type TraceContext = {
     actorId?: string | null;
     actorType?: string | null;
@@ -79,6 +95,19 @@ export type TraceRequest = {
     input?: Record<string, any>;
     options?: Record<string, any>;
 };
+export type SpanStartOptions = {
+    attributes?: SpanAttributes;
+    kind?: SpanKind;
+    mode?: TraceMode;
+    name?: string;
+    parentSpanId?: string | null;
+    request?: TraceRequest;
+};
+export type SpanEventInput = {
+    attributes?: SpanAttributes;
+    name: string;
+    payload?: unknown;
+};
 export type TraceStructuredInputInsight = {
     format: 'xml';
     role: string;
@@ -101,14 +130,18 @@ export type TraceSummaryFlags = {
     hasStructuredInput: boolean;
 };
 export type TraceRecord = {
+    attributes: SpanAttributes;
     context: NormalizedTraceContext;
     endedAt: string | null;
     error: Record<string, any> | null;
+    events: SpanEvent[];
     hierarchy: TraceHierarchy;
     id: string;
     kind: string;
     mode: TraceMode;
     model: string | null;
+    name: string;
+    parentSpanId: string | null;
     provider: string | null;
     request: {
         input?: Record<string, any>;
@@ -116,6 +149,9 @@ export type TraceRecord = {
     };
     response: Record<string, any> | null;
     startedAt: string;
+    spanContext: SpanContext;
+    spanKind: SpanKind;
+    spanStatus: SpanStatus;
     status: TraceStatus;
     stream: null | {
         chunkCount: number;
@@ -153,14 +189,14 @@ export type TraceSummary = {
     tags: TraceTags;
 };
 export type TraceEvent = {
+    span?: TraceRecord;
+    spanId: string | null;
     timestamp: string;
-    trace?: TraceRecord;
-    traceId: string | null;
     type: string;
 };
 export type UIReloadEvent = {
     timestamp: string;
-    traceId: null;
+    spanId: null;
     type: 'ui:reload';
 };
 export type TraceListResponse = {
@@ -233,14 +269,13 @@ export type UIWatchController = {
     stop(): Promise<void>;
 };
 export type LocalLLMTracer = {
+    addSpanEvent(spanId: string, event: SpanEventInput): void;
     configure(config?: TraceConfig): void;
+    endSpan(spanId: string, response?: unknown): void;
     isEnabled(): boolean;
-    recordError(traceId: string, error: unknown): void;
-    recordInvokeFinish(traceId: string, response: unknown): void;
-    recordInvokeStart(context: TraceContext, request: TraceRequest): string;
-    recordStreamChunk(traceId: string, chunk: unknown): void;
-    recordStreamFinish(traceId: string, chunk: unknown): void;
-    recordStreamStart(context: TraceContext, request: TraceRequest): string;
+    recordException(spanId: string, error: unknown): void;
+    runWithActiveSpan<T>(spanId: string, callback: () => T): T;
+    startSpan(context: TraceContext, options?: SpanStartOptions): string;
     startServer(): Promise<{
         host: string;
         port: number;

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
-import { type NormalizedTraceContext, type TraceContext, type TraceInsights, type TraceMode, type TraceRecord, type TraceSummary } from './types';
+import { type NormalizedTraceContext, type SpanEventInput, type TraceContext, type TraceInsights, type TraceMode, type TraceRecord, type TraceSummary } from './types';
 export declare function safeClone<T>(value: T): T;
+export declare function toSpanEventInputFromChunk(chunk: unknown): SpanEventInput;
 export declare function toErrorPayload(error: any): Record<string, any> | null;
 export declare function sanitizeHeaders(headers: Record<string, any> | undefined): Record<string, any>;
 export declare function envFlag(name: string): boolean;

package/dist/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.safeClone = safeClone;
+exports.toSpanEventInputFromChunk = toSpanEventInputFromChunk;
 exports.toErrorPayload = toErrorPayload;
 exports.sanitizeHeaders = sanitizeHeaders;
 exports.envFlag = envFlag;
@@ -30,6 +31,19 @@ function safeClone(value) {
         return value;
     }
 }
+function toSpanEventInputFromChunk(chunk) {
+    const payload = safeClone(chunk);
+    const eventType = typeof payload?.type === 'string' && payload.type ? payload.type : 'event';
+    const attributes = payload !== null && typeof payload === 'object' ? { ...payload } : {};
+    if ('type' in attributes) {
+        delete attributes.type;
+    }
+    return {
+        attributes,
+        name: `stream.${eventType}`,
+        payload: payload ?? undefined,
+    };
+}
 function toErrorPayload(error) {
     if (!error) {
         return null;

package/examples/nested-tool-call.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const { spawn } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const readline = require('node:readline/promises');
+const process = require('node:process');
+
+const { getLocalLLMTracer, wrapChatModel } = require('../dist/index.js');
+
+const DEMO_TIMEOUT_MS = 15000;
+const PORT = Number(process.env.LLM_TRACE_PORT) || 4319;
+const SESSION_ID = `nested-tool-demo-${randomUUID().slice(0, 8)}`;
+
+async function main() {
+  process.env.LLM_TRACE_ENABLED ??= '1';
+
+  const tracer = getLocalLLMTracer({ port: PORT });
+  const serverInfo = await tracer.startServer();
+  if (!serverInfo?.url) {
+    throw new Error('Failed to start the Loupe dashboard.');
+  }
+
+  log(`[demo] Loupe dashboard: ${serverInfo.url}`);
+  openBrowser(serverInfo.url);
+  log(`[demo] Session: ${SESSION_ID}`);
+
+  const nestedResearchModel = wrapChatModel(
+    {
+      async invoke(input) {
+        const question = input?.messages?.[0]?.content || '';
+        return {
+          message: {
+            role: 'assistant',
+            content: `Tool research result for "${question}": compare rain gear, walking shoes, and a light sweater.`,
+          },
+          tool_calls: [],
+          usage: {
+            tokens: { prompt: 9, completion: 14 },
+            pricing: { prompt: 0.000001, completion: 0.000002 },
+          },
+        };
+      },
+      async *stream(input) {
+        const content = `Tool research stream for "${input?.messages?.[0]?.content || ''}".`;
+        yield { type: 'begin', role: 'assistant' };
+        yield { type: 'chunk', content };
+        yield {
+          type: 'finish',
+          message: { role: 'assistant', content },
+          tool_calls: [],
+          usage: {
+            tokens: { prompt: 9, completion: 14 },
+            pricing: { prompt: 0.000001, completion: 0.000002 },
+          },
+        };
+      },
+    },
+    () => ({
+      sessionId: SESSION_ID,
+      rootSessionId: SESSION_ID,
+      rootActorId: 'travel-assistant',
+      actorId: 'weather-research-tool',
+      provider: 'mock-llm',
+      model: 'tool-researcher-v1',
+      stage: 'tool:research',
+      tags: {
+        example: 'nested-tool-call',
+        role: 'tool-llm',
+      },
+    }),
+    { port: PORT },
+  );
+
+  const rootAssistantModel = wrapChatModel(
+    {
+      async invoke(input) {
+        const question = input?.messages?.[0]?.content || '';
+        const toolResult = await nestedResearchModel.invoke(
+          {
+            messages: [
+              {
+                role: 'user',
+                content: `Research facts needed for: ${question}`,
+              },
+            ],
+          },
+          {},
+        );
+
+        return {
+          message: {
+            role: 'assistant',
+            content: [
+              `Final answer for "${question}"`,
+              '',
+              toolResult.message.content,
+              '',
+              'Pack layers, waterproof gear, and comfortable shoes.',
+            ].join('\n'),
+          },
+          tool_calls: [],
+          usage: {
+            tokens: { prompt: 12, completion: 18 },
+            pricing: { prompt: 0.000001, completion: 0.000002 },
+          },
+        };
+      },
+      async *stream(input) {
+        const question = input?.messages?.[0]?.content || '';
+        yield { type: 'begin', role: 'assistant' };
+        yield { type: 'chunk', content: 'Let me research that with the tool model.\n\n' };
+
+        let toolContent = '';
+        for await (const chunk of nestedResearchModel.stream(
+          {
+            messages: [
+              {
+                role: 'user',
+                content: `Research facts needed for: ${question}`,
+              },
+            ],
+          },
+          {},
+        )) {
+          if (chunk?.type === 'chunk' && typeof chunk.content === 'string') {
+            toolContent += chunk.content;
+          }
+        }
+
+        const finalContent = [
+          `Final answer for "${question}"`,
+          '',
+          toolContent,
+          '',
+          'Pack layers, waterproof gear, and comfortable shoes.',
+        ].join('\n');
+
+        yield { type: 'chunk', content: finalContent };
+        yield {
+          type: 'finish',
+          message: { role: 'assistant', content: finalContent },
+          tool_calls: [],
+          usage: {
+            tokens: { prompt: 12, completion: 18 },
+            pricing: { prompt: 0.000001, completion: 0.000002 },
+          },
+        };
+      },
+    },
+    () => ({
+      sessionId: SESSION_ID,
+      rootSessionId: SESSION_ID,
+      rootActorId: 'travel-assistant',
+      actorId: 'travel-assistant',
+      provider: 'mock-llm',
+      model: 'trip-planner-v1',
+      stage: 'assistant',
+      tags: {
+        example: 'nested-tool-call',
+        role: 'root-llm',
+      },
+    }),
+    { port: PORT },
+  );
+
+  const prompt = 'I am taking a rainy weekend trip to London. What should I pack?';
+  log(`[demo] User: ${prompt}`);
+  const response = await rootAssistantModel.invoke({
+    messages: [{ role: 'user', content: prompt }],
+  });
+  log(`[demo] Assistant:\n${response.message.content}`);
+  log('[demo] This run creates a parent span for the assistant call and a child span for the tool LLM call.');
+  log(`[demo] Keep this process alive while you inspect ${serverInfo.url}`);
+
+  await waitForDashboardExit(serverInfo.url);
+}
+
+function openBrowser(url) {
+  if (!process.stdout.isTTY || process.env.CI || process.env.LOUPE_OPEN_BROWSER === '0') {
+    return;
+  }
+
+  const command =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'linux'
+          ? ['xdg-open', [url]]
+          : null;
+
+  if (!command) {
+    return;
+  }
+
+  try {
+    const child = spawn(command[0], command[1], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', () => {});
+    child.unref();
+  } catch (_error) {
+    // Ignore browser launch failures. The dashboard URL is already printed.
+  }
+}
+
+async function waitForDashboardExit(url) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    log(`[demo] Non-interactive terminal detected. Leaving the dashboard up for ${Math.round(DEMO_TIMEOUT_MS / 1000)} seconds: ${url}`);
+    await new Promise((resolve) => setTimeout(resolve, DEMO_TIMEOUT_MS));
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    await rl.question('[demo] Press Enter to stop the demo and close the dashboard.\n');
+  } finally {
+    rl.close();
+  }
+}
+
+function log(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`[demo] ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtharrison/loupe",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Lightweight local tracing dashboard for LLM calls",
   "author": "Matt Harrison",
   "license": "MIT",