@agentv/core 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,97 @@
1
1
  import * as ai from 'ai';
2
2
 
3
+ /**
4
+ * Trace event types for capturing agent execution traces.
5
+ * Provides a normalized, provider-agnostic model for tool-call trajectories.
6
+ */
7
+ /**
8
+ * Supported trace event types.
9
+ */
10
+ type TraceEventType = 'model_step' | 'tool_call' | 'tool_result' | 'message' | 'error';
11
+ /**
12
+ * Normalized trace event representing a single step in agent execution.
13
+ * Provider-agnostic format for tool-call trajectory evaluation.
14
+ */
15
+ interface TraceEvent {
16
+ /** Event type */
17
+ readonly type: TraceEventType;
18
+ /** ISO 8601 timestamp */
19
+ readonly timestamp: string;
20
+ /** Stable identifier for pairing tool_call/tool_result */
21
+ readonly id?: string;
22
+ /** Tool name (for tool_call/tool_result) */
23
+ readonly name?: string;
24
+ /** Tool input - any JSON value */
25
+ readonly input?: unknown;
26
+ /** Tool output - any JSON value */
27
+ readonly output?: unknown;
28
+ /** Message content (for message/model_step) */
29
+ readonly text?: string;
30
+ /** Provider-specific metadata */
31
+ readonly metadata?: Record<string, unknown>;
32
+ }
33
+ /**
34
+ * Compact summary of a trace for lightweight persistence.
35
+ * Included in results by default to avoid payload bloat.
36
+ */
37
+ interface TraceSummary {
38
+ /** Total number of events in trace */
39
+ readonly eventCount: number;
40
+ /** Unique tool names, sorted alphabetically */
41
+ readonly toolNames: readonly string[];
42
+ /** Map of tool name to call count */
43
+ readonly toolCallsByName: Readonly<Record<string, number>>;
44
+ /** Number of error events */
45
+ readonly errorCount: number;
46
+ }
47
+ /**
48
+ * Configuration for tool_trajectory evaluator.
49
+ */
50
+ interface ToolTrajectoryEvaluatorConfig {
51
+ readonly name: string;
52
+ readonly type: 'tool_trajectory';
53
+ /** Matching mode */
54
+ readonly mode: 'any_order' | 'in_order' | 'exact';
55
+ /** Minimum call counts per tool (for any_order mode) */
56
+ readonly minimums?: Readonly<Record<string, number>>;
57
+ /** Expected tool sequence (for in_order/exact modes) */
58
+ readonly expected?: readonly ToolTrajectoryExpectedItem[];
59
+ }
60
+ /**
61
+ * Expected tool call item in a trajectory sequence.
62
+ */
63
+ interface ToolTrajectoryExpectedItem {
64
+ readonly tool: string;
65
+ }
66
+ /**
67
+ * Expected tool call specification for expected_messages validation.
68
+ */
69
+ interface ExpectedToolCall {
70
+ /** Tool name (required) */
71
+ readonly tool: string;
72
+ /** Tool input - if specified, must match exactly */
73
+ readonly input?: unknown;
74
+ /** Tool output - if specified, must match exactly */
75
+ readonly output?: unknown;
76
+ }
77
+ /**
78
+ * Type guard for TraceEventType values.
79
+ */
80
+ declare function isTraceEventType(value: unknown): value is TraceEventType;
81
+ /**
82
+ * Type guard for TraceEvent objects.
83
+ */
84
+ declare function isTraceEvent(value: unknown): value is TraceEvent;
85
+ /**
86
+ * Type guard for ExpectedToolCall objects.
87
+ */
88
+ declare function isExpectedToolCall(value: unknown): value is ExpectedToolCall;
89
+ /**
90
+ * Compute a lightweight summary from a full trace.
91
+ * Used for default result persistence without payload bloat.
92
+ */
93
+ declare function computeTraceSummary(trace: readonly TraceEvent[]): TraceSummary;
94
+
3
95
  /**
4
96
  * JSON primitive values appearing in AgentV payloads.
5
97
  */
@@ -41,12 +133,21 @@ type UserTestMessage = {
41
133
  readonly role: 'user';
42
134
  readonly content: TestMessageContent;
43
135
  };
136
+ /**
137
+ * Tool call specification for expected_messages validation.
138
+ */
139
+ type TestMessageToolCall = {
140
+ readonly tool: string;
141
+ readonly input?: unknown;
142
+ };
44
143
  /**
45
144
  * Assistant response message.
46
145
  */
47
146
  type AssistantTestMessage = {
48
147
  readonly role: 'assistant';
49
148
  readonly content: TestMessageContent;
149
+ /** Optional tool_calls for expected_messages validation against traces */
150
+ readonly tool_calls?: readonly TestMessageToolCall[];
50
151
  };
51
152
  /**
52
153
  * Tool invocation message.
@@ -75,7 +176,7 @@ declare function isJsonValue(value: unknown): value is JsonValue;
75
176
  * Guard validating raw test messages.
76
177
  */
77
178
  declare function isTestMessage(value: unknown): value is TestMessage;
78
- declare const EVALUATOR_KIND_VALUES: readonly ["code_judge", "llm_judge", "rubric", "composite"];
179
+ declare const EVALUATOR_KIND_VALUES: readonly ["code_judge", "llm_judge", "rubric", "composite", "tool_trajectory", "expected_messages"];
79
180
  type EvaluatorKind = (typeof EVALUATOR_KIND_VALUES)[number];
80
181
  declare function isEvaluatorKind(value: unknown): value is EvaluatorKind;
81
182
  type CodeEvaluatorConfig = {
@@ -118,7 +219,11 @@ type CompositeEvaluatorConfig = {
118
219
  readonly evaluators: readonly EvaluatorConfig[];
119
220
  readonly aggregator: CompositeAggregatorConfig;
120
221
  };
121
- type EvaluatorConfig = CodeEvaluatorConfig | LlmJudgeEvaluatorConfig | CompositeEvaluatorConfig;
222
+ type ExpectedMessagesEvaluatorConfig = {
223
+ readonly name: string;
224
+ readonly type: 'expected_messages';
225
+ };
226
+ type EvaluatorConfig = CodeEvaluatorConfig | LlmJudgeEvaluatorConfig | CompositeEvaluatorConfig | ToolTrajectoryEvaluatorConfig | ExpectedMessagesEvaluatorConfig;
122
227
  /**
123
228
  * Eval case definition sourced from AgentV specs.
124
229
  */
@@ -159,6 +264,10 @@ interface EvaluationResult {
159
264
  readonly evaluator_provider_request?: JsonObject;
160
265
  readonly evaluator_results?: readonly EvaluatorResult[];
161
266
  readonly error?: string;
267
+ /** Lightweight summary of the execution trace (always included when available) */
268
+ readonly trace_summary?: TraceSummary;
269
+ /** Full trace events (only included when --include-trace flag is set) */
270
+ readonly trace?: readonly TraceEvent[];
162
271
  }
163
272
  type EvaluationVerdict = 'pass' | 'fail' | 'borderline';
164
273
  interface EvaluatorResult {
@@ -206,6 +315,10 @@ interface ProviderResponse {
206
315
  readonly reasoning?: string;
207
316
  readonly raw?: unknown;
208
317
  readonly usage?: JsonObject;
318
+ /** Normalized trace events from agent execution */
319
+ readonly trace?: readonly TraceEvent[];
320
+ /** Reference to external trace file (alternative to inline trace) */
321
+ readonly traceRef?: string;
209
322
  }
210
323
  interface Provider {
211
324
  readonly id: string;
@@ -359,6 +472,10 @@ declare function normalizeLineEndings(content: string): string;
359
472
  * This ensures consistent behavior across Windows (CRLF) and Unix (LF) systems.
360
473
  */
361
474
  declare function readTextFile(filePath: string): Promise<string>;
475
+ /**
476
+ * Read a JSON file and parse it.
477
+ */
478
+ declare function readJsonFile<T = unknown>(filePath: string): Promise<T>;
362
479
  /**
363
480
  * Find git repository root by walking up the directory tree.
364
481
  */
@@ -435,6 +552,8 @@ interface MockResolvedConfig {
435
552
  readonly delayMs?: number;
436
553
  readonly delayMinMs?: number;
437
554
  readonly delayMaxMs?: number;
555
+ /** Mock trace events for testing tool_trajectory evaluator */
556
+ readonly trace?: readonly TraceEvent[];
438
557
  }
439
558
  interface VSCodeResolvedConfig {
440
559
  readonly command: string;
@@ -511,7 +630,7 @@ type ResolvedTarget = {
511
630
  readonly providerBatching?: boolean;
512
631
  readonly config: CliResolvedConfig;
513
632
  };
514
- declare function resolveTargetDefinition(definition: TargetDefinition, env?: EnvLookup): ResolvedTarget;
633
+ declare function resolveTargetDefinition(definition: TargetDefinition, env?: EnvLookup, evalFilePath?: string): ResolvedTarget;
515
634
 
516
635
  declare function readTargetDefinitions(filePath: string): Promise<readonly TargetDefinition[]>;
517
636
  declare function listTargetNames(definitions: readonly TargetDefinition[]): readonly string[];
@@ -563,6 +682,10 @@ interface EvaluationContext {
563
682
  readonly judgeProvider?: Provider;
564
683
  readonly evaluatorTemplateOverride?: string;
565
684
  readonly evaluator?: EvaluatorConfig;
685
+ /** Normalized trace events from provider execution (if available) */
686
+ readonly candidateTrace?: readonly TraceEvent[];
687
+ /** Lightweight summary of trace events (if available) */
688
+ readonly candidateTraceSummary?: TraceSummary;
566
689
  }
567
690
  interface EvaluationScore {
568
691
  readonly score: number;
@@ -624,6 +747,30 @@ declare class CodeEvaluator implements Evaluator {
624
747
  constructor(options: CodeEvaluatorOptions);
625
748
  evaluate(context: EvaluationContext): Promise<EvaluationScore>;
626
749
  }
750
+ interface ToolTrajectoryEvaluatorOptions {
751
+ readonly config: ToolTrajectoryEvaluatorConfig;
752
+ }
753
+ declare class ToolTrajectoryEvaluator implements Evaluator {
754
+ readonly kind = "tool_trajectory";
755
+ private readonly config;
756
+ constructor(options: ToolTrajectoryEvaluatorOptions);
757
+ evaluate(context: EvaluationContext): EvaluationScore;
758
+ private evaluateAnyOrder;
759
+ private evaluateInOrder;
760
+ private evaluateExact;
761
+ }
762
+ /**
763
+ * Evaluator that validates tool_calls in expected_messages against the actual trace.
764
+ * Extracts tool_calls from assistant messages in expected_messages and compares them
765
+ * sequentially against tool_call events in the trace.
766
+ */
767
+ declare class ExpectedMessagesEvaluator implements Evaluator {
768
+ readonly kind = "expected_messages";
769
+ evaluate(context: EvaluationContext): EvaluationScore;
770
+ private extractExpectedToolCalls;
771
+ private validateToolCalls;
772
+ private deepEquals;
773
+ }
627
774
  interface EvaluatorFactory {
628
775
  create(config: EvaluatorConfig, context: EvaluationContext): Evaluator;
629
776
  }
@@ -714,4 +861,4 @@ type AgentKernel = {
714
861
  };
715
862
  declare function createAgentKernel(): AgentKernel;
716
863
 
717
- export { type AgentKernel, type AnthropicResolvedConfig, type AssistantTestMessage, type AzureResolvedConfig, type ChildEvaluatorResult, type CliResolvedConfig, CodeEvaluator, type CodeEvaluatorConfig, type CodeEvaluatorOptions, type CompositeAggregatorConfig, CompositeEvaluator, type CompositeEvaluatorConfig, type CompositeEvaluatorOptions, type EnsureSubagentsOptions, type EnsureSubagentsResult, type EnvLookup, type EvalCase, type EvaluationCache, type EvaluationContext, type EvaluationResult, type EvaluationScore, type EvaluationVerdict, type Evaluator, type EvaluatorConfig, type EvaluatorFactory, type EvaluatorKind, type EvaluatorResult, type GeminiResolvedConfig, type GenerateRubricsOptions, type JsonObject, type JsonPrimitive, type JsonValue, LlmJudgeEvaluator, type LlmJudgeEvaluatorConfig, type LlmJudgeEvaluatorOptions, type MockResolvedConfig, type ProgressEvent, type PromptInputs, type Provider, type ProviderKind, type ProviderRequest, type ProviderResponse, type ResolvedTarget, type RubricItem, type RunEvalCaseOptions, type RunEvaluationOptions, type SystemTestMessage, TEST_MESSAGE_ROLES, type TargetDefinition, type TestMessage, type TestMessageContent, type TestMessageRole, type ToolTestMessage, type UserTestMessage, type VSCodeResolvedConfig, buildDirectoryChain, buildPromptInputs, buildSearchRoots, consumeCodexLogEntries, createAgentKernel, createProvider, ensureVSCodeSubagents, extractCodeBlocks, fileExists, findGitRoot, generateRubrics, getHitCount, isEvaluatorKind, isGuidelineFile, isJsonObject, isJsonValue, isTestMessage, isTestMessageRole, listTargetNames, loadEvalCases, normalizeLineEndings, readTargetDefinitions, readTestSuiteMetadata, readTextFile, resolveAndCreateProvider, resolveFileReference, resolveTargetDefinition, runEvalCase, runEvaluation, subscribeToCodexLogEntries };
864
+ export { type AgentKernel, type AnthropicResolvedConfig, type AssistantTestMessage, type AzureResolvedConfig, type ChildEvaluatorResult, type CliResolvedConfig, CodeEvaluator, type CodeEvaluatorConfig, type CodeEvaluatorOptions, type CompositeAggregatorConfig, CompositeEvaluator, type CompositeEvaluatorConfig, type CompositeEvaluatorOptions, type EnsureSubagentsOptions, type EnsureSubagentsResult, type EnvLookup, type EvalCase, type EvaluationCache, type EvaluationContext, type EvaluationResult, type EvaluationScore, type EvaluationVerdict, type Evaluator, type EvaluatorConfig, type EvaluatorFactory, type EvaluatorKind, type EvaluatorResult, ExpectedMessagesEvaluator, type ExpectedMessagesEvaluatorConfig, type ExpectedToolCall, type GeminiResolvedConfig, type GenerateRubricsOptions, type JsonObject, type JsonPrimitive, type JsonValue, LlmJudgeEvaluator, type LlmJudgeEvaluatorConfig, type LlmJudgeEvaluatorOptions, type MockResolvedConfig, type ProgressEvent, type PromptInputs, type Provider, type ProviderKind, type ProviderRequest, type ProviderResponse, type ResolvedTarget, type RubricItem, type RunEvalCaseOptions, type RunEvaluationOptions, type SystemTestMessage, TEST_MESSAGE_ROLES, type TargetDefinition, type TestMessage, type TestMessageContent, type TestMessageRole, type TestMessageToolCall, type ToolTestMessage, ToolTrajectoryEvaluator, type ToolTrajectoryEvaluatorConfig, type ToolTrajectoryEvaluatorOptions, type ToolTrajectoryExpectedItem, type TraceEvent, type TraceEventType, type TraceSummary, type UserTestMessage, type VSCodeResolvedConfig, buildDirectoryChain, buildPromptInputs, buildSearchRoots, computeTraceSummary, consumeCodexLogEntries, createAgentKernel, createProvider, ensureVSCodeSubagents, extractCodeBlocks, fileExists, findGitRoot, generateRubrics, getHitCount, isEvaluatorKind, isExpectedToolCall, isGuidelineFile, isJsonObject, isJsonValue, isTestMessage, isTestMessageRole, isTraceEvent, isTraceEventType, listTargetNames, loadEvalCases, normalizeLineEndings, readJsonFile, readTargetDefinitions, readTestSuiteMetadata, readTextFile, resolveAndCreateProvider, resolveFileReference, resolveTargetDefinition, runEvalCase, runEvaluation, subscribeToCodexLogEntries };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,97 @@
1
1
  import * as ai from 'ai';
2
2
 
3
+ /**
4
+ * Trace event types for capturing agent execution traces.
5
+ * Provides a normalized, provider-agnostic model for tool-call trajectories.
6
+ */
7
+ /**
8
+ * Supported trace event types.
9
+ */
10
+ type TraceEventType = 'model_step' | 'tool_call' | 'tool_result' | 'message' | 'error';
11
+ /**
12
+ * Normalized trace event representing a single step in agent execution.
13
+ * Provider-agnostic format for tool-call trajectory evaluation.
14
+ */
15
+ interface TraceEvent {
16
+ /** Event type */
17
+ readonly type: TraceEventType;
18
+ /** ISO 8601 timestamp */
19
+ readonly timestamp: string;
20
+ /** Stable identifier for pairing tool_call/tool_result */
21
+ readonly id?: string;
22
+ /** Tool name (for tool_call/tool_result) */
23
+ readonly name?: string;
24
+ /** Tool input - any JSON value */
25
+ readonly input?: unknown;
26
+ /** Tool output - any JSON value */
27
+ readonly output?: unknown;
28
+ /** Message content (for message/model_step) */
29
+ readonly text?: string;
30
+ /** Provider-specific metadata */
31
+ readonly metadata?: Record<string, unknown>;
32
+ }
33
+ /**
34
+ * Compact summary of a trace for lightweight persistence.
35
+ * Included in results by default to avoid payload bloat.
36
+ */
37
+ interface TraceSummary {
38
+ /** Total number of events in trace */
39
+ readonly eventCount: number;
40
+ /** Unique tool names, sorted alphabetically */
41
+ readonly toolNames: readonly string[];
42
+ /** Map of tool name to call count */
43
+ readonly toolCallsByName: Readonly<Record<string, number>>;
44
+ /** Number of error events */
45
+ readonly errorCount: number;
46
+ }
47
+ /**
48
+ * Configuration for tool_trajectory evaluator.
49
+ */
50
+ interface ToolTrajectoryEvaluatorConfig {
51
+ readonly name: string;
52
+ readonly type: 'tool_trajectory';
53
+ /** Matching mode */
54
+ readonly mode: 'any_order' | 'in_order' | 'exact';
55
+ /** Minimum call counts per tool (for any_order mode) */
56
+ readonly minimums?: Readonly<Record<string, number>>;
57
+ /** Expected tool sequence (for in_order/exact modes) */
58
+ readonly expected?: readonly ToolTrajectoryExpectedItem[];
59
+ }
60
+ /**
61
+ * Expected tool call item in a trajectory sequence.
62
+ */
63
+ interface ToolTrajectoryExpectedItem {
64
+ readonly tool: string;
65
+ }
66
+ /**
67
+ * Expected tool call specification for expected_messages validation.
68
+ */
69
+ interface ExpectedToolCall {
70
+ /** Tool name (required) */
71
+ readonly tool: string;
72
+ /** Tool input - if specified, must match exactly */
73
+ readonly input?: unknown;
74
+ /** Tool output - if specified, must match exactly */
75
+ readonly output?: unknown;
76
+ }
77
+ /**
78
+ * Type guard for TraceEventType values.
79
+ */
80
+ declare function isTraceEventType(value: unknown): value is TraceEventType;
81
+ /**
82
+ * Type guard for TraceEvent objects.
83
+ */
84
+ declare function isTraceEvent(value: unknown): value is TraceEvent;
85
+ /**
86
+ * Type guard for ExpectedToolCall objects.
87
+ */
88
+ declare function isExpectedToolCall(value: unknown): value is ExpectedToolCall;
89
+ /**
90
+ * Compute a lightweight summary from a full trace.
91
+ * Used for default result persistence without payload bloat.
92
+ */
93
+ declare function computeTraceSummary(trace: readonly TraceEvent[]): TraceSummary;
94
+
3
95
  /**
4
96
  * JSON primitive values appearing in AgentV payloads.
5
97
  */
@@ -41,12 +133,21 @@ type UserTestMessage = {
41
133
  readonly role: 'user';
42
134
  readonly content: TestMessageContent;
43
135
  };
136
+ /**
137
+ * Tool call specification for expected_messages validation.
138
+ */
139
+ type TestMessageToolCall = {
140
+ readonly tool: string;
141
+ readonly input?: unknown;
142
+ };
44
143
  /**
45
144
  * Assistant response message.
46
145
  */
47
146
  type AssistantTestMessage = {
48
147
  readonly role: 'assistant';
49
148
  readonly content: TestMessageContent;
149
+ /** Optional tool_calls for expected_messages validation against traces */
150
+ readonly tool_calls?: readonly TestMessageToolCall[];
50
151
  };
51
152
  /**
52
153
  * Tool invocation message.
@@ -75,7 +176,7 @@ declare function isJsonValue(value: unknown): value is JsonValue;
75
176
  * Guard validating raw test messages.
76
177
  */
77
178
  declare function isTestMessage(value: unknown): value is TestMessage;
78
- declare const EVALUATOR_KIND_VALUES: readonly ["code_judge", "llm_judge", "rubric", "composite"];
179
+ declare const EVALUATOR_KIND_VALUES: readonly ["code_judge", "llm_judge", "rubric", "composite", "tool_trajectory", "expected_messages"];
79
180
  type EvaluatorKind = (typeof EVALUATOR_KIND_VALUES)[number];
80
181
  declare function isEvaluatorKind(value: unknown): value is EvaluatorKind;
81
182
  type CodeEvaluatorConfig = {
@@ -118,7 +219,11 @@ type CompositeEvaluatorConfig = {
118
219
  readonly evaluators: readonly EvaluatorConfig[];
119
220
  readonly aggregator: CompositeAggregatorConfig;
120
221
  };
121
- type EvaluatorConfig = CodeEvaluatorConfig | LlmJudgeEvaluatorConfig | CompositeEvaluatorConfig;
222
+ type ExpectedMessagesEvaluatorConfig = {
223
+ readonly name: string;
224
+ readonly type: 'expected_messages';
225
+ };
226
+ type EvaluatorConfig = CodeEvaluatorConfig | LlmJudgeEvaluatorConfig | CompositeEvaluatorConfig | ToolTrajectoryEvaluatorConfig | ExpectedMessagesEvaluatorConfig;
122
227
  /**
123
228
  * Eval case definition sourced from AgentV specs.
124
229
  */
@@ -159,6 +264,10 @@ interface EvaluationResult {
159
264
  readonly evaluator_provider_request?: JsonObject;
160
265
  readonly evaluator_results?: readonly EvaluatorResult[];
161
266
  readonly error?: string;
267
+ /** Lightweight summary of the execution trace (always included when available) */
268
+ readonly trace_summary?: TraceSummary;
269
+ /** Full trace events (only included when --include-trace flag is set) */
270
+ readonly trace?: readonly TraceEvent[];
162
271
  }
163
272
  type EvaluationVerdict = 'pass' | 'fail' | 'borderline';
164
273
  interface EvaluatorResult {
@@ -206,6 +315,10 @@ interface ProviderResponse {
206
315
  readonly reasoning?: string;
207
316
  readonly raw?: unknown;
208
317
  readonly usage?: JsonObject;
318
+ /** Normalized trace events from agent execution */
319
+ readonly trace?: readonly TraceEvent[];
320
+ /** Reference to external trace file (alternative to inline trace) */
321
+ readonly traceRef?: string;
209
322
  }
210
323
  interface Provider {
211
324
  readonly id: string;
@@ -359,6 +472,10 @@ declare function normalizeLineEndings(content: string): string;
359
472
  * This ensures consistent behavior across Windows (CRLF) and Unix (LF) systems.
360
473
  */
361
474
  declare function readTextFile(filePath: string): Promise<string>;
475
+ /**
476
+ * Read a JSON file and parse it.
477
+ */
478
+ declare function readJsonFile<T = unknown>(filePath: string): Promise<T>;
362
479
  /**
363
480
  * Find git repository root by walking up the directory tree.
364
481
  */
@@ -435,6 +552,8 @@ interface MockResolvedConfig {
435
552
  readonly delayMs?: number;
436
553
  readonly delayMinMs?: number;
437
554
  readonly delayMaxMs?: number;
555
+ /** Mock trace events for testing tool_trajectory evaluator */
556
+ readonly trace?: readonly TraceEvent[];
438
557
  }
439
558
  interface VSCodeResolvedConfig {
440
559
  readonly command: string;
@@ -511,7 +630,7 @@ type ResolvedTarget = {
511
630
  readonly providerBatching?: boolean;
512
631
  readonly config: CliResolvedConfig;
513
632
  };
514
- declare function resolveTargetDefinition(definition: TargetDefinition, env?: EnvLookup): ResolvedTarget;
633
+ declare function resolveTargetDefinition(definition: TargetDefinition, env?: EnvLookup, evalFilePath?: string): ResolvedTarget;
515
634
 
516
635
  declare function readTargetDefinitions(filePath: string): Promise<readonly TargetDefinition[]>;
517
636
  declare function listTargetNames(definitions: readonly TargetDefinition[]): readonly string[];
@@ -563,6 +682,10 @@ interface EvaluationContext {
563
682
  readonly judgeProvider?: Provider;
564
683
  readonly evaluatorTemplateOverride?: string;
565
684
  readonly evaluator?: EvaluatorConfig;
685
+ /** Normalized trace events from provider execution (if available) */
686
+ readonly candidateTrace?: readonly TraceEvent[];
687
+ /** Lightweight summary of trace events (if available) */
688
+ readonly candidateTraceSummary?: TraceSummary;
566
689
  }
567
690
  interface EvaluationScore {
568
691
  readonly score: number;
@@ -624,6 +747,30 @@ declare class CodeEvaluator implements Evaluator {
624
747
  constructor(options: CodeEvaluatorOptions);
625
748
  evaluate(context: EvaluationContext): Promise<EvaluationScore>;
626
749
  }
750
+ interface ToolTrajectoryEvaluatorOptions {
751
+ readonly config: ToolTrajectoryEvaluatorConfig;
752
+ }
753
+ declare class ToolTrajectoryEvaluator implements Evaluator {
754
+ readonly kind = "tool_trajectory";
755
+ private readonly config;
756
+ constructor(options: ToolTrajectoryEvaluatorOptions);
757
+ evaluate(context: EvaluationContext): EvaluationScore;
758
+ private evaluateAnyOrder;
759
+ private evaluateInOrder;
760
+ private evaluateExact;
761
+ }
762
+ /**
763
+ * Evaluator that validates tool_calls in expected_messages against the actual trace.
764
+ * Extracts tool_calls from assistant messages in expected_messages and compares them
765
+ * sequentially against tool_call events in the trace.
766
+ */
767
+ declare class ExpectedMessagesEvaluator implements Evaluator {
768
+ readonly kind = "expected_messages";
769
+ evaluate(context: EvaluationContext): EvaluationScore;
770
+ private extractExpectedToolCalls;
771
+ private validateToolCalls;
772
+ private deepEquals;
773
+ }
627
774
  interface EvaluatorFactory {
628
775
  create(config: EvaluatorConfig, context: EvaluationContext): Evaluator;
629
776
  }
@@ -714,4 +861,4 @@ type AgentKernel = {
714
861
  };
715
862
  declare function createAgentKernel(): AgentKernel;
716
863
 
717
- export { type AgentKernel, type AnthropicResolvedConfig, type AssistantTestMessage, type AzureResolvedConfig, type ChildEvaluatorResult, type CliResolvedConfig, CodeEvaluator, type CodeEvaluatorConfig, type CodeEvaluatorOptions, type CompositeAggregatorConfig, CompositeEvaluator, type CompositeEvaluatorConfig, type CompositeEvaluatorOptions, type EnsureSubagentsOptions, type EnsureSubagentsResult, type EnvLookup, type EvalCase, type EvaluationCache, type EvaluationContext, type EvaluationResult, type EvaluationScore, type EvaluationVerdict, type Evaluator, type EvaluatorConfig, type EvaluatorFactory, type EvaluatorKind, type EvaluatorResult, type GeminiResolvedConfig, type GenerateRubricsOptions, type JsonObject, type JsonPrimitive, type JsonValue, LlmJudgeEvaluator, type LlmJudgeEvaluatorConfig, type LlmJudgeEvaluatorOptions, type MockResolvedConfig, type ProgressEvent, type PromptInputs, type Provider, type ProviderKind, type ProviderRequest, type ProviderResponse, type ResolvedTarget, type RubricItem, type RunEvalCaseOptions, type RunEvaluationOptions, type SystemTestMessage, TEST_MESSAGE_ROLES, type TargetDefinition, type TestMessage, type TestMessageContent, type TestMessageRole, type ToolTestMessage, type UserTestMessage, type VSCodeResolvedConfig, buildDirectoryChain, buildPromptInputs, buildSearchRoots, consumeCodexLogEntries, createAgentKernel, createProvider, ensureVSCodeSubagents, extractCodeBlocks, fileExists, findGitRoot, generateRubrics, getHitCount, isEvaluatorKind, isGuidelineFile, isJsonObject, isJsonValue, isTestMessage, isTestMessageRole, listTargetNames, loadEvalCases, normalizeLineEndings, readTargetDefinitions, readTestSuiteMetadata, readTextFile, resolveAndCreateProvider, resolveFileReference, resolveTargetDefinition, runEvalCase, runEvaluation, subscribeToCodexLogEntries };
864
+ export { type AgentKernel, type AnthropicResolvedConfig, type AssistantTestMessage, type AzureResolvedConfig, type ChildEvaluatorResult, type CliResolvedConfig, CodeEvaluator, type CodeEvaluatorConfig, type CodeEvaluatorOptions, type CompositeAggregatorConfig, CompositeEvaluator, type CompositeEvaluatorConfig, type CompositeEvaluatorOptions, type EnsureSubagentsOptions, type EnsureSubagentsResult, type EnvLookup, type EvalCase, type EvaluationCache, type EvaluationContext, type EvaluationResult, type EvaluationScore, type EvaluationVerdict, type Evaluator, type EvaluatorConfig, type EvaluatorFactory, type EvaluatorKind, type EvaluatorResult, ExpectedMessagesEvaluator, type ExpectedMessagesEvaluatorConfig, type ExpectedToolCall, type GeminiResolvedConfig, type GenerateRubricsOptions, type JsonObject, type JsonPrimitive, type JsonValue, LlmJudgeEvaluator, type LlmJudgeEvaluatorConfig, type LlmJudgeEvaluatorOptions, type MockResolvedConfig, type ProgressEvent, type PromptInputs, type Provider, type ProviderKind, type ProviderRequest, type ProviderResponse, type ResolvedTarget, type RubricItem, type RunEvalCaseOptions, type RunEvaluationOptions, type SystemTestMessage, TEST_MESSAGE_ROLES, type TargetDefinition, type TestMessage, type TestMessageContent, type TestMessageRole, type TestMessageToolCall, type ToolTestMessage, ToolTrajectoryEvaluator, type ToolTrajectoryEvaluatorConfig, type ToolTrajectoryEvaluatorOptions, type ToolTrajectoryExpectedItem, type TraceEvent, type TraceEventType, type TraceSummary, type UserTestMessage, type VSCodeResolvedConfig, buildDirectoryChain, buildPromptInputs, buildSearchRoots, computeTraceSummary, consumeCodexLogEntries, createAgentKernel, createProvider, ensureVSCodeSubagents, extractCodeBlocks, fileExists, findGitRoot, generateRubrics, getHitCount, isEvaluatorKind, isExpectedToolCall, isGuidelineFile, isJsonObject, isJsonValue, isTestMessage, isTestMessageRole, isTraceEvent, isTraceEventType, listTargetNames, loadEvalCases, normalizeLineEndings, readJsonFile, readTargetDefinitions, readTestSuiteMetadata, readTextFile, resolveAndCreateProvider, resolveFileReference, resolveTargetDefinition, runEvalCase, runEvaluation, subscribeToCodexLogEntries };