@mtharrison/loupe 1.1.1 → 1.3.0

package/dist/session-nav.js

@@ -1,11 +1,96 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveSessionNavItems = deriveSessionNavItems;
+exports.sortSessionNodesForNav = sortSessionNodesForNav;
+exports.findSessionNodePath = findSessionNodePath;
+exports.findSessionNodeById = findSessionNodeById;
+exports.getNewestTraceIdForNode = getNewestTraceIdForNode;
+exports.resolveSessionTreeSelection = resolveSessionTreeSelection;
+exports.getDefaultExpandedSessionTreeNodeIds = getDefaultExpandedSessionTreeNodeIds;
 function deriveSessionNavItems(sessionNodes, traceById) {
     return sessionNodes
         .map((node) => deriveSessionNavItem(node, traceById))
         .sort(compareSessionNavItems);
 }
+function sortSessionNodesForNav(sessionNodes, traceById) {
+    const itemById = new Map(sessionNodes.map((node) => [node.id, deriveSessionNavItem(node, traceById)]));
+    return sessionNodes
+        .slice()
+        .sort((left, right) => compareSessionNavItems(itemById.get(left.id), itemById.get(right.id)));
+}
+function findSessionNodePath(nodes, id, trail = []) {
+    for (const node of nodes) {
+        const nextTrail = [...trail, node];
+        if (node.id === id) {
+            return nextTrail;
+        }
+        const childTrail = findSessionNodePath(node.children, id, nextTrail);
+        if (childTrail.length) {
+            return childTrail;
+        }
+    }
+    return [];
+}
+function findSessionNodeById(nodes, id) {
+    return findSessionNodePath(nodes, id).at(-1) ?? null;
+}
+function getNewestTraceIdForNode(node) {
+    if (!node?.traceIds.length) {
+        return null;
+    }
+    if (typeof node.meta?.traceId === "string" && node.meta.traceId) {
+        return node.meta.traceId;
+    }
+    return node.traceIds[0] || null;
+}
+function resolveSessionTreeSelection(sessionNodes, selectedNodeId, selectedTraceId) {
+    const selectedNode = selectedNodeId
+        ? findSessionNodeById(sessionNodes, selectedNodeId)
+        : null;
+    const selectedTraceNode = selectedTraceId
+        ? findSessionNodeById(sessionNodes, `trace:${selectedTraceId}`)
+        : null;
+    const fallbackNode = selectedNode ?? selectedTraceNode ?? sessionNodes[0] ?? null;
+    if (!fallbackNode) {
+        return {
+            selectedNodeId: null,
+            selectedTraceId: null,
+        };
+    }
+    const nextSelectedNodeId = selectedNode?.id ?? fallbackNode.id;
+    const nextSelectedTraceId = selectedTraceId && fallbackNode.traceIds.includes(selectedTraceId)
+        ? selectedTraceId
+        : getNewestTraceIdForNode(fallbackNode);
+    return {
+        selectedNodeId: nextSelectedNodeId,
+        selectedTraceId: nextSelectedTraceId,
+    };
+}
+function getDefaultExpandedSessionTreeNodeIds(sessionNodes, activeSessionId, selectedNodeId) {
+    const expanded = new Set();
+    const activeSession = (activeSessionId
+        ? sessionNodes.find((node) => node.id === activeSessionId) ?? null
+        : null) ?? sessionNodes[0] ?? null;
+    if (!activeSession) {
+        return expanded;
+    }
+    if (activeSession.children.length) {
+        expanded.add(activeSession.id);
+    }
+    visitSessionTree(activeSession.children, (node) => {
+        if (node.children.length && node.type === "actor") {
+            expanded.add(node.id);
+        }
+    });
+    if (selectedNodeId) {
+        for (const node of findSessionNodePath([activeSession], selectedNodeId)) {
+            if (node.children.length) {
+                expanded.add(node.id);
+            }
+        }
+    }
+    return expanded;
+}
 function deriveSessionNavItem(node, traceById) {
     const traces = node.traceIds
         .map((traceId) => traceById.get(traceId))
@@ -130,3 +215,9 @@ function formatCompactTimestamp(value) {
         minute: "2-digit",
     });
 }
+function visitSessionTree(nodes, visitor) {
+    for (const node of nodes) {
+        visitor(node);
+        visitSessionTree(node.children, visitor);
+    }
+}

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 = {
@@ -202,6 +238,24 @@ export interface ChatModelLike<TInput = any, TOptions = any, TValue = any, TChun
     invoke(input: TInput, options?: TOptions): Promise<TValue>;
     stream(input: TInput, options?: TOptions): AsyncGenerator<TChunk>;
 }
+export type OpenAIChatCompletionCreateParamsLike = Record<string, any> & {
+    messages?: Record<string, any>[];
+    model?: string | null;
+    stream?: boolean | null;
+};
+export interface OpenAIChatCompletionStreamLike<TChunk = any> extends AsyncIterable<TChunk> {
+    [Symbol.asyncIterator](): AsyncIterator<TChunk>;
+}
+export interface OpenAIChatCompletionsLike<TParams = OpenAIChatCompletionCreateParamsLike, TOptions = Record<string, any>, TResponse = any, TChunk = any> {
+    create(params: TParams, options?: TOptions): Promise<TResponse> | Promise<OpenAIChatCompletionStreamLike<TChunk>> | OpenAIChatCompletionStreamLike<TChunk>;
+}
+export interface OpenAIClientLike<TParams = OpenAIChatCompletionCreateParamsLike, TOptions = Record<string, any>, TResponse = any, TChunk = any> {
+    chat: {
+        completions: OpenAIChatCompletionsLike<TParams, TOptions, TResponse, TChunk>;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
 export type TraceServer = {
     broadcast(event: TraceEvent | UIReloadEvent): void;
     close(): void;
@@ -215,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;