@tangle-network/agent-eval 0.144.11 → 0.144.13

package/dist/traces.d.ts

@@ -1,12 +1,411 @@
+import { c as ValidationError, o as LimitExceededError, r as CaptureIntegrityError, s as NotFoundError, t as AgentEvalError } from "./errors-DEE6u6ot.js";
 import { C as TraceEvent, D as isSandboxSpan, E as isRetrievalSpan, O as isToolSpan, S as ToolSpan, T as isLlmSpan, _ as Span, a as FAILURE_CLASSES, b as SpanStatus, c as JudgeSpan, d as RetrievalSpan, f as Run, g as SandboxSpan, h as RunStatus, i as EventKind, l as LlmSpan, m as RunOutcome, n as BudgetLedgerEntry, o as FailureClass, p as RunLayer, r as BudgetSpec, s as GenericSpan, t as Artifact, u as Message, v as SpanBase, w as isJudgeSpan, x as TRACE_SCHEMA_VERSION, y as SpanKind } from "./schema-BtVldJ3T.js";
-import { a as ExtractedUsage, c as extractUsageFromResponse, i as ExtractUsageFromSseOptions, l as extractUsageFromSse, n as CaptureFetchOptions, o as SseUsageMode, r as captureFetchToRawSink, s as extractUsage, t as CaptureFetchContext } from "./index-CQTZ-4XN.js";
-import { At as InMemoryRawProviderSinkOptions, Dt as FileSystemRawProviderSink, Ft as RawProviderSink, It as RawProviderSinkFilter, Lt as defaultProviderRedactor, Mt as ProviderRedactor, Nt as RawProviderDirection, Ot as FileSystemRawProviderSinkOptions, Pt as RawProviderEvent, Rt as providerFromBaseUrl, jt as NoopRawProviderSink, kt as InMemoryRawProviderSink } from "./types-D216SgwM.js";
+import { a as RunRecord, l as RunTerminalOutcome, s as RunSplitTag, u as RunTokenUsage } from "./run-record-CKiihE6f.js";
+import { a as ExtractedUsage, c as extractUsageFromResponse, i as ExtractUsageFromSseOptions, l as extractUsageFromSse, n as CaptureFetchOptions, o as SseUsageMode, r as captureFetchToRawSink, s as extractUsage, t as CaptureFetchContext } from "./capture-fetch-DDvpjVRU.js";
+import { $ as InMemoryRawProviderSinkOptions, Q as InMemoryRawProviderSink, X as FileSystemRawProviderSink, Z as FileSystemRawProviderSinkOptions, at as RawProviderSinkFilter, et as NoopRawProviderSink, it as RawProviderSink, nt as RawProviderDirection, ot as defaultProviderRedactor, rt as RawProviderEvent, st as providerFromBaseUrl, tt as ProviderRedactor } from "./types-Cx3YUh2r.js";
 import { a as RunFilter, i as InMemoryTraceStore, n as FileSystemTraceStore, o as SpanFilter, r as FileSystemTraceStoreOptions, s as TraceStore, t as EventFilter } from "./store-CT9YIIve.js";
 import { a as TraceEmitterOptions, i as TraceEmitter, n as RunCompleteHookContext, o as llmSpanFromProvider, r as SpanHandle, t as RunCompleteHook } from "./emitter-DGQGoLyj.js";
-import { a as RunIntegrityReport, i as RunIntegrityIssueCode, n as RunIntegrityExpectations, o as assertRunCaptured, r as RunIntegrityIssue, s as throwIfRunIncomplete, t as RunIntegrityError } from "./integrity-BuqEKu-x.js";
-import { $ as traceAnalystOnRunComplete, A as stringField, At as OtlpSpanRoleInput, B as TraceInsightReadiness, Bt as exportRunAsOtlp, C as ProjectedOtlpSpan, Ct as createOtelTracingStore, D as inferOtlpKind, Dt as OtelExporter, E as firstStringAttr, Et as OtelExportConfig, F as TraceInsightFinding, Ft as traceSpanKindToOpenInferenceKind, G as defaultTraceInsightPanel, H as TraceInsightTask, I as TraceInsightPanelRole, It as OTEL_AGENT_EVAL_SCOPE, J as inferDomainKeywords, K as describeTraceInsightScope, L as TraceInsightPromptInput, Lt as OtlpExport, M as flattenOtlpExportToNdjson, Mt as applyToolSpanOtlpAttributes, N as OtlpFlatLine, Nt as classifyOtlpSpanRole, O as projectOtlpFlatLine, Ot as createOtelExporter, P as TraceInsightContext, Pt as isOtlpModelCall, Q as TraceAnalystHookOptions, R as TraceInsightQualityGate, Rt as OtlpResourceSpans, S as otlpToTraceRunRecords, St as redactValue, T as extractOtlpAttributes, Tt as ExportableSpan, U as buildTraceInsightContext, V as TraceInsightSuite, W as buildTraceInsightPrompt, X as scoreTraceInsightReadiness, Y as planTraceInsightQuestions, Z as tokenizeDomainWords, _ as OtlpTraceRunRecord, _t as DEFAULT_REDACTION_RULES, a as ReplayFetchOptions, at as TraceFileMissingError, b as otlpRowsToTraceRunRecords, bt as RedactionRule, c as ToolTraceMissingError, ct as AnalyzeTracesInput, d as OtlpFileTraceStoreOptions, dt as analyzeTraces, et as SpanNotFoundError, f as ToolSpansToTraceAnalysisStoreOptions, ft as createBoundedTraceAnalysisStore, g as OtlpToRunRecordsOptions, gt as convertTraceStoresToOtlp, h as TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, ht as TracesToOtlpResult, i as ReplayCacheStats, it as TraceFileMalformedError, j as FlattenOtlpOptions, jt as ToolSpanOtlpInput, k as readOtlpStatus, kt as OtlpSpanRole, l as toolSpansToTraceAnalysisStore, lt as AnalyzeTracesOptions, m as TRACE_ANALYST_ACTOR_DESCRIPTION, mt as TraceStoreToOtlpOptions, n as ReplayCacheEntry, nt as TraceAnalysisStoreContractError, o as createReplayFetch, ot as TraceFileTooLargeError, p as otlpTextToTraceAnalysisStore, pt as TraceStoreSource, q as domainEvidencePattern, r as ReplayCacheMissError, rt as TraceAnalysisValidationError, s as iterateRawCalls, st as TraceNotFoundError, t as ReplayCache, tt as TraceAnalysisLimitError, u as OtlpFileTraceStore, ut as AnalyzeTracesResult, v as TraceAggregate, vt as REDACTION_VERSION, w as asString, wt as otelRunCompleteHook, x as otlpToRunRecords, xt as redactString, y as otlpRowsToRunRecords, yt as RedactionReport, z as TraceInsightQuestion, zt as OtlpSpan } from "./replay-DbhZ4Ked.js";
+import { a as RunIntegrityReport, i as RunIntegrityIssueCode, n as RunIntegrityExpectations, o as assertRunCaptured, r as RunIntegrityIssue, s as throwIfRunIncomplete, t as RunIntegrityError } from "./integrity-OrcI9Nau.js";
+import { A as createBoundedTraceAnalysisStore, B as OtlpSpan, C as scoreTraceInsightReadiness, D as AnalyzeTracesResult, E as AnalyzeTracesOptions, F as redactString, I as redactValue, L as OTEL_AGENT_EVAL_SCOPE, M as REDACTION_VERSION, N as RedactionReport, O as analyzeTraces, P as RedactionRule, R as OtlpExport, S as planTraceInsightQuestions, T as AnalyzeTracesInput, V as exportRunAsOtlp, _ as buildTraceInsightPrompt, a as ToolSpansToTraceAnalysisStoreOptions, b as domainEvidencePattern, c as TraceInsightFinding, d as TraceInsightQualityGate, f as TraceInsightQuestion, g as buildTraceInsightContext, h as TraceInsightTask, i as OtlpFileTraceStoreOptions, j as DEFAULT_REDACTION_RULES, k as OtlpFlatLine, l as TraceInsightPanelRole, m as TraceInsightSuite, n as toolSpansToTraceAnalysisStore, o as otlpTextToTraceAnalysisStore, p as TraceInsightReadiness, r as OtlpFileTraceStore, s as TraceInsightContext, t as ToolTraceMissingError, u as TraceInsightPromptInput, v as defaultTraceInsightPanel, w as tokenizeDomainWords, x as inferDomainKeywords, y as describeTraceInsightScope, z as OtlpResourceSpans } from "./store-tool-spans-DbDLOBOb.js";
 import { C as TOOL_LATENCY_MS, D as asNumber, E as applyLlmSpanOtlpAttributes, O as contextInputTokens, S as TOOL_ARGS_CAPTURED, T as TOOL_NAME_ATTR_KEYS, _ as LlmSpanOtlpInput, a as LLM_CACHE_WRITE_TOKEN_ATTR_KEYS, b as RUN_COST_ATTR_KEYS, c as LLM_COST_USD, d as LLM_MODEL_ATTR_KEYS, f as LLM_MODEL_NAME, g as LLM_REASONING_TOKEN_ATTR_KEYS, h as LLM_REASONING_TOKENS, i as LLM_CACHE_WRITE_TOKENS, k as firstNumberAttr, l as LLM_INPUT_TOKENS, m as LLM_OUTPUT_TOKEN_ATTR_KEYS, n as LLM_CACHED_TOKENS, o as LLM_CONTEXT_TOKENS, p as LLM_OUTPUT_TOKENS, r as LLM_CACHED_TOKEN_ATTR_KEYS, s as LLM_COST_ATTR_KEYS, t as INPUT_VALUE, u as LLM_INPUT_TOKEN_ATTR_KEYS, v as OPENINFERENCE_SPAN_KIND, w as TOOL_NAME, x as SPAN_KIND_ATTR_KEYS, y as OUTPUT_VALUE } from "./attribute-vocabulary-DLJ6303h.js";
 import { a as judgeSpans, c as runsForScenario, i as hasCapturedToolArgs, l as toolSpans, n as argHash, o as llmSpans, r as groupBy, s as runFailureClass, t as aggregateLlm } from "./query-CJ_DX8vl.js";
-import { A as SearchSpanResult, B as ViewSpansResult, C as TRACE_ANALYSIS_LIMITS, D as DatasetOverview, E as DEFAULT_TRACE_ANALYST_BUDGETS, F as TraceAnalystFilters, H as ViewTraceResult, I as TraceAnalystSpan, L as TraceAnalystSpanKind, M as SpanMatchRecord, N as TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, O as ErrorCluster, P as TraceAnalystByteBudgets, R as TraceAnalystSpanStatus, S as BoundedTraceAnalysisStoreOptions, T as TraceAnalysisStoreContext, V as ViewTraceOversized, j as SearchTraceResult, k as QueryTracesPage, w as TraceAnalysisStore, z as TraceAnalystTraceSummary } from "./types-BvDKaULh.js";
-import { _ as TraceAnalysisToolDescriptor, g as TRACE_ANALYST_TOOL_NAMESPACE, h as BuildTraceAnalysisToolsOptions, v as buildTraceAnalysisToolDescriptors, y as traceAnalystFunctionGroup } from "./engine-3hL-XqwJ.js";
-export { type AnalyzeTracesInput, type AnalyzeTracesOptions, type AnalyzeTracesResult, Artifact, type BoundedTraceAnalysisStoreOptions, BudgetLedgerEntry, BudgetSpec, type BuildTraceAnalysisToolsOptions, CaptureFetchContext, CaptureFetchOptions, DEFAULT_REDACTION_RULES, DEFAULT_TRACE_ANALYST_BUDGETS, type DatasetOverview, type ErrorCluster, EventFilter, EventKind, ExportableSpan, ExtractUsageFromSseOptions, ExtractedUsage, FAILURE_CLASSES, FailureClass, FileSystemRawProviderSink, FileSystemRawProviderSinkOptions, FileSystemTraceStore, FileSystemTraceStoreOptions, type FlattenOtlpOptions, GenericSpan, INPUT_VALUE, InMemoryRawProviderSink, InMemoryRawProviderSinkOptions, InMemoryTraceStore, JudgeSpan, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_CACHE_WRITE_TOKENS, LLM_CACHE_WRITE_TOKEN_ATTR_KEYS, LLM_CONTEXT_TOKENS, LLM_COST_ATTR_KEYS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_MODEL_ATTR_KEYS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, LLM_OUTPUT_TOKEN_ATTR_KEYS, LLM_REASONING_TOKENS, LLM_REASONING_TOKEN_ATTR_KEYS, LlmSpan, LlmSpanOtlpInput, Message, NoopRawProviderSink, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, OUTPUT_VALUE, OtelExportConfig, OtelExporter, OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, OtlpResourceSpans, OtlpSpan, OtlpSpanRole, OtlpSpanRoleInput, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, ProviderRedactor, type QueryTracesPage, REDACTION_VERSION, RUN_COST_ATTR_KEYS, RawProviderDirection, RawProviderEvent, RawProviderSink, RawProviderSinkFilter, RedactionReport, RedactionRule, ReplayCache, ReplayCacheEntry, ReplayCacheMissError, ReplayCacheStats, ReplayFetchOptions, RetrievalSpan, Run, RunCompleteHook, RunCompleteHookContext, RunFilter, RunIntegrityError, RunIntegrityExpectations, RunIntegrityIssue, RunIntegrityIssueCode, RunIntegrityReport, RunLayer, RunOutcome, RunStatus, SPAN_KIND_ATTR_KEYS, SandboxSpan, type SearchSpanResult, type SearchTraceResult, Span, SpanBase, SpanFilter, SpanHandle, SpanKind, type SpanMatchRecord, SpanNotFoundError, SpanStatus, SseUsageMode, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYSIS_LIMITS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_TOOL_NAMESPACE, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TRACE_SCHEMA_VERSION, ToolSpan, ToolSpanOtlpInput, type ToolSpansToTraceAnalysisStoreOptions, ToolTraceMissingError, type TraceAggregate, TraceAnalysisLimitError, type TraceAnalysisStore, type TraceAnalysisStoreContext, TraceAnalysisStoreContractError, type TraceAnalysisToolDescriptor, TraceAnalysisValidationError, type TraceAnalystByteBudgets, type TraceAnalystFilters, type TraceAnalystHookOptions, type TraceAnalystSpan, type TraceAnalystSpanKind, type TraceAnalystSpanStatus, type TraceAnalystTraceSummary, TraceEmitter, TraceEmitterOptions, TraceEvent, TraceFileMalformedError, TraceFileMissingError, TraceFileTooLargeError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, TraceStore, TraceStoreSource, TraceStoreToOtlpOptions, TracesToOtlpResult, type ViewSpansResult, type ViewTraceOversized, type ViewTraceResult, aggregateLlm, analyzeTraces, applyLlmSpanOtlpAttributes, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalysisToolDescriptors, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, classifyOtlpSpanRole, contextInputTokens, convertTraceStoresToOtlp, createBoundedTraceAnalysisStore, createOtelExporter, createOtelTracingStore, createReplayFetch, defaultProviderRedactor, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, groupBy, hasCapturedToolArgs, inferDomainKeywords, inferOtlpKind, isJudgeSpan, isLlmSpan, isOtlpModelCall, isRetrievalSpan, isSandboxSpan, isToolSpan, iterateRawCalls, judgeSpans, llmSpanFromProvider, llmSpans, otelRunCompleteHook, otlpRowsToRunRecords, otlpRowsToTraceRunRecords, otlpTextToTraceAnalysisStore, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, toolSpansToTraceAnalysisStore, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };
+import "./index-Ba3YrbAL.js";
+import { A as SearchSpanResult, B as ViewSpansResult, C as TRACE_ANALYSIS_LIMITS, D as DatasetOverview, E as DEFAULT_TRACE_ANALYST_BUDGETS, F as TraceAnalystFilters, H as ViewTraceResult, I as TraceAnalystSpan, L as TraceAnalystSpanKind, M as SpanMatchRecord, N as TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, O as ErrorCluster, P as TraceAnalystByteBudgets, R as TraceAnalystSpanStatus, S as BoundedTraceAnalysisStoreOptions, T as TraceAnalysisStoreContext, V as ViewTraceOversized, j as SearchTraceResult, k as QueryTracesPage, w as TraceAnalysisStore, z as TraceAnalystTraceSummary } from "./types-DLQx4mKU.js";
+import { _ as TraceAnalysisToolDescriptor, g as TRACE_ANALYST_TOOL_NAMESPACE, h as BuildTraceAnalysisToolsOptions, v as buildTraceAnalysisToolDescriptors, y as traceAnalystFunctionGroup } from "./engine-otFpE2gF.js";
+//#region src/trace/otlp-attributes.d.ts
+type ToolSpanOtlpInput = Pick<ToolSpan, 'toolName' | 'args' | 'argsCaptured' | 'result' | 'latencyMs'>;
+type OtlpSpanRole = 'AGENT' | 'CHAIN' | 'EVALUATOR' | 'GUARDRAIL' | 'LLM' | 'SPAN' | 'TOOL' | 'UNKNOWN';
+interface OtlpSpanRoleInput {
+  name: string;
+  attributes: Record<string, unknown>;
+  kind?: string | null;
+}
+/**
+ * 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.
+ */
+declare function classifyOtlpSpanRole(input: OtlpSpanRoleInput): OtlpSpanRole;
+declare function isOtlpModelCall(input: OtlpSpanRoleInput): boolean;
+declare function applyToolSpanOtlpAttributes(attributes: Record<string, unknown>, span: ToolSpanOtlpInput): void;
+declare function traceSpanKindToOpenInferenceKind(kind: string): string;
+//#endregion
+//#region src/trace/otel-export.d.ts
+interface OtelExportConfig {
+  /** OTLP endpoint. Reads OTEL_EXPORTER_OTLP_ENDPOINT env by default. */
+  endpoint?: string;
+  /** OTLP headers. Reads OTEL_EXPORTER_OTLP_HEADERS env by default. */
+  headers?: Record<string, string>;
+  /** Batch size before flush. Default 64. */
+  batchSize?: number;
+  /** Flush interval ms. Default 5000. */
+  flushIntervalMs?: number;
+  /** Resource attributes stamped on every export. */
+  resourceAttributes?: Record<string, string | number | boolean>;
+  /** Service name. Default 'agent-eval'. */
+  serviceName?: string;
+}
+interface OtelExporter {
+  /** Called by the TraceEmitter on every span close. */
+  exportSpan(span: ExportableSpan): void;
+  /** Force flush pending spans. */
+  flush(): Promise<void>;
+  /** Shutdown cleanly — flushes remaining spans and stops the timer. */
+  shutdown(): Promise<void>;
+}
+interface ExportableSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind: string;
+  startedAt: number;
+  endedAt?: number;
+  status?: string;
+  error?: string;
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cachedTokens?: number;
+  cacheWriteTokens?: number;
+  costUsd?: number;
+  tool?: ToolSpanOtlpInput;
+  attributes?: Record<string, unknown>;
+}
+/**
+ * Create an OTEL exporter. Returns undefined when no endpoint is configured
+ * (neither via config nor env) — callers should check before attaching.
+ */
+declare function createOtelExporter(config?: OtelExportConfig): OtelExporter | undefined;
+//#endregion
+//#region src/trace/otel-bridge.d.ts
+/**
+ * Create a RunCompleteHook that exports all spans from the completed run
+ * to the OTEL exporter, then flushes.
+ */
+declare function otelRunCompleteHook(exporter: OtelExporter): RunCompleteHook;
+/**
+ * Create an auto-exporting TraceStore wrapper that intercepts updateSpan
+ * calls. When a span gets an endedAt, it's exported immediately. This
+ * gives real-time streaming instead of batch-at-end.
+ *
+ * This is the preferred integration path: wrap the store before
+ * constructing the TraceEmitter.
+ */
+declare function createOtelTracingStore(inner: TraceStore, exporter: OtelExporter, traceId: string): TraceStore;
+//#endregion
+//#region src/trace/store-to-otlp.d.ts
+interface TracesToOtlpResult {
+  /** Total spans emitted across every cell. */
+  spanCount: number;
+  /** Total run-anchor spans (one per Run) appended for analyst visibility. */
+  runCount: number;
+  /** Cells whose shards parsed cleanly. */
+  cellCount: number;
+  /** Cells that errored mid-conversion — surfaced so a partial conversion
+   *  isn't silently masked. */
+  cellErrorCount: number;
+}
+/**
+ * A trace source the analyst should ingest. Two layouts are supported:
+ *
+ *   - `celled` (default): the root holds one cell subdirectory per
+ *     persona/variant, each a `FileSystemTraceStore` (`runs.ndjson`,
+ *     `spans.ndjson`, `events.ndjson`).
+ *   - `flat`: the root is itself a single `FileSystemTraceStore` (e.g. a
+ *     production-ingestion sidecar that appends one ndjson set directly under
+ *     the chosen directory).
+ */
+interface TraceStoreSource {
+  /** Absolute path to the trace store root. */
+  root: string;
+  /** Layout — `celled` (default) or `flat`. */
+  layout?: 'celled' | 'flat';
+  /** OTLP `service.name` for this source. Overrides the options default. */
+  serviceName?: string;
+}
+/** Domain hooks. The walker is generic; consumers inject the namespaced
+ *  attributes that ride along on every run + span for analyst discovery. */
+interface TraceStoreToOtlpOptions {
+  /** Default OTLP `service.name` when a source doesn't set its own.
+   *  Default `agent-eval`. */
+  serviceName?: string;
+  /** Extra resource attributes per run, e.g.
+   *  `(run) => ({ 'legal.persona_id': run.tags?.personaId ?? '' })`. */
+  resourceAttributes?: (run: Run) => Record<string, unknown>;
+  /** Extra attributes on the per-run anchor span, e.g. domain outcome fields. */
+  runAttributes?: (run: Run) => Record<string, unknown>;
+}
+/**
+ * Read every per-cell shard under each source root and write a flat OTLP-JSONL
+ * view of the corpus to `outPath`. Each cell directory is a
+ * `FileSystemTraceStore` — NDJSON append-only with size-based rotation;
+ * `updateRun`/`updateSpan` append `{ id, ...patch, _update: true }` rows
+ * rather than rewriting, so readers must merge those patches in (done here).
+ *
+ * A `string` source is treated as a celled root.
+ */
+declare function convertTraceStoresToOtlp(source: string | TraceStoreSource | readonly TraceStoreSource[], outPath: string, opts?: TraceStoreToOtlpOptions): TracesToOtlpResult;
+//#endregion
+//#region src/trace-analyst/errors.d.ts
+/** Invalid trace-tool arguments, including malformed filters and regexes. */
+declare class TraceAnalysisValidationError extends ValidationError {
+  readonly code: 'validation';
+}
+/** A trace read cannot fit within a documented count or byte limit. */
+declare class TraceAnalysisLimitError extends LimitExceededError {
+  readonly code: 'limit_exceeded';
+  readonly operation: string;
+  readonly actual: number;
+  readonly limit: number;
+  constructor(operation: string, actual: number, limit: number, message?: string);
+}
+/** A supplied store returned a shape that violates the trace read contract. */
+declare class TraceAnalysisStoreContractError extends AgentEvalError {
+  readonly code: 'backend_integrity';
+  readonly operation: string;
+  constructor(operation: string, message: string, options?: {
+    cause?: unknown;
+  });
+}
+declare class TraceFileMissingError extends NotFoundError {
+  readonly code: 'not_found';
+  readonly path: string;
+  constructor(path: string);
+}
+declare class TraceFileTooLargeError extends TraceAnalysisLimitError {
+  readonly path: string;
+  readonly size_bytes: number;
+  readonly max_bytes: number;
+  constructor(path: string, size_bytes: number, max_bytes: number);
+}
+declare class TraceFileMalformedError extends CaptureIntegrityError {
+  readonly path: string;
+  readonly line_number: number;
+  readonly byte_offset: number;
+  constructor(path: string, line_number: number, byte_offset: number, cause?: unknown);
+}
+declare class TraceNotFoundError extends NotFoundError {
+  readonly code: 'not_found';
+  readonly trace_id: string;
+  constructor(trace_id: string);
+}
+declare class SpanNotFoundError extends NotFoundError {
+  readonly code: 'not_found';
+  readonly trace_id: string;
+  readonly span_id: string;
+  constructor(trace_id: string, span_id: string);
+}
+//#endregion
+//#region src/trace-analyst/hook.d.ts
+interface TraceAnalystHookOptions {
+  /**
+   * Options forwarded to `analyzeTraces`. The hook supplies the question
+   * if you don't pass one — defaulting to a launch-grade prompt that asks
+   * for failure modes, surprising findings, and a recommendation.
+   */
+  analyze: Omit<AnalyzeTracesOptions, 'source'> & {
+    source?: AnalyzeTracesOptions['source'];
+  };
+  /**
+   * Override the question. The default is intentionally generic:
+   * "Summarise what happened in this run, surface any failure modes,
+   *  surprising findings, or evidence the verdict is wrong."
+   */
+  question?: string;
+  /**
+   * Persist the result. The hook calls this with the analysis output and
+   * the run context. Common implementations write to a TraceAnalysisStore
+   * or append to a per-run JSONL.
+   */
+  save?: (result: AnalyzeTracesResult, ctx: RunCompleteHookContext) => Promise<void>;
+  /**
+   * Predicate gating execution per run. Default: every completed run.
+   * Use to skip aborted runs, debug runs, or runs without LLM activity.
+   */
+  shouldRun?: (ctx: RunCompleteHookContext) => boolean;
+  /**
+   * Optional gate: if set and returns false, the hook records the failure
+   * as a log event on the run instead of staying quiet. The caller can
+   * then trigger downstream alerts off `analyst_gate_failed` log events.
+   */
+  gateOn?: (result: AnalyzeTracesResult, ctx: RunCompleteHookContext) => boolean;
+}
+declare function traceAnalystOnRunComplete(opts: TraceAnalystHookOptions): RunCompleteHook;
+//#endregion
+//#region src/trace-analyst/otlp-flatten.d.ts
+interface FlattenOtlpOptions {
+  /** `'openinference'` (default) maps source per-span attributes into the
+   *  canonical OpenInference vocabulary the analyst readers consume. `'none'`
+   *  passes attributes through untouched. */
+  attributeVocabulary?: 'openinference' | 'none';
+  /** Override the numeric-kind → otlp-string mapping. */
+  kindMap?: Partial<Record<number, string>>;
+}
+declare function flattenOtlpExportToNdjson(otlpExport: OtlpExport, opts?: FlattenOtlpOptions): OtlpFlatLine[];
+//#endregion
+//#region src/trace-analyst/otlp-span.d.ts
+/**
+ * The structural fields a flat OTLP-JSONL line projects to. `attributes`
+ * is the merged resource+span attribute map (span overrides resource);
+ * the named fields are the pivots every reader of a trace needs without
+ * paying the full attribute materialisation.
+ */
+interface ProjectedOtlpSpan {
+  trace_id: string;
+  span_id: string;
+  parent_span_id: string | null;
+  name: string;
+  kind: TraceAnalystSpanKind;
+  start_time: string;
+  end_time: string;
+  duration_ms: number;
+  status: TraceAnalystSpanStatus;
+  status_message: string | undefined;
+  service_name: string | null;
+  agent_name: string | null;
+  model_name: string | null;
+  tool_name: string | null;
+  /** Merged resource + span attributes, span winning on overlap. */
+  attributes: Record<string, unknown>;
+}
+/**
+ * Project one parsed OTLP-JSONL object to `ProjectedOtlpSpan`, or `null`
+ * when the line is missing the mandatory `trace_id` + `span_id`.
+ */
+declare function projectOtlpFlatLine(raw: Record<string, unknown>): ProjectedOtlpSpan | null;
+declare function readOtlpStatus(raw: Record<string, unknown>): {
+  code: TraceAnalystSpanStatus;
+  message: string | undefined;
+};
+declare function inferOtlpKind(attrs: Record<string, unknown>): TraceAnalystSpanKind;
+/**
+ * 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.
+ */
+declare function extractOtlpAttributes(raw: Record<string, unknown>): Record<string, unknown>;
+declare function stringField(raw: Record<string, unknown>, key: string): string | undefined;
+declare function asString(v: unknown): string | null;
+/** First non-empty string value across a list of candidate attribute keys. */
+declare function firstStringAttr(attrs: Record<string, unknown>, keys: readonly string[]): string | null;
+//#endregion
+//#region src/trace-analyst/otlp-to-run-records.d.ts
+interface OtlpToRunRecordsOptions {
+  /** Logical experiment grouping for every produced record. */
+  experimentId: string;
+  /** Candidate (variant) id — the surface these traces exercised. The
+   *  bench passes the proposer label here so `compareOptimizationMethods` can pair rows. */
+  candidateId: string;
+  /** Split assignment for every produced record. Default `'holdout'` —
+   *  ingested traces are evidence, not the optimizer's training pool. */
+  splitTag?: RunSplitTag;
+  /** Git SHA the traces were produced from. Default `'unknown'`. */
+  commitSha?: string;
+  /** sha256 of the effective prompt surface. Default `'unknown'`. */
+  promptHash?: string;
+  /** sha256 of the effective config. Default `'unknown'`. */
+  configHash?: string;
+  /** RNG seed recorded on every row. Default 0. */
+  seed?: number;
+  /**
+   * Fallback model snapshot when the trace exposes no LLM model attribute
+   * OR exposes a bare alias `validateRunRecord` would reject. The trace's
+   * own model wins when it already carries a snapshot. Default
+   * `'unknown@otlp'` (opaque-snapshot form the validator accepts).
+   */
+  fallbackModel?: string;
+  /**
+   * USD per total token (input+output) used to price a trace when no
+   * per-span cost attribute is present. When unset, an unpriced trace
+   * records `costUsd: null` and `raw.cost_unpriced = 1`.
+   */
+  priceUsdPerToken?: number;
+  /**
+   * Map each OTLP `trace_id` to the logical run it belongs to. Use this when a
+   * provider emits several traces for one task attempt. All mapped traces are
+   * aggregated into one record; duplicate span ids remain isolated by their
+   * source trace. The callback must return a non-empty id for every trace.
+   *
+   * When omitted, every `trace_id` remains an independent run.
+   */
+  logicalRunIdForTrace?: (traceId: string) => string;
+  /**
+   * Score for a produced run's outcome (AppWorld `world.evaluate()` →
+   * TGC/SGC, or
+   * any [0,1] task-success signal). Keyed by the logical run id when
+   * `logicalRunIdForTrace` is supplied, otherwise by `trace_id`. When the map
+   * has no entry or the function returns undefined, the record remains
+   * unlabeled.
+   */
+  scoreForTrace?: (runId: string, span: TraceAggregate) => number | undefined;
+  /**
+   * Per-record judge metadata when an external judge produced the score.
+   * Keyed by the logical run id when supplied, otherwise by `trace_id`.
+   */
+  judgeMetadataForTrace?: (runId: string) => RunRecord['judgeMetadata'] | undefined;
+}
+/** A `RunRecord` plus the verbatim prompt/completion text when the trace's
+ *  LLM spans exposed it. The text is NOT on the validated `RunRecord`
+ *  (`outcome.raw` is numeric-only) but consumers ingesting full traces want
+ *  it — so it rides alongside. */
+interface OtlpTraceRunRecord {
+  record: RunRecord;
+  /** Verbatim first-LLM-span `input.value`, when present. */
+  promptText?: string;
+  /** Verbatim last-LLM-span `output.value`, when present. */
+  completionText?: string;
+}
+/** Per-trace rollup the score callback can inspect. */
+interface TraceAggregate {
+  traceId: string;
+  /** Number of source OTLP traces folded into this run. */
+  sourceTraceCount: number;
+  /** Source OTLP trace ids folded into this run, sorted for deterministic audit output. */
+  sourceTraceIds: readonly string[];
+  spanCount: number;
+  llmSpanCount: number;
+  toolSpanCount: number;
+  agentSpanCount: number;
+  errorSpanCount: number;
+  executionErrorCount: number;
+  processErrorCount: number;
+  guardrailErrorCount: number;
+  judgeErrorCount: number;
+  propagatedErrorCount: number;
+  unclassifiedErrorCount: number;
+  tokenUsage: RunTokenUsage;
+  /** First error span's normalized status message, if any. */
+  firstErrorMessage?: string;
+  model: string;
+  startTime: string;
+  endTime: string;
+  wallMs: number;
+  /** Root-span terminal result. Child span errors do not change this value. */
+  terminalOutcome: RunTerminalOutcome;
+}
+/**
+ * Parse + aggregate an OTLP traces.jsonl string into validated
+ * `RunRecord[]` (one per trace). Use {@link otlpToTraceRunRecords} when you
+ * also want the verbatim prompt/completion text alongside each record.
+ */
+declare function otlpToRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): RunRecord[];
+/**
+ * Aggregate already-parsed OTLP flat rows without serializing them back to
+ * JSONL. This is the in-memory counterpart to {@link otlpToRunRecords}; both
+ * paths share projection, reconciliation, validation, and ordering.
+ */
+declare function otlpRowsToRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): RunRecord[];
+/** As {@link otlpToRunRecords} but returns the prompt/completion text too. */
+declare function otlpToTraceRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+/** Parsed-row counterpart to {@link otlpToTraceRunRecords}. */
+declare function otlpRowsToTraceRunRecords(rows: Iterable<object>, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+//#endregion
+//#region src/trace-analyst/prompts.d.ts
+/** General policy for recursive, evidence-backed trace analysis. */
+declare const TRACE_ANALYST_ACTOR_DESCRIPTION = "Answer the question by inspecting the OTLP trace dataset with the available tools.\n\n1. Call getDatasetOverview first. Use its real trace ids and dataset size to plan the investigation.\n2. Narrow with queryTraces and countTraces before scanning large payloads.\n3. For a small trace, use viewTrace. For a large trace, use searchTrace and then viewSpans or searchSpan.\n4. Never invent a trace id, span id, tool result, error, frequency, or final outcome.\n5. When a search reports has_more, refine the query before drawing a conclusion.\n6. Use llm_query only over evidence already loaded. A recursive query cannot inspect traces itself.\n7. Cite exact evidence URIs returned by the tools. Include a short exact excerpt when it supports the claim.\n8. Return no finding when the available evidence cannot support one.\n\nThe prose answer must directly answer the question and state important uncertainty.\nThe findings array contains only actionable or decision-relevant claims supported by inspected evidence.";
+declare const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-research-v1-2026-07-30";
+//#endregion
+export { type AnalyzeTracesInput, type AnalyzeTracesOptions, type AnalyzeTracesResult, Artifact, type BoundedTraceAnalysisStoreOptions, BudgetLedgerEntry, BudgetSpec, type BuildTraceAnalysisToolsOptions, CaptureFetchContext, CaptureFetchOptions, DEFAULT_REDACTION_RULES, DEFAULT_TRACE_ANALYST_BUDGETS, type DatasetOverview, type ErrorCluster, EventFilter, EventKind, ExportableSpan, ExtractUsageFromSseOptions, ExtractedUsage, FAILURE_CLASSES, FailureClass, FileSystemRawProviderSink, FileSystemRawProviderSinkOptions, FileSystemTraceStore, FileSystemTraceStoreOptions, type FlattenOtlpOptions, GenericSpan, INPUT_VALUE, InMemoryRawProviderSink, InMemoryRawProviderSinkOptions, InMemoryTraceStore, JudgeSpan, LLM_CACHED_TOKENS, LLM_CACHED_TOKEN_ATTR_KEYS, LLM_CACHE_WRITE_TOKENS, LLM_CACHE_WRITE_TOKEN_ATTR_KEYS, LLM_CONTEXT_TOKENS, LLM_COST_ATTR_KEYS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_MODEL_ATTR_KEYS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, LLM_OUTPUT_TOKEN_ATTR_KEYS, LLM_REASONING_TOKENS, LLM_REASONING_TOKEN_ATTR_KEYS, LlmSpan, LlmSpanOtlpInput, Message, NoopRawProviderSink, OPENINFERENCE_SPAN_KIND, OTEL_AGENT_EVAL_SCOPE, OUTPUT_VALUE, OtelExportConfig, OtelExporter, OtlpExport, OtlpFileTraceStore, type OtlpFileTraceStoreOptions, type OtlpFlatLine, OtlpResourceSpans, OtlpSpan, OtlpSpanRole, OtlpSpanRoleInput, type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, type ProjectedOtlpSpan, ProviderRedactor, type QueryTracesPage, REDACTION_VERSION, RUN_COST_ATTR_KEYS, RawProviderDirection, RawProviderEvent, RawProviderSink, RawProviderSinkFilter, RedactionReport, RedactionRule, RetrievalSpan, Run, RunCompleteHook, RunCompleteHookContext, RunFilter, RunIntegrityError, RunIntegrityExpectations, RunIntegrityIssue, RunIntegrityIssueCode, RunIntegrityReport, RunLayer, RunOutcome, RunStatus, SPAN_KIND_ATTR_KEYS, SandboxSpan, type SearchSpanResult, type SearchTraceResult, Span, SpanBase, SpanFilter, SpanHandle, SpanKind, type SpanMatchRecord, SpanNotFoundError, SpanStatus, SseUsageMode, TOOL_ARGS_CAPTURED, TOOL_LATENCY_MS, TOOL_NAME, TOOL_NAME_ATTR_KEYS, TRACE_ANALYSIS_LIMITS, TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_TOOL_NAMESPACE, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, TRACE_SCHEMA_VERSION, ToolSpan, ToolSpanOtlpInput, type ToolSpansToTraceAnalysisStoreOptions, ToolTraceMissingError, type TraceAggregate, TraceAnalysisLimitError, type TraceAnalysisStore, type TraceAnalysisStoreContext, TraceAnalysisStoreContractError, type TraceAnalysisToolDescriptor, TraceAnalysisValidationError, type TraceAnalystByteBudgets, type TraceAnalystFilters, type TraceAnalystHookOptions, type TraceAnalystSpan, type TraceAnalystSpanKind, type TraceAnalystSpanStatus, type TraceAnalystTraceSummary, TraceEmitter, TraceEmitterOptions, TraceEvent, TraceFileMalformedError, TraceFileMissingError, TraceFileTooLargeError, type TraceInsightContext, type TraceInsightFinding, type TraceInsightPanelRole, type TraceInsightPromptInput, type TraceInsightQualityGate, type TraceInsightQuestion, type TraceInsightReadiness, type TraceInsightSuite, type TraceInsightTask, TraceNotFoundError, TraceStore, TraceStoreSource, TraceStoreToOtlpOptions, TracesToOtlpResult, type ViewSpansResult, type ViewTraceOversized, type ViewTraceResult, aggregateLlm, analyzeTraces, applyLlmSpanOtlpAttributes, applyToolSpanOtlpAttributes, argHash, asNumber, asString, assertRunCaptured, buildTraceAnalysisToolDescriptors, buildTraceInsightContext, buildTraceInsightPrompt, captureFetchToRawSink, classifyOtlpSpanRole, contextInputTokens, convertTraceStoresToOtlp, createBoundedTraceAnalysisStore, createOtelExporter, createOtelTracingStore, defaultProviderRedactor, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, exportRunAsOtlp, extractOtlpAttributes, extractUsage, extractUsageFromResponse, extractUsageFromSse, firstNumberAttr, firstStringAttr, flattenOtlpExportToNdjson, groupBy, hasCapturedToolArgs, inferDomainKeywords, inferOtlpKind, isJudgeSpan, isLlmSpan, isOtlpModelCall, isRetrievalSpan, isSandboxSpan, isToolSpan, judgeSpans, llmSpanFromProvider, llmSpans, otelRunCompleteHook, otlpRowsToRunRecords, otlpRowsToTraceRunRecords, otlpTextToTraceAnalysisStore, otlpToRunRecords, otlpToTraceRunRecords, planTraceInsightQuestions, projectOtlpFlatLine, providerFromBaseUrl, readOtlpStatus, redactString, redactValue, runFailureClass, runsForScenario, scoreTraceInsightReadiness, stringField, throwIfRunIncomplete, tokenizeDomainWords, toolSpans, toolSpansToTraceAnalysisStore, traceAnalystFunctionGroup, traceAnalystOnRunComplete, traceSpanKindToOpenInferenceKind };
+//# sourceMappingURL=traces.d.ts.map

package/dist/traces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traces.d.ts","names":[],"sources":["../src/trace/otlp-attributes.ts","../src/trace/otel-export.ts","../src/trace/otel-bridge.ts","../src/trace/store-to-otlp.ts","../src/trace-analyst/errors.ts","../src/trace-analyst/hook.ts","../src/trace-analyst/otlp-flatten.ts","../src/trace-analyst/otlp-span.ts","../src/trace-analyst/otlp-to-run-records.ts","../src/trace-analyst/prompts.ts"],"mappings":"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"}