@mtharrison/loupe 1.1.0 → 1.1.1

package/dist/session-nav.d.ts

@@ -0,0 +1,34 @@
+export type SessionNavHierarchyNode = {
+    children: SessionNavHierarchyNode[];
+    count: number;
+    id: string;
+    meta: Record<string, any>;
+    traceIds: string[];
+    type: string;
+};
+export type SessionNavTraceSummary = {
+    costUsd: number | null;
+    flags?: {
+        hasHighlights: boolean;
+    };
+    hierarchy: {
+        rootActorId: string;
+        sessionId: string;
+    };
+    id: string;
+    startedAt: string;
+    status: "pending" | "ok" | "error";
+};
+export type SessionNavItem = {
+    callCount: number;
+    costUsd: number | null;
+    hasHighlights: boolean;
+    id: string;
+    latestStartedAt: string | null;
+    latestTimestamp: string | null;
+    primaryActor: string;
+    primaryLabel: string;
+    shortSessionId: string;
+    status: "error" | "ok" | "pending";
+};
+export declare function deriveSessionNavItems(sessionNodes: SessionNavHierarchyNode[], traceById: Map<string, SessionNavTraceSummary>): SessionNavItem[];

package/dist/session-nav.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveSessionNavItems = deriveSessionNavItems;
+function deriveSessionNavItems(sessionNodes, traceById) {
+    return sessionNodes
+        .map((node) => deriveSessionNavItem(node, traceById))
+        .sort(compareSessionNavItems);
+}
+function deriveSessionNavItem(node, traceById) {
+    const traces = node.traceIds
+        .map((traceId) => traceById.get(traceId))
+        .filter((trace) => Boolean(trace));
+    const latestTrace = getLatestTrace(traces);
+    const sessionId = getSessionId(node) ?? latestTrace?.hierarchy.sessionId ?? "unknown";
+    const shortSessionId = shortId(sessionId);
+    const primaryActor = getPrimaryActor(node) ?? latestTrace?.hierarchy.rootActorId ?? shortSessionId;
+    return {
+        callCount: node.count,
+        costUsd: getCostUsd(node, traces),
+        hasHighlights: traces.some((trace) => Boolean(trace.flags?.hasHighlights)),
+        id: node.id,
+        latestStartedAt: latestTrace?.startedAt ?? null,
+        latestTimestamp: latestTrace?.startedAt
+            ? formatCompactTimestamp(latestTrace.startedAt)
+            : null,
+        primaryActor,
+        primaryLabel: primaryActor,
+        shortSessionId,
+        status: getAggregateStatus(traces),
+    };
+}
+function getCostUsd(node, traces) {
+    if (typeof node.meta?.costUsd === "number" &&
+        Number.isFinite(node.meta.costUsd)) {
+        return roundCostUsd(node.meta.costUsd);
+    }
+    const traceCosts = traces
+        .map((trace) => trace.costUsd)
+        .filter((value) => typeof value === "number" && Number.isFinite(value));
+    if (!traceCosts.length) {
+        return null;
+    }
+    return roundCostUsd(traceCosts.reduce((sum, value) => sum + value, 0));
+}
+function getLatestTrace(traces) {
+    let latestTrace = null;
+    let latestTimestamp = Number.NEGATIVE_INFINITY;
+    for (const trace of traces) {
+        const nextTimestamp = Date.parse(trace.startedAt);
+        if (!Number.isFinite(nextTimestamp)) {
+            continue;
+        }
+        if (nextTimestamp > latestTimestamp) {
+            latestTrace = trace;
+            latestTimestamp = nextTimestamp;
+        }
+    }
+    return latestTrace;
+}
+function getAggregateStatus(traces) {
+    if (traces.some((trace) => trace.status === "error")) {
+        return "error";
+    }
+    if (traces.some((trace) => trace.status === "pending")) {
+        return "pending";
+    }
+    return "ok";
+}
+function getSessionId(node) {
+    if (typeof node.meta?.sessionId === "string" && node.meta.sessionId) {
+        return node.meta.sessionId;
+    }
+    if (node.id.startsWith("session:")) {
+        return node.id.slice("session:".length);
+    }
+    return null;
+}
+function getPrimaryActor(node) {
+    const actorNode = node.children.find((child) => child.type === "actor");
+    return (actorNode?.meta?.actorId ??
+        actorNode?.meta?.rootActorId ??
+        node.meta?.rootActorId ??
+        null);
+}
+function compareSessionNavItems(left, right) {
+    const timestampDelta = toSortableTimestamp(right.latestStartedAt) -
+        toSortableTimestamp(left.latestStartedAt);
+    if (timestampDelta !== 0) {
+        return timestampDelta;
+    }
+    const statusDelta = getStatusRank(left.status) - getStatusRank(right.status);
+    if (statusDelta !== 0) {
+        return statusDelta;
+    }
+    const costDelta = (right.costUsd ?? 0) - (left.costUsd ?? 0);
+    if (costDelta !== 0) {
+        return costDelta;
+    }
+    return left.primaryLabel.localeCompare(right.primaryLabel);
+}
+function getStatusRank(status) {
+    switch (status) {
+        case "error":
+            return 0;
+        case "pending":
+            return 1;
+        default:
+            return 2;
+    }
+}
+function toSortableTimestamp(value) {
+    if (!value) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY;
+}
+function roundCostUsd(value) {
+    return Math.round(value * 1e12) / 1e12;
+}
+function shortId(value) {
+    if (!value) {
+        return "unknown";
+    }
+    return value.length > 8 ? value.slice(0, 8) : value;
+}
+function formatCompactTimestamp(value) {
+    return new Date(value).toLocaleTimeString([], {
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}

package/dist/store.js

@@ -220,7 +220,10 @@ class TraceStore extends node_events_1.EventEmitter {
         }
     }
     cloneTrace(trace) {
-        return (0, utils_1.safeClone)(trace);
+        return {
+            ...(0, utils_1.safeClone)(trace),
+            insights: (0, utils_1.getTraceInsights)(trace),
+        };
     }
     filteredTraces(filters = {}) {
         const tagFilters = normalizeTagFilters(filters.tags || filters.tagFilters);

package/dist/types.d.ts

@@ -79,6 +79,27 @@ export type TraceRequest = {
     input?: Record<string, any>;
     options?: Record<string, any>;
 };
+export type TraceStructuredInputInsight = {
+    format: 'xml';
+    role: string;
+    snippet: string;
+    tags: string[];
+};
+export type TraceHighlightInsight = {
+    description: string;
+    kind: string;
+    snippet: string;
+    source: string;
+    title: string;
+};
+export type TraceInsights = {
+    highlights: TraceHighlightInsight[];
+    structuredInputs: TraceStructuredInputInsight[];
+};
+export type TraceSummaryFlags = {
+    hasHighlights: boolean;
+    hasStructuredInput: boolean;
+};
 export type TraceRecord = {
     context: NormalizedTraceContext;
     endedAt: string | null;
@@ -106,6 +127,7 @@ export type TraceRecord = {
             usage: Record<string, any> | null;
         };
     };
+    insights?: TraceInsights;
     tags: TraceTags;
     usage: Record<string, any> | null;
 };
@@ -113,6 +135,7 @@ export type TraceSummary = {
     costUsd: number | null;
     durationMs: number | null;
     endedAt: string | null;
+    flags?: TraceSummaryFlags;
     hierarchy: TraceHierarchy;
     id: string;
     kind: string;

package/dist/ui-build.js

@@ -24,7 +24,7 @@ function createBuildOptions() {
         loader: {
             '.svg': 'dataurl',
         },
-        splitting: false,
+        splitting: true,
         minify: false,
         sourcemap: false,
         logLevel: 'silent',

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import { type NormalizedTraceContext, type TraceContext, type TraceMode, type TraceRecord, type TraceSummary } from './types';
+import { type NormalizedTraceContext, type TraceContext, type TraceInsights, type TraceMode, type TraceRecord, type TraceSummary } from './types';
 export declare function safeClone<T>(value: T): T;
 export declare function toErrorPayload(error: any): Record<string, any> | null;
 export declare function sanitizeHeaders(headers: Record<string, any> | undefined): Record<string, any>;
@@ -7,4 +7,5 @@ export declare function stringifyRecord(record: Record<string, any>): Record<str
 export declare function normalizeTraceContext(context: TraceContext | undefined, mode: TraceMode): NormalizedTraceContext;
 export declare function summariseValue(value: unknown, maxLength?: number): string;
 export declare function getUsageCostUsd(usage: Record<string, any> | null | undefined): number | null;
+export declare function getTraceInsights(trace: TraceRecord): TraceInsights;
 export declare function toSummary(trace: TraceRecord): TraceSummary;

package/dist/utils.js

@@ -8,6 +8,7 @@ exports.stringifyRecord = stringifyRecord;
 exports.normalizeTraceContext = normalizeTraceContext;
 exports.summariseValue = summariseValue;
 exports.getUsageCostUsd = getUsageCostUsd;
+exports.getTraceInsights = getTraceInsights;
 exports.toSummary = toSummary;
 function safeClone(value) {
     if (value === undefined) {
@@ -253,12 +254,84 @@ function extractResponsePreview(trace) {
     }
     return '';
 }
+function getTraceInsights(trace) {
+    const structuredInputs = [];
+    const highlights = [];
+    const seenStructured = new Set();
+    const seenHighlights = new Set();
+    for (const message of collectTraceMessages(trace)) {
+        const text = toInsightText(message.content);
+        if (!text) {
+            continue;
+        }
+        const structuredMarkup = detectStructuredMarkup(text);
+        if (structuredMarkup) {
+            const structuredKey = `${message.source}:${structuredMarkup.tags.join('|')}:${structuredMarkup.snippet}`;
+            if (!seenStructured.has(structuredKey)) {
+                structuredInputs.push({
+                    format: 'xml',
+                    role: message.role,
+                    snippet: structuredMarkup.snippet,
+                    tags: structuredMarkup.tags,
+                });
+                seenStructured.add(structuredKey);
+            }
+            const highlightKey = `structured:${message.source}:${structuredMarkup.tags.join('|')}`;
+            if (!seenHighlights.has(highlightKey)) {
+                highlights.push({
+                    kind: 'structured-input',
+                    title: `Structured ${message.role} input`,
+                    description: `Contains XML-like markup (${structuredMarkup.tags.slice(0, 3).join(', ')}) that may influence guardrail behavior.`,
+                    source: message.source,
+                    snippet: structuredMarkup.snippet,
+                });
+                seenHighlights.add(highlightKey);
+            }
+        }
+        if ((message.role === 'user' || message.role === 'system') && looksLikeLongPrompt(text)) {
+            const longKey = `long:${message.source}`;
+            if (!seenHighlights.has(longKey)) {
+                highlights.push({
+                    kind: 'long-message',
+                    title: `Long ${message.role} message`,
+                    description: 'Large prompt payloads often hide embedded instructions, policies, or contextual data worth inspecting.',
+                    source: message.source,
+                    snippet: createSnippet(text, 240),
+                });
+                seenHighlights.add(longKey);
+            }
+        }
+    }
+    if (trace.kind === 'guardrail') {
+        const contextSummary = [trace.context.guardrailPhase, trace.context.guardrailType, trace.context.systemType]
+            .filter(Boolean)
+            .join(' / ');
+        if (contextSummary) {
+            highlights.push({
+                kind: 'guardrail-context',
+                title: `${capitalize(trace.context.guardrailPhase || 'guardrail')} guardrail context`,
+                description: `This trace ran inside ${contextSummary}.`,
+                source: 'trace:guardrail',
+                snippet: createSnippet(contextSummary, 180),
+            });
+        }
+    }
+    return {
+        structuredInputs,
+        highlights,
+    };
+}
 function toSummary(trace) {
     const durationMs = trace.endedAt ? Math.max(0, Date.parse(trace.endedAt) - Date.parse(trace.startedAt)) : null;
+    const insights = trace.insights || getTraceInsights(trace);
     return {
         costUsd: getUsageCostUsd(trace.usage),
         durationMs,
         endedAt: trace.endedAt,
+        flags: {
+            hasHighlights: insights.highlights.length > 0,
+            hasStructuredInput: insights.structuredInputs.length > 0,
+        },
         hierarchy: safeClone(trace.hierarchy),
         id: trace.id,
         kind: trace.kind,
@@ -278,3 +351,103 @@ function toSummary(trace) {
         tags: safeClone(trace.tags),
     };
 }
+function collectTraceMessages(trace) {
+    const entries = [];
+    const requestMessages = trace.request?.input?.messages;
+    if (Array.isArray(requestMessages)) {
+        for (const [index, message] of requestMessages.entries()) {
+            entries.push({
+                content: message?.content,
+                role: typeof message?.role === 'string' ? message.role : 'unknown',
+                source: `request:${index}`,
+            });
+        }
+    }
+    const responseMessage = trace.response?.message || trace.stream?.reconstructed?.message;
+    if (responseMessage?.content !== undefined) {
+        entries.push({
+            content: responseMessage.content,
+            role: typeof responseMessage.role === 'string' ? responseMessage.role : 'assistant',
+            source: 'response:0',
+        });
+    }
+    return entries;
+}
+function toInsightText(content) {
+    if (typeof content === 'string') {
+        const trimmed = content.trim();
+        return trimmed ? trimmed : null;
+    }
+    if (Array.isArray(content)) {
+        const parts = content
+            .map((item) => {
+            if (typeof item === 'string') {
+                return item;
+            }
+            if (typeof item?.text === 'string') {
+                return item.text;
+            }
+            if (typeof item?.text?.value === 'string') {
+                return item.text.value;
+            }
+            if (typeof item?.content === 'string') {
+                return item.content;
+            }
+            return '';
+        })
+            .filter(Boolean);
+        return parts.length ? parts.join('\n\n').trim() : null;
+    }
+    if (typeof content?.text === 'string') {
+        return content.text.trim() || null;
+    }
+    if (typeof content?.text?.value === 'string') {
+        return content.text.value.trim() || null;
+    }
+    if (typeof content?.content === 'string') {
+        return content.content.trim() || null;
+    }
+    return null;
+}
+function detectStructuredMarkup(text) {
+    const tagRegex = /<\/?([A-Za-z][\w:-]*)\b[^>]*>/g;
+    const tagNames = [];
+    let match = tagRegex.exec(text);
+    while (match) {
+        tagNames.push(match[1].toLowerCase());
+        match = tagRegex.exec(text);
+    }
+    const uniqueTags = [...new Set(tagNames)];
+    if (!uniqueTags.length) {
+        return null;
+    }
+    const hasInstructionalTag = uniqueTags.some((tag) => ['assistant', 'instruction', 'option', 'policy', 'system', 'user'].includes(tag));
+    const hasMultipleTags = uniqueTags.length >= 2;
+    const hasClosingTag = /<\/[A-Za-z][\w:-]*>/.test(text);
+    if (!hasClosingTag && !hasInstructionalTag && !hasMultipleTags) {
+        return null;
+    }
+    return {
+        snippet: createSnippet(text, 220),
+        tags: uniqueTags.slice(0, 6),
+    };
+}
+function looksLikeLongPrompt(text) {
+    return text.length >= 1200 || countLines(text) >= 20;
+}
+function countLines(text) {
+    return text.split(/\r?\n/).length;
+}
+function createSnippet(text, maxLength) {
+    const trimmed = text.trim().replace(/\s+/g, ' ');
+    if (trimmed.length <= maxLength) {
+        return trimmed;
+    }
+    return `${trimmed.slice(0, maxLength - 1)}...`;
+}
+function capitalize(value) {
+    if (!value) {
+        return '';
+    }
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}

package/package.json

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