@mtharrison/loupe 1.3.0 → 1.5.0

package/dist/index.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTraceEnabled = isTraceEnabled;
 exports.getLocalLLMTracer = getLocalLLMTracer;
@@ -11,6 +44,7 @@ exports.__resetLocalLLMTracerForTests = __resetLocalLLMTracerForTests;
 exports.wrapChatModel = wrapChatModel;
 exports.wrapOpenAIClient = wrapOpenAIClient;
 const node_async_hooks_1 = require("node:async_hooks");
+const childProcess = __importStar(require("node:child_process"));
 const server_1 = require("./server");
 const store_1 = require("./store");
 const ui_build_1 = require("./ui-build");
@@ -19,7 +53,10 @@ 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');
+    if (process.env.LLM_TRACE_ENABLED !== undefined) {
+        return (0, utils_1.envFlag)('LLM_TRACE_ENABLED');
+    }
+    return process.env.NODE_ENV === 'development';
 }
 function getLocalLLMTracer(config = {}) {
     if (!singleton) {
@@ -180,6 +217,7 @@ function wrapOpenAIClient(client, getContext, config) {
 class LocalLLMTracerImpl {
     config;
     loggedUrl;
+    openedBrowser;
     portWasExplicit;
     server;
     serverFailed;
@@ -202,6 +240,7 @@ class LocalLLMTracerImpl {
         this.serverStartPromise = null;
         this.serverFailed = false;
         this.loggedUrl = false;
+        this.openedBrowser = false;
         this.uiWatcher = null;
     }
     configure(config = {}) {
@@ -278,6 +317,10 @@ class LocalLLMTracerImpl {
                     this.loggedUrl = true;
                     process.stdout.write(`[llm-trace] dashboard: ${this.serverInfo.url}\n`);
                 }
+                if (!this.openedBrowser && this.serverInfo && shouldAutoOpenDashboard()) {
+                    this.openedBrowser = true;
+                    openBrowser(this.serverInfo.url);
+                }
                 return this.serverInfo;
             }
             catch (error) {
@@ -292,6 +335,37 @@ class LocalLLMTracerImpl {
         return this.serverStartPromise;
     }
 }
+function shouldAutoOpenDashboard() {
+    if (process.env.LOUPE_OPEN_BROWSER === '0') {
+        return false;
+    }
+    return (process.env.NODE_ENV === 'development'
+        && !process.env.CI
+        && !!process.stdout.isTTY);
+}
+function openBrowser(url) {
+    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 = childProcess.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.
+    }
+}
 function normaliseRequest(request) {
     return {
         input: (0, utils_1.safeClone)(request?.input),

package/dist/session-nav.d.ts

@@ -41,4 +41,4 @@ export declare function findSessionNodePath(nodes: SessionNavHierarchyNode[], id
 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>;
+export declare function getDefaultExpandedSessionTreeNodeIds(sessionNodes: SessionNavHierarchyNode[], activeSessionId: string | null, selectedNodeId: string | null, selectedTraceId?: string | null): Set<string>;

package/dist/session-nav.js

@@ -66,7 +66,7 @@ function resolveSessionTreeSelection(sessionNodes, selectedNodeId, selectedTrace
         selectedTraceId: nextSelectedTraceId,
     };
 }
-function getDefaultExpandedSessionTreeNodeIds(sessionNodes, activeSessionId, selectedNodeId) {
+function getDefaultExpandedSessionTreeNodeIds(sessionNodes, activeSessionId, selectedNodeId, selectedTraceId = null) {
     const expanded = new Set();
     const activeSession = (activeSessionId
         ? sessionNodes.find((node) => node.id === activeSessionId) ?? null
@@ -89,6 +89,13 @@ function getDefaultExpandedSessionTreeNodeIds(sessionNodes, activeSessionId, sel
             }
         }
     }
+    if (selectedTraceId) {
+        for (const node of findSessionNodePath([activeSession], `trace:${selectedTraceId}`)) {
+            if (node.children.length) {
+                expanded.add(node.id);
+            }
+        }
+    }
     return expanded;
 }
 function deriveSessionNavItem(node, traceById) {

package/dist/store.d.ts

@@ -17,6 +17,7 @@ export declare class TraceStore extends EventEmitter {
     clear(): void;
     hierarchy(filters?: TraceFilters): HierarchyResponse;
     private recordStart;
+    private findTraceBySpanReference;
     private evictIfNeeded;
     private cloneTrace;
     private filteredTraces;

package/dist/store.js

@@ -141,51 +141,49 @@ class TraceStore extends node_events_1.EventEmitter {
             };
         }
         const roots = new Map();
+        const traceBySpanId = new Map();
+        const traceNodeByTraceId = new Map();
+        const traceSessionByTraceId = new Map();
+        const parentNodeById = new Map();
         for (const trace of traces) {
-            const sessionId = trace.hierarchy.sessionId || 'unknown-session';
+            const sessionId = getTraceSessionId(trace);
             const sessionNode = getOrCreateNode(roots, `session:${sessionId}`, 'session', `Session ${sessionId}`, {
                 sessionId,
                 chatId: trace.hierarchy.chatId,
-            });
-            const lineage = [sessionNode];
-            const rootActorId = trace.hierarchy.rootActorId || 'unknown-actor';
-            const actorNode = getOrCreateNode(sessionNode.children, `actor:${sessionId}:${rootActorId}`, 'actor', rootActorId, {
-                actorId: rootActorId,
-                rootActorId,
-                sessionId,
+                rootActorId: trace.hierarchy.rootActorId,
                 topLevelAgentId: trace.hierarchy.topLevelAgentId,
             });
-            lineage.push(actorNode);
-            let currentNode = actorNode;
-            if (trace.hierarchy.kind === 'guardrail') {
-                const label = `${trace.hierarchy.guardrailPhase || 'guardrail'} guardrail`;
-                currentNode = getOrCreateNode(currentNode.children, `guardrail:${sessionId}:${rootActorId}:${trace.context.guardrailType || label}`, 'guardrail', label, {
-                    guardrailPhase: trace.hierarchy.guardrailPhase || null,
-                    guardrailType: trace.context.guardrailType || null,
-                    systemType: trace.context.systemType || null,
-                    watchdogPhase: trace.hierarchy.watchdogPhase || null,
-                });
-                lineage.push(currentNode);
-            }
-            else if (trace.hierarchy.childActorId) {
-                currentNode = getOrCreateNode(currentNode.children, `child-actor:${sessionId}:${rootActorId}:${trace.hierarchy.childActorId}`, 'child-actor', trace.hierarchy.childActorId, {
-                    actorId: trace.hierarchy.childActorId,
-                    childActorId: trace.hierarchy.childActorId,
-                    delegatedAgentId: trace.hierarchy.delegatedAgentId,
-                });
-                lineage.push(currentNode);
+            const traceNode = createTraceNode(trace);
+            traceBySpanId.set(trace.spanContext.spanId, trace);
+            traceNodeByTraceId.set(trace.id, traceNode);
+            traceSessionByTraceId.set(trace.id, sessionId);
+        }
+        for (const trace of traces) {
+            const sessionId = traceSessionByTraceId.get(trace.id) || 'unknown-session';
+            const sessionNode = roots.get(`session:${sessionId}`);
+            const traceNode = traceNodeByTraceId.get(trace.id);
+            if (!sessionNode || !traceNode) {
+                continue;
             }
-            if (trace.hierarchy.stage) {
-                currentNode = getOrCreateNode(currentNode.children, `stage:${sessionId}:${rootActorId}:${trace.hierarchy.childActorId || 'root'}:${trace.hierarchy.stage}`, 'stage', trace.hierarchy.stage, {
-                    stage: trace.hierarchy.stage,
-                    workflowState: trace.hierarchy.workflowState,
-                });
-                lineage.push(currentNode);
+            const parentTrace = trace.parentSpanId ? traceBySpanId.get(trace.parentSpanId) : null;
+            const parentTraceNode = parentTrace &&
+                traceSessionByTraceId.get(parentTrace.id) === sessionId &&
+                parentTrace.id !== trace.id
+                ? traceNodeByTraceId.get(parentTrace.id) || null
+                : null;
+            parentNodeById.set(traceNode.id, parentTraceNode || sessionNode);
+        }
+        for (const trace of traces) {
+            const traceNode = traceNodeByTraceId.get(trace.id);
+            const parentNode = traceNode ? parentNodeById.get(traceNode.id) || null : null;
+            if (!traceNode || !parentNode) {
+                continue;
             }
-            const traceNode = createTraceNode(trace);
-            currentNode.children.set(traceNode.id, traceNode);
-            for (const node of new Set(lineage)) {
-                applyTraceRollup(node, trace);
+            parentNode.children.set(traceNode.id, traceNode);
+            let currentNode = parentNode;
+            while (currentNode) {
+                applyTraceRollup(currentNode, trace);
+                currentNode = parentNodeById.get(currentNode.id) || null;
             }
         }
         return {
@@ -195,9 +193,9 @@ class TraceStore extends node_events_1.EventEmitter {
         };
     }
     recordStart(mode, context, request, options = {}) {
-        const traceContext = (0, utils_1.normalizeTraceContext)(context, mode);
+        const traceContext = applyConversationIdToContext((0, utils_1.normalizeTraceContext)(context, mode), options.attributes);
         const traceId = randomId();
-        const parentSpan = options.parentSpanId ? this.traces.get(options.parentSpanId) : null;
+        const parentSpan = this.findTraceBySpanReference(options.parentSpanId);
         const startedAt = new Date().toISOString();
         const trace = {
             attributes: buildSpanAttributes(traceContext, mode, request, options.attributes),
@@ -253,6 +251,21 @@ class TraceStore extends node_events_1.EventEmitter {
         this.publish('span:start', traceId, { trace: this.cloneTrace(trace) });
         return traceId;
     }
+    findTraceBySpanReference(spanReference) {
+        if (!spanReference) {
+            return null;
+        }
+        const byTraceId = this.traces.get(spanReference);
+        if (byTraceId) {
+            return byTraceId;
+        }
+        for (const trace of this.traces.values()) {
+            if (trace.spanContext.spanId === spanReference) {
+                return trace;
+            }
+        }
+        return null;
+    }
     evictIfNeeded() {
         while (this.order.length > this.maxTraces) {
             const oldest = this.order.shift();
@@ -420,6 +433,35 @@ function buildGroupHierarchy(traces, groupBy) {
     }
     return [...groups.values()].map(serialiseNode);
 }
+function getTraceSessionId(trace) {
+    const conversationId = toNonEmptyString(trace.attributes?.['gen_ai.conversation.id']);
+    return conversationId || trace.hierarchy.sessionId || 'unknown-session';
+}
+function applyConversationIdToContext(context, extraAttributes) {
+    const conversationId = toNonEmptyString(extraAttributes?.['gen_ai.conversation.id']);
+    if (!conversationId || conversationId === context.sessionId) {
+        return context;
+    }
+    return {
+        ...context,
+        sessionId: conversationId,
+        chatId: conversationId,
+        rootSessionId: context.rootSessionId || conversationId,
+        rootChatId: context.rootChatId || conversationId,
+        tags: {
+            ...context.tags,
+            sessionId: conversationId,
+            chatId: conversationId,
+            rootSessionId: context.rootSessionId || conversationId,
+            rootChatId: context.rootChatId || conversationId,
+        },
+        hierarchy: {
+            ...context.hierarchy,
+            sessionId: conversationId,
+            chatId: conversationId,
+        },
+    };
+}
 function randomId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -469,6 +511,9 @@ function getDefaultSpanName(context, mode) {
     const prefix = context.provider || 'llm';
     return `${prefix}.${mode}`;
 }
+function toNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value : null;
+}
 function buildSpanAttributes(context, mode, request, extraAttributes) {
     const base = {
         'gen_ai.conversation.id': context.sessionId || undefined,

package/dist/utils.js

@@ -134,7 +134,9 @@ function normalizeTraceContext(context, mode) {
     const explicitKind = normalizeKind(raw.kind);
     let kind = explicitKind || 'actor';
     if (!explicitKind) {
-        if (guardrailType || guardrailPhase) {
+        // Keep generic guardrail metadata from masking actual delegated-agent spans.
+        // Explicit guardrail spans or spans with a concrete phase still remain guardrails.
+        if (guardrailPhase || (guardrailType && !isChildActor)) {
             kind = 'guardrail';
         }
         else if (stage) {