observability-toolkit 2.0.0 → 2.1.0

package/dist/lib/agent-judge/agent-eval-metrics.js

@@ -0,0 +1,715 @@
+/**
+ * Agent Evaluation Metrics
+ *
+ * Higher-level evaluation metrics for agent quality assessment.
+ * Builds on agent-as-judge.ts primitives for comprehensive agent evaluation.
+ *
+ * Single-Turn Metrics:
+ * - Task Completion: End-to-end goal achievement
+ * - Tool Correctness: Proper tool selection
+ * - Argument Correctness: Valid tool parameters
+ *
+ * Multi-Turn Metrics:
+ * - Conversation Completeness: User satisfaction
+ * - Turn Relevancy: On-topic responses
+ * - Handoff Correctness: Appropriate delegation
+ *
+ * @see BACKLOG.md Agent Evaluation Metrics section
+ */
+import { z } from 'zod';
+import { normalizedScoreSchema } from '../core/shared-schemas.js';
+import { stepScoreSchema, toolVerificationSchema } from '../../backends/index.js';
+import { PERCENT_MULTIPLIER, } from '../core/units.js';
+import { BINARY_SCALE_EXCELLENT_THRESHOLD, SCORE_BAND_ADEQUATE, SCORE_BAND_EXCELLENT, SCORE_BAND_GOOD, STEP_SCALE_ADEQUATE_THRESHOLD, } from '../quality/quality-constants.js';
+// ============================================================================
+// Schemas and Types
+// ============================================================================
+/** Record of a tool call */
+export const toolCallRecordSchema = z.object({
+    name: z.string(),
+    arguments: z.record(z.string(), z.unknown()),
+    result: z.unknown().optional(),
+    timestamp: z.string().optional(),
+});
+/** Single-turn evaluation input */
+export const singleTurnInputSchema = z.object({
+    task: z.string(),
+    response: z.string(),
+    expectedResponse: z.string().optional(),
+    toolCalls: z.array(toolCallRecordSchema),
+    expectedTools: z.array(z.string()).optional(),
+    groundTruth: z.record(z.string(), z.unknown()).optional(),
+});
+/** Single turn in a conversation */
+export const conversationTurnSchema = z.object({
+    index: z.number().int().nonnegative(),
+    speaker: z.enum(['user', 'agent']),
+    content: z.string(),
+    timestamp: z.string().optional(),
+    toolCalls: z.array(toolCallRecordSchema).optional(),
+});
+/** Handoff between agents */
+export const handoffEventSchema = z.object({
+    fromAgent: z.string(),
+    toAgent: z.string(),
+    reason: z.string(),
+    wasAppropriate: z.boolean().optional(),
+    timestamp: z.string().optional(),
+});
+/** Multi-turn conversation input */
+export const multiTurnInputSchema = z.object({
+    turns: z.array(conversationTurnSchema),
+    userIntent: z.string(),
+    userSatisfied: z.boolean().optional(),
+    handoffs: z.array(handoffEventSchema).optional(),
+});
+/** Single-turn evaluation result */
+export const singleTurnMetricsSchema = z.object({
+    taskCompletion: normalizedScoreSchema,
+    toolCorrectness: normalizedScoreSchema,
+    argumentCorrectness: normalizedScoreSchema,
+    overallScore: normalizedScoreSchema,
+    toolVerifications: z.array(toolVerificationSchema),
+    explanation: z.string(),
+});
+/** Multi-turn evaluation result */
+export const multiTurnMetricsSchema = z.object({
+    conversationCompleteness: normalizedScoreSchema,
+    turnRelevancy: normalizedScoreSchema,
+    handoffCorrectness: normalizedScoreSchema.nullable(),
+    overallScore: normalizedScoreSchema,
+    turnScores: z.array(stepScoreSchema),
+    turnCount: z.number().int().nonnegative(),
+    explanation: z.string(),
+});
+/** Weights for single-turn metric aggregation */
+export const singleTurnWeightsSchema = z.object({
+    taskCompletion: z.number().nonnegative(),
+    toolCorrectness: z.number().nonnegative(),
+    argumentCorrectness: z.number().nonnegative(),
+});
+/** Weights for multi-turn metric aggregation */
+export const multiTurnWeightsSchema = z.object({
+    conversationCompleteness: z.number().nonnegative(),
+    turnRelevancy: z.number().nonnegative(),
+    handoffCorrectness: z.number().nonnegative(),
+});
+// ============================================================================
+// Weight Sub-Constants
+// ============================================================================
+const SINGLE_TURN_TOOL_CORRECTNESS_WEIGHT = 0.3;
+const SINGLE_TURN_ARG_CORRECTNESS_WEIGHT = 0.2;
+const MULTI_TURN_RELEVANCY_WEIGHT = 0.35;
+const MULTI_TURN_HANDOFF_WEIGHT = 0.15;
+const TOOL_VERIFICATION_TOOL_CORRECT_WEIGHT = 0.4;
+const TOOL_VERIFICATION_ARGS_WEIGHT = 0.3;
+const TOOL_VERIFICATION_RESULT_WEIGHT = 0.3;
+const TASK_COMPLETION_HAS_RESPONSE_WEIGHT = 0.3;
+const TASK_COMPLETION_SUBSTANTIVE_WEIGHT = 0.2;
+const TASK_COMPLETION_HAS_TOOLS_WEIGHT = 0.2;
+const TASK_COMPLETION_RESULTS_WEIGHT = 0.3;
+const TURN_RELEVANCY_TOOL_CALL_BONUS_WEIGHT = 0.2;
+const LONG_RESPONSE_BONUS_WEIGHT = 0.3;
+const MEDIUM_RESPONSE_BONUS_WEIGHT = 0.15;
+const LONG_RESPONSE_MIN_LENGTH = 100;
+const MEDIUM_RESPONSE_MIN_LENGTH = 50;
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default weights for single-turn metrics */
+export const DEFAULT_SINGLE_TURN_WEIGHTS = {
+    taskCompletion: STEP_SCALE_ADEQUATE_THRESHOLD,
+    toolCorrectness: SINGLE_TURN_TOOL_CORRECTNESS_WEIGHT,
+    argumentCorrectness: SINGLE_TURN_ARG_CORRECTNESS_WEIGHT,
+};
+/** Default weights for multi-turn metrics */
+export const DEFAULT_MULTI_TURN_WEIGHTS = {
+    conversationCompleteness: STEP_SCALE_ADEQUATE_THRESHOLD,
+    turnRelevancy: MULTI_TURN_RELEVANCY_WEIGHT,
+    handoffCorrectness: MULTI_TURN_HANDOFF_WEIGHT,
+};
+/** Scoring thresholds and limits for evaluation */
+export const SCORING_THRESHOLDS = {
+    /** Minimum response length for substantive response bonus */
+    SUBSTANTIVE_RESPONSE_MIN_LENGTH: 50,
+    /** Minimum word length for relevancy keyword matching */
+    MIN_WORD_LENGTH_FOR_RELEVANCY: 3,
+    /** Maximum keywords to consider for overlap calculation */
+    MAX_KEYWORDS_FOR_OVERLAP: 10,
+    /** Maximum content length to process (DoS protection) */
+    MAX_CONTENT_LENGTH: 10_000,
+    /** Maximum words to extract for relevancy (DoS protection) */
+    MAX_WORD_COUNT: 1_000,
+};
+/** Weights for tool verification scoring */
+export const TOOL_VERIFICATION_WEIGHTS = {
+    TOOL_CORRECT: TOOL_VERIFICATION_TOOL_CORRECT_WEIGHT,
+    ARGS_CORRECT: TOOL_VERIFICATION_ARGS_WEIGHT,
+    RESULT_CORRECT: TOOL_VERIFICATION_RESULT_WEIGHT,
+};
+/** Weights for task completion scoring */
+export const TASK_COMPLETION_WEIGHTS = {
+    HAS_RESPONSE: TASK_COMPLETION_HAS_RESPONSE_WEIGHT,
+    SUBSTANTIVE_RESPONSE: TASK_COMPLETION_SUBSTANTIVE_WEIGHT,
+    HAS_TOOL_CALLS: TASK_COMPLETION_HAS_TOOLS_WEIGHT,
+    TOOL_RESULTS_COMPLETE: TASK_COMPLETION_RESULTS_WEIGHT,
+};
+/** Precision used for score rounding and normalization */
+export const SCORE_ROUNDING_PRECISION = 10_000;
+/** Heuristic constants for conversation completeness scoring */
+export const CONVERSATION_COMPLETENESS_HEURISTICS = {
+    RESPONDS_TO_USER_TURNS: TASK_COMPLETION_HAS_RESPONSE_WEIGHT,
+    ENDS_WITH_AGENT_RESPONSE: SINGLE_TURN_ARG_CORRECTNESS_WEIGHT,
+    USES_TOOLS_WHEN_NEEDED: SINGLE_TURN_ARG_CORRECTNESS_WEIGHT,
+    LONG_RESPONSE_MIN_LENGTH: LONG_RESPONSE_MIN_LENGTH,
+    MEDIUM_RESPONSE_MIN_LENGTH: MEDIUM_RESPONSE_MIN_LENGTH,
+    LONG_RESPONSE_BONUS: LONG_RESPONSE_BONUS_WEIGHT,
+    MEDIUM_RESPONSE_BONUS: MEDIUM_RESPONSE_BONUS_WEIGHT,
+};
+/** Bonus relevancy score when an agent turn includes tool calls */
+export const TURN_RELEVANCY_TOOL_CALL_BONUS = TURN_RELEVANCY_TOOL_CALL_BONUS_WEIGHT;
+/** Minimum reason length to treat heuristic handoffs as justified */
+export const HANDOFF_REASON_MIN_LENGTH = 10;
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Clamp score to valid range [0, 1]
+ */
+function clampScore(score) {
+    if (!Number.isFinite(score))
+        return 0;
+    return Math.max(0, Math.min(1, score));
+}
+/**
+ * Round score to 4 decimal places for display consistency
+ */
+function roundScore(score) {
+    return Math.round(score * SCORE_ROUNDING_PRECISION) / SCORE_ROUNDING_PRECISION;
+}
+/**
+ * Validate weights sum is positive
+ */
+function validateWeights(weights, name) {
+    const values = Object.values(weights);
+    if (values.some(v => !Number.isFinite(v) || v < 0)) {
+        throw new TypeError(`${name}: All weight values must be non-negative finite numbers`);
+    }
+    const sum = values.reduce((a, b) => a + b, 0);
+    if (sum <= 0) {
+        throw new TypeError(`${name}: Weight sum must be positive, got ${sum}`);
+    }
+}
+/**
+ * Check if object is safe from prototype pollution
+ */
+function isSafeObject(obj) {
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return false;
+    }
+    const proto = Object.prototype.toString.call(obj);
+    if (proto !== '[object Object]') {
+        return false;
+    }
+    // Check for prototype pollution attempts - check own properties only
+    const dangerous = ['__proto__', 'constructor', 'prototype'];
+    return !dangerous.some(key => Object.prototype.hasOwnProperty.call(obj, key));
+}
+/**
+ * Validate SingleTurnInput has required fields
+ */
+function validateSingleTurnInput(input) {
+    if (!input || typeof input !== 'object') {
+        throw new TypeError('Input must be a valid SingleTurnInput object');
+    }
+    const obj = input;
+    if (typeof obj.task !== 'string') {
+        throw new TypeError('Input.task must be a string');
+    }
+    if (typeof obj.response !== 'string') {
+        throw new TypeError('Input.response must be a string');
+    }
+    if (!Array.isArray(obj.toolCalls)) {
+        throw new TypeError('Input.toolCalls must be an array');
+    }
+}
+/**
+ * Validate MultiTurnInput has required fields
+ */
+function validateMultiTurnInput(input) {
+    if (!input || typeof input !== 'object') {
+        throw new TypeError('Input must be a valid MultiTurnInput object');
+    }
+    const obj = input;
+    if (typeof obj.userIntent !== 'string') {
+        throw new TypeError('Input.userIntent must be a string');
+    }
+    if (!Array.isArray(obj.turns)) {
+        throw new TypeError('Input.turns must be an array');
+    }
+    // Validate each turn has valid speaker
+    for (const turn of obj.turns) {
+        if (turn.speaker !== 'user' && turn.speaker !== 'agent') {
+            throw new TypeError('Each turn.speaker must be "user" or "agent"');
+        }
+    }
+}
+// ============================================================================
+// Single-Turn Evaluation Functions
+// ============================================================================
+/**
+ * Evaluate task completion using simple heuristics.
+ * For LLM-based evaluation, use the judge patterns from agent-as-judge.ts.
+ *
+ * @param input - Single-turn evaluation input
+ * @returns Task completion score (0-1)
+ * @throws TypeError if input is invalid
+ */
+export function evaluateTaskCompletion(input) {
+    validateSingleTurnInput(input);
+    let score = 0;
+    // Has response
+    if (input.response.trim().length > 0) {
+        score += TASK_COMPLETION_WEIGHTS.HAS_RESPONSE;
+    }
+    // Has substantive response
+    if (input.response.length > SCORING_THRESHOLDS.SUBSTANTIVE_RESPONSE_MIN_LENGTH) {
+        score += TASK_COMPLETION_WEIGHTS.SUBSTANTIVE_RESPONSE;
+    }
+    // Made tool calls
+    if (input.toolCalls.length > 0) {
+        score += TASK_COMPLETION_WEIGHTS.HAS_TOOL_CALLS;
+    }
+    // All tool calls have results
+    if (input.toolCalls.length > 0) {
+        const withResults = input.toolCalls.filter(tc => tc.result !== undefined);
+        const resultRatio = withResults.length / input.toolCalls.length;
+        score += TASK_COMPLETION_WEIGHTS.TOOL_RESULTS_COMPLETE * resultRatio;
+    }
+    else {
+        // No tools needed, award points
+        score += TASK_COMPLETION_WEIGHTS.TOOL_RESULTS_COMPLETE;
+    }
+    return clampScore(score);
+}
+/**
+ * Evaluate tool correctness using reference comparison.
+ *
+ * @param input - Single-turn evaluation input
+ * @returns Tool correctness score (0-1) and verification details
+ * @throws TypeError if input is invalid
+ */
+export function evaluateToolCorrectness(input) {
+    validateSingleTurnInput(input);
+    if (input.toolCalls.length === 0) {
+        // No tool calls - if expected tools exist, score is 0; otherwise perfect
+        if (input.expectedTools && input.expectedTools.length > 0) {
+            return { score: 0, verifications: [] };
+        }
+        return { score: 1, verifications: [] };
+    }
+    const verifications = [];
+    let totalScore = 0;
+    for (const tc of input.toolCalls) {
+        const expectedIndex = input.expectedTools
+            ? input.expectedTools.indexOf(tc.name)
+            : -1;
+        const toolCorrect = input.expectedTools
+            ? expectedIndex >= 0
+            : true; // No expected list means we assume correct
+        // Argument validation with prototype pollution check
+        const argsCorrect = isSafeObject(tc.arguments) &&
+            Object.keys(tc.arguments).length > 0;
+        const resultCorrect = tc.result !== undefined && tc.result !== null;
+        // Weighted score for this tool call
+        const score = ((toolCorrect ? TOOL_VERIFICATION_WEIGHTS.TOOL_CORRECT : 0) +
+            (argsCorrect ? TOOL_VERIFICATION_WEIGHTS.ARGS_CORRECT : 0) +
+            (resultCorrect ? TOOL_VERIFICATION_WEIGHTS.RESULT_CORRECT : 0));
+        verifications.push({
+            toolName: tc.name,
+            toolCorrect,
+            argsCorrect: !!argsCorrect,
+            resultCorrect,
+            score,
+            expectedTool: input.expectedTools?.[expectedIndex],
+        });
+        totalScore += score;
+    }
+    return {
+        score: clampScore(totalScore / input.toolCalls.length),
+        verifications,
+    };
+}
+/**
+ * Evaluate argument correctness using schema or reference validation.
+ *
+ * @param input - Single-turn evaluation input
+ * @returns Argument correctness score (0-1)
+ * @throws TypeError if input is invalid
+ */
+export function evaluateArgumentCorrectness(input) {
+    validateSingleTurnInput(input);
+    if (input.toolCalls.length === 0) {
+        return 1; // No tool calls to evaluate
+    }
+    let correctArgs = 0;
+    let totalArgs = 0;
+    for (const tc of input.toolCalls) {
+        if (!isSafeObject(tc.arguments)) {
+            totalArgs++;
+            continue;
+        }
+        const argValues = Object.values(tc.arguments);
+        totalArgs += argValues.length || 1;
+        for (const value of argValues) {
+            // Check for valid argument values
+            if (value !== null && value !== undefined && value !== '') {
+                correctArgs++;
+            }
+        }
+    }
+    return clampScore(totalArgs > 0 ? correctArgs / totalArgs : 1);
+}
+/**
+ * Compute all single-turn metrics.
+ *
+ * @param input - Single-turn evaluation input
+ * @param weights - Optional custom weights
+ * @returns Complete single-turn metrics
+ * @throws TypeError if weights are invalid
+ */
+export function computeSingleTurnMetrics(input, weights = DEFAULT_SINGLE_TURN_WEIGHTS) {
+    validateWeights(weights, 'SingleTurnWeights');
+    const taskCompletion = evaluateTaskCompletion(input);
+    const { score: toolCorrectness, verifications } = evaluateToolCorrectness(input);
+    const argumentCorrectness = evaluateArgumentCorrectness(input);
+    // Normalize weights
+    const totalWeight = weights.taskCompletion + weights.toolCorrectness + weights.argumentCorrectness;
+    const normalizedWeights = {
+        taskCompletion: weights.taskCompletion / totalWeight,
+        toolCorrectness: weights.toolCorrectness / totalWeight,
+        argumentCorrectness: weights.argumentCorrectness / totalWeight,
+    };
+    const overallScore = taskCompletion * normalizedWeights.taskCompletion +
+        toolCorrectness * normalizedWeights.toolCorrectness +
+        argumentCorrectness * normalizedWeights.argumentCorrectness;
+    const explanations = [];
+    if (taskCompletion < BINARY_SCALE_EXCELLENT_THRESHOLD) {
+        explanations.push(`Task completion low (${(taskCompletion * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    if (toolCorrectness < SCORE_BAND_EXCELLENT) {
+        explanations.push(`Tool selection issues (${(toolCorrectness * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    if (argumentCorrectness < SCORE_BAND_EXCELLENT) {
+        explanations.push(`Argument validation issues (${(argumentCorrectness * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    return {
+        taskCompletion: roundScore(taskCompletion),
+        toolCorrectness: roundScore(toolCorrectness),
+        argumentCorrectness: roundScore(argumentCorrectness),
+        overallScore: roundScore(overallScore),
+        toolVerifications: verifications,
+        explanation: explanations.length > 0
+            ? explanations.join('; ')
+            : 'All metrics within acceptable range',
+    };
+}
+// ============================================================================
+// Multi-Turn Evaluation Functions
+// ============================================================================
+/**
+ * Evaluate conversation completeness.
+ *
+ * @param input - Multi-turn conversation input
+ * @returns Conversation completeness score (0-1)
+ * @throws TypeError if input is invalid
+ */
+export function evaluateConversationCompleteness(input) {
+    validateMultiTurnInput(input);
+    // If explicit satisfaction signal exists, use it
+    if (input.userSatisfied !== undefined) {
+        return input.userSatisfied ? 1 : 0;
+    }
+    // Heuristic-based evaluation
+    let score = 0;
+    // Has agent responses
+    const agentTurns = input.turns.filter(t => t.speaker === 'agent');
+    const userTurns = input.turns.filter(t => t.speaker === 'user');
+    if (agentTurns.length === 0) {
+        return 0;
+    }
+    // Agent responded to all user turns
+    if (agentTurns.length >= userTurns.length - 1) {
+        score += CONVERSATION_COMPLETENESS_HEURISTICS.RESPONDS_TO_USER_TURNS;
+    }
+    // Last turn is from agent (conversation ended with response)
+    if (input.turns.length > 0 && input.turns[input.turns.length - 1].speaker === 'agent') {
+        score += CONVERSATION_COMPLETENESS_HEURISTICS.ENDS_WITH_AGENT_RESPONSE;
+    }
+    // Agent used tools appropriately
+    const agentToolUsage = agentTurns.some(t => t.toolCalls && t.toolCalls.length > 0);
+    if (agentToolUsage) {
+        score += CONVERSATION_COMPLETENESS_HEURISTICS.USES_TOOLS_WHEN_NEEDED;
+    }
+    // Conversation progressed (increasing content)
+    const avgAgentLength = agentTurns.reduce((sum, t) => sum + t.content.length, 0) / agentTurns.length;
+    if (avgAgentLength > CONVERSATION_COMPLETENESS_HEURISTICS.LONG_RESPONSE_MIN_LENGTH) {
+        score += CONVERSATION_COMPLETENESS_HEURISTICS.LONG_RESPONSE_BONUS;
+    }
+    else if (avgAgentLength > CONVERSATION_COMPLETENESS_HEURISTICS.MEDIUM_RESPONSE_MIN_LENGTH) {
+        score += CONVERSATION_COMPLETENESS_HEURISTICS.MEDIUM_RESPONSE_BONUS;
+    }
+    return clampScore(score);
+}
+/**
+ * Evaluate turn relevancy for each agent turn.
+ *
+ * @param input - Multi-turn conversation input
+ * @returns Per-turn relevancy scores
+ * @throws TypeError if input is invalid
+ */
+export function evaluateTurnRelevancy(input) {
+    validateMultiTurnInput(input);
+    const scores = [];
+    // Helper to extract keywords with DoS protection
+    const extractKeywords = (content) => {
+        const truncated = content.slice(0, SCORING_THRESHOLDS.MAX_CONTENT_LENGTH);
+        const normalizeWord = (w) => w.replace(/[^\w]/g, '');
+        const words = truncated.toLowerCase()
+            .split(/\s+/)
+            .slice(0, SCORING_THRESHOLDS.MAX_WORD_COUNT)
+            .map(normalizeWord)
+            .filter(w => w.length > SCORING_THRESHOLDS.MIN_WORD_LENGTH_FOR_RELEVANCY);
+        return new Set(words);
+    };
+    for (let i = 0; i < input.turns.length; i++) {
+        const turn = input.turns[i];
+        if (turn.speaker !== 'agent')
+            continue;
+        // Find preceding user turn
+        const precedingUserTurn = input.turns
+            .slice(0, i)
+            .reverse()
+            .find(t => t.speaker === 'user');
+        let relevancyScore = STEP_SCALE_ADEQUATE_THRESHOLD; // Default neutral score
+        let explanation = 'Unable to assess relevancy';
+        if (precedingUserTurn) {
+            const userWords = extractKeywords(precedingUserTurn.content);
+            const agentWords = extractKeywords(turn.content);
+            // Iterate over smaller set for efficiency
+            const [smaller, larger] = userWords.size <= agentWords.size
+                ? [userWords, agentWords]
+                : [agentWords, userWords];
+            const overlap = [...smaller].filter(w => larger.has(w)).length;
+            const overlapRatio = userWords.size > 0
+                ? overlap / Math.min(userWords.size, SCORING_THRESHOLDS.MAX_KEYWORDS_FOR_OVERLAP)
+                : 0;
+            // Has some overlap
+            if (overlapRatio > 0) {
+                relevancyScore = clampScore(STEP_SCALE_ADEQUATE_THRESHOLD + overlapRatio * STEP_SCALE_ADEQUATE_THRESHOLD);
+                explanation = `${overlap} keyword matches with user query`;
+            }
+            // Has tool calls (likely trying to help)
+            if (turn.toolCalls && turn.toolCalls.length > 0) {
+                relevancyScore = clampScore(relevancyScore + TURN_RELEVANCY_TOOL_CALL_BONUS);
+                explanation += '; made tool calls';
+            }
+        }
+        scores.push({
+            step: i,
+            score: roundScore(relevancyScore),
+            explanation,
+        });
+    }
+    return scores;
+}
+/**
+ * Evaluate handoff correctness.
+ *
+ * @param input - Multi-turn conversation input
+ * @returns Handoff correctness score (0-1) or null if no handoffs
+ * @throws TypeError if input is invalid
+ */
+export function evaluateHandoffCorrectness(input) {
+    validateMultiTurnInput(input);
+    if (!input.handoffs || input.handoffs.length === 0) {
+        return null; // No handoffs to evaluate
+    }
+    // If explicit annotations exist, use them
+    const annotated = input.handoffs.filter(h => h.wasAppropriate !== undefined);
+    if (annotated.length > 0) {
+        const appropriate = annotated.filter(h => h.wasAppropriate).length;
+        return clampScore(appropriate / annotated.length);
+    }
+    // Heuristic: assume handoffs with reasons are appropriate
+    const withReasons = input.handoffs.filter(h => h.reason && h.reason.length > HANDOFF_REASON_MIN_LENGTH);
+    return clampScore(withReasons.length / input.handoffs.length);
+}
+/**
+ * Compute all multi-turn metrics.
+ *
+ * @param input - Multi-turn conversation input
+ * @param weights - Optional custom weights
+ * @returns Complete multi-turn metrics
+ * @throws TypeError if weights are invalid
+ */
+export function computeMultiTurnMetrics(input, weights = DEFAULT_MULTI_TURN_WEIGHTS) {
+    validateWeights(weights, 'MultiTurnWeights');
+    const conversationCompleteness = evaluateConversationCompleteness(input);
+    const turnScores = evaluateTurnRelevancy(input);
+    const handoffCorrectness = evaluateHandoffCorrectness(input);
+    // Calculate average turn relevancy
+    const turnRelevancy = turnScores.length > 0
+        ? turnScores.reduce((sum, s) => sum + s.score, 0) / turnScores.length
+        : 1;
+    // Normalize weights (exclude handoff if no handoffs)
+    let totalWeight = weights.conversationCompleteness + weights.turnRelevancy;
+    if (handoffCorrectness !== null) {
+        totalWeight += weights.handoffCorrectness;
+    }
+    const normalizedWeights = {
+        conversationCompleteness: weights.conversationCompleteness / totalWeight,
+        turnRelevancy: weights.turnRelevancy / totalWeight,
+        handoffCorrectness: handoffCorrectness !== null
+            ? weights.handoffCorrectness / totalWeight
+            : 0,
+    };
+    let overallScore = conversationCompleteness * normalizedWeights.conversationCompleteness +
+        turnRelevancy * normalizedWeights.turnRelevancy;
+    if (handoffCorrectness !== null) {
+        overallScore += handoffCorrectness * normalizedWeights.handoffCorrectness;
+    }
+    const explanations = [];
+    if (conversationCompleteness < BINARY_SCALE_EXCELLENT_THRESHOLD) {
+        explanations.push(`Conversation may be incomplete (${(conversationCompleteness * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    if (turnRelevancy < BINARY_SCALE_EXCELLENT_THRESHOLD) {
+        explanations.push(`Turn relevancy issues detected (${(turnRelevancy * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    if (handoffCorrectness !== null && handoffCorrectness < SCORE_BAND_GOOD) {
+        explanations.push(`Some handoffs may be inappropriate (${(handoffCorrectness * PERCENT_MULTIPLIER).toFixed(0)}%)`);
+    }
+    return {
+        conversationCompleteness: roundScore(conversationCompleteness),
+        turnRelevancy: roundScore(turnRelevancy),
+        handoffCorrectness: handoffCorrectness !== null ? roundScore(handoffCorrectness) : null,
+        overallScore: roundScore(overallScore),
+        turnScores,
+        turnCount: input.turns.length,
+        explanation: explanations.length > 0
+            ? explanations.join('; ')
+            : 'All metrics within acceptable range',
+    };
+}
+// ============================================================================
+// Conversion Functions
+// ============================================================================
+/**
+ * Convert single-turn metrics to EvaluationResult format.
+ *
+ * @param metrics - Single-turn metrics
+ * @param metadata - Additional metadata (including optional timestamp for consistency)
+ * @returns Array of EvaluationResult records
+ */
+export function singleTurnMetricsToEvaluations(metrics, metadata = {}) {
+    const timestamp = metadata.timestamp || new Date().toISOString();
+    const base = {
+        timestamp,
+        sessionId: metadata.sessionId,
+        agentId: metadata.agentId,
+        agentName: metadata.agentName,
+        evaluator: metadata.evaluator || 'heuristic',
+        evaluatorType: metadata.evaluatorType || 'rule',
+    };
+    return [
+        {
+            ...base,
+            evaluationName: 'task_completion',
+            scoreValue: metrics.taskCompletion,
+            scoreLabel: metrics.taskCompletion >= BINARY_SCALE_EXCELLENT_THRESHOLD ? 'pass' : 'fail',
+            scoreUnit: 'ratio_0_1',
+        },
+        {
+            ...base,
+            evaluationName: 'tool_correctness',
+            scoreValue: metrics.toolCorrectness,
+            scoreLabel: metrics.toolCorrectness >= SCORE_BAND_EXCELLENT ? 'pass' : 'fail',
+            scoreUnit: 'ratio_0_1',
+            toolVerifications: metrics.toolVerifications,
+        },
+        {
+            ...base,
+            evaluationName: 'argument_correctness',
+            scoreValue: metrics.argumentCorrectness,
+            scoreLabel: metrics.argumentCorrectness >= SCORE_BAND_EXCELLENT ? 'pass' : 'fail',
+            scoreUnit: 'ratio_0_1',
+        },
+        {
+            ...base,
+            evaluationName: 'agent_overall',
+            scoreValue: metrics.overallScore,
+            scoreLabel: metrics.overallScore >= SCORE_BAND_GOOD ? 'pass' : (metrics.overallScore >= SCORE_BAND_ADEQUATE ? 'partial' : 'fail'),
+            scoreUnit: 'ratio_0_1',
+            explanation: metrics.explanation,
+        },
+    ];
+}
+/**
+ * Convert multi-turn metrics to EvaluationResult format.
+ *
+ * @param metrics - Multi-turn metrics
+ * @param metadata - Additional metadata (including optional timestamp for consistency)
+ * @returns Array of EvaluationResult records
+ */
+export function multiTurnMetricsToEvaluations(metrics, metadata = {}) {
+    const timestamp = metadata.timestamp || new Date().toISOString();
+    const base = {
+        timestamp,
+        sessionId: metadata.sessionId,
+        agentId: metadata.agentId,
+        agentName: metadata.agentName,
+        evaluator: metadata.evaluator || 'heuristic',
+        evaluatorType: metadata.evaluatorType || 'rule',
+    };
+    const results = [
+        {
+            ...base,
+            evaluationName: 'conversation_completeness',
+            scoreValue: metrics.conversationCompleteness,
+            scoreLabel: metrics.conversationCompleteness >= BINARY_SCALE_EXCELLENT_THRESHOLD ? 'complete' : 'incomplete',
+            scoreUnit: 'ratio_0_1',
+        },
+        {
+            ...base,
+            evaluationName: 'turn_relevancy',
+            scoreValue: metrics.turnRelevancy,
+            scoreLabel: metrics.turnRelevancy >= BINARY_SCALE_EXCELLENT_THRESHOLD ? 'relevant' : 'off-topic',
+            scoreUnit: 'ratio_0_1',
+            stepScores: metrics.turnScores,
+            trajectoryLength: metrics.turnCount,
+        },
+        {
+            ...base,
+            evaluationName: 'conversation_overall',
+            scoreValue: metrics.overallScore,
+            scoreLabel: metrics.overallScore >= SCORE_BAND_GOOD ? 'pass' : (metrics.overallScore >= SCORE_BAND_ADEQUATE ? 'partial' : 'fail'),
+            scoreUnit: 'ratio_0_1',
+            explanation: metrics.explanation,
+            trajectoryLength: metrics.turnCount,
+        },
+    ];
+    // Add handoff evaluation if applicable
+    if (metrics.handoffCorrectness !== null) {
+        results.push({
+            ...base,
+            evaluationName: 'handoff_correctness',
+            scoreValue: metrics.handoffCorrectness,
+            scoreLabel: metrics.handoffCorrectness >= SCORE_BAND_GOOD ? 'appropriate' : 'inappropriate',
+            scoreUnit: 'ratio_0_1',
+        });
+    }
+    return results;
+}
+// ============================================================================
+// Helpers
+//# sourceMappingURL=agent-eval-metrics.js.map