@opensearch-project/agent-health 0.3.0 → 0.5.2

package/lib/dist/services/traces/tracePoller.js

@@ -0,0 +1,309 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { debug } from '../../lib/debug.js';
+import { fetchTracesByRunIds } from './index.js';
+import { asyncRunStorage } from '../storage/asyncRunStorage.js';
+import { executeBuildTrajectoryHook } from '../../lib/hooks.js';
+import { buildEvaluatorErrorPatch } from '../../services/evaluation/evaluatorError.js';
+// Polling configuration. Defaults are overridable via env vars so that
+// CI / E2E runs without a real OpenSearch trace backend can fail fast
+// instead of waiting the full ~10 min before the poller gives up.
+//
+// NOTE: this module is imported by browser code (RunDetailsContent.tsx) for
+// recovery polling, where `process` is not defined. Guard the access so we
+// silently fall back to defaults in the browser instead of throwing
+// `ReferenceError: process is not defined` at module load time.
+const envInt = (name, fallback) => {
+    const raw = typeof process !== 'undefined' && process?.env ? process.env[name] : undefined;
+    if (!raw)
+        return fallback;
+    const parsed = parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+const DEFAULT_POLL_INTERVAL_MS = envInt('TRACE_POLL_INTERVAL_MS', 10000); // 10 seconds
+const DEFAULT_MAX_ATTEMPTS = envInt('TRACE_POLL_MAX_ATTEMPTS', 60); // 10 minutes total at default interval
+const MAX_POLL_CEILING = 60; // Hard ceiling: never exceed 60 attempts regardless of agent config or env override
+/**
+ * Trace Polling Manager
+ *
+ * Singleton that manages active polling for trace availability.
+ * State is in-memory only - polling is short-lived (~10 min max).
+ *
+ * Polling runs in two places for redundancy:
+ * - Server (experimentRunner.ts): Primary - starts immediately after agent execution
+ * - Browser (RunDetailsContent.tsx): Recovery - starts when viewing a pending report
+ */
+class TracePollingManager {
+    constructor() {
+        this.polls = new Map();
+        this.callbacks = new Map();
+        this.completionPromises = new Map();
+    }
+    /**
+     * Start polling for traces for a specific report
+     */
+    startPolling(reportId, runId, callbacks, options) {
+        // Don't start if already polling for this report
+        if (this.polls.has(reportId) && this.polls.get(reportId).running) {
+            debug('TracePoller', `Already polling for report ${reportId}`);
+            return;
+        }
+        const state = {
+            reportId,
+            runId,
+            attempts: 0,
+            maxAttempts: Math.min(Number.isFinite(options?.maxAttempts) ? options.maxAttempts : DEFAULT_MAX_ATTEMPTS, MAX_POLL_CEILING),
+            intervalMs: options?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+            lastAttempt: null,
+            running: true,
+            agentConfig: options?.agentConfig,
+        };
+        this.polls.set(reportId, state);
+        this.callbacks.set(reportId, callbacks);
+        debug('TracePoller', `Starting polling for report ${reportId}, runId ${runId}`);
+        this.poll(reportId);
+    }
+    /**
+     * Stop polling for a specific report.
+     * If a completion promise exists (from startPollingAsync), it is rejected
+     * so callers awaiting it are unblocked.
+     */
+    stopPolling(reportId) {
+        const state = this.polls.get(reportId);
+        if (state) {
+            if (state.timerId) {
+                clearTimeout(state.timerId);
+            }
+            state.running = false;
+            debug('TracePoller', `Stopped polling for report ${reportId}`);
+        }
+        // Reject any pending completion promise so awaiting callers don't hang
+        const pending = this.completionPromises.get(reportId);
+        if (pending) {
+            pending.reject(new Error(`Polling stopped for report ${reportId}`));
+            this.completionPromises.delete(reportId);
+        }
+        this.callbacks.delete(reportId);
+        this.polls.delete(reportId);
+    }
+    /**
+     * Get the state for a specific poll
+     */
+    getState(reportId) {
+        return this.polls.get(reportId);
+    }
+    /**
+     * Get all active polls
+     */
+    getAllActivePolls() {
+        const active = new Map();
+        this.polls.forEach((state, reportId) => {
+            if (state.running) {
+                active.set(reportId, state);
+            }
+        });
+        return active;
+    }
+    /**
+     * Start polling and return a Promise that resolves when polling completes.
+     * This allows callers (e.g., benchmark runner) to await trace availability
+     * instead of firing and forgetting.
+     *
+     * If polling is already active for this reportId, returns the existing
+     * completion promise (no duplicate poll started).
+     */
+    startPollingAsync(reportId, runId, callbacks, options) {
+        // If already polling, return the existing completion promise
+        const existing = this.completionPromises.get(reportId);
+        if (existing && this.polls.has(reportId) && this.polls.get(reportId).running) {
+            debug('TracePoller', `Already polling for report ${reportId}, returning existing promise`);
+            return new Promise((resolve, reject) => {
+                const current = this.completionPromises.get(reportId);
+                this.completionPromises.set(reportId, {
+                    resolve: () => { current.resolve(); resolve(); },
+                    reject: (err) => { current.reject(err); reject(err); },
+                });
+            });
+        }
+        return new Promise((resolve, reject) => {
+            this.completionPromises.set(reportId, { resolve, reject });
+            // Wrap callbacks to resolve/reject the promise on completion
+            const wrappedCallbacks = {
+                onTracesFound: async (spans, report) => {
+                    try {
+                        await callbacks.onTracesFound(spans, report);
+                        this.completionPromises.get(reportId)?.resolve();
+                    }
+                    catch (err) {
+                        this.completionPromises.get(reportId)?.reject(err);
+                    }
+                    finally {
+                        this.completionPromises.delete(reportId);
+                    }
+                },
+                onAttempt: callbacks.onAttempt,
+                onError: (error) => {
+                    callbacks.onError(error);
+                    this.completionPromises.get(reportId)?.reject(error);
+                    this.completionPromises.delete(reportId);
+                },
+            };
+            this.startPolling(reportId, runId, wrappedCallbacks, options);
+        });
+    }
+    /**
+     * Execute a single poll attempt
+     */
+    async poll(reportId) {
+        const state = this.polls.get(reportId);
+        const callbacks = this.callbacks.get(reportId);
+        if (!state || !state.running) {
+            return;
+        }
+        state.attempts++;
+        state.lastAttempt = new Date().toISOString();
+        debug('TracePoller', `Poll attempt ${state.attempts}/${state.maxAttempts} for report ${reportId}`);
+        // Notify about attempt
+        callbacks?.onAttempt?.(state.attempts, state.maxAttempts);
+        // Update report with attempt count
+        try {
+            await asyncRunStorage.updateReport(reportId, {
+                traceFetchAttempts: state.attempts,
+                lastTraceFetchAt: state.lastAttempt,
+            });
+        }
+        catch (err) {
+            console.warn(`[TracePoller] Failed to update attempt count:`, err);
+        }
+        try {
+            // Try to fetch traces
+            const result = await fetchTracesByRunIds([state.runId]);
+            if (result.spans && result.spans.length > 0) {
+                // Traces found!
+                debug('TracePoller', `Found ${result.spans.length} spans for report ${reportId}`);
+                // Get the current report
+                const report = await asyncRunStorage.getReportById(reportId);
+                if (!report) {
+                    throw new Error(`Report ${reportId} not found`);
+                }
+                // Build trajectory from trace spans
+                const { trajectory, shouldContinuePolling } = await this.buildTrajectory(result.spans, state);
+                // Check if we should continue polling
+                if (shouldContinuePolling) {
+                    if (state.attempts >= state.maxAttempts) {
+                        console.log(`[TracePoller] Max attempts reached with incomplete trace`);
+                        state.running = false;
+                        callbacks?.onError(new Error(`Trace incomplete after ${state.maxAttempts} attempts`));
+                        await asyncRunStorage.updateReport(reportId, buildEvaluatorErrorPatch('trace_incomplete', `found ${result.spans.length} spans but no root span after ${state.maxAttempts} attempts`)).catch(err => console.error(`[TracePoller] Failed to update report error status:`, err));
+                        this.callbacks.delete(reportId);
+                        this.polls.delete(reportId);
+                    }
+                    else {
+                        // Schedule next poll
+                        state.timerId = setTimeout(() => this.poll(reportId), state.intervalMs);
+                    }
+                    return;
+                }
+                // Trajectory is ready - only overwrite if the hook produced steps
+                if (trajectory.length > 0) {
+                    report.trajectory = trajectory;
+                }
+                // Stop polling and notify success
+                state.running = false;
+                try {
+                    await callbacks?.onTracesFound(result.spans, report);
+                }
+                catch (callbackErr) {
+                    // onTracesFound failed (e.g., judge + error recovery both failed).
+                    // Write error status so the report doesn't stay stuck in 'pending'.
+                    console.error(`[TracePoller] onTracesFound callback failed for report ${reportId}:`, callbackErr);
+                    try {
+                        await asyncRunStorage.updateReport(reportId, buildEvaluatorErrorPatch('trace_callback_failed', callbackErr));
+                    }
+                    catch (updateErr) {
+                        console.error(`[TracePoller] CRITICAL: Failed to update report ${reportId} error status after callback failure.`, updateErr);
+                    }
+                }
+                this.callbacks.delete(reportId);
+                this.polls.delete(reportId);
+            }
+            else {
+                // No traces yet
+                if (state.attempts >= state.maxAttempts) {
+                    // Max attempts reached
+                    debug('TracePoller', `Max attempts reached for report ${reportId}`);
+                    state.running = false;
+                    callbacks?.onError(new Error(`Traces not available after ${state.maxAttempts} attempts`));
+                    // Update report with error status - critical as report will remain stuck otherwise
+                    try {
+                        await asyncRunStorage.updateReport(reportId, buildEvaluatorErrorPatch('trace_timeout', `traces not available after ${state.maxAttempts} attempts (${state.maxAttempts * state.intervalMs / 60000} minutes)`));
+                    }
+                    catch (updateErr) {
+                        console.error(`[TracePoller] CRITICAL: Failed to update report ${reportId} error status. Report may be stuck in pending state.`, updateErr);
+                    }
+                    this.callbacks.delete(reportId);
+                    this.polls.delete(reportId);
+                }
+                else {
+                    // Schedule next poll
+                    state.timerId = setTimeout(() => this.poll(reportId), state.intervalMs);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[TracePoller] Error polling for report ${reportId}:`, error);
+            if (state.attempts >= state.maxAttempts) {
+                state.running = false;
+                callbacks?.onError(error);
+                // Update report with error status - critical as report will remain stuck otherwise
+                try {
+                    await asyncRunStorage.updateReport(reportId, buildEvaluatorErrorPatch('trace_fetch_failed', error));
+                }
+                catch (updateErr) {
+                    console.error(`[TracePoller] CRITICAL: Failed to update report ${reportId} error status. Report may be stuck in pending state.`, updateErr);
+                }
+                this.callbacks.delete(reportId);
+                this.polls.delete(reportId);
+            }
+            else {
+                // Schedule retry
+                state.timerId = setTimeout(() => this.poll(reportId), state.intervalMs);
+            }
+        }
+    }
+    /**
+     * Build trajectory from spans with proper error handling
+     */
+    async buildTrajectory(spans, state) {
+        const traceId = spans[0]?.traceId;
+        if (!traceId) {
+            console.warn(`[TracePoller] No traceId found in spans`);
+            return { trajectory: [], shouldContinuePolling: false };
+        }
+        // If no buildTrajectory hook, return empty trajectory (will use SSE trajectory)
+        if (!state.agentConfig?.hooks?.buildTrajectory) {
+            return { trajectory: [], shouldContinuePolling: false };
+        }
+        try {
+            console.log(`[TracePoller] Building trajectory from hook for trace ${traceId}`);
+            const hookResult = await executeBuildTrajectoryHook(state.agentConfig.hooks, { spans, runId: state.runId }, state.agentConfig.key);
+            if (hookResult !== null) {
+                console.log(`[TracePoller] Hook returned ${hookResult.length} trajectory steps`);
+                return { trajectory: hookResult, shouldContinuePolling: false };
+            }
+            else {
+                console.log(`[TracePoller] Hook returned null - trace not ready yet`);
+                return { trajectory: [], shouldContinuePolling: true };
+            }
+        }
+        catch (err) {
+            console.error(`[TracePoller] Failed to build trajectory for ${traceId}:`, err);
+            return { trajectory: [], shouldContinuePolling: false };
+        }
+    }
+}
+// Singleton instance
+export const tracePollingManager = new TracePollingManager();
+//# sourceMappingURL=tracePoller.js.map

package/lib/dist/services/traces/tracePoller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracePoller.js","sourceRoot":"","sources":["../../../../services/traces/tracePoller.ts"],"names":[],"mappings":"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"}

package/lib/dist/services/traces/traceStats.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Trace Statistics Utilities
+ *
+ * Shared helper functions for calculating trace statistics.
+ * Used by TraceFlowView.
+ */
+import { CategorizedSpan, SpanCategory } from '../../types/index.js';
+/**
+ * Category statistics for trace analysis
+ */
+export interface CategoryStats {
+    category: SpanCategory;
+    count: number;
+    totalDuration: number;
+    percentage: number;
+}
+/**
+ * Tool usage information
+ */
+export interface ToolInfo {
+    name: string;
+    count: number;
+    totalDuration: number;
+}
+/**
+ * Extract tool name from a span
+ */
+export declare function extractToolName(span: CategorizedSpan): string | null;
+/**
+ * Flatten span tree and collect all spans
+ */
+export declare function flattenSpans(spans: CategorizedSpan[]): CategorizedSpan[];
+/**
+ * Calculate category statistics from spans
+ *
+ * Percentages are calculated relative to the sum of all category durations,
+ * not trace duration, because spans can overlap (LLM calls inside AGENT spans).
+ * This ensures percentages naturally sum to 100%.
+ */
+export declare function calculateCategoryStats(spans: CategorizedSpan[], _totalDuration: number): CategoryStats[];
+/**
+ * Extract unique tools with usage stats
+ */
+export declare function extractToolStats(spans: CategorizedSpan[]): ToolInfo[];
+//# sourceMappingURL=traceStats.d.ts.map

package/lib/dist/services/traces/traceStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceStats.d.ts","sourceRoot":"","sources":["../../../../services/traces/traceStats.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CA8BpE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAcxE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,cAAc,EAAE,MAAM,GAAG,aAAa,EAAE,CA6BxG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,QAAQ,EAAE,CA2BrE"}

package/lib/dist/services/traces/traceStats.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ATTR_GEN_AI_TOOL_NAME } from '@opentelemetry/semantic-conventions/incubating';
+/**
+ * Extract tool name from a span
+ */
+export function extractToolName(span) {
+    // Try gen_ai.tool.name attribute first (OTel semantic convention)
+    const toolName = span.attributes?.[ATTR_GEN_AI_TOOL_NAME];
+    if (toolName)
+        return toolName;
+    // Parse from displayName or name
+    const name = span.displayName || span.name || '';
+    // Look for tool name patterns
+    const patterns = [
+        /execute_tool\s+(\S+)/i,
+        /executeTools,\s*(\S+)/i,
+        /tool\.execute\s+(\S+)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = name.match(pattern);
+        if (match)
+            return match[1];
+    }
+    // Try to get the last meaningful part after comma
+    if (name.includes(',')) {
+        const parts = name.split(',');
+        const lastPart = parts[parts.length - 1].trim();
+        if (lastPart && !lastPart.includes('agent.node')) {
+            return lastPart;
+        }
+    }
+    return null;
+}
+/**
+ * Flatten span tree and collect all spans
+ */
+export function flattenSpans(spans) {
+    const result = [];
+    const collect = (spanList) => {
+        for (const span of spanList) {
+            result.push(span);
+            if (span.children && span.children.length > 0) {
+                collect(span.children);
+            }
+        }
+    };
+    collect(spans);
+    return result;
+}
+/**
+ * Calculate category statistics from spans
+ *
+ * Percentages are calculated relative to the sum of all category durations,
+ * not trace duration, because spans can overlap (LLM calls inside AGENT spans).
+ * This ensures percentages naturally sum to 100%.
+ */
+export function calculateCategoryStats(spans, _totalDuration) {
+    const categoryMap = new Map();
+    for (const span of spans) {
+        const existing = categoryMap.get(span.category) || { count: 0, duration: 0 };
+        categoryMap.set(span.category, {
+            count: existing.count + 1,
+            duration: existing.duration + (span.duration || 0),
+        });
+    }
+    // Calculate sum of all category durations for percentage calculation
+    let sumOfAllDurations = 0;
+    categoryMap.forEach((data) => {
+        sumOfAllDurations += data.duration;
+    });
+    const stats = [];
+    categoryMap.forEach((data, category) => {
+        stats.push({
+            category,
+            count: data.count,
+            totalDuration: data.duration,
+            percentage: sumOfAllDurations > 0 ? (data.duration / sumOfAllDurations) * 100 : 0,
+        });
+    });
+    // Sort by duration descending
+    return stats.sort((a, b) => b.totalDuration - a.totalDuration);
+}
+/**
+ * Extract unique tools with usage stats
+ */
+export function extractToolStats(spans) {
+    const toolMap = new Map();
+    for (const span of spans) {
+        if (span.category === 'TOOL') {
+            const toolName = extractToolName(span);
+            if (toolName) {
+                const existing = toolMap.get(toolName) || { count: 0, duration: 0 };
+                toolMap.set(toolName, {
+                    count: existing.count + 1,
+                    duration: existing.duration + (span.duration || 0),
+                });
+            }
+        }
+    }
+    const tools = [];
+    toolMap.forEach((data, name) => {
+        tools.push({
+            name,
+            count: data.count,
+            totalDuration: data.duration,
+        });
+    });
+    // Sort by usage count descending
+    return tools.sort((a, b) => b.count - a.count);
+}
+//# sourceMappingURL=traceStats.js.map

package/lib/dist/services/traces/traceStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceStats.js","sourceRoot":"","sources":["../../../../services/traces/traceStats.ts"],"names":[],"mappings":"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"}

package/lib/dist/services/traces/traceSummary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * traceSummary
+ *
+ * Computes a compact summary for a trace's span tree — the same set of
+ * non-redundant signals shown in the Agent Traces inline-expansion header
+ * strip and the fullscreen header. Keeping the computation in one place
+ * means inline and fullscreen render exactly the same numbers from the
+ * same source-of-truth (`categorizeSpanTree` for category buckets,
+ * `gen_ai.usage.*` attribute aggregation for tokens, and dedup over
+ * `gen_ai.request.model` / `gen_ai.response.model` / `model` for the
+ * model name list).
+ */
+import { Span } from '../../types/index.js';
+export interface TraceSummary {
+    llm: number;
+    tool: number;
+    agent: number;
+    evalCount: number;
+    errors: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** Largest single-span input-token count in the trace. Used for
+        context-window utilization (Ctx%) — the peak request, not the sum. */
+    peakInputTokens: number;
+    models: string[];
+}
+/**
+ * Aggregate the headline signals from a span tree.
+ *
+ * The category counts come from {@link countByCategory} on a categorized
+ * tree. The token counters look at every span (including children) and
+ * sum the OTel GenAI usage attributes, with `prompt_tokens` /
+ * `completion_tokens` accepted as fallbacks for older instrumentation
+ * that pre-dates the input/output rename. Models are collected and
+ * deduplicated across the trace because some agents fan out to multiple
+ * models in one trace (e.g. a planner + a tool-using model).
+ */
+export declare function computeTraceSummary(spanTree: Span[]): TraceSummary;
+/**
+ * True when no headline signal is present (no LLM/tool/agent/eval span,
+ * no errors, no token counters, no model). Callers can use this to fall
+ * back to a "no summary attributes available" placeholder instead of
+ * collapsing to an empty bar.
+ */
+export declare function isEmptyTraceSummary(s: TraceSummary): boolean;
+//# sourceMappingURL=traceSummary.d.ts.map

package/lib/dist/services/traces/traceSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceSummary.d.ts","sourceRoot":"","sources":["../../../../services/traces/traceSummary.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAI/B,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB;6EACyE;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,YAAY,CAqClE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAU5D"}

package/lib/dist/services/traces/traceSummary.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { categorizeSpanTree, countByCategory } from './spanCategorization.js';
+import { flattenSpans } from './traceStats.js';
+/**
+ * Aggregate the headline signals from a span tree.
+ *
+ * The category counts come from {@link countByCategory} on a categorized
+ * tree. The token counters look at every span (including children) and
+ * sum the OTel GenAI usage attributes, with `prompt_tokens` /
+ * `completion_tokens` accepted as fallbacks for older instrumentation
+ * that pre-dates the input/output rename. Models are collected and
+ * deduplicated across the trace because some agents fan out to multiple
+ * models in one trace (e.g. a planner + a tool-using model).
+ */
+export function computeTraceSummary(spanTree) {
+    const categorized = categorizeSpanTree(spanTree);
+    const counts = countByCategory(categorized);
+    const flat = flattenSpans(categorized);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let totalTokens = 0;
+    let peakInputTokens = 0;
+    const modelSet = new Set();
+    for (const s of flat) {
+        const a = s.attributes || {};
+        const it = Number(a['gen_ai.usage.input_tokens'] ?? a['gen_ai.usage.prompt_tokens'] ?? a['input_tokens'] ?? 0) || 0;
+        const ot = Number(a['gen_ai.usage.output_tokens'] ?? a['gen_ai.usage.completion_tokens'] ?? a['output_tokens'] ?? 0) || 0;
+        inputTokens += it;
+        outputTokens += ot;
+        totalTokens += it + ot;
+        if (it > peakInputTokens)
+            peakInputTokens = it;
+        const m = a['gen_ai.request.model'] || a['gen_ai.response.model'] || a['model'];
+        if (typeof m === 'string' && m.trim())
+            modelSet.add(m.trim());
+    }
+    return {
+        llm: counts.LLM,
+        tool: counts.TOOL,
+        agent: counts.AGENT,
+        evalCount: counts.EVAL,
+        errors: counts.ERROR,
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        peakInputTokens,
+        models: Array.from(modelSet),
+    };
+}
+/**
+ * True when no headline signal is present (no LLM/tool/agent/eval span,
+ * no errors, no token counters, no model). Callers can use this to fall
+ * back to a "no summary attributes available" placeholder instead of
+ * collapsing to an empty bar.
+ */
+export function isEmptyTraceSummary(s) {
+    return (s.llm === 0 &&
+        s.tool === 0 &&
+        s.agent === 0 &&
+        s.evalCount === 0 &&
+        s.errors === 0 &&
+        s.totalTokens === 0 &&
+        s.models.length === 0);
+}
+//# sourceMappingURL=traceSummary.js.map

package/lib/dist/services/traces/traceSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceSummary.js","sourceRoot":"","sources":["../../../../services/traces/traceSummary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAiB5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAEvC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAEnC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC;QAC7B,MAAM,EAAE,GACN,MAAM,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC,4BAA4B,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3G,MAAM,EAAE,GACN,MAAM,CAAC,CAAC,CAAC,4BAA4B,CAAC,IAAI,CAAC,CAAC,gCAAgC,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACjH,WAAW,IAAI,EAAE,CAAC;QAClB,YAAY,IAAI,EAAE,CAAC;QACnB,WAAW,IAAI,EAAE,GAAG,EAAE,CAAC;QACvB,IAAI,EAAE,GAAG,eAAe;YAAE,eAAe,GAAG,EAAE,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC;QAChF,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,IAAI;QACtB,MAAM,EAAE,MAAM,CAAC,KAAK;QACpB,WAAW;QACX,YAAY;QACZ,WAAW;QACX,eAAe;QACf,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAe;IACjD,OAAO,CACL,CAAC,CAAC,GAAG,KAAK,CAAC;QACX,CAAC,CAAC,IAAI,KAAK,CAAC;QACZ,CAAC,CAAC,KAAK,KAAK,CAAC;QACb,CAAC,CAAC,SAAS,KAAK,CAAC;QACjB,CAAC,CAAC,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,WAAW,KAAK,CAAC;QACnB,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CACtB,CAAC;AACJ,CAAC"}

package/lib/dist/services/traces/utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Trace Utility Functions
+ */
+import { Span } from '../../types/index.js';
+/**
+ * Format duration in human-readable format
+ */
+export declare function formatDuration(ms: number | null | undefined): string;
+/**
+ * Extract key attributes based on span type
+ */
+export declare function getKeyAttributes(span: Span): Record<string, string | number | null>;
+/**
+ * Estimate token count from text (rough approximation)
+ */
+export declare function estimateTokens(text: string | object | null | undefined): number;
+/**
+ * Truncate text with ellipsis
+ */
+export declare function truncateText(text: string, maxLength: number): string;
+/**
+ * Format timestamp for display
+ */
+export declare function formatTimestamp(timestamp: string): string;
+/**
+ * Format large numbers in compact notation: 999 → "999", 1200 → "1.2k", 1500000 → "1.5M"
+ */
+export declare function formatCompact(n: number): string;
+/**
+ * Parse JSON safely
+ */
+export declare function safeParseJSON(str: string): object | string;
+//# sourceMappingURL=utils.d.ts.map