@mtharrison/loupe 1.0.0

package/dist/store.js

@@ -0,0 +1,377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceStore = void 0;
+const node_events_1 = require("node:events");
+const utils_1 = require("./utils");
+class TraceStore extends node_events_1.EventEmitter {
+    maxTraces;
+    order;
+    traces;
+    constructor(options = {}) {
+        super();
+        this.maxTraces = Math.max(1, Number(options.maxTraces) || 1000);
+        this.order = [];
+        this.traces = new Map();
+    }
+    recordInvokeStart(context, request) {
+        return this.recordStart('invoke', context, request);
+    }
+    recordInvokeFinish(traceId, response) {
+        const trace = this.traces.get(traceId);
+        if (!trace) {
+            return;
+        }
+        trace.response = (0, utils_1.safeClone)(response);
+        trace.usage = (0, utils_1.safeClone)(response?.usage);
+        trace.status = 'ok';
+        trace.endedAt = new Date().toISOString();
+        this.publish('trace:update', traceId, { trace: this.cloneTrace(trace) });
+    }
+    recordStreamStart(context, request) {
+        return this.recordStart('stream', context, request);
+    }
+    recordStreamChunk(traceId, chunk) {
+        const trace = this.traces.get(traceId);
+        if (!trace || !trace.stream) {
+            return;
+        }
+        const clone = (0, utils_1.safeClone)(chunk);
+        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') {
+            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 (chunk?.type === 'begin') {
+            trace.stream.reconstructed.message.role = chunk.role;
+        }
+        if (chunk?.type === 'finish') {
+            trace.response = clone;
+            trace.usage = (0, utils_1.safeClone)(chunk.usage);
+            trace.stream.reconstructed.message = {
+                ...((0, utils_1.safeClone)(chunk.message) || {}),
+                content: trace.stream.reconstructed.message.content ||
+                    (typeof chunk.message?.content === 'string' ? chunk.message.content : chunk.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.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);
+        const response = {
+            items,
+            total: this.order.length,
+            filtered: items.length,
+        };
+        if (filters.groupBy) {
+            response.groups = groupTraceSummaries(items, filters.groupBy);
+        }
+        return response;
+    }
+    get(traceId) {
+        const trace = this.traces.get(traceId);
+        return trace ? this.cloneTrace(trace) : null;
+    }
+    clear() {
+        this.order = [];
+        this.traces.clear();
+        this.publish('trace:clear', null, {});
+    }
+    hierarchy(filters = {}) {
+        const traces = this.filteredTraces(filters);
+        if (filters.groupBy) {
+            return {
+                total: this.order.length,
+                filtered: traces.length,
+                rootNodes: buildGroupHierarchy(traces, filters.groupBy),
+            };
+        }
+        const roots = new Map();
+        for (const trace of traces) {
+            const sessionId = trace.hierarchy.sessionId || 'unknown-session';
+            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,
+                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);
+            }
+            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 traceNode = createTraceNode(trace);
+            currentNode.children.set(traceNode.id, traceNode);
+            for (const node of new Set(lineage)) {
+                applyTraceRollup(node, trace);
+            }
+        }
+        return {
+            total: this.order.length,
+            filtered: traces.length,
+            rootNodes: [...roots.values()].map(serialiseNode),
+        };
+    }
+    recordStart(mode, context, request) {
+        const traceContext = (0, utils_1.normalizeTraceContext)(context, mode);
+        const traceId = randomId();
+        const startedAt = new Date().toISOString();
+        const trace = {
+            context: traceContext,
+            endedAt: null,
+            error: null,
+            hierarchy: traceContext.hierarchy,
+            id: traceId,
+            kind: traceContext.kind,
+            mode,
+            model: traceContext.model,
+            provider: traceContext.provider,
+            request: {
+                input: (0, utils_1.safeClone)(request?.input),
+                options: {
+                    ...(request?.options ? (0, utils_1.safeClone)(request.options) : {}),
+                    headers: (0, utils_1.sanitizeHeaders)(request?.options?.headers),
+                },
+            },
+            response: null,
+            startedAt,
+            status: 'pending',
+            stream: mode === 'stream'
+                ? {
+                    chunkCount: 0,
+                    events: [],
+                    firstChunkMs: null,
+                    reconstructed: {
+                        message: { role: null, content: null },
+                        tool_calls: [],
+                        usage: null,
+                    },
+                }
+                : null,
+            tags: traceContext.tags,
+            usage: null,
+        };
+        this.order.push(traceId);
+        this.traces.set(traceId, trace);
+        this.evictIfNeeded();
+        this.publish('trace:add', traceId, { trace: this.cloneTrace(trace) });
+        return traceId;
+    }
+    evictIfNeeded() {
+        while (this.order.length > this.maxTraces) {
+            const oldest = this.order.shift();
+            const removed = oldest ? this.traces.get(oldest) : null;
+            if (oldest) {
+                this.traces.delete(oldest);
+            }
+            this.publish('trace:evict', oldest || null, removed ? { trace: this.cloneTrace(removed) } : {});
+        }
+    }
+    cloneTrace(trace) {
+        return (0, utils_1.safeClone)(trace);
+    }
+    filteredTraces(filters = {}) {
+        const tagFilters = normalizeTagFilters(filters.tags || filters.tagFilters);
+        return this.order
+            .map((id) => this.traces.get(id))
+            .filter(Boolean)
+            .filter((trace) => {
+            if (filters.status && trace.status !== filters.status) {
+                return false;
+            }
+            if (filters.kind && trace.kind !== filters.kind) {
+                return false;
+            }
+            if (filters.model && trace.model !== filters.model) {
+                return false;
+            }
+            if (filters.provider && trace.provider !== filters.provider) {
+                return false;
+            }
+            if (filters.traceIds && !filters.traceIds.includes(trace.id)) {
+                return false;
+            }
+            if (tagFilters.length > 0) {
+                for (const [key, value] of tagFilters) {
+                    if (trace.tags[key] !== value) {
+                        return false;
+                    }
+                }
+            }
+            if (filters.search) {
+                const needle = String(filters.search).toLowerCase();
+                const haystack = JSON.stringify({
+                    context: trace.context,
+                    error: trace.error,
+                    request: trace.request,
+                    response: trace.response,
+                    stream: trace.stream,
+                    tags: trace.tags,
+                }).toLowerCase();
+                if (!haystack.includes(needle)) {
+                    return false;
+                }
+            }
+            return true;
+        })
+            .reverse();
+    }
+    publish(type, traceId, payload) {
+        const event = {
+            type,
+            traceId,
+            timestamp: new Date().toISOString(),
+            ...payload,
+        };
+        this.emit('event', event);
+    }
+}
+exports.TraceStore = TraceStore;
+function groupTraceSummaries(items, groupBy) {
+    const groups = new Map();
+    for (const item of items) {
+        const groupValue = item.tags[groupBy] || 'ungrouped';
+        const group = groups.get(groupValue) || {
+            value: groupValue,
+            count: 0,
+            items: [],
+        };
+        group.count += 1;
+        group.items.push(item);
+        groups.set(groupValue, group);
+    }
+    return [...groups.values()];
+}
+function normalizeTagFilters(value) {
+    if (!value) {
+        return [];
+    }
+    const entries = Array.isArray(value) ? value : [value];
+    return entries
+        .flatMap((entry) => String(entry).split(','))
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => {
+        const [key, ...rest] = entry.split(':');
+        return [key, rest.join(':')];
+    })
+        .filter(([key, filterValue]) => key && filterValue);
+}
+function getOrCreateNode(collection, id, type, label, meta = {}) {
+    if (!collection.has(id)) {
+        collection.set(id, {
+            id,
+            type,
+            label,
+            count: 0,
+            meta,
+            traceIds: [],
+            children: new Map(),
+        });
+    }
+    return collection.get(id);
+}
+function createTraceNode(trace) {
+    return {
+        id: `trace:${trace.id}`,
+        type: 'trace',
+        label: trace.model ? `${trace.model} ${trace.mode}` : trace.id,
+        count: 1,
+        meta: {
+            costUsd: (0, utils_1.getUsageCostUsd)(trace.usage),
+            traceId: trace.id,
+            status: trace.status,
+            provider: trace.provider,
+            model: trace.model,
+        },
+        traceIds: [trace.id],
+        children: new Map(),
+    };
+}
+function applyTraceRollup(node, trace) {
+    node.traceIds.push(trace.id);
+    node.count += 1;
+    const traceCost = (0, utils_1.getUsageCostUsd)(trace.usage);
+    if (traceCost !== null) {
+        node.meta.costUsd = (typeof node.meta.costUsd === 'number' ? node.meta.costUsd : 0) + traceCost;
+    }
+}
+function serialiseNode(node) {
+    return {
+        id: node.id,
+        type: node.type,
+        label: node.label,
+        count: node.count,
+        traceIds: [...node.traceIds],
+        meta: (0, utils_1.safeClone)(node.meta),
+        children: [...node.children.values()].map(serialiseNode),
+    };
+}
+function buildGroupHierarchy(traces, groupBy) {
+    const groups = new Map();
+    for (const trace of traces) {
+        const value = trace.tags[groupBy] || 'ungrouped';
+        const node = getOrCreateNode(groups, `group:${groupBy}:${value}`, 'group', `${groupBy}: ${value}`, {
+            groupBy,
+            value,
+        });
+        applyTraceRollup(node, trace);
+        node.children.set(`trace:${trace.id}`, createTraceNode(trace));
+    }
+    return [...groups.values()].map(serialiseNode);
+}
+function randomId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/theme.d.ts

@@ -0,0 +1,6 @@
+export type ThemeMode = 'light' | 'dark';
+export declare const THEME_STORAGE_KEY = "llm-trace-theme";
+export declare function isThemeMode(value: unknown): value is ThemeMode;
+export declare function resolvePreferredTheme(): ThemeMode;
+export declare function applyTheme(theme: ThemeMode): void;
+export declare function renderThemeBootstrapScript(): string;

package/dist/theme.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THEME_STORAGE_KEY = void 0;
+exports.isThemeMode = isThemeMode;
+exports.resolvePreferredTheme = resolvePreferredTheme;
+exports.applyTheme = applyTheme;
+exports.renderThemeBootstrapScript = renderThemeBootstrapScript;
+exports.THEME_STORAGE_KEY = 'llm-trace-theme';
+function isThemeMode(value) {
+    return value === 'light' || value === 'dark';
+}
+function resolvePreferredTheme() {
+    const documentRef = getDocument();
+    if (documentRef) {
+        const theme = documentRef.documentElement?.dataset?.theme;
+        if (isThemeMode(theme)) {
+            return theme;
+        }
+    }
+    const windowRef = getWindow();
+    if (windowRef) {
+        try {
+            const stored = windowRef.localStorage?.getItem(exports.THEME_STORAGE_KEY);
+            if (isThemeMode(stored)) {
+                return stored;
+            }
+        }
+        catch (_error) {
+            // Ignore storage errors and fall back to system preference.
+        }
+        if (windowRef.matchMedia?.('(prefers-color-scheme: dark)').matches) {
+            return 'dark';
+        }
+    }
+    return 'light';
+}
+function applyTheme(theme) {
+    const documentRef = getDocument();
+    if (documentRef) {
+        documentRef.documentElement.dataset.theme = theme;
+        documentRef.documentElement.style.colorScheme = theme;
+    }
+    const windowRef = getWindow();
+    if (windowRef) {
+        try {
+            windowRef.localStorage?.setItem(exports.THEME_STORAGE_KEY, theme);
+        }
+        catch (_error) {
+            // Ignore storage errors in local dev.
+        }
+    }
+}
+function renderThemeBootstrapScript() {
+    return `(function(){try{var key=${JSON.stringify(exports.THEME_STORAGE_KEY)};var stored=localStorage.getItem(key);var theme=(stored==='light'||stored==='dark')?stored:((window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches)?'dark':'light');document.documentElement.dataset.theme=theme;document.documentElement.style.colorScheme=theme;}catch(_err){document.documentElement.dataset.theme='light';document.documentElement.style.colorScheme='light';}})();`;
+}
+function getWindow() {
+    if (typeof globalThis !== 'object' || !('window' in globalThis)) {
+        return null;
+    }
+    return globalThis.window ?? null;
+}
+function getDocument() {
+    if (typeof globalThis !== 'object' || !('document' in globalThis)) {
+        return null;
+    }
+    return globalThis.document ?? null;
+}

package/dist/types.d.ts

@@ -0,0 +1,209 @@
+export type TraceMode = 'invoke' | 'stream';
+export type TraceStatus = 'pending' | 'ok' | 'error';
+export type TraceConfig = {
+    host?: string;
+    maxTraces?: number;
+    port?: number;
+    uiHotReload?: boolean;
+};
+export type TraceTags = Record<string, string>;
+export type TraceContext = {
+    actorId?: string | null;
+    actorType?: string | null;
+    guardrailPhase?: string | null;
+    guardrailType?: string | null;
+    kind?: string | null;
+    model?: string | null;
+    parentSessionId?: string | null;
+    provider?: string | null;
+    rootActorId?: string | null;
+    rootSessionId?: string | null;
+    sessionId?: string | null;
+    stage?: string | null;
+    tags?: Record<string, string | null | undefined>;
+    tenantId?: string | null;
+    userId?: string | null;
+    agentId?: string | null;
+    chatId?: string | null;
+    contextType?: string | null;
+    parentChatId?: string | null;
+    rootChatId?: string | null;
+    systemType?: string | null;
+    topLevelAgentId?: string | null;
+    watchdogPhase?: string | null;
+    workflowState?: string | null;
+};
+export type TraceHierarchy = {
+    childActorId: string | null;
+    guardrailPhase: string | null;
+    guardrailType: string | null;
+    kind: string;
+    rootActorId: string;
+    sessionId: string;
+    stage: string | null;
+    chatId: string;
+    delegatedAgentId: string | null;
+    systemType: string | null;
+    topLevelAgentId: string;
+    watchdogPhase: string | null;
+    workflowState: string | null;
+};
+export type NormalizedTraceContext = {
+    actorId: string | null;
+    actorType: string | null;
+    guardrailPhase: string | null;
+    guardrailType: string | null;
+    hierarchy: TraceHierarchy;
+    kind: string;
+    model: string | null;
+    parentSessionId: string | null;
+    provider: string | null;
+    rootActorId: string | null;
+    rootSessionId: string | null;
+    sessionId: string | null;
+    stage: string | null;
+    tags: TraceTags;
+    tenantId: string | null;
+    userId: string | null;
+    agentId: string | null;
+    chatId: string | null;
+    contextType: string | null;
+    parentChatId: string | null;
+    rootChatId: string | null;
+    systemType: string | null;
+    topLevelAgentId: string | null;
+    watchdogPhase: string | null;
+    workflowState: string | null;
+};
+export type TraceRequest = {
+    input?: Record<string, any>;
+    options?: Record<string, any>;
+};
+export type TraceRecord = {
+    context: NormalizedTraceContext;
+    endedAt: string | null;
+    error: Record<string, any> | null;
+    hierarchy: TraceHierarchy;
+    id: string;
+    kind: string;
+    mode: TraceMode;
+    model: string | null;
+    provider: string | null;
+    request: {
+        input?: Record<string, any>;
+        options: Record<string, any>;
+    };
+    response: Record<string, any> | null;
+    startedAt: string;
+    status: TraceStatus;
+    stream: null | {
+        chunkCount: number;
+        events: Record<string, any>[];
+        firstChunkMs: number | null;
+        reconstructed: {
+            message: Record<string, any>;
+            tool_calls: Record<string, any>[];
+            usage: Record<string, any> | null;
+        };
+    };
+    tags: TraceTags;
+    usage: Record<string, any> | null;
+};
+export type TraceSummary = {
+    costUsd: number | null;
+    durationMs: number | null;
+    endedAt: string | null;
+    hierarchy: TraceHierarchy;
+    id: string;
+    kind: string;
+    mode: TraceMode;
+    model: string | null;
+    provider: string | null;
+    requestPreview: string;
+    responsePreview: string;
+    startedAt: string;
+    status: TraceStatus;
+    stream: null | {
+        chunkCount: number;
+        firstChunkMs: number | null;
+    };
+    tags: TraceTags;
+};
+export type TraceEvent = {
+    timestamp: string;
+    trace?: TraceRecord;
+    traceId: string | null;
+    type: string;
+};
+export type UIReloadEvent = {
+    timestamp: string;
+    traceId: null;
+    type: 'ui:reload';
+};
+export type TraceListResponse = {
+    filtered: number;
+    groups?: Array<{
+        count: number;
+        items: TraceSummary[];
+        value: string;
+    }>;
+    items: TraceSummary[];
+    total: number;
+};
+export type HierarchyNode = {
+    children: HierarchyNode[];
+    count: number;
+    id: string;
+    label: string;
+    meta: Record<string, any>;
+    traceIds: string[];
+    type: string;
+};
+export type HierarchyResponse = {
+    filtered: number;
+    rootNodes: HierarchyNode[];
+    total: number;
+};
+export type TraceFilters = {
+    groupBy?: string;
+    kind?: string;
+    model?: string;
+    provider?: string;
+    search?: string;
+    status?: string;
+    tagFilters?: string[];
+    tags?: string[];
+    traceIds?: string[];
+};
+export interface ChatModelLike<TInput = any, TOptions = any, TValue = any, TChunk = any> {
+    invoke(input: TInput, options?: TOptions): Promise<TValue>;
+    stream(input: TInput, options?: TOptions): AsyncGenerator<TChunk>;
+}
+export type TraceServer = {
+    broadcast(event: TraceEvent | UIReloadEvent): void;
+    close(): void;
+    start(): Promise<{
+        host: string;
+        port: number;
+        url: string;
+    } | null>;
+};
+export type UIWatchController = {
+    stop(): Promise<void>;
+};
+export type LocalLLMTracer = {
+    configure(config?: TraceConfig): 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;
+    startServer(): Promise<{
+        host: string;
+        port: number;
+        url: string;
+    } | null>;
+    store: any;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ui-build.d.ts

@@ -0,0 +1,3 @@
+import { type UIWatchController } from './types';
+export declare function buildUIAssets(): Promise<void>;
+export declare function maybeStartUIWatcher(onReload: () => void, enabled?: boolean): Promise<UIWatchController | null>;