@opensearch-project/agent-health 0.4.0 → 0.6.0

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

@@ -0,0 +1,131 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { hasAnyWarnings, getCategoryMeta } from './spanCategorization.js';
+import { isContainerSpan } from './executionOrderTransform.js';
+/**
+ * Flatten span tree into execution order, skipping container spans
+ * Container span children are promoted to their parent's level
+ */
+function flattenInExecutionOrder(spanTree) {
+    const result = [];
+    const processSpan = (span) => {
+        // Safely extract children with default empty array
+        const children = (span.children ?? []);
+        const sortedChildren = children.length > 0
+            ? [...children].sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime())
+            : [];
+        if (isContainerSpan(span)) {
+            // Skip container, process children directly
+            for (const child of sortedChildren) {
+                processSpan(child);
+            }
+        }
+        else {
+            // Include this span, then process children
+            result.push(span);
+            for (const child of sortedChildren) {
+                processSpan(child);
+            }
+        }
+    };
+    // Sort root spans by start time
+    const sortedRoots = [...spanTree].sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime());
+    for (const root of sortedRoots) {
+        processSpan(root);
+    }
+    return result;
+}
+/**
+ * Build subtitle for an IntentNode from its spans
+ */
+function buildSubtitle(spans) {
+    if (spans.length === 1) {
+        return spans[0].displayName || spans[0].name;
+    }
+    // For multiple spans, show first few names
+    const names = spans.slice(0, 3).map(s => s.displayName || s.name);
+    if (spans.length > 3) {
+        return `${names.join(', ')}...`;
+    }
+    return names.join(', ');
+}
+/**
+ * Group consecutive same-category spans into IntentNodes
+ */
+function groupConsecutive(spans) {
+    if (spans.length === 0)
+        return [];
+    const nodes = [];
+    let currentGroup = [spans[0]];
+    let currentCategory = spans[0].category;
+    let currentStartIndex = 0; // Track global span index
+    for (let i = 1; i < spans.length; i++) {
+        const span = spans[i];
+        if (span.category === currentCategory) {
+            // Same category - add to current group
+            currentGroup.push(span);
+        }
+        else {
+            // Different category - close current group, start new one
+            nodes.push(createIntentNode(currentGroup, nodes.length, currentStartIndex));
+            currentStartIndex += currentGroup.length;
+            currentGroup = [span];
+            currentCategory = span.category;
+        }
+    }
+    // Don't forget the last group
+    if (currentGroup.length > 0) {
+        nodes.push(createIntentNode(currentGroup, nodes.length, currentStartIndex));
+    }
+    return nodes;
+}
+/**
+ * Create an IntentNode from a group of consecutive spans
+ */
+function createIntentNode(spans, order, startIndex) {
+    const category = spans[0].category;
+    const meta = getCategoryMeta(category);
+    const count = spans.length;
+    // Calculate total duration for all spans in this node
+    const totalDuration = spans.reduce((sum, span) => sum + (span.duration ?? 0), 0);
+    return {
+        id: `intent-${category}-${order}`,
+        category,
+        spans,
+        count,
+        displayName: count > 1 ? `${meta.label} ×${count}` : meta.label,
+        subtitle: buildSubtitle(spans),
+        hasWarnings: hasAnyWarnings(spans),
+        executionOrder: order,
+        startIndex,
+        totalDuration,
+    };
+}
+/**
+ * Transform a categorized span tree into IntentNodes for the Intent view.
+ * Groups only consecutive same-category spans, preserving execution order.
+ */
+export function spansToIntentNodes(spanTree) {
+    // 1. Flatten all spans in execution order (skip container spans)
+    const flatSpans = flattenInExecutionOrder(spanTree);
+    // 2. Group consecutive same-category spans
+    return groupConsecutive(flatSpans);
+}
+/**
+ * Get the root/container span for display as header (if exists)
+ */
+export function getRootContainerSpan(spanTree) {
+    if (spanTree.length === 0)
+        return null;
+    // Find first container span (usually the agent.run)
+    for (const span of spanTree) {
+        if (isContainerSpan(span)) {
+            return span;
+        }
+    }
+    // Fallback to first span if no container found
+    return spanTree[0];
+}
+//# sourceMappingURL=intentTransform.js.map

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

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

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

@@ -0,0 +1,63 @@
+/**
+ * Derive Strategy C correlation hints (`agents` array) for the agent (trace)
+ * judge from a persisted run report.
+ *
+ * Background (#264): the agent (trace) judge's `query_spans` tool reads
+ * `/api/traces` to find the spans it should reason over. Without these hints
+ * the route only matches spans whose `gen_ai.request.id` equals
+ * agent-health's runId (Strategy B) — i.e. agent-health's OWN eval-emitter
+ * spans. Subprocess agents like claude-code emit instrumentation under their
+ * own session ids, so they're invisible to Strategy B alone.
+ *
+ * Forwarding `agents: [{serviceName, startedAt, endedAt}]` lets `/api/traces`
+ * union Strategy B with Strategy C (service.name + time-window). This is the
+ * same correlation the run-detail Traces tab uses (see
+ * components/RunDetailsContent.tsx), extracted here so the trace judge tool
+ * and the UI converge on one read-side query.
+ *
+ * The full unification (one shared `buildSpanQuery(report)` for every
+ * caller) is tracked in #264 — this helper is the minimum surgery to make
+ * the agent (trace) judge functional in the meantime.
+ */
+import type { TestCaseRun, ConnectorProtocol } from '../../types/index.js';
+export interface JudgeAgentsHint {
+    serviceName: string;
+    startedAt: number;
+    endedAt: number;
+    /**
+     * Agent-emitted session id (Strategy D). When present, trace queries
+     * correlate precisely on `attributes.session.id` (unioned with the
+     * service.name + window fallback). Sourced from `report.sessionId`.
+     */
+    sessionId?: string;
+}
+/**
+ * Resolve the `service.name` an agent emits OTel spans under. Priority:
+ *   1. Explicit `agentConfig.traceServiceName` (the per-agent override).
+ *   2. Protocol-default from the table above.
+ *   3. `<connectorProtocol>-agent` heuristic (last-resort fallback).
+ *   4. `<agentKey>-agent` as a final guess when protocol is unknown.
+ *
+ * Returns `undefined` when none of the above is derivable; the caller
+ * should then skip Strategy C and fall back to Strategy B alone.
+ */
+export declare function resolveAgentServiceName(args: {
+    agentTraceServiceName?: string;
+    connectorProtocol?: ConnectorProtocol;
+    agentKey?: string;
+}): string | undefined;
+/**
+ * Build the `agents: [{...}]` array to forward as `JudgeRequest.agents`.
+ *
+ * `endedAt` defaults to the report's persisted timestamp; `startedAt`
+ * defaults to that minus `performanceMetrics.durationMs` (with slack), or
+ * a 30-minute lookback when duration is missing. The trace tool sends
+ * these through to `/api/traces` which intersects them with
+ * `service.name = serviceName`.
+ *
+ * Returns an empty array when we can't derive a meaningful service name —
+ * the caller can still pass that and the route just falls back to
+ * Strategy B (runIds-only) without breaking.
+ */
+export declare function buildJudgeAgentsHints(report: Pick<TestCaseRun, 'agentKey' | 'connectorProtocol' | 'timestamp' | 'performanceMetrics' | 'sessionId'>, agentTraceServiceName?: string): JudgeAgentsHint[];
+//# sourceMappingURL=judgeAgentsHints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"judgeAgentsHints.d.ts","sourceRoot":"","sources":["../../../../services/traces/judgeAgentsHints.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AA4B9D,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAQrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,mBAAmB,GAAG,WAAW,GAAG,oBAAoB,GAAG,WAAW,CAAC,EAC9G,qBAAqB,CAAC,EAAE,MAAM,GAC7B,eAAe,EAAE,CAyBnB"}

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

@@ -0,0 +1,89 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Default `service.name` per connector protocol/key, mirroring `AGENTS.md`'s
+ * "Trace correlation conventions" table. Used when the agent config doesn't
+ * set an explicit `traceServiceName`. Keyed by `string` rather than
+ * `ConnectorProtocol` so user-configured connectors (e.g. `kiro`, which
+ * isn't in the upstream union) still resolve to a default.
+ */
+const PROTOCOL_TO_SERVICE_NAME = {
+    'claude-code': 'claude-code-agent',
+    'kiro': 'kiro-agent',
+    'pi': 'pi-agent',
+    'agui-streaming': 'observio-sample-agent',
+    'subprocess': 'subprocess-agent',
+};
+/** Time-window slack on each side of the run window to absorb clock skew. */
+const SLACK_MS = 60_000;
+/**
+ * Lookback used when `report.performanceMetrics.durationMs` is missing
+ * (older runs persisted before that field). Wide enough to cover any
+ * realistic run, narrow enough to keep noise on a shared OTel cluster
+ * minimal. Mirrors the run-detail Traces tab fallback.
+ */
+const FALLBACK_LOOKBACK_MS = 30 * 60_000;
+/**
+ * Resolve the `service.name` an agent emits OTel spans under. Priority:
+ *   1. Explicit `agentConfig.traceServiceName` (the per-agent override).
+ *   2. Protocol-default from the table above.
+ *   3. `<connectorProtocol>-agent` heuristic (last-resort fallback).
+ *   4. `<agentKey>-agent` as a final guess when protocol is unknown.
+ *
+ * Returns `undefined` when none of the above is derivable; the caller
+ * should then skip Strategy C and fall back to Strategy B alone.
+ */
+export function resolveAgentServiceName(args) {
+    if (args.agentTraceServiceName)
+        return args.agentTraceServiceName;
+    if (args.connectorProtocol && PROTOCOL_TO_SERVICE_NAME[args.connectorProtocol]) {
+        return PROTOCOL_TO_SERVICE_NAME[args.connectorProtocol];
+    }
+    if (args.connectorProtocol)
+        return `${args.connectorProtocol}-agent`;
+    if (args.agentKey)
+        return `${args.agentKey}-agent`;
+    return undefined;
+}
+/**
+ * Build the `agents: [{...}]` array to forward as `JudgeRequest.agents`.
+ *
+ * `endedAt` defaults to the report's persisted timestamp; `startedAt`
+ * defaults to that minus `performanceMetrics.durationMs` (with slack), or
+ * a 30-minute lookback when duration is missing. The trace tool sends
+ * these through to `/api/traces` which intersects them with
+ * `service.name = serviceName`.
+ *
+ * Returns an empty array when we can't derive a meaningful service name —
+ * the caller can still pass that and the route just falls back to
+ * Strategy B (runIds-only) without breaking.
+ */
+export function buildJudgeAgentsHints(report, agentTraceServiceName) {
+    const serviceName = resolveAgentServiceName({
+        agentTraceServiceName,
+        connectorProtocol: report.connectorProtocol,
+        agentKey: report.agentKey,
+    });
+    if (!serviceName)
+        return [];
+    const ts = Date.parse(report.timestamp || '') || Date.now();
+    const durationMs = report.performanceMetrics?.durationMs ?? 0;
+    const span = durationMs > 0 ? durationMs + SLACK_MS : FALLBACK_LOOKBACK_MS;
+    // `report.timestamp` is NOT reliably the run END: trace-mode / subprocess
+    // reports (e.g. Claude Code) are persisted at run START, so anchoring the
+    // window's `endedAt` on the timestamp and looking only backwards lands the
+    // entire window BEFORE the run and misses every span. Anchor SYMMETRICALLY
+    // around the timestamp by ±(duration + slack) so the window covers the run
+    // whether the timestamp marks its start or its end (empty-by-default is the
+    // worse failure mode — see trace-correlation notes). Mirrors the deep-dive's
+    // resolveWindow.
+    return [{
+            serviceName,
+            startedAt: ts - span,
+            endedAt: ts + span,
+            ...(report.sessionId ? { sessionId: report.sessionId } : {}),
+        }];
+}
+//# sourceMappingURL=judgeAgentsHints.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"judgeAgentsHints.js","sourceRoot":"","sources":["../../../../services/traces/judgeAgentsHints.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0BH;;;;;;GAMG;AACH,MAAM,wBAAwB,GAA2B;IACvD,aAAa,EAAE,mBAAmB;IAClC,MAAM,EAAE,YAAY;IACpB,IAAI,EAAE,UAAU;IAChB,gBAAgB,EAAE,uBAAuB;IACzC,YAAY,EAAE,kBAAkB;CACjC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,EAAE,GAAG,MAAM,CAAC;AAczC;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAIvC;IACC,IAAI,IAAI,CAAC,qBAAqB;QAAE,OAAO,IAAI,CAAC,qBAAqB,CAAC;IAClE,IAAI,IAAI,CAAC,iBAAiB,IAAI,wBAAwB,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC/E,OAAO,wBAAwB,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,IAAI,CAAC,iBAAiB;QAAE,OAAO,GAAG,IAAI,CAAC,iBAAiB,QAAQ,CAAC;IACrE,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,IAAI,CAAC,QAAQ,QAAQ,CAAC;IACnD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA8G,EAC9G,qBAA8B;IAE9B,MAAM,WAAW,GAAG,uBAAuB,CAAC;QAC1C,qBAAqB;QACrB,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC,CAAC;IACH,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAC;IAE5B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAC5D,MAAM,UAAU,GAAG,MAAM,CAAC,kBAAkB,EAAE,UAAU,IAAI,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,oBAAoB,CAAC;IAC3E,0EAA0E;IAC1E,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,iBAAiB;IACjB,OAAO,CAAC;YACN,WAAW;YACX,SAAS,EAAE,EAAE,GAAG,IAAI;YACpB,OAAO,EAAE,EAAE,GAAG,IAAI;YAClB,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7D,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * Message Extraction Service
+ *
+ * Transforms OTel spans into a chronological conversation message list.
+ * Supports Claude Code telemetry events and generic OTel GenAI conventions.
+ */
+import { Span, ConversationMessage } from '../../types/index.js';
+/**
+ * Extract conversation messages from a flat array of spans.
+ *
+ * Claude Code emits spans with events: user_prompt, api_request, tool_decision, tool_result.
+ * Generic agents use OTel GenAI conventions: llm.request/llm.response events and gen_ai.* attributes.
+ */
+export declare function extractMessagesFromSpans(spans: Span[], serviceName?: string): ConversationMessage[];
+//# sourceMappingURL=messageExtraction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messageExtraction.d.ts","sourceRoot":"","sources":["../../../../services/traces/messageExtraction.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,IAAI,EAAE,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,mBAAmB,EAAE,CA4BvB"}

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

@@ -0,0 +1,313 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Extract conversation messages from a flat array of spans.
+ *
+ * Claude Code emits spans with events: user_prompt, api_request, tool_decision, tool_result.
+ * Generic agents use OTel GenAI conventions: llm.request/llm.response events and gen_ai.* attributes.
+ */
+export function extractMessagesFromSpans(spans, serviceName) {
+    if (!spans || spans.length === 0)
+        return [];
+    const isClaudeCode = serviceName?.startsWith('claude-code') ||
+        spans.some(s => String(s.attributes?.['service.name'] ?? '').startsWith('claude-code')) ||
+        spans.some(s => s.name?.startsWith('claude_code.'));
+    const sorted = [...spans]
+        .filter(s => s.startTime && !isNaN(new Date(s.startTime).getTime()))
+        .sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime());
+    const messages = [];
+    // tool_use_ids that already produced a tool_result message from a `tool`
+    // span's own `tool.output` event, so the sibling `tool.execution` span
+    // (sorted after the call) doesn't push a duplicate result message.
+    const resultEmittedForToolUseId = new Set();
+    for (const span of sorted) {
+        if (isClaudeCode) {
+            extractClaudeCodeMessages(span, messages, resultEmittedForToolUseId);
+        }
+        else {
+            extractGenericMessages(span, messages);
+        }
+    }
+    return messages;
+}
+/**
+ * Extract messages from Claude Code span events.
+ *
+ * Claude Code span hierarchy:
+ *   interaction (root) → llm_request / tool → tool.execution
+ *
+ * Event names: user_prompt, api_request, tool_decision, tool_result
+ */
+function extractClaudeCodeMessages(span, messages, resultEmittedForToolUseId) {
+    const events = span.events || [];
+    const attrs = span.attributes || {};
+    const spanName = span.name?.toLowerCase() || '';
+    // User prompt from interaction span attribute (Claude Code stores it directly)
+    if (spanName.includes('interaction') && attrs['user_prompt'] && attrs['user_prompt'] !== '<REDACTED>') {
+        messages.push({
+            id: `${span.spanId}-user-prompt`,
+            timestamp: span.startTime,
+            role: 'user',
+            content: String(attrs['user_prompt']),
+            metadata: { spanId: span.spanId, spanName: span.name },
+        });
+    }
+    // User prompt events on interaction spans (legacy path)
+    for (const event of events) {
+        if (event.name === 'user_prompt') {
+            const content = event.attributes?.['user.prompt'] ||
+                event.attributes?.['prompt'] ||
+                event.attributes?.['content'] || '';
+            if (content && !messages.some(m => m.id === `${span.spanId}-user-prompt`)) {
+                messages.push({
+                    id: `${span.spanId}-user-prompt-ev`,
+                    timestamp: event.time || span.startTime,
+                    role: 'user',
+                    content: content || '[User prompt — content not captured. Set OTEL_LOG_USER_PROMPTS=1]',
+                    metadata: { spanId: span.spanId, spanName: span.name },
+                });
+            }
+        }
+    }
+    // Tool decision / tool call spans
+    if (spanName.includes('tool') && !spanName.includes('execution') && !spanName.includes('blocked')) {
+        const toolName = attrs['tool_name'] || attrs['gen_ai.tool.name'] || attrs['tool.name'] || span.name;
+        const toolInput = attrs['tool_input'] || attrs['gen_ai.tool.input'] || attrs['full_command'] || '';
+        // Check for tool_decision events
+        const toolDecisionEvent = events.find(e => e.name === 'tool_decision');
+        const input = toolDecisionEvent?.attributes?.['input'] ||
+            toolDecisionEvent?.attributes?.['tool.input'] ||
+            toolInput;
+        if (toolName) {
+            messages.push({
+                id: `${span.spanId}-tool-call`,
+                timestamp: span.startTime,
+                role: 'tool_call',
+                content: typeof input === 'object' ? JSON.stringify(input, null, 2) : String(input || ''),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    toolName: String(toolName),
+                    durationMs: span.duration || (new Date(span.endTime).getTime() - new Date(span.startTime).getTime()),
+                },
+            });
+        }
+        // tool.output event on the tool span (Claude Code emits output here).
+        // Dedup is symmetric with the tool.execution branch below: whichever one
+        // is processed first (normally this one, but a sibling tool.execution
+        // span could sort first under clock skew) marks the tool_use_id, and the
+        // other skips — so a tool call with both result shapes present never
+        // produces two tool_result messages regardless of span order.
+        const toolOutputEvent = events.find(e => e.name === 'tool.output');
+        if (toolOutputEvent) {
+            const output = toolOutputEvent.attributes?.['output'] ||
+                toolOutputEvent.attributes?.['result'] || '';
+            const toolUseId = attrs['tool_use_id'] || attrs['gen_ai.tool.call.id'];
+            const alreadyEmitted = toolUseId != null && resultEmittedForToolUseId.has(String(toolUseId));
+            if (output && !alreadyEmitted) {
+                if (toolUseId)
+                    resultEmittedForToolUseId.add(String(toolUseId));
+                messages.push({
+                    id: `${span.spanId}-tool-output-ev`,
+                    timestamp: toolOutputEvent.time || span.endTime,
+                    role: 'tool_result',
+                    content: typeof output === 'object' ? JSON.stringify(output, null, 2) : String(output),
+                    metadata: {
+                        spanId: span.spanId,
+                        spanName: span.name,
+                        toolName: String(toolName),
+                    },
+                });
+            }
+        }
+    }
+    // Tool result events (legacy path)
+    for (const event of events) {
+        if (event.name === 'tool_result') {
+            const content = event.attributes?.['result'] ||
+                event.attributes?.['output'] ||
+                event.attributes?.['tool.output'] || '';
+            messages.push({
+                id: `${span.spanId}-tool-result-${event.time}`,
+                timestamp: event.time || span.endTime,
+                role: 'tool_result',
+                content: typeof content === 'object' ? JSON.stringify(content, null, 2) : String(content || '[Tool result — content not captured. Set OTEL_LOG_TOOL_CONTENT=1]'),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    toolName: String(span.attributes?.['tool_name'] || span.attributes?.['gen_ai.tool.name'] || ''),
+                },
+            });
+        }
+    }
+    // Tool result from tool.execution span attributes (fallback)
+    if (spanName.includes('tool.execution') || spanName.includes('tool_execution')) {
+        const execToolUseId = attrs['tool_use_id'] || attrs['gen_ai.tool.call.id'];
+        const alreadyEmitted = execToolUseId != null && resultEmittedForToolUseId.has(String(execToolUseId));
+        const output = attrs['gen_ai.tool.output'] || attrs['tool.output'] || attrs['output'];
+        if (output && !alreadyEmitted && !events.some(e => e.name === 'tool_result')) {
+            if (execToolUseId != null)
+                resultEmittedForToolUseId.add(String(execToolUseId));
+            messages.push({
+                id: `${span.spanId}-tool-output`,
+                timestamp: span.endTime,
+                role: 'tool_result',
+                content: typeof output === 'object' ? JSON.stringify(output, null, 2) : String(output),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    toolName: String(attrs['tool_name'] || attrs['gen_ai.tool.name'] || ''),
+                },
+            });
+        }
+    }
+    // LLM response from llm_request spans
+    if (spanName.includes('llm') || spanName.includes('api_request')) {
+        const model = attrs['model'] || attrs['gen_ai.request.model'] || '';
+        const inputTokens = attrs['input_tokens'] || attrs['gen_ai.usage.input_tokens'];
+        const outputTokens = attrs['output_tokens'] || attrs['gen_ai.usage.output_tokens'];
+        // Look for api_request or llm.response events for the completion
+        const responseEvent = events.find(e => e.name === 'llm.response' || e.name === 'api_response');
+        const completion = responseEvent?.attributes?.['llm.completion'] ||
+            responseEvent?.attributes?.['completion'] ||
+            attrs['gen_ai.completion'] || '';
+        if (completion) {
+            messages.push({
+                id: `${span.spanId}-assistant`,
+                timestamp: span.endTime,
+                role: 'assistant',
+                content: String(completion),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    model: String(model),
+                    inputTokens: inputTokens ? Number(inputTokens) : undefined,
+                    outputTokens: outputTokens ? Number(outputTokens) : undefined,
+                    durationMs: span.duration || (new Date(span.endTime).getTime() - new Date(span.startTime).getTime()),
+                },
+            });
+        }
+    }
+}
+/**
+ * Extract messages from generic OTel GenAI spans.
+ * Uses standard llm.request/llm.response events and gen_ai.* attributes.
+ */
+function extractGenericMessages(span, messages) {
+    const events = span.events || [];
+    const attrs = span.attributes || {};
+    // LLM request event → extract user prompt
+    const llmRequest = events.find(e => e.name === 'llm.request');
+    if (llmRequest) {
+        const prompt = llmRequest.attributes?.['llm.prompt'] ||
+            llmRequest.attributes?.['gen_ai.prompt'] ||
+            attrs['gen_ai.prompt'];
+        if (prompt) {
+            messages.push({
+                id: `${span.spanId}-prompt`,
+                timestamp: span.startTime,
+                role: 'user',
+                content: typeof prompt === 'object' ? JSON.stringify(prompt, null, 2) : String(prompt),
+                metadata: { spanId: span.spanId, spanName: span.name },
+            });
+        }
+    }
+    // LLM response event → extract completion
+    const llmResponse = events.find(e => e.name === 'llm.response');
+    if (llmResponse) {
+        const completion = llmResponse.attributes?.['llm.completion'] ||
+            attrs['gen_ai.completion'];
+        if (completion) {
+            messages.push({
+                id: `${span.spanId}-completion`,
+                timestamp: span.endTime,
+                role: 'assistant',
+                content: typeof completion === 'object' ? JSON.stringify(completion, null, 2) : String(completion),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    model: String(attrs['gen_ai.request.model'] || ''),
+                    inputTokens: attrs['gen_ai.usage.input_tokens'] ? Number(attrs['gen_ai.usage.input_tokens']) : undefined,
+                    outputTokens: attrs['gen_ai.usage.output_tokens'] ? Number(attrs['gen_ai.usage.output_tokens']) : undefined,
+                    durationMs: span.duration || (new Date(span.endTime).getTime() - new Date(span.startTime).getTime()),
+                },
+            });
+        }
+    }
+    // Tool spans → tool_call + tool_result.
+    // OTel GenAI conveys tool arguments/results three ways (issue #319/#320):
+    // spec attributes (gen_ai.tool.call.arguments/.result), span events
+    // (gen_ai.tool.message / gen_ai.choice — what Strands emits), and the
+    // legacy non-spec attribute names kept as vendor-compat fallbacks.
+    const toolName = attrs['gen_ai.tool.name'] || attrs['tool.name'];
+    if (toolName) {
+        const toolMessageEvent = events.find(e => e.name === 'gen_ai.tool.message');
+        const toolChoiceEvent = events.find(e => e.name === 'gen_ai.choice');
+        const toolInput = attrs['gen_ai.tool.call.arguments'] ||
+            toolMessageEvent?.attributes?.['content'] ||
+            attrs['gen_ai.tool.input'] || attrs['input'];
+        // Emit the tool_call even when arguments weren't captured — the tool WAS
+        // invoked, and the judge needs to see that (issue #320 root cause 2).
+        messages.push({
+            id: `${span.spanId}-tool-call`,
+            timestamp: span.startTime,
+            role: 'tool_call',
+            content: toolInput
+                ? (typeof toolInput === 'object' ? JSON.stringify(toolInput, null, 2) : String(toolInput))
+                : '',
+            metadata: {
+                spanId: span.spanId,
+                spanName: span.name,
+                toolName: String(toolName),
+                durationMs: span.duration || (new Date(span.endTime).getTime() - new Date(span.startTime).getTime()),
+            },
+        });
+        const toolOutput = attrs['gen_ai.tool.call.result'] ||
+            toolChoiceEvent?.attributes?.['message'] ||
+            toolChoiceEvent?.attributes?.['content'] ||
+            attrs['gen_ai.tool.output'] || attrs['output'];
+        if (toolOutput) {
+            messages.push({
+                id: `${span.spanId}-tool-result`,
+                timestamp: span.endTime,
+                role: 'tool_result',
+                content: typeof toolOutput === 'object' ? JSON.stringify(toolOutput, null, 2) : String(toolOutput),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    toolName: String(toolName),
+                },
+            });
+        }
+    }
+    // Fallback: attributes-only extraction when no events present
+    if (events.length === 0 && !toolName) {
+        const prompt = attrs['gen_ai.prompt'] || attrs['test.case.input'];
+        const completion = attrs['gen_ai.completion'] || attrs['test.case.output'];
+        if (prompt) {
+            messages.push({
+                id: `${span.spanId}-attr-prompt`,
+                timestamp: span.startTime,
+                role: 'user',
+                content: typeof prompt === 'object' ? JSON.stringify(prompt, null, 2) : String(prompt),
+                metadata: { spanId: span.spanId, spanName: span.name },
+            });
+        }
+        if (completion) {
+            messages.push({
+                id: `${span.spanId}-attr-completion`,
+                timestamp: span.endTime,
+                role: 'assistant',
+                content: typeof completion === 'object' ? JSON.stringify(completion, null, 2) : String(completion),
+                metadata: {
+                    spanId: span.spanId,
+                    spanName: span.name,
+                    model: String(attrs['gen_ai.request.model'] || ''),
+                },
+            });
+        }
+    }
+}
+//# sourceMappingURL=messageExtraction.js.map