@mtharrison/loupe 1.1.1 → 1.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { type ChatModelLike, type LocalLLMTracer, type TraceConfig, type TraceContext, type TraceRequest } from './types';
-export type { ChatModelLike, HierarchyNode, HierarchyResponse, LocalLLMTracer, NormalizedTraceContext, 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,11 +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,19 +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');
 }
@@ -31,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) {
@@ -68,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;
             }
         },
@@ -85,29 +86,101 @@ 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;
             }
         },
     };
 }
+function wrapOpenAIClient(client, getContext, config) {
+    if (!client || typeof client.chat?.completions?.create !== 'function') {
+        throw new TypeError('wrapOpenAIClient expects an OpenAI client with chat.completions.create().');
+    }
+    const wrappedCompletions = new Proxy(client.chat.completions, {
+        get(target, prop, receiver) {
+            if (prop === 'create') {
+                return async (params, options) => {
+                    const tracer = getLocalLLMTracer(config);
+                    if (!tracer.isEnabled()) {
+                        return target.create.call(target, params, options);
+                    }
+                    const context = withOpenAITraceContext(getContext ? getContext() : {}, params);
+                    if (params?.stream) {
+                        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 tracer.runWithActiveSpan(traceId, () => target.create.call(target, params, options));
+                            return wrapOpenAIChatCompletionsStream(stream, tracer, traceId);
+                        }
+                        catch (error) {
+                            tracer.recordException(traceId, error);
+                            throw error;
+                        }
+                    }
+                    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 tracer.runWithActiveSpan(traceId, () => target.create.call(target, params, options));
+                        tracer.endSpan(traceId, normalizeOpenAIChatCompletionResponse(response));
+                        return response;
+                    }
+                    catch (error) {
+                        tracer.recordException(traceId, error);
+                        throw error;
+                    }
+                };
+            }
+            return bindMethod(target, Reflect.get(target, prop, receiver));
+        },
+    });
+    const wrappedChat = new Proxy(client.chat, {
+        get(target, prop, receiver) {
+            if (prop === 'completions') {
+                return wrappedCompletions;
+            }
+            return bindMethod(target, Reflect.get(target, prop, receiver));
+        },
+    });
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'chat') {
+                return wrappedChat;
+            }
+            return bindMethod(target, Reflect.get(target, prop, receiver));
+        },
+    });
+}
 class LocalLLMTracerImpl {
     config;
     loggedUrl;
+    portWasExplicit;
     server;
     serverFailed;
     serverInfo;
@@ -121,6 +194,7 @@ class LocalLLMTracerImpl {
             port: 4319,
             uiHotReload: false,
         };
+        this.portWasExplicit = false;
         this.configure(config);
         this.store = new store_1.TraceStore({ maxTraces: this.config.maxTraces });
         this.server = null;
@@ -134,9 +208,11 @@ class LocalLLMTracerImpl {
         if (this.serverInfo && (config.host || config.port)) {
             return;
         }
+        const explicitPort = getConfiguredPort(config.port, process.env.LLM_TRACE_PORT, this.portWasExplicit ? this.config.port : undefined);
+        this.portWasExplicit = explicitPort !== undefined;
         this.config = {
             host: config.host || this.config.host || process.env.LLM_TRACE_HOST || '127.0.0.1',
-            port: Number(config.port || this.config.port || process.env.LLM_TRACE_PORT) || 4319,
+            port: explicitPort ?? DEFAULT_TRACE_PORT,
             maxTraces: Number(config.maxTraces || this.config.maxTraces || process.env.LLM_TRACE_MAX_TRACES) || 1000,
             uiHotReload: typeof config.uiHotReload === 'boolean'
                 ? config.uiHotReload
@@ -151,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);
@@ -163,13 +260,16 @@ class LocalLLMTracerImpl {
         }
         this.serverStartPromise = (async () => {
             try {
-                this.server = (0, server_1.createTraceServer)(this.store, this.config);
+                this.server = (0, server_1.createTraceServer)(this.store, {
+                    ...this.config,
+                    allowPortFallback: !this.portWasExplicit,
+                });
                 this.serverInfo = await this.server.start();
                 if (this.serverInfo && !this.uiWatcher) {
                     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);
@@ -191,30 +291,273 @@ class LocalLLMTracerImpl {
         })();
         return this.serverStartPromise;
     }
-    recordInvokeStart(context, request) {
-        void this.startServer();
-        return this.store.recordInvokeStart(context, normaliseRequest(request));
+}
+function normaliseRequest(request) {
+    return {
+        input: (0, utils_1.safeClone)(request?.input),
+        options: (0, utils_1.safeClone)(request?.options),
+    };
+}
+function bindMethod(target, value) {
+    return typeof value === 'function' ? value.bind(target) : value;
+}
+function getConfiguredPort(configPort, envPort, currentExplicitPort) {
+    if (typeof configPort === 'number' && Number.isFinite(configPort)) {
+        return configPort;
     }
-    recordInvokeFinish(traceId, response) {
-        this.store.recordInvokeFinish(traceId, (0, utils_1.safeClone)(response));
+    if (envPort !== undefined) {
+        const parsed = Number(envPort);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
     }
-    recordStreamStart(context, request) {
-        void this.startServer();
-        return this.store.recordStreamStart(context, normaliseRequest(request));
+    return typeof currentExplicitPort === 'number' && Number.isFinite(currentExplicitPort) ? currentExplicitPort : undefined;
+}
+function withOpenAITraceContext(context, params) {
+    return {
+        ...(context || {}),
+        model: context?.model || (typeof params?.model === 'string' ? params.model : null),
+        provider: context?.provider || 'openai',
+    };
+}
+function wrapOpenAIChatCompletionsStream(stream, tracer, traceId) {
+    const state = {
+        content: '',
+        finished: false,
+        finishReasons: [],
+        began: false,
+        role: null,
+        toolCalls: new Map(),
+        usage: null,
+    };
+    const emitBegin = (role) => {
+        if (state.began) {
+            return;
+        }
+        state.began = true;
+        const nextRole = role || state.role || 'assistant';
+        state.role = nextRole;
+        tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({ type: 'begin', role: nextRole }));
+    };
+    const emitFinish = () => {
+        if (state.finished) {
+            return;
+        }
+        emitBegin(state.role);
+        state.finished = true;
+        tracer.endSpan(traceId, {
+            type: 'finish',
+            finish_reasons: state.finishReasons,
+            message: {
+                role: state.role || 'assistant',
+                content: state.content || null,
+            },
+            tool_calls: serializeOpenAIToolCalls(state.toolCalls),
+            usage: (0, utils_1.safeClone)(state.usage),
+        });
+    };
+    const processChunk = (chunk) => {
+        const raw = (0, utils_1.safeClone)(chunk);
+        const chunkToolCalls = [];
+        const finishReasons = new Set();
+        const contentParts = [];
+        const choices = Array.isArray(chunk?.choices) ? chunk.choices : [];
+        let sawEvent = false;
+        for (const choice of choices) {
+            const delta = choice?.delta || {};
+            if (typeof delta?.role === 'string' && delta.role) {
+                state.role = delta.role;
+                sawEvent = true;
+            }
+            for (const part of extractOpenAITextParts(delta?.content)) {
+                state.content = `${state.content}${part}`;
+                contentParts.push(part);
+                sawEvent = true;
+            }
+            if (Array.isArray(delta?.tool_calls) && delta.tool_calls.length > 0) {
+                sawEvent = true;
+                for (const toolCall of delta.tool_calls) {
+                    mergeOpenAIToolCallDelta(state.toolCalls, toolCall);
+                    chunkToolCalls.push((0, utils_1.safeClone)(toolCall));
+                }
+            }
+            if (typeof choice?.finish_reason === 'string' && choice.finish_reason) {
+                finishReasons.add(choice.finish_reason);
+            }
+        }
+        const usage = normalizeOpenAIUsage(chunk?.usage);
+        if (usage) {
+            state.usage = usage;
+            sawEvent = true;
+        }
+        for (const finishReason of finishReasons) {
+            state.finishReasons.push(finishReason);
+        }
+        if (sawEvent) {
+            emitBegin(state.role);
+        }
+        if (contentParts.length > 0) {
+            tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({
+                type: 'chunk',
+                content: contentParts.join(''),
+                finish_reasons: [...finishReasons],
+                raw,
+                tool_calls: chunkToolCalls,
+                usage,
+            }));
+            return;
+        }
+        tracer.addSpanEvent(traceId, (0, utils_1.toSpanEventInputFromChunk)({
+            type: 'event',
+            finish_reasons: [...finishReasons],
+            raw,
+            tool_calls: chunkToolCalls,
+            usage,
+        }));
+    };
+    const createWrappedIterator = (iterator) => ({
+        async next(...args) {
+            try {
+                const result = await iterator.next(...args);
+                if (result.done) {
+                    emitFinish();
+                    return result;
+                }
+                processChunk(result.value);
+                return result;
+            }
+            catch (error) {
+                tracer.recordException(traceId, error);
+                throw error;
+            }
+        },
+        async return(value) {
+            try {
+                const result = typeof iterator.return === 'function'
+                    ? await iterator.return(value)
+                    : {
+                        done: true,
+                        value,
+                    };
+                emitFinish();
+                return result;
+            }
+            catch (error) {
+                tracer.recordException(traceId, error);
+                throw error;
+            }
+        },
+        async throw(error) {
+            tracer.recordException(traceId, error);
+            if (typeof iterator.throw === 'function') {
+                return iterator.throw(error);
+            }
+            throw error;
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    });
+    return new Proxy(stream, {
+        get(target, prop, receiver) {
+            if (prop === Symbol.asyncIterator) {
+                return () => createWrappedIterator(target[Symbol.asyncIterator]());
+            }
+            return bindMethod(target, Reflect.get(target, prop, receiver));
+        },
+    });
+}
+function normalizeOpenAIChatCompletionResponse(response) {
+    const message = response?.choices?.[0]?.message;
+    return {
+        finish_reason: response?.choices?.[0]?.finish_reason || null,
+        id: response?.id || null,
+        message: normalizeOpenAIMessage(message),
+        model: response?.model || null,
+        object: response?.object || null,
+        raw: (0, utils_1.safeClone)(response),
+        tool_calls: Array.isArray(message?.tool_calls) ? (0, utils_1.safeClone)(message.tool_calls) : [],
+        usage: normalizeOpenAIUsage(response?.usage),
+    };
+}
+function normalizeOpenAIMessage(message) {
+    return {
+        ...(0, utils_1.safeClone)(message),
+        content: normalizeOpenAIMessageContent(message),
+        role: typeof message?.role === 'string' ? message.role : 'assistant',
+    };
+}
+function normalizeOpenAIMessageContent(message) {
+    const content = extractOpenAITextParts(message?.content);
+    if (content.length > 0) {
+        return content.join('');
     }
-    recordStreamChunk(traceId, chunk) {
-        this.store.recordStreamChunk(traceId, (0, utils_1.safeClone)(chunk));
+    if (typeof message?.refusal === 'string' && message.refusal) {
+        return message.refusal;
     }
-    recordStreamFinish(traceId, chunk) {
-        this.store.recordStreamFinish(traceId, (0, utils_1.safeClone)(chunk));
+    return message?.content ?? null;
+}
+function extractOpenAITextParts(content) {
+    if (typeof content === 'string' && content) {
+        return [content];
+    }
+    if (!Array.isArray(content)) {
+        return [];
     }
-    recordError(traceId, error) {
-        this.store.recordError(traceId, error);
+    const parts = [];
+    for (const item of content) {
+        if (typeof item === 'string' && item) {
+            parts.push(item);
+            continue;
+        }
+        if (typeof item?.text === 'string' && item.text) {
+            parts.push(item.text);
+            continue;
+        }
+        if (typeof item?.content === 'string' && item.content) {
+            parts.push(item.content);
+        }
     }
+    return parts;
 }
-function normaliseRequest(request) {
+function normalizeOpenAIUsage(usage) {
+    if (!usage || typeof usage !== 'object') {
+        return null;
+    }
     return {
-        input: (0, utils_1.safeClone)(request?.input),
-        options: (0, utils_1.safeClone)(request?.options),
+        raw: (0, utils_1.safeClone)(usage),
+        tokens: {
+            completion: typeof usage?.completion_tokens === 'number' ? usage.completion_tokens : null,
+            prompt: typeof usage?.prompt_tokens === 'number' ? usage.prompt_tokens : null,
+            total: typeof usage?.total_tokens === 'number' ? usage.total_tokens : null,
+        },
     };
 }
+function mergeOpenAIToolCallDelta(target, delta) {
+    const index = Number.isInteger(delta?.index) ? delta.index : target.size;
+    const current = (0, utils_1.safeClone)(target.get(index) || { function: { arguments: '' } });
+    if (delta?.id) {
+        current.id = delta.id;
+    }
+    if (delta?.type) {
+        current.type = delta.type;
+    }
+    if (delta?.function?.name) {
+        current.function = {
+            ...(current.function || {}),
+            name: delta.function.name,
+        };
+    }
+    if (delta?.function?.arguments) {
+        current.function = {
+            ...(current.function || {}),
+            arguments: `${current.function?.arguments || ''}${delta.function.arguments}`,
+        };
+    }
+    target.set(index, current);
+}
+function serializeOpenAIToolCalls(toolCalls) {
+    return [...toolCalls.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, value]) => (0, utils_1.safeClone)(value));
+}

package/dist/server.d.ts

@@ -1,6 +1,7 @@
 import { type TraceServer } from './types';
 import { TraceStore } from './store';
 export declare function createTraceServer(store: TraceStore, options?: {
+    allowPortFallback?: boolean;
     host?: string;
     port?: number;
 }): TraceServer;

package/dist/server.js

@@ -11,11 +11,12 @@ const node_url_1 = require("node:url");
 const ui_1 = require("./ui");
 function createTraceServer(store, options = {}) {
     const host = options.host || '127.0.0.1';
-    const port = Number(options.port) || 4319;
+    const requestedPort = toPortNumber(options.port, 4319);
+    let activePort = requestedPort;
     const clients = new Set();
     const server = node_http_1.default.createServer(async (req, res) => {
         try {
-            const url = new node_url_1.URL(req.url || '/', `http://${req.headers.host || `${host}:${port}`}`);
+            const url = new node_url_1.URL(req.url || '/', `http://${req.headers.host || `${host}:${activePort}`}`);
             if (req.method === 'GET' && url.pathname === '/') {
                 sendHtml(res, (0, ui_1.renderAppHtml)());
                 return;
@@ -62,18 +63,13 @@ function createTraceServer(store, options = {}) {
     });
     return {
         async start() {
-            await new Promise((resolve, reject) => {
-                server.once('error', reject);
-                server.listen(port, host, () => {
-                    server.removeListener('error', reject);
-                    resolve();
-                });
-            });
+            await listenWithFallback(server, host, requestedPort, options.allowPortFallback);
+            activePort = getBoundPort(server, requestedPort);
             server.unref();
             return {
                 host,
-                port,
-                url: `http://${host}:${port}`,
+                port: activePort,
+                url: `http://${host}:${activePort}`,
             };
         },
         broadcast,
@@ -92,6 +88,41 @@ function createTraceServer(store, options = {}) {
         }
     }
 }
+async function listenWithFallback(server, host, port, allowPortFallback = false) {
+    await new Promise((resolve, reject) => {
+        const tryListen = (nextPort, canFallback) => {
+            const onError = (error) => {
+                server.removeListener('listening', onListening);
+                if (canFallback && error?.code === 'EADDRINUSE') {
+                    tryListen(0, false);
+                    return;
+                }
+                reject(error);
+            };
+            const onListening = () => {
+                server.removeListener('error', onError);
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(nextPort, host);
+        };
+        tryListen(port, allowPortFallback);
+    });
+}
+function getBoundPort(server, fallbackPort) {
+    const address = server.address();
+    if (address && typeof address === 'object' && typeof address.port === 'number') {
+        return address.port;
+    }
+    return fallbackPort;
+}
+function toPortNumber(value, fallback) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    return fallback;
+}
 function parseFilters(url) {
     return {
         search: url.searchParams.get('search') || undefined,

package/dist/session-nav.d.ts

@@ -31,4 +31,14 @@ export type SessionNavItem = {
     shortSessionId: string;
     status: "error" | "ok" | "pending";
 };
+export type SessionTreeSelection = {
+    selectedNodeId: string | null;
+    selectedTraceId: string | null;
+};
 export declare function deriveSessionNavItems(sessionNodes: SessionNavHierarchyNode[], traceById: Map<string, SessionNavTraceSummary>): SessionNavItem[];
+export declare function sortSessionNodesForNav(sessionNodes: SessionNavHierarchyNode[], traceById: Map<string, SessionNavTraceSummary>): SessionNavHierarchyNode[];
+export declare function findSessionNodePath(nodes: SessionNavHierarchyNode[], id: string, trail?: SessionNavHierarchyNode[]): SessionNavHierarchyNode[];
+export declare function findSessionNodeById(nodes: SessionNavHierarchyNode[], id: string): SessionNavHierarchyNode | null;
+export declare function getNewestTraceIdForNode(node: SessionNavHierarchyNode | null | undefined): string | null;
+export declare function resolveSessionTreeSelection(sessionNodes: SessionNavHierarchyNode[], selectedNodeId: string | null, selectedTraceId: string | null): SessionTreeSelection;
+export declare function getDefaultExpandedSessionTreeNodeIds(sessionNodes: SessionNavHierarchyNode[], activeSessionId: string | null, selectedNodeId: string | null): Set<string>;