@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/tools-BmuN627J.js

@@ -0,0 +1,1085 @@
+import { a as NotFoundError } from "./errors-8YnH8WlF.js";
+import { INPUT_VALUE, LLM_MODEL_ATTR_KEYS, OUTPUT_VALUE, SPAN_KIND_ATTR_KEYS, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS } from "./trace-attributes.js";
+import { AxJSRuntime, agent, f, fn } from "@ax-llm/ax";
+import { readFile, stat } from "node:fs/promises";
+//#region src/trace/otlp-attributes.ts
+/** Canonical OpenInference-over-OTLP attribute vocabulary used at the trace boundary. */
+const TOOL_SPAN_ATTRIBUTE_KEYS = [
+	TOOL_NAME,
+	TOOL_ARGS_CAPTURED,
+	TOOL_LATENCY_MS,
+	INPUT_VALUE,
+	OUTPUT_VALUE
+];
+const EXPLICIT_SPAN_ROLES = /* @__PURE__ */ new Set([
+	"AGENT",
+	"CHAIN",
+	"EVALUATOR",
+	"GUARDRAIL",
+	"LLM",
+	"SPAN",
+	"TOOL"
+]);
+/**
+* Classify a span once for both measurement and error accounting.
+* An explicit OpenInference kind wins; untyped spans use the same tool and
+* model signals in online and offline intake.
+*/
+function classifyOtlpSpanRole(input) {
+	const explicitKind = input.kind ?? firstStringAttribute(input.attributes, SPAN_KIND_ATTR_KEYS);
+	if (explicitKind) {
+		const normalized = explicitKind.toUpperCase();
+		if (EXPLICIT_SPAN_ROLES.has(normalized)) return normalized;
+	}
+	if (firstStringAttribute(input.attributes, TOOL_NAME_ATTR_KEYS) !== void 0 || /^(?:function|tool)[.:/]/i.test(input.name)) return "TOOL";
+	const spanType = input.attributes["span.type"];
+	if (typeof spanType === "string" && spanType.toLowerCase() === "llm_request" || /(?:^|[.:/_-])(?:chat[._-]?completions?|llm)(?:$|[.:/_-])/i.test(input.name) || firstStringAttribute(input.attributes, LLM_MODEL_ATTR_KEYS) !== void 0 || typeof input.attributes["gen_ai.operation.name"] === "string") return "LLM";
+	return "UNKNOWN";
+}
+function isOtlpModelCall(input) {
+	return classifyOtlpSpanRole(input) === "LLM";
+}
+function toolSpanOtlpAttributes(span) {
+	const argsCaptured = span.argsCaptured !== false;
+	const attributes = {
+		[TOOL_NAME]: span.toolName,
+		[TOOL_ARGS_CAPTURED]: argsCaptured
+	};
+	if (span.latencyMs !== void 0) attributes[TOOL_LATENCY_MS] = span.latencyMs;
+	if (argsCaptured) attributes[INPUT_VALUE] = stringifyTraceValue(span.args);
+	if (span.result !== void 0) attributes[OUTPUT_VALUE] = stringifyTraceValue(span.result);
+	return attributes;
+}
+function applyToolSpanOtlpAttributes(attributes, span) {
+	for (const key of TOOL_SPAN_ATTRIBUTE_KEYS) delete attributes[key];
+	Object.assign(attributes, toolSpanOtlpAttributes(span));
+}
+function traceSpanKindToOpenInferenceKind(kind) {
+	switch (kind) {
+		case "llm": return "LLM";
+		case "tool": return "TOOL";
+		case "retrieval": return "CHAIN";
+		case "judge": return "EVALUATOR";
+		case "sandbox": return "CHAIN";
+		case "agent": return "AGENT";
+		default: return "SPAN";
+	}
+}
+function firstStringAttribute(attributes, keys) {
+	for (const key of keys) {
+		const value = attributes[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function stringifyTraceValue(value) {
+	if (value === void 0) return "null";
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/trace-analyst/otlp-span.ts
+/**
+* Canonical OTLP-flat-line readers shared by every consumer of the
+* OTLP-JSONL wire shape (one OTLP span per line; the form
+* `flattenOtlpExportToNdjson` produces and the form AppWorld / HALO
+* emit via their OpenInference OTLP exporter).
+*
+* `OtlpFileTraceStore` indexes spans with these; `otlpToRunRecords`
+* aggregates spans into `RunRecord`s with the same readers. One parser,
+* one vocabulary — a divergence between the analyst's view of a trace and
+* the RunRecord projected from it is a class of bug this consolidation
+* removes by construction.
+*
+* Vocabulary. The readers understand BOTH dialects that appear in the
+* wild:
+*   - the substrate's own `llm.*` / `tool.*` / `span.kind` attributes
+*     (`flattenSpanAttributes` in `trace/otel.ts`), and
+*   - the OpenInference / inference-export attributes AppWorld / HALO
+*     emit (`openinference.span.kind`, `inference.observation_kind`,
+*     `inference.llm.input_tokens`, `llm.token_count.prompt`, …).
+*
+* Pure, no I/O.
+*/
+/**
+* Project one parsed OTLP-JSONL object to `ProjectedOtlpSpan`, or `null`
+* when the line is missing the mandatory `trace_id` + `span_id`.
+*/
+function projectOtlpFlatLine(raw) {
+	const trace_id = stringField(raw, "trace_id") ?? stringField(raw, "traceId");
+	const span_id = stringField(raw, "span_id") ?? stringField(raw, "spanId");
+	if (!trace_id || !span_id) return null;
+	const parent_id = normalizeParentSpanId(trace_id, span_id, stringField(raw, "parent_span_id") ?? stringField(raw, "parentSpanId") ?? null);
+	const name = stringField(raw, "name") ?? "unknown";
+	const start_time = stringField(raw, "start_time") ?? stringField(raw, "startTime") ?? "";
+	const end_time = stringField(raw, "end_time") ?? stringField(raw, "endTime") ?? start_time;
+	const status = readOtlpStatus(raw);
+	const attributes = extractOtlpAttributes(raw);
+	const service_name = asString(attributes["service.name"]) ?? asString(attributes["resource.attributes.service.name"]) ?? null;
+	const agent_name = asString(attributes["agent.name"]) ?? asString(attributes["inference.agent.name"]) ?? asString(attributes["inference.agent_name"]) ?? null;
+	const model_name = firstStringAttr(attributes, LLM_MODEL_ATTR_KEYS);
+	const tool_name = firstStringAttr(attributes, TOOL_NAME_ATTR_KEYS);
+	const kind = inferOtlpKind(attributes);
+	let duration_ms = 0;
+	if (start_time && end_time) {
+		const a = spanEpochMillis(start_time);
+		const b = spanEpochMillis(end_time);
+		if (a !== null && b !== null) duration_ms = Math.max(0, b - a);
+	}
+	return {
+		trace_id,
+		span_id,
+		parent_span_id: parent_id && parent_id.length > 0 ? parent_id : null,
+		name,
+		kind,
+		start_time,
+		end_time,
+		duration_ms,
+		status: status.code,
+		status_message: status.message,
+		service_name,
+		agent_name,
+		model_name,
+		tool_name,
+		attributes
+	};
+}
+function normalizeParentSpanId(traceId, spanId, parentId) {
+	if (!parentId) return null;
+	const prefix = `${traceId}:`;
+	return spanId.startsWith(prefix) && !parentId.startsWith(prefix) ? `${prefix}${parentId}` : parentId;
+}
+function readOtlpStatus(raw) {
+	const status = raw.status;
+	if (status && typeof status === "object" && !Array.isArray(status)) {
+		const codeRaw = status.code;
+		const code = codeRaw === "STATUS_CODE_OK" || codeRaw === "OK" ? "OK" : codeRaw === "STATUS_CODE_ERROR" || codeRaw === "ERROR" ? "ERROR" : "UNSET";
+		const messageRaw = status.message;
+		return {
+			code,
+			message: typeof messageRaw === "string" && messageRaw.length > 0 ? messageRaw : void 0
+		};
+	}
+	return {
+		code: "UNSET",
+		message: void 0
+	};
+}
+function inferOtlpKind(attrs) {
+	const opik = firstStringAttr(attrs, SPAN_KIND_ATTR_KEYS);
+	if (opik) {
+		const upper = opik.toUpperCase();
+		if (upper === "AGENT" || upper === "LLM" || upper === "TOOL" || upper === "CHAIN" || upper === "EVALUATOR" || upper === "GUARDRAIL" || upper === "SPAN") return upper;
+	}
+	return "UNKNOWN";
+}
+/**
+* Flatten OTLP `attributes` + `resource.attributes` into a single
+* dotted-key map. Span attributes override resource attributes when keys
+* overlap. Nested objects/arrays are preserved as-is.
+*/
+function extractOtlpAttributes(raw) {
+	const out = {};
+	const resource = raw.resource;
+	if (resource && typeof resource === "object" && !Array.isArray(resource)) {
+		const ra = resource.attributes;
+		if (ra && typeof ra === "object" && !Array.isArray(ra)) for (const [k, v] of Object.entries(ra)) out[k] = v;
+	}
+	const spanAttrs = raw.attributes;
+	if (spanAttrs && typeof spanAttrs === "object" && !Array.isArray(spanAttrs)) for (const [k, v] of Object.entries(spanAttrs)) out[k] = v;
+	return out;
+}
+function stringField(raw, key) {
+	const v = raw[key];
+	return typeof v === "string" ? v : void 0;
+}
+function asString(v) {
+	return typeof v === "string" && v.length > 0 ? v : null;
+}
+/** First non-empty string value across a list of candidate attribute keys. */
+function firstStringAttr(attrs, keys) {
+	for (const k of keys) {
+		const s = asString(attrs[k]);
+		if (s !== null) return s;
+	}
+	return null;
+}
+/**
+* Parse a span timestamp to epoch millis, or null when empty/unparseable. The
+* OTLP readers accept BOTH ISO-8601 and epoch-millis-string dialects, so raw
+* string comparison (`<`, `localeCompare`) mis-orders across dialects and
+* `Date.parse` returns NaN for a bare epoch-millis string.
+*/
+function spanEpochMillis(ts) {
+	if (!ts) return null;
+	if (/^\d+$/.test(ts)) return Number(ts);
+	const n = Date.parse(ts);
+	return Number.isNaN(n) ? null : n;
+}
+/**
+* Order comparator for span timestamps across mixed ISO/epoch dialects.
+* Unparseable timestamps sort as epoch 0 (earliest), never NaN (which would
+* make the sort non-deterministic).
+*/
+function compareSpanTime(a, b) {
+	return (spanEpochMillis(a) ?? 0) - (spanEpochMillis(b) ?? 0);
+}
+//#endregion
+//#region src/trace-analyst/store.ts
+/** Compile a regex with the same anchoring + flags semantics across
+*  implementations. Throws on invalid pattern — callers should surface
+*  that to the agent so it can refine instead of looping. */
+function compileSearchRegex(pattern) {
+	let source = pattern;
+	let flags = "m";
+	if (source.startsWith("(?i)")) {
+		source = source.slice(4);
+		flags += "i";
+	}
+	return new RegExp(source, flags);
+}
+/** Truncate string payload deterministically for tool responses.
+*  Marker is parseable so downstream consumers can detect truncation
+*  and decide whether to fetch surgically. */
+function truncateForBudget(value, byteCap) {
+	const original = Buffer.byteLength(value, "utf8");
+	if (original <= byteCap) return value;
+	const ratio = byteCap / original;
+	let cut = Math.max(0, Math.floor(value.length * ratio));
+	while (cut > 0 && Buffer.byteLength(value.slice(0, cut), "utf8") > byteCap) cut -= 1;
+	return `${value.slice(0, cut)}\n[trace-analyst truncated: original ${original} bytes]`;
+}
+//#endregion
+//#region src/trace-analyst/types.ts
+const DEFAULT_TRACE_ANALYST_BUDGETS = {
+	perCallByteCeiling: 15e4,
+	perAttributeViewBudget: 4096,
+	perAttributeSpanBudget: 16384,
+	perMatchTextBudget: 1024
+};
+/** Marker substituted in place of truncated string payloads. Callers
+*  parsing tool output can detect it deterministically. */
+const TRACE_ANALYST_TRUNCATION_MARKER_PREFIX = "[trace-analyst truncated:";
+//#endregion
+//#region src/trace-analyst/store-otlp.ts
+/**
+* `OtlpFileTraceStore` — read-only OTLP-JSONL trace store for the
+* trace-analyst.
+*
+* Wire shape. Each line of the input file is one OTLP-shaped span. The
+* store understands flattened OTLP JSONL plus the OpenInference vocab.
+* We project upstream's full
+* span shape down to `TraceAnalystSpan` lazily — full materialisation
+* only happens for the spans the agent actually requests.
+*
+* Indexing. On first read the store builds an in-memory index keyed
+* by `trace_id` carrying:
+*   - byte offsets + lengths for each span line (for surgical reads
+*     without re-parsing the whole file)
+*   - a `TraceAnalystTraceSummary` rollup
+*   - sets of services / agents / models / tools / has_errors
+*   - byte size of the trace's JSONL slab
+*
+* Memory bound. The index keeps span metadata only — names, kinds,
+* offsets, status. Attribute payloads stay on disk until requested.
+* For a 50MB JSONL with 50k spans, the index is ~5MB.
+*
+* Concurrency. The store builds the index once on first read and
+* caches it. Subsequent reads reuse the index. The file is opened on
+* each read; we never hold a long-lived FD.
+*/
+/** Lines indexed between event-loop yields. Bounded synchronous work per
+*  tick keeps the index build from starving other tasks on large files
+*  while staying coarse enough that the yields are cheap. */
+const INDEX_YIELD_LINES = 5e3;
+/** Hand control back to the event loop without busy-waiting. */
+function yieldToEventLoop() {
+	return new Promise((resolve) => setImmediate(resolve));
+}
+var OtlpFileTraceStore = class {
+	path;
+	perAttributeViewBudget;
+	perAttributeSpanBudget;
+	perCallByteCeiling;
+	perMatchTextBudget;
+	maxFileBytes;
+	indexPromise;
+	/** Cached UTF-8 buffer of the file. We pin it once because every
+	*  read needs slice access and re-reading on each call balloons the
+	*  syscall count. */
+	bufferPromise;
+	constructor(opts) {
+		this.path = opts.path;
+		this.perAttributeViewBudget = opts.perAttributeViewBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perAttributeViewBudget;
+		this.perAttributeSpanBudget = opts.perAttributeSpanBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perAttributeSpanBudget;
+		this.perCallByteCeiling = opts.perCallByteCeiling ?? DEFAULT_TRACE_ANALYST_BUDGETS.perCallByteCeiling;
+		this.perMatchTextBudget = opts.perMatchTextBudget ?? DEFAULT_TRACE_ANALYST_BUDGETS.perMatchTextBudget;
+		this.maxFileBytes = opts.maxFileBytes ?? 268435456;
+	}
+	async getOverview(filters) {
+		const idx = await this.index();
+		const matched = await this.matchedTraces(idx, filters);
+		const services = /* @__PURE__ */ new Set();
+		const agents = /* @__PURE__ */ new Set();
+		const models = /* @__PURE__ */ new Set();
+		const tools = /* @__PURE__ */ new Set();
+		let rawBytes = 0;
+		let earliest = null;
+		let latest = null;
+		let errorTraceCount = 0;
+		let errorSpanCount = 0;
+		const clusters = /* @__PURE__ */ new Map();
+		for (const t of matched) {
+			if (t.service_name) services.add(t.service_name);
+			if (t.agent_name) agents.add(t.agent_name);
+			for (const m of t.models) models.add(m);
+			for (const tn of t.tools) tools.add(tn);
+			rawBytes += t.raw_jsonl_bytes;
+			if (!earliest || compareSpanTime(t.start_time, earliest) < 0) earliest = t.start_time;
+			if (!latest || compareSpanTime(t.end_time, latest) > 0) latest = t.end_time;
+			if (t.has_errors) {
+				errorTraceCount += 1;
+				for (const s of t.spans) {
+					if (s.status !== "ERROR") continue;
+					errorSpanCount += 1;
+					accumulateErrorCluster(clusters, t.trace_id, s);
+				}
+			}
+		}
+		const sample_trace_ids = matched.slice(0, 20).map((t) => t.trace_id);
+		return {
+			total_traces: matched.length,
+			raw_jsonl_bytes: rawBytes,
+			services: [...services].sort(),
+			agents: [...agents].sort(),
+			models: [...models].sort(),
+			tool_names: [...tools].sort(),
+			sample_trace_ids,
+			errors: {
+				trace_count: errorTraceCount,
+				span_count: errorSpanCount
+			},
+			error_clusters: finalizeErrorClusters(clusters, errorTraceCount),
+			time_range: earliest && latest ? {
+				earliest,
+				latest
+			} : null
+		};
+	}
+	async queryTraces(opts) {
+		if (!Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 200) throw new RangeError(`queryTraces.limit must be 1..200, got ${opts.limit}`);
+		const offset = opts.offset ?? 0;
+		if (!Number.isInteger(offset) || offset < 0) throw new RangeError(`queryTraces.offset must be >=0, got ${offset}`);
+		const idx = await this.index();
+		const matched = await this.matchedTraces(idx, opts.filters);
+		const slice = matched.slice(offset, offset + opts.limit);
+		return {
+			traces: slice.map((t) => this.toSummary(t)),
+			total: matched.length,
+			has_more: offset + slice.length < matched.length
+		};
+	}
+	async countTraces(filters) {
+		const idx = await this.index();
+		return (await this.matchedTraces(idx, filters)).length;
+	}
+	async viewTrace(opts) {
+		const trace = (await this.index()).byTrace.get(opts.trace_id);
+		if (!trace) throw new TraceNotFoundError(opts.trace_id);
+		const cap = opts.per_attribute_byte_cap ?? this.perAttributeViewBudget;
+		const buf = await this.buffer();
+		const spans = [];
+		let runningBytes = 0;
+		let span_response_bytes_max = 0;
+		const counter = { value: 0 };
+		for (const s of trace.spans) {
+			const projected = this.projectSpan(buf, trace.trace_id, s, cap, counter);
+			const bytes = Buffer.byteLength(JSON.stringify(projected), "utf8");
+			span_response_bytes_max = Math.max(span_response_bytes_max, bytes);
+			runningBytes += bytes;
+			if (runningBytes > this.perCallByteCeiling) return {
+				trace_id: trace.trace_id,
+				oversized: this.buildOversizedSummary(trace, span_response_bytes_max)
+			};
+			spans.push(projected);
+		}
+		return {
+			trace_id: trace.trace_id,
+			spans
+		};
+	}
+	async viewSpans(opts) {
+		const trace = (await this.index()).byTrace.get(opts.trace_id);
+		if (!trace) throw new TraceNotFoundError(opts.trace_id);
+		if (opts.span_ids.length === 0) return {
+			trace_id: trace.trace_id,
+			spans: [],
+			missing_span_ids: [],
+			truncated_attribute_count: 0
+		};
+		if (opts.span_ids.length > 100) throw new RangeError(`viewSpans.span_ids cap is 100, got ${opts.span_ids.length}`);
+		const cap = opts.per_attribute_byte_cap ?? this.perAttributeSpanBudget;
+		const wantSet = new Set(opts.span_ids);
+		const found = trace.spans.filter((s) => wantSet.has(s.span_id));
+		const missing = opts.span_ids.filter((id) => !found.some((f) => f.span_id === id));
+		const buf = await this.buffer();
+		const spans = [];
+		const counter = { value: 0 };
+		let runningBytes = 0;
+		for (const s of found) {
+			const projected = this.projectSpan(buf, trace.trace_id, s, cap, counter);
+			const bytes = Buffer.byteLength(JSON.stringify(projected), "utf8");
+			runningBytes += bytes;
+			if (runningBytes > this.perCallByteCeiling) break;
+			spans.push(projected);
+		}
+		return {
+			trace_id: trace.trace_id,
+			spans,
+			missing_span_ids: missing,
+			truncated_attribute_count: counter.value
+		};
+	}
+	async searchTrace(opts) {
+		const max_matches = opts.max_matches ?? 50;
+		if (!Number.isInteger(max_matches) || max_matches < 1 || max_matches > 500) throw new RangeError(`searchTrace.max_matches must be 1..500, got ${max_matches}`);
+		const trace = (await this.index()).byTrace.get(opts.trace_id);
+		if (!trace) throw new TraceNotFoundError(opts.trace_id);
+		const re = compileSearchRegex(opts.regex_pattern);
+		const buf = await this.buffer();
+		const hits = [];
+		let total = 0;
+		let capped = false;
+		for (const s of trace.spans) {
+			const remaining = max_matches - hits.length;
+			const localHits = await this.scanSpanForMatches(buf, trace.trace_id, s, re, this.perMatchTextBudget, remaining);
+			total += localHits.total;
+			for (const h of localHits.records) {
+				if (hits.length >= max_matches) break;
+				hits.push(h);
+			}
+			if (hits.length >= max_matches) {
+				capped = true;
+				break;
+			}
+		}
+		return {
+			trace_id: trace.trace_id,
+			hits,
+			total_matches: capped ? hits.length : total,
+			has_more: capped || total > hits.length
+		};
+	}
+	async searchSpan(opts) {
+		const max_matches = opts.max_matches ?? 50;
+		if (!Number.isInteger(max_matches) || max_matches < 1 || max_matches > 500) throw new RangeError(`searchSpan.max_matches must be 1..500, got ${max_matches}`);
+		const trace = (await this.index()).byTrace.get(opts.trace_id);
+		if (!trace) throw new TraceNotFoundError(opts.trace_id);
+		const span = trace.spans.find((s) => s.span_id === opts.span_id);
+		if (!span) throw new SpanNotFoundError(opts.trace_id, opts.span_id);
+		const re = compileSearchRegex(opts.regex_pattern);
+		const buf = await this.buffer();
+		const localHits = await this.scanSpanForMatches(buf, trace.trace_id, span, re, this.perMatchTextBudget, max_matches);
+		return {
+			trace_id: trace.trace_id,
+			span_id: span.span_id,
+			hits: localHits.records,
+			total_matches: localHits.total,
+			has_more: localHits.total > localHits.records.length
+		};
+	}
+	/** Force the index to materialise. Useful to amortise startup cost
+	*  before the first agent call. */
+	async ensureIndexed() {
+		await this.index();
+	}
+	async buffer() {
+		if (!this.bufferPromise) this.bufferPromise = this.readGuarded();
+		return this.bufferPromise;
+	}
+	/** Stat-then-read so an oversized file fails loud BEFORE we allocate a
+	*  multi-hundred-MB Buffer and OOM the process. A missing file surfaces
+	*  as TraceFileMissingError; any other stat/read error propagates. */
+	async readGuarded() {
+		let stats;
+		try {
+			stats = await stat(this.path);
+		} catch (err) {
+			if (err?.code === "ENOENT") throw new TraceFileMissingError(this.path);
+			throw err;
+		}
+		if (stats.size > this.maxFileBytes) throw new TraceFileTooLargeError(this.path, stats.size, this.maxFileBytes);
+		return readFile(this.path);
+	}
+	async index() {
+		if (!this.indexPromise) this.indexPromise = this.buildIndex();
+		return this.indexPromise;
+	}
+	async buildIndex() {
+		const buf = await this.buffer();
+		const byTrace = /* @__PURE__ */ new Map();
+		let cursor = 0;
+		let sinceYield = 0;
+		while (cursor < buf.length) {
+			if (++sinceYield >= INDEX_YIELD_LINES) {
+				sinceYield = 0;
+				await yieldToEventLoop();
+			}
+			const newlineIndex = buf.indexOf(10, cursor);
+			const lineEnd = newlineIndex === -1 ? buf.length : newlineIndex;
+			const lineLength = lineEnd - cursor;
+			if (lineLength === 0) {
+				cursor = lineEnd + 1;
+				continue;
+			}
+			const lineSlice = buf.subarray(cursor, lineEnd).toString("utf8");
+			const lineOffset = cursor;
+			cursor = lineEnd + 1;
+			let parsed;
+			try {
+				parsed = JSON.parse(lineSlice);
+			} catch {
+				continue;
+			}
+			if (!parsed || typeof parsed !== "object") continue;
+			const span = projectOtlpFlatLine(parsed);
+			if (!span) continue;
+			let entry = byTrace.get(span.trace_id);
+			if (!entry) {
+				entry = {
+					trace_id: span.trace_id,
+					service_name: span.service_name,
+					agent_name: span.agent_name,
+					span_count: 0,
+					has_errors: false,
+					start_time: span.start_time,
+					end_time: span.end_time,
+					duration_ms: 0,
+					raw_jsonl_bytes: 0,
+					models: /* @__PURE__ */ new Set(),
+					tools: /* @__PURE__ */ new Set(),
+					spans: []
+				};
+				byTrace.set(span.trace_id, entry);
+			} else {
+				if (!entry.service_name && span.service_name) entry.service_name = span.service_name;
+				if (!entry.agent_name && span.agent_name) entry.agent_name = span.agent_name;
+			}
+			const indexEntry = {
+				span_id: span.span_id,
+				parent_span_id: span.parent_span_id,
+				name: span.name,
+				kind: span.kind,
+				start_time: span.start_time,
+				end_time: span.end_time,
+				duration_ms: span.duration_ms,
+				status: span.status,
+				status_message: span.status_message,
+				service_name: span.service_name,
+				agent_name: span.agent_name,
+				model_name: span.model_name,
+				tool_name: span.tool_name,
+				line_byte_offset: lineOffset,
+				line_byte_length: lineLength
+			};
+			entry.spans.push(indexEntry);
+			entry.span_count += 1;
+			entry.raw_jsonl_bytes += lineLength + 1;
+			if (span.status === "ERROR") entry.has_errors = true;
+			if (compareSpanTime(span.start_time, entry.start_time) < 0) entry.start_time = span.start_time;
+			if (compareSpanTime(span.end_time, entry.end_time) > 0) entry.end_time = span.end_time;
+			if (span.model_name) entry.models.add(span.model_name);
+			if (span.tool_name) entry.tools.add(span.tool_name);
+		}
+		let totalRawBytes = 0;
+		for (const t of byTrace.values()) {
+			totalRawBytes += t.raw_jsonl_bytes;
+			t.spans.sort((a, b) => compareSpanTime(a.start_time, b.start_time) || a.line_byte_offset - b.line_byte_offset);
+			const startMs = spanEpochMillis(t.start_time);
+			const endMs = spanEpochMillis(t.end_time);
+			t.duration_ms = startMs === null || endMs === null ? 0 : Math.max(0, endMs - startMs);
+		}
+		const sortedTraceIds = [...byTrace.keys()].sort();
+		return {
+			byTrace,
+			totalRawBytes,
+			sortedTraceIds
+		};
+	}
+	async matchedTraces(idx, filters) {
+		const traces = idx.sortedTraceIds.map((id) => idx.byTrace.get(id)).filter(isPresent);
+		if (!filters) return traces;
+		const indexedFiltered = traces.filter((t) => {
+			if (filters.has_errors !== void 0 && t.has_errors !== filters.has_errors) return false;
+			if (filters.service_names && filters.service_names.length > 0) {
+				if (!t.service_name || !filters.service_names.includes(t.service_name)) return false;
+			}
+			if (filters.agent_names && filters.agent_names.length > 0) {
+				if (!t.agent_name || !filters.agent_names.includes(t.agent_name)) return false;
+			}
+			if (filters.model_names && filters.model_names.length > 0) {
+				if (![...t.models].some((m) => filters.model_names.includes(m))) return false;
+			}
+			if (filters.tool_names && filters.tool_names.length > 0) {
+				if (![...t.tools].some((tn) => filters.tool_names.includes(tn))) return false;
+			}
+			if (filters.start_time_after && t.start_time < filters.start_time_after) return false;
+			if (filters.start_time_before && t.start_time > filters.start_time_before) return false;
+			return true;
+		});
+		if (!filters.regex_pattern) return indexedFiltered;
+		const re = compileSearchRegex(filters.regex_pattern);
+		const buf = await this.buffer();
+		const out = [];
+		for (const t of indexedFiltered) {
+			let matched = false;
+			for (const s of t.spans) {
+				const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length);
+				if (re.test(slice.toString("utf8"))) {
+					matched = true;
+					break;
+				}
+			}
+			if (matched) out.push(t);
+		}
+		return out;
+	}
+	toSummary(t) {
+		return {
+			trace_id: t.trace_id,
+			service_name: t.service_name,
+			agent_name: t.agent_name,
+			span_count: t.span_count,
+			has_errors: t.has_errors,
+			start_time: t.start_time,
+			end_time: t.end_time,
+			duration_ms: t.duration_ms,
+			raw_jsonl_bytes: t.raw_jsonl_bytes,
+			models: [...t.models].sort(),
+			tools: [...t.tools].sort()
+		};
+	}
+	projectSpan(buf, trace_id, s, perAttrCap, counter) {
+		const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length).toString("utf8");
+		let raw = {};
+		try {
+			const parsed = JSON.parse(slice);
+			if (parsed && typeof parsed === "object") raw = parsed;
+		} catch {}
+		const attrs = extractOtlpAttributes(raw);
+		const projected = {};
+		for (const [k, v] of Object.entries(attrs)) if (typeof v === "string") {
+			const trunc = truncateForBudget(v, perAttrCap);
+			if (trunc !== v) counter.value += 1;
+			projected[k] = trunc;
+		} else if (Array.isArray(v) || v && typeof v === "object") {
+			const json = JSON.stringify(v);
+			const trunc = truncateForBudget(json, perAttrCap);
+			if (trunc !== json) {
+				counter.value += 1;
+				projected[k] = trunc;
+			} else projected[k] = v;
+		} else projected[k] = v;
+		return {
+			trace_id,
+			span_id: s.span_id,
+			parent_span_id: s.parent_span_id,
+			name: s.name,
+			kind: s.kind,
+			start_time: s.start_time,
+			end_time: s.end_time,
+			duration_ms: s.duration_ms,
+			status: s.status,
+			status_message: s.status_message,
+			service_name: s.service_name,
+			agent_name: s.agent_name,
+			model_name: s.model_name,
+			tool_name: s.tool_name,
+			attributes: projected
+		};
+	}
+	buildOversizedSummary(t, span_response_bytes_max) {
+		const counts = /* @__PURE__ */ new Map();
+		let errorCount = 0;
+		for (const s of t.spans) {
+			counts.set(s.name, (counts.get(s.name) ?? 0) + 1);
+			if (s.status === "ERROR") errorCount += 1;
+		}
+		const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 20);
+		return {
+			span_count: t.span_count,
+			top_span_names: top,
+			span_response_bytes_max,
+			error_span_count: errorCount
+		};
+	}
+	async scanSpanForMatches(buf, trace_id, s, re, textBudget, recordCap) {
+		const slice = buf.subarray(s.line_byte_offset, s.line_byte_offset + s.line_byte_length).toString("utf8");
+		const records = [];
+		const globalRe = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
+		let total = 0;
+		let hasMore = false;
+		let m = globalRe.exec(slice);
+		while (m !== null) {
+			total += 1;
+			if (m.index === globalRe.lastIndex) globalRe.lastIndex += 1;
+			if (records.length >= recordCap) {
+				hasMore = true;
+				break;
+			}
+			const before = slice.slice(Math.max(0, m.index - textBudget / 2), m.index);
+			const after = slice.slice(m.index + m[0].length, m.index + m[0].length + Math.floor(textBudget / 2));
+			records.push({
+				trace_id,
+				span_id: s.span_id,
+				span_name: s.name,
+				span_kind: s.kind,
+				attribute_path: bestAttributePathForOffset(slice, m.index) ?? "span.raw",
+				matched_text: truncateForBudget(m[0], textBudget),
+				context_before: truncateForBudget(before, textBudget),
+				context_after: truncateForBudget(after, textBudget),
+				match_offset: m.index
+			});
+			m = globalRe.exec(slice);
+		}
+		return {
+			records,
+			total,
+			hasMore
+		};
+	}
+};
+var TraceFileMissingError = class extends NotFoundError {
+	constructor(path) {
+		super(`trace file not found: ${path}`);
+	}
+};
+var TraceFileTooLargeError = class extends Error {
+	path;
+	size_bytes;
+	max_bytes;
+	constructor(path, size_bytes, max_bytes) {
+		super(`trace file ${path} is ${size_bytes} bytes, over the ${max_bytes}-byte limit; raise OtlpFileTraceStoreOptions.maxFileBytes or pre-split the file`);
+		this.path = path;
+		this.size_bytes = size_bytes;
+		this.max_bytes = max_bytes;
+	}
+};
+var TraceNotFoundError = class extends NotFoundError {
+	trace_id;
+	constructor(trace_id) {
+		super(`trace not found: ${trace_id}`);
+		this.trace_id = trace_id;
+	}
+};
+var SpanNotFoundError = class extends NotFoundError {
+	trace_id;
+	span_id;
+	constructor(trace_id, span_id) {
+		super(`span ${span_id} not found in trace ${trace_id}`);
+		this.trace_id = trace_id;
+		this.span_id = span_id;
+	}
+};
+function isPresent(v) {
+	return v !== void 0;
+}
+/** A `"` at `idx` is a real JSON delimiter only when the run of `\`
+*  immediately preceding it is even-length; an odd run means the quote
+*  is escaped (`\"`) and is part of a string value, not a boundary. */
+function isUnescapedQuote(slice, idx) {
+	if (slice[idx] !== "\"") return false;
+	let backslashes = 0;
+	let b = idx - 1;
+	while (b >= 0 && slice[b] === "\\") {
+		backslashes += 1;
+		b -= 1;
+	}
+	return backslashes % 2 === 0;
+}
+/** Scan backwards from `from` (inclusive) for the nearest UNescaped `"`.
+*  Returns its index, or -1 when none is found. */
+function prevUnescapedQuote(slice, from) {
+	for (let i = from; i >= 0; i -= 1) if (slice[i] === "\"" && isUnescapedQuote(slice, i)) return i;
+	return -1;
+}
+/**
+* Best-effort: locate the JSON path for the substring at `offset` in
+* a single span's JSONL slice. The slice is '...,"key":"value..."' — we
+* walk back from `offset` to the value-opening quote, past the `:`, to
+* the key's closing then opening quote, skipping `\"`-escaped quotes that
+* live inside string values. Returns `null` when the offset doesn't fall
+* inside a recognisable string field.
+*/
+function bestAttributePathForOffset(slice, offset) {
+	const valueQuote = prevUnescapedQuote(slice, Math.min(offset, slice.length - 1));
+	if (valueQuote < 1) return null;
+	let j = valueQuote - 1;
+	while (j >= 0 && slice[j] !== ":") j -= 1;
+	if (j < 1) return null;
+	const keyClose = prevUnescapedQuote(slice, j - 1);
+	if (keyClose < 1) return null;
+	const keyOpen = prevUnescapedQuote(slice, keyClose - 1);
+	if (keyOpen < 0) return null;
+	return slice.slice(keyOpen + 1, keyClose);
+}
+const ERROR_CLUSTER_MAX = 50;
+const ERROR_CLUSTER_EXEMPLARS = 5;
+const SIGNATURE_MAX_CHARS = 160;
+/** Collapse volatile tokens so semantically identical failures share a key:
+*  hex/uuid ids → <id>, numbers → #, quoted/abs paths → <path>, durations →
+*  <dur>, whitespace collapsed. Empty/absent messages fall back to the span
+*  name so a no-message error still forms a real cluster. */
+function normalizeErrorSignature(message, spanName) {
+	const raw = (message ?? "").trim();
+	const norm = (raw.length > 0 ? raw : `(${spanName || "error"} — no message)`).replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<id>").replace(/\b[0-9a-f]{12,}\b/gi, "<id>").replace(/(?:\/[\w.\-@]+){2,}/g, "<path>").replace(/\b\d+(?:\.\d+)?(ms|s|m|h|kb|mb|gb)?\b/gi, (_m, u) => u ? `#${u}` : "#").replace(/\s+/g, " ").trim();
+	return norm.length > SIGNATURE_MAX_CHARS ? `${norm.slice(0, SIGNATURE_MAX_CHARS)}…` : norm;
+}
+function bump(map, key) {
+	if (!key) return;
+	map.set(key, (map.get(key) ?? 0) + 1);
+}
+function topKey(map) {
+	let best = null;
+	let bestN = 0;
+	for (const [k, n] of map) if (n > bestN) {
+		best = k;
+		bestN = n;
+	}
+	return best;
+}
+function accumulateErrorCluster(clusters, traceId, span) {
+	const signature = normalizeErrorSignature(span.status_message, span.name);
+	let acc = clusters.get(signature);
+	if (!acc) {
+		acc = {
+			signature,
+			sample: (span.status_message ?? span.name ?? "").slice(0, 500),
+			traceIds: /* @__PURE__ */ new Set(),
+			spanIds: [],
+			spanCount: 0,
+			spanNames: /* @__PURE__ */ new Map(),
+			toolNames: /* @__PURE__ */ new Map()
+		};
+		clusters.set(signature, acc);
+	}
+	acc.traceIds.add(traceId);
+	acc.spanCount += 1;
+	if (acc.spanIds.length < ERROR_CLUSTER_EXEMPLARS && !acc.spanIds.includes(span.span_id)) acc.spanIds.push(span.span_id);
+	bump(acc.spanNames, span.name);
+	bump(acc.toolNames, span.tool_name);
+}
+function finalizeErrorClusters(clusters, errorTraceCount) {
+	const out = [...clusters.values()].map((acc) => ({
+		signature: acc.signature,
+		status_message_sample: acc.sample,
+		span_name: topKey(acc.spanNames),
+		tool_name: topKey(acc.toolNames),
+		trace_count: acc.traceIds.size,
+		span_count: acc.spanCount,
+		prevalence: errorTraceCount > 0 ? acc.traceIds.size / errorTraceCount : 0,
+		exemplar_trace_ids: [...acc.traceIds].slice(0, ERROR_CLUSTER_EXEMPLARS),
+		exemplar_span_ids: acc.spanIds.slice(0, ERROR_CLUSTER_EXEMPLARS)
+	}));
+	out.sort((a, b) => b.trace_count - a.trace_count || b.span_count - a.span_count);
+	return out.slice(0, ERROR_CLUSTER_MAX);
+}
+const TRACE_ANALYSIS_COMPLETION_INSTRUCTION = `This host consumes your executor result directly; there is no downstream responder for this run. Ignore generic executor guidance that says a responder will format the answer. You must produce the final report and findings yourself.
+
+Return exactly one executable JavaScript program per turn. Never emit multiple JavaScript or code fences; put every tool call and the final call in that one program.
+
+When the analysis is complete, call \`await final(${JSON.stringify("Submit the completed trace analysis.")}, { report, findings })\` exactly once. Do not return a one-argument string from \`final(...)\`.`;
+var TraceAnalysisTurnLimitError = class extends Error {
+	analystId;
+	maxTurns;
+	constructor(analystId, maxTurns, cause) {
+		super(`Trace analyst '${analystId}' reached maxTurns=${maxTurns} without a structured final result`, { cause });
+		this.name = "TraceAnalysisTurnLimitError";
+		this.analystId = analystId;
+		this.maxTurns = maxTurns;
+	}
+};
+async function runTraceAnalysisLoop(options) {
+	validateLoopLimits(options);
+	const config = {
+		agentIdentity: {
+			name: options.id,
+			description: options.description
+		},
+		contextFields: [],
+		runtime: new AxJSRuntime({
+			permissions: [],
+			blockDynamicImport: true,
+			allowedModules: [],
+			freezeIntrinsics: true,
+			blockShadowRealm: true,
+			preventGlobalThisExtensions: false
+		}),
+		maxSubAgentCalls: options.maxSubqueries,
+		maxTurns: options.maxTurns,
+		maxRuntimeChars: options.maxRuntimeChars,
+		maxBatchedLlmQueryConcurrency: options.maxParallelSubqueries,
+		promptLevel: "detailed",
+		contextPolicy: {
+			preset: "full",
+			budget: "balanced"
+		},
+		functions: options.tools,
+		executorOptions: {
+			description: `${options.prompt.trim()}\n\n${TRACE_ANALYSIS_COMPLETION_INSTRUCTION}`,
+			...options.model ? { model: options.model } : {},
+			showThoughts: false,
+			thinkingTokenBudget: "none"
+		},
+		...options.onTurn ? { actorTurnCallback: options.onTurn } : {},
+		bubbleErrors: [TraceFileMissingError]
+	};
+	const analyst = options.findingType === "string" ? agent("question:string -> report:string, findings:string[]", config) : agent("question:string -> report:string, findings:json[]", config);
+	const state = await analyst.executor.run(options.ai, { question: options.question }, options.signal ? { abortSignal: options.signal } : void 0);
+	let completed;
+	try {
+		completed = options.findingType === "string" ? readTraceAnalysisCompletion(state.executorResult, "string") : readTraceAnalysisCompletion(state.executorResult, "object");
+	} catch (error) {
+		if (state.turnCount >= options.maxTurns) throw new TraceAnalysisTurnLimitError(options.id, options.maxTurns, error);
+		throw new Error(`Trace analyst '${options.id}' stopped without a structured final result`, { cause: error });
+	}
+	return {
+		...completed,
+		usage: analyst.executor.getUsage(),
+		chatLog: analyst.executor.getChatLog(),
+		turnCount: state.turnCount
+	};
+}
+function readTraceAnalysisCompletion(value, findingType) {
+	if (!value || typeof value !== "object") throw new Error("Trace analyst did not return a structured final result");
+	const completion = value;
+	if (completion.type !== "final" || !Array.isArray(completion.args) || completion.args.length !== 2 || completion.args[0] !== "Submit the completed trace analysis.") throw new Error("Trace analyst did not return a structured final result");
+	const payload = completion.args[1];
+	if (!payload || typeof payload !== "object") throw new Error("Trace analyst final result must contain report and findings");
+	const { report, findings } = payload;
+	if (typeof report !== "string" || !Array.isArray(findings)) throw new Error("Trace analyst final result must contain report and findings");
+	if (findingType === "string") {
+		if (findings.some((finding) => typeof finding !== "string")) throw new Error("Trace analyst final result must contain string findings");
+		return {
+			report,
+			findings
+		};
+	}
+	if (findings.some((finding) => !finding || typeof finding !== "object" || Array.isArray(finding))) throw new Error("Trace analyst final result must contain object findings");
+	return {
+		report,
+		findings
+	};
+}
+function validateLoopLimits(options) {
+	if (!Number.isSafeInteger(options.maxSubqueries) || options.maxSubqueries < 0) throw new TypeError("maxSubqueries must be a non-negative integer");
+	if (!Number.isSafeInteger(options.maxParallelSubqueries) || options.maxParallelSubqueries < 1) throw new TypeError("maxParallelSubqueries must be a positive integer");
+}
+//#endregion
+//#region src/trace-analyst/tools.ts
+const NAMESPACE = "traces";
+const filtersField = f.json("Filter set. ALL fields are AND-composed. Leave empty to scan everything.").optional();
+/**
+* Build the trace-analyst function set. Pass the result into
+* `agent(...).functions.local`.
+*/
+function buildTraceAnalystTools(opts) {
+	const { store } = opts;
+	return [
+		fn("getDatasetOverview").description("Dataset rollup: total traces, raw_jsonl_bytes, services, agents, models, tools, and sample_trace_ids (real ids passable to view/search). Always call this FIRST without a regex_pattern.").namespace(NAMESPACE).arg("filters", filtersField).returns(f.json("DatasetOverview")).handler(async ({ filters }) => store.getOverview(parseFilters(filters))).build(),
+		fn("queryTraces").description("Paginated trace summaries. Each summary carries raw_jsonl_bytes — use it to size traces BEFORE calling viewTrace. Narrow with indexed filters before adding regex_pattern.").namespace(NAMESPACE).arg("filters", filtersField).arg("limit", f.number("Page size, 1..200")).arg("offset", f.number("Page offset; default 0").optional()).returns(f.json("QueryTracesPage")).handler(async ({ filters, limit, offset }) => store.queryTraces({
+			filters: parseFilters(filters),
+			limit: assertPageLimit(limit),
+			offset: assertOffset(offset)
+		})).build(),
+		fn("countTraces").description("Count traces matching `filters`. Use as a cheap pre-flight before opting into a regex_pattern scan.").namespace(NAMESPACE).arg("filters", filtersField).returns(f.number("count")).handler(async ({ filters }) => store.countTraces(parseFilters(filters))).build(),
+		fn("viewTrace").description("Return ALL spans for a single trace, with each attribute capped at ~4KB. If the response would exceed the per-call ceiling the result carries `oversized` instead of `spans` — DO NOT retry with the same trace_id; switch to searchTrace / viewSpans.").namespace(NAMESPACE).arg("trace_id", f.string("Real trace id from a prior overview/query")).returns(f.json("ViewTraceResult")).handler(async ({ trace_id }) => store.viewTrace({ trace_id: assertString(trace_id, "trace_id") })).build(),
+		fn("viewSpans").description("Surgical read of specific spans within a trace, with each attribute capped at ~16KB (4× the discovery cap). Use after searchTrace narrows to specific span_ids.").namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("span_ids", f.string("Span ids to fetch").array()).returns(f.json("ViewSpansResult")).handler(async ({ trace_id, span_ids }) => store.viewSpans({
+			trace_id: assertString(trace_id, "trace_id"),
+			span_ids: assertStringArray(span_ids, "span_ids")
+		})).build(),
+		fn("searchTrace").description("Regex search across all spans of one trace. Returns `{trace_id, hits: SpanMatchRecord[], total_matches, has_more}`. **Iterate `result.hits`, NOT `result.matches`** — the field is `hits`. Each hit has `{span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset}`. Bounded regardless of trace size by max_matches (1..500, default 50). If has_more=true, REFINE the regex rather than blindly raising max_matches.").namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("regex_pattern", f.string("JS-compatible regex, multiline")).arg("max_matches", f.number("Max records returned, 1..500; default 50").optional()).returns(f.json("SearchTraceResult")).handler(async ({ trace_id, regex_pattern, max_matches }) => store.searchTrace({
+			trace_id: assertString(trace_id, "trace_id"),
+			regex_pattern: assertRegex(regex_pattern),
+			max_matches: assertMaxMatches(max_matches)
+		})).build(),
+		fn("searchSpan").description("Regex search inside a single span. Use when viewSpans returned a 16KB-truncated payload and you need to narrow further. Returns `{trace_id, span_id, hits: SpanMatchRecord[], total_matches, has_more}` — iterate `result.hits`, NOT `result.matches`.").namespace(NAMESPACE).arg("trace_id", f.string("Real trace id")).arg("span_id", f.string("Real span id within trace")).arg("regex_pattern", f.string("JS-compatible regex, multiline")).arg("max_matches", f.number("Max records, 1..500; default 50").optional()).returns(f.json("SearchSpanResult")).handler(async ({ trace_id, span_id, regex_pattern, max_matches }) => store.searchSpan({
+			trace_id: assertString(trace_id, "trace_id"),
+			span_id: assertString(span_id, "span_id"),
+			regex_pattern: assertRegex(regex_pattern),
+			max_matches: assertMaxMatches(max_matches)
+		})).build()
+	];
+}
+/**
+* Convenience: same shape as `buildTraceAnalystTools` but returns the
+* grouped form expected when registering trace tools alongside other
+* agent function modules. */
+function traceAnalystFunctionGroup(opts) {
+	return {
+		namespace: NAMESPACE,
+		title: "Trace Analysis",
+		selectionCriteria: "Use for any inspection of OTLP-shaped trace data.",
+		description: "Discovery → narrow → deep-read tools over a JSONL trace dataset. Always call getDatasetOverview first.",
+		functions: buildTraceAnalystTools(opts)
+	};
+}
+function parseFilters(input) {
+	if (input == null) return void 0;
+	if (typeof input !== "object" || Array.isArray(input)) throw new TypeError(`filters must be an object, got ${typeof input}`);
+	const f = input;
+	const out = {};
+	if (typeof f.has_errors === "boolean") out.has_errors = f.has_errors;
+	out.service_names = stringArrayOrUndefined(f.service_names, "service_names");
+	out.agent_names = stringArrayOrUndefined(f.agent_names, "agent_names");
+	out.model_names = stringArrayOrUndefined(f.model_names, "model_names");
+	out.tool_names = stringArrayOrUndefined(f.tool_names, "tool_names");
+	if (typeof f.start_time_after === "string") out.start_time_after = f.start_time_after;
+	if (typeof f.start_time_before === "string") out.start_time_before = f.start_time_before;
+	if (typeof f.regex_pattern === "string") {
+		if (f.regex_pattern.length === 0) throw new TypeError("filters.regex_pattern cannot be empty");
+		out.regex_pattern = f.regex_pattern;
+	}
+	return out;
+}
+function stringArrayOrUndefined(v, label) {
+	if (v === void 0 || v === null) return void 0;
+	if (!Array.isArray(v)) throw new TypeError(`${label} must be an array of strings`);
+	if (v.some((x) => typeof x !== "string")) throw new TypeError(`${label} entries must be strings`);
+	return v;
+}
+function assertPageLimit(limit) {
+	if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 200) throw new RangeError(`limit must be an integer 1..200`);
+	return limit;
+}
+function assertOffset(offset) {
+	if (offset === void 0) return void 0;
+	if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) throw new RangeError(`offset must be a non-negative integer`);
+	return offset;
+}
+function assertRegex(pattern) {
+	if (typeof pattern !== "string" || pattern.length === 0) throw new TypeError(`regex_pattern must be a non-empty string`);
+	new RegExp(pattern, "m");
+	return pattern;
+}
+function assertMaxMatches(n) {
+	if (n === void 0) return void 0;
+	if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > 500) throw new RangeError(`max_matches must be an integer 1..500`);
+	return n;
+}
+function assertString(v, label) {
+	if (typeof v !== "string" || v.length === 0) throw new TypeError(`${label} must be a non-empty string`);
+	return v;
+}
+function assertStringArray(v, label) {
+	if (!Array.isArray(v)) throw new TypeError(`${label} must be an array of strings`);
+	if (v.some((x) => typeof x !== "string")) throw new TypeError(`${label} entries must be strings`);
+	return v;
+}
+//#endregion
+export { traceSpanKindToOpenInferenceKind as S, spanEpochMillis as _, SpanNotFoundError as a, classifyOtlpSpanRole as b, DEFAULT_TRACE_ANALYST_BUDGETS as c, compareSpanTime as d, extractOtlpAttributes as f, readOtlpStatus as g, projectOtlpFlatLine as h, OtlpFileTraceStore as i, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX as l, inferOtlpKind as m, traceAnalystFunctionGroup as n, TraceFileMissingError as o, firstStringAttr as p, runTraceAnalysisLoop as r, TraceNotFoundError as s, buildTraceAnalystTools as t, asString as u, stringField as v, isOtlpModelCall as x, applyToolSpanOtlpAttributes as y };
+
+//# sourceMappingURL=tools-BmuN627J.js.map