@ls-stack/agent-eval 0.58.0 → 0.58.2

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { $ as startEvalBackgroundJob, A as repoFile, B as getCurrentScope, C as evalTracer, D as deserializeCacheValue, E as deserializeCacheRecording, F as appendToEvalOutput, G as mergeEvalOutput, H as incrementEvalOutput, J as runInEvalScope, K as nextEvalId, L as evalAssert, M as readManualInputFile, N as evalExpect, Nt as getEvalRegistry, O as serializeCacheRecording, P as EvalAssertionError, Q as setScopeCacheContext, R as evalLog, S as evalSpan, T as hashCacheKeySync, U as isInEvalScope, V as getEvalCaseInput, Y as runInExistingEvalScope, Z as setEvalOutput, at as extractLlmCalls, b as buildTraceTree, it as extractApiCalls, j as manualInputFileValueSchema, k as serializeCacheValue, lt as getNestedAttribute, nt as extractCacheEntries, ot as simulateLlmCallCost, q as runInEvalRuntimeScope, rt as extractCacheHits, st as simulateTokenAllocation, w as hashCacheKey, x as captureEvalSpanError, y as z, z as evalTime } from "./runExecution-C4kAOhC1.mjs";
-import { a as materializeManualInputFiles, i as isManualInputFileValue, n as createRunner, o as stageManualInputFile, r as cleanupStagedManualInputFiles, s as stageManualInputFileFromPath, t as runCli } from "./cli-Cf37PZKi.mjs";
-import { n as matchesEvalTags, t as defineEval } from "./src-303BocMW.mjs";
-export { EvalAssertionError, appendToEvalOutput, buildTraceTree, captureEvalSpanError, cleanupStagedManualInputFiles, createRunner, defineEval, deserializeCacheRecording, deserializeCacheValue, evalAssert, evalExpect, evalLog, evalSpan, evalTime, evalTracer, extractApiCalls, extractCacheEntries, extractCacheHits, extractLlmCalls, getCurrentScope, getEvalCaseInput, getEvalRegistry, getNestedAttribute, hashCacheKey, hashCacheKeySync, incrementEvalOutput, isInEvalScope, isManualInputFileValue, manualInputFileValueSchema, matchesEvalTags, materializeManualInputFiles, mergeEvalOutput, nextEvalId, readManualInputFile, repoFile, runCli, runInEvalRuntimeScope, runInEvalScope, runInExistingEvalScope, serializeCacheRecording, serializeCacheValue, setEvalOutput, setScopeCacheContext, simulateLlmCallCost, simulateTokenAllocation, stageManualInputFile, stageManualInputFileFromPath, startEvalBackgroundJob, z };
+import { $ as setScopeCacheContext, A as repoFile, B as evalTime, C as evalTracer, D as deserializeCacheValue, E as deserializeCacheRecording, F as EvalRuntimeUsageError, Ft as getEvalRegistry, H as getEvalCaseInput, I as appendToEvalOutput, J as runInEvalRuntimeScope, K as mergeEvalOutput, M as readManualInputFile, N as evalExpect, O as serializeCacheRecording, P as EvalAssertionError, Q as setEvalOutput, R as evalAssert, S as evalSpan, T as hashCacheKeySync, U as incrementEvalOutput, V as getCurrentScope, W as isInEvalScope, X as runInExistingEvalScope, Y as runInEvalScope, at as extractApiCalls, b as buildTraceTree, ct as simulateTokenAllocation, et as startEvalBackgroundJob, it as extractCacheHits, j as manualInputFileValueSchema, k as serializeCacheValue, ot as extractLlmCalls, q as nextEvalId, rt as extractCacheEntries, st as simulateLlmCallCost, ut as getNestedAttribute, w as hashCacheKey, x as captureEvalSpanError, y as z, z as evalLog } from "./runExecution-pHJ0_TzH.mjs";
+import { a as materializeManualInputFiles, i as isManualInputFileValue, n as createRunner, o as stageManualInputFile, r as cleanupStagedManualInputFiles, s as stageManualInputFileFromPath, t as runCli } from "./cli-HBwXIJsg.mjs";
+import { n as matchesEvalTags, t as defineEval } from "./src-AeXGBJ26.mjs";
+export { EvalAssertionError, EvalRuntimeUsageError, appendToEvalOutput, buildTraceTree, captureEvalSpanError, cleanupStagedManualInputFiles, createRunner, defineEval, deserializeCacheRecording, deserializeCacheValue, evalAssert, evalExpect, evalLog, evalSpan, evalTime, evalTracer, extractApiCalls, extractCacheEntries, extractCacheHits, extractLlmCalls, getCurrentScope, getEvalCaseInput, getEvalRegistry, getNestedAttribute, hashCacheKey, hashCacheKeySync, incrementEvalOutput, isInEvalScope, isManualInputFileValue, manualInputFileValueSchema, matchesEvalTags, materializeManualInputFiles, mergeEvalOutput, nextEvalId, readManualInputFile, repoFile, runCli, runInEvalRuntimeScope, runInEvalScope, runInExistingEvalScope, serializeCacheRecording, serializeCacheValue, setEvalOutput, setScopeCacheContext, simulateLlmCallCost, simulateTokenAllocation, stageManualInputFile, stageManualInputFileFromPath, startEvalBackgroundJob, z };

package/dist/runChild.mjs

@@ -1,5 +1,5 @@
-import { At as evalChartsConfigSchema, Ct as buildEvalKey, Dt as evalStatAggregateSchema, I as configureEvalRunLogs, Ot as evalStatsConfigSchema, bt as runSummarySchema, et as createRunRequestSchema, jt as columnDefSchema, kt as manualInputDescriptorSchema, l as registerAgentEvalsPackageResolutionHooks, p as loadConfig, v as createFsCacheStore, yt as runManifestSchema } from "./runExecution-C4kAOhC1.mjs";
-import { S as parseEvalDiscovery, m as persistRunState, r as getTargetEvals$1, t as executeRun } from "./runOrchestration-5xEiQxiS.mjs";
+import { At as evalStatsConfigSchema, L as configureEvalRunLogs, Mt as evalChartsConfigSchema, Nt as columnDefSchema, Tt as buildEvalKey, bt as runManifestSchema, jt as manualInputDescriptorSchema, kt as evalStatAggregateSchema, l as registerAgentEvalsPackageResolutionHooks, p as loadConfig, tt as createRunRequestSchema, v as createFsCacheStore, xt as runSummarySchema } from "./runExecution-pHJ0_TzH.mjs";
+import { S as parseEvalDiscovery, m as persistRunState, r as getTargetEvals$1, t as executeRun } from "./runOrchestration-ngVXShH4.mjs";
 import { z } from "zod/v4";
 import { readFile } from "node:fs/promises";
 import { relative } from "node:path";

package/dist/{runExecution-C4kAOhC1.mjs → runExecution-pHJ0_TzH.mjs}

@@ -851,6 +851,7 @@ const runLogLevelSchema = z.enum([
 const runLogPhaseSchema = z.enum([
 	"eval",
 	"derive",
+	"tracingAssertions",
 	"outputsSchema",
 	"scorer"
 ]);
@@ -1008,6 +1009,9 @@ const removeDefaultConfigSchema = z.union([z.literal(true), z.array(defaultConfi
 const evalDeriveValueFnSchema = z.custom((value) => typeof value === "function", { message: "Expected a derive output function" });
 /** Schema for keyed or object-returning trace-derived output config. */
 const evalDeriveConfigSchema = z.union([z.custom((value) => typeof value === "function", { message: "Expected a deriveFromTracing function" }), z.record(z.string().min(1), evalDeriveValueFnSchema)]);
+const evalTracingAssertionsFnSchema = z.custom((value) => typeof value === "function", { message: "Expected a tracing assertions function" });
+/** Schema for function or keyed trace-derived assertion config. */
+const evalTracingAssertionsConfigSchema = z.union([z.custom((value) => typeof value === "function", { message: "Expected a tracingAssertions function" }), z.record(z.string().min(1), evalTracingAssertionsFnSchema)]);
 /** Schema for UI overrides on derived or scored columns. */
 const evalColumnOverrideSchema = z.object({
 	label: z.string().optional(),
@@ -1411,6 +1415,7 @@ const agentEvalsConfigSchema = z.object({
 	traceDisplay: traceDisplayInputConfigSchema.optional(),
 	columns: evalColumnsSchema.optional(),
 	deriveFromTracing: evalDeriveConfigSchema.optional(),
+	tracingAssertions: evalTracingAssertionsConfigSchema.optional(),
 	stats: evalStatsConfigSchema.optional(),
 	defaultStatAggregate: evalStatAggregateSchema.optional(),
 	llmCalls: llmCallsConfigSchema.optional(),
@@ -1847,8 +1852,9 @@ function deriveScopedSummaryFromCases(params) {
 * freshness state.
 */
 function getEvalDisplayStatus(params) {
-	const { stale, outdated, lastRunStatus, isRunning = false } = params;
+	const { stale, outdated, lastRunStatus, isRunning = false, isEnqueued = false } = params;
 	if (isRunning || lastRunStatus === "running") return "running";
+	if (isEnqueued) return "enqueued";
 	if (lastRunStatus === "pass") {
 		if (stale) return "stale";
 		if (outdated) return "outdated";
@@ -2651,6 +2657,7 @@ const scopeStorage = new AsyncLocalStorage();
 const runtimeScopeStorage = new AsyncLocalStorage();
 const evalClockStorage = new AsyncLocalStorage();
 const activeSpanStackStorage = new AsyncLocalStorage();
+const recordingStackStorage = new AsyncLocalStorage();
 let activeEvalScopeCount = 0;
 let activeEvalRuntimeScopeCount = 0;
 let consoleCaptureEnabled = true;
@@ -2717,6 +2724,17 @@ var EvalAssertionError = class extends Error {
 		this.name = "EvalAssertionError";
 	}
 };
+/** Error thrown when an SDK helper is used in an unsupported runner phase. */
+var EvalRuntimeUsageError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EvalRuntimeUsageError";
+	}
+};
+/** Throw when assertion helpers are used in a runner phase that forbids them. */
+function assertEvalAssertionsAllowed(apiName) {
+	if (getCurrentScope() && runtimeScopeStorage.getStore() === "derive") throw new EvalRuntimeUsageError(`${apiName} cannot be used inside deriveFromTracing. Use tracingAssertions for trace-derived assertions.`);
+}
 function getEvalClockStateNowMs(state) {
 	const elapsedMs = state.frozen ? 0 : realDate.now() - state.realStartMs;
 	return state.startMs + elapsedMs + state.offsetMs;
@@ -2803,13 +2821,29 @@ async function runWithActiveSpan(span, fn) {
 	const currentStack = activeSpanStackStorage.getStore() ?? [];
 	return await activeSpanStackStorage.run([...currentStack, span], fn);
 }
+/** Execute a callback with a cache recording frame scoped to this async branch. */
+async function runWithCacheRecordingFrame(frame, fn) {
+	const currentStack = recordingStackStorage.getStore() ?? [];
+	return await recordingStackStorage.run([...currentStack, frame], fn);
+}
+function getCurrentCacheRecordingFrame(scope) {
+	if (scope.replayingDepth > 0) return void 0;
+	return recordingStackStorage.getStore()?.at(-1);
+}
+/** Mark a span as created by the active cache recorder, when one exists. */
+function recordSpanForActiveCacheRecording(scope, spanId) {
+	if (scope.replayingDepth > 0) return;
+	for (const frame of recordingStackStorage.getStore() ?? []) frame.spanIds.add(spanId);
+}
 /**
 * Return the current eval runner phase for this async execution.
 *
 * Returns `null` outside eval-owned work, `env` while the runner is loading
 * eval modules for a run, `cases` while generating cases, `eval` while running
-* case `execute`, `derive` while deriving outputs from traces, `outputsSchema`
-* while validating outputs, and `scorer` while computing scores.
+* case `execute`, `derive` while deriving outputs from traces,
+* `tracingAssertions` while checking trace-derived assertions,
+* `outputsSchema` while validating outputs, and `scorer` while computing
+* scores.
 */
 function isInEvalScope() {
 	if (activeEvalRuntimeScopeCount === 0) return null;
@@ -2830,7 +2864,7 @@ function normalizeLogLevel(level) {
 }
 function getCurrentLogPhase() {
 	const runtimeScope = runtimeScopeStorage.getStore();
-	if (runtimeScope === "eval" || runtimeScope === "derive" || runtimeScope === "outputsSchema" || runtimeScope === "scorer") return runtimeScope;
+	if (runtimeScope === "eval" || runtimeScope === "derive" || runtimeScope === "tracingAssertions" || runtimeScope === "outputsSchema" || runtimeScope === "scorer") return runtimeScope;
 	return null;
 }
 function formatLogArgs(args) {
@@ -3110,7 +3144,6 @@ async function runInEvalScope(caseId, fn, options = {}) {
 		logs: [],
 		spans: [],
 		checkpoints: /* @__PURE__ */ new Map(),
-		recordingStack: [],
 		replayingDepth: 0,
 		cacheContext: options.cacheContext,
 		caseCacheRefs: [],
@@ -3150,10 +3183,16 @@ function nextEvalId() {
 	scope.nextEvalIdCounter++;
 	return `${scope.idPrefix}-${scope.nextEvalIdCounter}`;
 }
-function recordOpIfActive(scope, op) {
-	if (scope.replayingDepth > 0) return;
-	const top = scope.recordingStack.at(-1);
-	if (top) top.ops.push(op);
+function recordCacheRecordingOpIfActive(scope, op) {
+	getCurrentCacheRecordingFrame(scope)?.ops.push(op);
+}
+function recordCacheRecordingAttributesIfActive(scope, span, attributes) {
+	const frames = recordingStackStorage.getStore();
+	if (scope.replayingDepth > 0 || frames === void 0) return;
+	for (const [key, value] of Object.entries(attributes)) {
+		if (key.startsWith("cache.")) continue;
+		for (const frame of frames) if (span.id === frame.replayParentSpanId) frame.finalAttributes[key] = value;
+	}
 }
 function normalizeEvalOutputOptions(options) {
 	if (options === void 0) return void 0;
@@ -3185,7 +3224,7 @@ function setEvalOutput(key, value, options = void 0) {
 	scope.outputs[key] = value;
 	const column = normalizeEvalOutputOptions(options);
 	if (column !== void 0) scope.outputColumnOverrides[key] = column;
-	recordOpIfActive(scope, {
+	recordCacheRecordingOpIfActive(scope, {
 		kind: "setOutput",
 		key,
 		value,
@@ -3205,7 +3244,7 @@ function appendToEvalOutput(key, value) {
 	if (existing === void 0) scope.outputs[key] = [value];
 	else if (Array.isArray(existing)) scope.outputs[key] = [...copyArray$1(existing), value];
 	else scope.outputs[key] = [existing, value];
-	recordOpIfActive(scope, {
+	recordCacheRecordingOpIfActive(scope, {
 		kind: "appendOutput",
 		key,
 		value
@@ -3223,7 +3262,7 @@ function mergeEvalOutput(key, patch) {
 	const existing = scope.outputs[key];
 	if (existing === void 0) {
 		scope.outputs[key] = { ...patch };
-		recordOpIfActive(scope, {
+		recordCacheRecordingOpIfActive(scope, {
 			kind: "mergeOutput",
 			key,
 			patch
@@ -3238,7 +3277,7 @@ function mergeEvalOutput(key, patch) {
 		...existing,
 		...patch
 	};
-	recordOpIfActive(scope, {
+	recordCacheRecordingOpIfActive(scope, {
 		kind: "mergeOutput",
 		key,
 		patch
@@ -3256,7 +3295,7 @@ function incrementEvalOutput(key, delta) {
 	const existing = scope.outputs[key];
 	if (existing === void 0) {
 		scope.outputs[key] = delta;
-		recordOpIfActive(scope, {
+		recordCacheRecordingOpIfActive(scope, {
 			kind: "incrementOutput",
 			key,
 			delta
@@ -3268,7 +3307,7 @@ function incrementEvalOutput(key, delta) {
 		return;
 	}
 	scope.outputs[key] = existing + delta;
-	recordOpIfActive(scope, {
+	recordCacheRecordingOpIfActive(scope, {
 		kind: "incrementOutput",
 		key,
 		delta
@@ -3280,10 +3319,12 @@ function incrementEvalOutput(key, delta) {
 * Calls made outside `runInEvalScope(...)` are ignored so shared workflow code
 * can safely reuse `evalAssert(...)` when it also runs outside an eval. The
 * TypeScript assertion signature still narrows the checked value after the
-* call.
+* call. Calls inside `deriveFromTracing` throw because derivations must only
+* write outputs; use `tracingAssertions` for trace-derived pass/fail checks.
 */
 function evalAssert(condition, message) {
 	const scope = getCurrentScope();
+	assertEvalAssertionsAllowed("evalAssert(...)");
 	if (condition) {
 		if (scope) scope.assertions.push({
 			message,
@@ -3434,6 +3475,7 @@ var EvalExpectationImpl = class EvalExpectationImpl {
 * case scope is active, matching `evalAssert(...)`.
 */
 function evalExpect(value) {
+	assertEvalAssertionsAllowed("evalExpect(...)");
 	return new EvalExpectationImpl(value, false);
 }
 //#endregion
@@ -3675,10 +3717,6 @@ async function materializeExternalJsonValues(value, store) {
 	if (!isRecordLike$3(value)) return value;
 	return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, entryValue]) => [key, await materializeExternalJsonValues(entryValue, store)])));
 }
-/** Clone one value through the same serialization path used for cache data. */
-async function cloneCacheValue(value, options = void 0) {
-	return deserializeCacheValue(await serializeCacheValue(value, options));
-}
 function normalizeCacheSerializationOptions(options) {
 	return {
 		compress: options?.compress !== false,
@@ -4109,29 +4147,6 @@ function valueKind$1(value) {
 function copyArray(value) {
 	return value.map((item) => item);
 }
-function stripCacheAttributes(attributes) {
-	if (!attributes) return {};
-	const result = {};
-	for (const [key, value] of Object.entries(attributes)) if (!key.startsWith("cache.")) result[key] = value;
-	return result;
-}
-async function snapshotNonCacheAttributes(span) {
-	const snapshot = await cloneCacheValue(stripCacheAttributes(span?.attributes));
-	return isRecordLike$2(snapshot) ? snapshot : {};
-}
-function diffNonCacheAttributes(before, after) {
-	const result = {};
-	for (const [key, value] of Object.entries(after)) if (!cacheAttributeValuesEqual(before[key], value)) result[key] = value;
-	return result;
-}
-function cacheAttributeValuesEqual(left, right) {
-	if (Object.is(left, right)) return true;
-	try {
-		return JSON.stringify(left) === JSON.stringify(right);
-	} catch {
-		return false;
-	}
-}
 function appendCacheRef(span, ref) {
 	if (span === void 0) return;
 	const existing = span.attributes?.["cache.refs"];
@@ -4150,7 +4165,7 @@ function recordCacheRef(scope, span, ref) {
 	}
 	scope.caseCacheRefs.push(ref);
 }
-function serializeSubSpanTree(scope, spanId) {
+function serializeSubSpanTree(scope, spanId, spanIds) {
 	const original = scope.spans.find((s) => s.id === spanId);
 	if (!original) return {
 		kind: "custom",
@@ -4163,7 +4178,7 @@ function serializeSubSpanTree(scope, spanId) {
 		warnings: void 0,
 		children: []
 	};
-	const children = scope.spans.filter((s) => s.parentId === spanId).map((child) => serializeSubSpanTree(scope, child.id));
+	const children = scope.spans.filter((s) => s.parentId === spanId && spanIds.has(s.id)).map((child) => serializeSubSpanTree(scope, child.id, spanIds));
 	return {
 		kind: original.kind,
 		name: original.name,
@@ -4179,9 +4194,9 @@ function serializeSubSpanTree(scope, spanId) {
 function appendSubSpanOps(scope, frame) {
 	for (let i = frame.baseSpanIndex; i < scope.spans.length; i++) {
 		const candidate = scope.spans[i];
-		if (candidate?.parentId === frame.replayParentSpanId) frame.ops.push({
+		if (candidate?.parentId === frame.replayParentSpanId && frame.spanIds.has(candidate.id)) frame.ops.push({
 			kind: "subSpan",
-			span: serializeSubSpanTree(scope, candidate.id)
+			span: serializeSubSpanTree(scope, candidate.id, frame.spanIds)
 		});
 	}
 }
@@ -4437,25 +4452,21 @@ function createTraceCache(generateSpanId) {
 			key: keyHash,
 			status: "bypass"
 		});
-		const beforeAttributes = await snapshotNonCacheAttributes(activeSpan);
 		const frame = {
 			baseSpanIndex: scope.spans.length,
 			replayParentSpanId: activeSpan?.id ?? null,
+			spanIds: /* @__PURE__ */ new Set(),
+			finalAttributes: {},
 			ops: []
 		};
-		scope.recordingStack.push(frame);
-		let bodyResult;
-		try {
-			bodyResult = await fn();
-		} finally {
-			scope.recordingStack.pop();
-		}
+		const bodyResult = await runWithCacheRecordingFrame(frame, async () => {
+			return await fn();
+		});
 		appendSubSpanOps(scope, frame);
 		if (canStore) {
-			const finalAttributes = diffNonCacheAttributes(beforeAttributes, await snapshotNonCacheAttributes(activeSpan));
 			const recording = {
 				returnValue: bodyResult,
-				finalAttributes,
+				finalAttributes: frame.finalAttributes,
 				ops: frame.ops
 			};
 			await cacheCtx.adapter.write({
@@ -4514,6 +4525,13 @@ function mergeSpanAttributes(span, attributes) {
 		...span.attributes,
 		...attributes
 	};
+	const scope = getCurrentScope();
+	if (scope !== void 0) recordCacheRecordingAttributesIfActive(scope, span, attributes);
+}
+function copyNonCacheAttributes(attributes) {
+	const result = {};
+	for (const [key, value] of Object.entries(attributes ?? {})) if (!key.startsWith("cache.")) result[key] = value;
+	return result;
 }
 function isRecordLike$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -4688,6 +4706,7 @@ function startExternalSpan(info) {
 		status: "running",
 		attributes: info.attributes
 	});
+	recordSpanForActiveCacheRecording(scope, id);
 	return createExternalSpanHandle(id);
 }
 function updateExternalSpan(info) {
@@ -4746,6 +4765,7 @@ function recordExternalSpan(info) {
 		warning: info.warning,
 		warnings: info.warnings
 	});
+	recordSpanForActiveCacheRecording(scope, id);
 	return id;
 }
 /**
@@ -4831,6 +4851,7 @@ async function traceSpanInternal(info, fn) {
 		attributes: info.attributes
 	};
 	scope.spans.push(spanRecord);
+	recordSpanForActiveCacheRecording(scope, id);
 	const activeSpan = createSpanHandle(spanRecord);
 	return await runWithActiveSpan(spanRecord, async () => {
 		try {
@@ -4880,21 +4901,19 @@ async function traceSpanInternal(info, fn) {
 				const frame = {
 					baseSpanIndex: scope.spans.length,
 					replayParentSpanId: id,
+					spanIds: /* @__PURE__ */ new Set(),
+					finalAttributes: copyNonCacheAttributes(spanRecord.attributes),
 					ops: []
 				};
-				scope.recordingStack.push(frame);
-				let bodyResult;
-				try {
-					bodyResult = await fn(activeSpan);
-				} finally {
-					scope.recordingStack.pop();
-				}
+				const bodyResult = await runWithCacheRecordingFrame(frame, async () => {
+					return await fn(activeSpan);
+				});
 				appendSubSpanOps(scope, frame);
 				finishSpanWithoutThrownError(spanRecord, realStartedAt);
 				if (canStore) {
 					const recording = {
 						returnValue: bodyResult,
-						finalAttributes: stripCacheAttributes(spanRecord.attributes),
+						finalAttributes: frame.finalAttributes,
 						finalStatus: spanRecord.status,
 						finalError: spanRecord.error,
 						finalErrors: spanRecord.errors,
@@ -4998,37 +5017,63 @@ const evalTracer = {
 			status: "ok",
 			attributes: { value: data }
 		});
-		if (scope.replayingDepth === 0) {
-			const top = scope.recordingStack.at(-1);
-			if (top) top.ops.push({
-				kind: "checkpoint",
-				name,
-				data
-			});
-		}
+		recordSpanForActiveCacheRecording(scope, id);
+		recordCacheRecordingOpIfActive(scope, {
+			kind: "checkpoint",
+			name,
+			data
+		});
 	}
 };
 /** Build a queryable trace tree helper from a flat span list and checkpoints. */
 function buildTraceTree(spans, checkpoints) {
+	const rootSpans = spans.filter((s) => s.parentId === null);
+	const flattenDfs = () => {
+		const result = [];
+		function visit(parentId) {
+			for (const childSpan of spans) if (childSpan.parentId === parentId) {
+				result.push(childSpan);
+				visit(childSpan.id);
+			}
+		}
+		visit(null);
+		return result;
+	};
+	const filterSpanNames = (sourceSpans, kind) => {
+		return sourceSpans.filter((span) => kind === void 0 || span.kind === kind).map((span) => span.name);
+	};
 	return {
 		spans,
-		rootSpans: spans.filter((s) => s.parentId === null),
+		rootSpans,
 		findSpan(name) {
 			return spans.find((s) => s.name === name);
 		},
+		findSpans(name) {
+			return spans.filter((s) => s.name === name);
+		},
+		hasSpan(name) {
+			return spans.some((s) => s.name === name);
+		},
 		findSpansByKind(kind) {
 			return spans.filter((s) => s.kind === kind);
 		},
+		findToolCallSpans() {
+			return spans.filter((s) => s.kind === "tool");
+		},
+		listToolCallSpanNames() {
+			return filterSpanNames(spans, "tool");
+		},
+		hasToolCallSpan(name) {
+			return spans.some((s) => s.kind === "tool" && s.name === name);
+		},
+		listSpanNames(kind) {
+			return filterSpanNames(spans, kind);
+		},
+		listSpanNamesDfs(kind) {
+			return filterSpanNames(flattenDfs(), kind);
+		},
 		flattenDfs() {
-			const result = [];
-			function visit(parentId) {
-				for (const childSpan of spans) if (childSpan.parentId === parentId) {
-					result.push(childSpan);
-					visit(childSpan.id);
-				}
-			}
-			visit(null);
-			return result;
+			return flattenDfs();
 		},
 		checkpoints
 	};
@@ -6670,7 +6715,7 @@ async function resolveDeriveFromTracingConfig(params) {
 	return derived;
 }
 async function runDeriveFromTracingConfig(params) {
-	if (params.deriveFromTracing === void 0) return;
+	if (params.deriveFromTracing === void 0) return null;
 	const { deriveFromTracing } = params;
 	try {
 		const derived = await runInExistingEvalScope(params.scope, "derive", async () => await resolveDeriveFromTracingConfig({
@@ -6682,13 +6727,53 @@ async function runDeriveFromTracingConfig(params) {
 			outputs: params.scope.outputs,
 			derived
 		});
+		return null;
 	} catch (e) {
+		if (e instanceof EvalRuntimeUsageError) return e;
 		const message = `deriveFromTracing threw: ${e instanceof Error ? e.message : String(e)}`;
 		recordAssertionFailure(params.scope, toAssertionFailure(message, e instanceof Error ? e : void 0));
+		return null;
 	}
 }
+async function runOneTracingAssertion(params) {
+	const { label, tracingAssertion, scope, traceTree, evalCase } = params;
+	const failureCountBefore = scope.assertionFailures.length;
+	const ctx = {
+		trace: traceTree,
+		input: evalCase.input,
+		case: evalCase
+	};
+	try {
+		await runInExistingEvalScope(scope, "tracingAssertions", async () => {
+			await callUnknownFunction(tracingAssertion, [ctx]);
+		});
+	} catch (e) {
+		if (e instanceof EvalAssertionError && scope.assertionFailures.length > failureCountBefore) return;
+		recordAssertionFailure(scope, toAssertionFailure(`${label} threw: ${e instanceof Error ? e.message : String(e)}`, e instanceof Error ? e : void 0));
+	}
+}
+async function runTracingAssertionsConfig(params) {
+	if (params.tracingAssertions === void 0) return;
+	if (typeof params.tracingAssertions === "function") {
+		await runOneTracingAssertion({
+			label: "tracingAssertions",
+			tracingAssertion: params.tracingAssertions,
+			scope: params.scope,
+			traceTree: params.traceTree,
+			evalCase: params.evalCase
+		});
+		return;
+	}
+	for (const [key, tracingAssertion] of Object.entries(params.tracingAssertions)) await runOneTracingAssertion({
+		label: `tracingAssertions "${key}"`,
+		tracingAssertion,
+		scope: params.scope,
+		traceTree: params.traceTree,
+		evalCase: params.evalCase
+	});
+}
 async function runCase(params) {
-	const { evalDef, evalId, evalKey = evalId, evalCase, globalTraceDisplay, globalColumns, globalDeriveFromTracing, llmCallsConfig = resolveLlmCallsConfig(void 0), apiCallsConfig = resolveApiCallsConfig(void 0), globalRemoveDefaultConfig, trial, startTime, cacheAdapter, cacheMode, moduleIsolation, evalFilePath, evalFileRelativePath = evalFilePath, workspaceRoot, artifactDir, runId } = params;
+	const { evalDef, evalId, evalKey = evalId, evalCase, globalTraceDisplay, globalColumns, globalDeriveFromTracing, globalTracingAssertions, llmCallsConfig = resolveLlmCallsConfig(void 0), apiCallsConfig = resolveApiCallsConfig(void 0), globalRemoveDefaultConfig, trial, startTime, cacheAdapter, cacheMode, moduleIsolation, evalFilePath, evalFileRelativePath = evalFilePath, workspaceRoot, artifactDir, runId } = params;
 	const scopedIdPrefix = buildScopedEvalIdPrefix({
 		evalId,
 		evalFilePath,
@@ -6733,22 +6818,36 @@ async function runCase(params) {
 		apiCallsConfig
 	});
 	const traceTree = buildTraceTree(spansWithDerivedAttributes, scope.checkpoints);
-	const nonAssertError = executeError && !(executeError instanceof EvalAssertionError) ? executeError : null;
+	let nonAssertError = executeError && !(executeError instanceof EvalAssertionError) ? executeError : null;
 	if (executeError instanceof EvalAssertionError && scope.assertionFailures.length === 0) recordAssertionFailure(scope, toAssertionFailure(executeError.message, executeError));
 	if (!nonAssertError) {
-		await runDeriveFromTracingConfig({
+		nonAssertError = await runDeriveFromTracingConfig({
 			deriveFromTracing: globalDeriveFromTracing,
 			scope,
 			traceTree,
 			evalCase
 		});
-		await runDeriveFromTracingConfig({
+		if (!nonAssertError) nonAssertError = await runDeriveFromTracingConfig({
 			deriveFromTracing: evalDef.deriveFromTracing,
 			scope,
 			traceTree,
 			evalCase
 		});
 	}
+	if (!nonAssertError) {
+		await runTracingAssertionsConfig({
+			tracingAssertions: globalTracingAssertions,
+			scope,
+			traceTree,
+			evalCase
+		});
+		await runTracingAssertionsConfig({
+			tracingAssertions: evalDef.tracingAssertions,
+			scope,
+			traceTree,
+			evalCase
+		});
+	}
 	if (!nonAssertError) addDefaultOutputs({
 		outputs: scope.outputs,
 		spans: spansWithDerivedAttributes,
@@ -6938,4 +7037,4 @@ function recordAssertionFailure(scope, failure) {
 	});
 }
 //#endregion
-export { startEvalBackgroundJob as $, repoFile as A, evalChartsConfigSchema as At, getCurrentScope as B, evalTracer as C, buildEvalKey as Ct, deserializeCacheValue as D, evalStatAggregateSchema as Dt, deserializeCacheRecording as E, caseRowSchema as Et, appendToEvalOutput as F, mergeEvalOutput as G, incrementEvalOutput as H, configureEvalRunLogs as I, runInEvalScope as J, nextEvalId as K, evalAssert as L, readManualInputFile as M, defineEval as Mt, evalExpect as N, getEvalRegistry as Nt, serializeCacheRecording as O, evalStatsConfigSchema as Ot, EvalAssertionError as P, runWithEvalRegistry as Pt, setScopeCacheContext as Q, evalLog as R, evalSpan as S, resolveLlmCallsConfig as St, hashCacheKeySync as T, caseDetailSchema as Tt, isInEvalScope as U, getEvalCaseInput as V, matchesEvalTags as W, runWithEvalClock as X, runInExistingEvalScope as Y, setEvalOutput as Z, createBufferedCacheStore as _, validateEvalTagName as _t, isCaseChildParentMessage as a, extractLlmCalls as at, buildTraceTree as b, runSummarySchema as bt, resolveArtifactPath as c, applyDerivedCallAttributes as ct, loadEvalModule as d, getEvalDisplayStatus as dt, createRunRequestSchema as et, resolveEvalDefaultConfig as f, deriveScopedSummaryFromCases as ft, commitPendingCacheWrites as g, matchesTagsFilter as gt, normalizeScoreDef as h, dedupeEvalTags as ht, isCaseChildMessage as i, extractApiCalls as it, manualInputFileValueSchema as j, columnDefSchema as jt, serializeCacheValue as k, manualInputDescriptorSchema as kt, registerAgentEvalsPackageResolutionHooks as l, getNestedAttribute as lt, buildDeclaredColumnDefs as m, deriveStatusFromChildStatuses as mt, resolveRunnableEvalCases as n, extractCacheEntries as nt, stripTerminalControlCodes as o, simulateLlmCallCost as ot, loadConfig as p, deriveStatusFromCaseRows as pt, runInEvalRuntimeScope as q, runCase as r, extractCacheHits as rt, resolveTracePresentation as s, simulateTokenAllocation as st, filterEvalCases as t, updateManualScoreRequestSchema as tt, runWithModuleIsolation as u, getEvalTitle as ut, createFsCacheStore as v, validateTagsFilterExpression as vt, hashCacheKey as w, getCaseRowCaseKey as wt, captureEvalSpanError as x, resolveApiCallsConfig as xt, z$1 as y, runManifestSchema as yt, evalTime as z };
+export { setScopeCacheContext as $, repoFile as A, evalStatsConfigSchema as At, evalTime as B, evalTracer as C, resolveLlmCallsConfig as Ct, deserializeCacheValue as D, caseDetailSchema as Dt, deserializeCacheRecording as E, getCaseRowCaseKey as Et, EvalRuntimeUsageError as F, getEvalRegistry as Ft, matchesEvalTags as G, getEvalCaseInput as H, appendToEvalOutput as I, runWithEvalRegistry as It, runInEvalRuntimeScope as J, mergeEvalOutput as K, configureEvalRunLogs as L, readManualInputFile as M, evalChartsConfigSchema as Mt, evalExpect as N, columnDefSchema as Nt, serializeCacheRecording as O, caseRowSchema as Ot, EvalAssertionError as P, defineEval as Pt, setEvalOutput as Q, evalAssert as R, evalSpan as S, resolveApiCallsConfig as St, hashCacheKeySync as T, buildEvalKey as Tt, incrementEvalOutput as U, getCurrentScope as V, isInEvalScope as W, runInExistingEvalScope as X, runInEvalScope as Y, runWithEvalClock as Z, createBufferedCacheStore as _, matchesTagsFilter as _t, isCaseChildParentMessage as a, extractApiCalls as at, buildTraceTree as b, runManifestSchema as bt, resolveArtifactPath as c, simulateTokenAllocation as ct, loadEvalModule as d, getEvalTitle as dt, startEvalBackgroundJob as et, resolveEvalDefaultConfig as f, getEvalDisplayStatus as ft, commitPendingCacheWrites as g, dedupeEvalTags as gt, normalizeScoreDef as h, deriveStatusFromChildStatuses as ht, isCaseChildMessage as i, extractCacheHits as it, manualInputFileValueSchema as j, manualInputDescriptorSchema as jt, serializeCacheValue as k, evalStatAggregateSchema as kt, registerAgentEvalsPackageResolutionHooks as l, applyDerivedCallAttributes as lt, buildDeclaredColumnDefs as m, deriveStatusFromCaseRows as mt, resolveRunnableEvalCases as n, updateManualScoreRequestSchema as nt, stripTerminalControlCodes as o, extractLlmCalls as ot, loadConfig as p, deriveScopedSummaryFromCases as pt, nextEvalId as q, runCase as r, extractCacheEntries as rt, resolveTracePresentation as s, simulateLlmCallCost as st, filterEvalCases as t, createRunRequestSchema as tt, runWithModuleIsolation as u, getNestedAttribute as ut, createFsCacheStore as v, validateEvalTagName as vt, hashCacheKey as w, buildCaseKey as wt, captureEvalSpanError as x, runSummarySchema as xt, z$1 as y, validateTagsFilterExpression as yt, evalLog as z };