@tangle-network/agent-eval 0.93.0 → 0.95.0

package/dist/trace-analyst/behavioral-metrics.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic behavioral metrics over OTLP spans — pure arithmetic, no LLM.
+ *
+ * These are the model-independent multiplier: the four trace-quality signals a
+ * tolerant analyzer (e.g. HALO) re-derives per run inside the model — token
+ * growth, output decay, tool monoculture, missing self-verification — computed
+ * here once, in TypeScript, with zero model judgment. A finding that falls out
+ * of arithmetic is trivially model-agnostic and cannot hallucinate the trend.
+ *
+ * General, not trace-specific: the detectors key off token trajectories and
+ * tool usage present in any agentic OTLP trace, not any one benchmark.
+ */
+import type { TraceAnalystSpan } from './types';
+export type SuboptimalCode = 'monotonic-input-growth' | 'output-length-decay' | 'single-tool-dependency' | 'no-self-verification';
+export interface SuboptimalSignal {
+    code: SuboptimalCode;
+    severity: 'high' | 'medium' | 'low';
+    /** Human-readable claim, with the backing numbers inlined. */
+    detail: string;
+    /** The exact figures the detector fired on — auditable, no model in the loop. */
+    evidence: Record<string, number | string | boolean>;
+}
+export interface BehavioralMetrics {
+    llmCallCount: number;
+    inputTokenTrajectory: number[];
+    outputTokenTrajectory: number[];
+    toolHistogram: Record<string, number>;
+    totalToolCalls: number;
+    distinctTools: number;
+    /** distinct/total tool calls; 1.0 when there are no tool calls. */
+    toolDiversityRatio: number;
+    hasSelfVerification: boolean;
+    signals: SuboptimalSignal[];
+}
+/**
+ * Reduce a span list to behavioral metrics + fired suboptimality signals.
+ * Pure + deterministic: same spans → same output, on any machine, no model.
+ */
+export declare function computeTraceMetrics(spans: readonly TraceAnalystSpan[]): BehavioralMetrics;
+//# sourceMappingURL=behavioral-metrics.d.ts.map

package/dist/trace-analyst/behavioral-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavioral-metrics.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/behavioral-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,MAAM,MAAM,cAAc,GACtB,wBAAwB,GACxB,qBAAqB,GACrB,wBAAwB,GACxB,sBAAsB,CAAA;AAE1B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAA;IACpB,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;IACnC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAA;IAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mBAAmB,EAAE,OAAO,CAAA;IAC5B,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAC5B;AA0CD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,iBAAiB,CAmGzF"}

package/dist/trace-analyst/behavioral-metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=behavioral-metrics.test.d.ts.map

package/dist/trace-analyst/behavioral-metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavioral-metrics.test.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/behavioral-metrics.test.ts"],"names":[],"mappings":""}

package/dist/trace-analyst/hook.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Trace-analyst auto-execution hook.
+ *
+ * Wires `analyzeTraces` into a `TraceEmitter`'s `onRunComplete` so a
+ * direct matrix run produces an analysis artifact without an out-of-band
+ * step. Designed for the case where the consumer reports "the analyst
+ * never ran" — the cause is almost always orchestration, not the analyst.
+ *
+ * Usage:
+ *
+ *   const emitter = new TraceEmitter(store, {
+ *     onRunComplete: [traceAnalystOnRunComplete({ analyze: opts, save })],
+ *   })
+ *
+ * Hooks are best-effort by default — they never crash the underlying run.
+ * The caller decides whether to gate the run on the analysis result via
+ * the `gateOn` callback.
+ */
+import type { RunCompleteHook, RunCompleteHookContext } from '../trace/emitter';
+import { type AnalyzeTracesOptions, type AnalyzeTracesResult } from './analyst';
+export 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;
+}
+export declare function traceAnalystOnRunComplete(opts: TraceAnalystHookOptions): RunCompleteHook;
+//# sourceMappingURL=hook.d.ts.map

package/dist/trace-analyst/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAC/E,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,mBAAmB,EAAiB,MAAM,WAAW,CAAA;AAE9F,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAA;IAC3F;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,OAAO,CAAA;IACpD;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,sBAAsB,KAAK,OAAO,CAAA;CAC/E;AAKD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,eAAe,CAmCxF"}

package/dist/trace-analyst/index.d.ts

@@ -0,0 +1,18 @@
+/** Ax RLM trace analyst over bounded OTLP-JSONL trace stores. */
+export { LLM_CACHED_TOKENS, LLM_COST_USD, LLM_INPUT_TOKENS, LLM_MODEL_NAME, LLM_OUTPUT_TOKENS, OPENINFERENCE_SPAN_KIND, TOOL_NAME, } from '../trace/otlp-attributes';
+export type { AnalyzeTracesInput, AnalyzeTracesOptions, AnalyzeTracesResult, AnalyzeTracesTurnSnapshot, } from './analyst';
+export { analyzeTraces } from './analyst';
+export type { TraceAnalystHookOptions } from './hook';
+export { traceAnalystOnRunComplete } from './hook';
+export type { TraceInsightContext, TraceInsightFinding, TraceInsightPanelRole, TraceInsightPromptInput, TraceInsightQualityGate, TraceInsightQuestion, TraceInsightReadiness, TraceInsightSuite, TraceInsightTask, } from './insights';
+export { buildTraceInsightContext, buildTraceInsightPrompt, defaultTraceInsightPanel, describeTraceInsightScope, domainEvidencePattern, inferDomainKeywords, planTraceInsightQuestions, scoreTraceInsightReadiness, tokenizeDomainWords, } from './insights';
+export { type FlattenOtlpOptions, flattenOtlpExportToNdjson, type OtlpFlatLine, } from './otlp-flatten';
+export { asNumber, asString, extractOtlpAttributes, firstNumberAttr, firstStringAttr, inferOtlpKind, type ProjectedOtlpSpan, projectOtlpFlatLine, readOtlpStatus, stringField, } from './otlp-span';
+export { type OtlpToRunRecordsOptions, type OtlpTraceRunRecord, otlpToRunRecords, otlpToTraceRunRecords, type TraceAggregate, } from './otlp-to-run-records';
+export { TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION, TRACE_ANALYST_SUBAGENT_DESCRIPTION, } from './prompts';
+export type { TraceAnalysisStore } from './store';
+export { OtlpFileTraceStore, type OtlpFileTraceStoreOptions, SpanNotFoundError, TraceFileMissingError, TraceNotFoundError, } from './store-otlp';
+export { buildTraceAnalystTools, traceAnalystFunctionGroup, } from './tools';
+export type { DatasetOverview, ErrorCluster, QueryTracesPage, SearchSpanResult, SearchTraceResult, SpanMatchRecord, TraceAnalystByteBudgets, TraceAnalystFilters, TraceAnalystSpan, TraceAnalystSpanKind, TraceAnalystSpanStatus, TraceAnalystTraceSummary, ViewSpansResult, ViewTraceOversized, ViewTraceResult, } from './types';
+export { DEFAULT_TRACE_ANALYST_BUDGETS, TRACE_ANALYST_TRUNCATION_MARKER_PREFIX, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/trace-analyst/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,SAAS,GACV,MAAM,0BAA0B,CAAA;AACjC,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,YAAY,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAA;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAA;AAClD,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,KAAK,kBAAkB,EACvB,yBAAyB,EACzB,KAAK,YAAY,GAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,aAAa,EACb,KAAK,iBAAiB,EACtB,mBAAmB,EACnB,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,cAAc,GACpB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,+BAA+B,EAC/B,uCAAuC,EACvC,kCAAkC,GACnC,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,eAAe,GAChB,MAAM,SAAS,CAAA;AAChB,OAAO,EACL,6BAA6B,EAC7B,sCAAsC,GACvC,MAAM,SAAS,CAAA"}

package/dist/trace-analyst/insights.d.ts

@@ -0,0 +1,71 @@
+export interface TraceInsightTask {
+    id: string;
+    name: string;
+    prompt?: string;
+    difficulty?: string;
+    tags?: string[];
+    outcome?: string;
+    score?: number;
+    gaps?: string[];
+}
+export interface TraceInsightSuite {
+    name: string;
+    collectionId?: string;
+    tasks: TraceInsightTask[];
+}
+export interface TraceInsightFinding {
+    kind: string;
+    severity?: string;
+    taskIds: string[];
+    evidence?: string;
+    proposedFixClass?: string;
+}
+export interface TraceInsightQuestion {
+    id: string;
+    question: string;
+    why: string;
+}
+export interface TraceInsightPanelRole {
+    id: string;
+    name: string;
+    responsibility: string;
+}
+export interface TraceInsightPromptInput {
+    suite: TraceInsightSuite;
+    findings?: TraceInsightFinding[];
+    agent?: Record<string, unknown>;
+    totals?: Record<string, unknown>;
+    maxRepresentativeTraces?: number;
+}
+export interface TraceInsightContext {
+    suite: TraceInsightSuite;
+    scope: string;
+    keywords: string[];
+    questions: TraceInsightQuestion[];
+    panel: TraceInsightPanelRole[];
+    findings: TraceInsightFinding[];
+    agent: Record<string, unknown> | null;
+    totals: Record<string, unknown> | null;
+}
+export interface TraceInsightQualityGate {
+    id: string;
+    label: string;
+    passed: boolean;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    detail: string;
+}
+export interface TraceInsightReadiness {
+    score: number;
+    grade: 'external-ready' | 'internal-review' | 'raw-analysis';
+    gates: TraceInsightQualityGate[];
+}
+export declare function tokenizeDomainWords(value: string): string[];
+export declare function inferDomainKeywords(suite: TraceInsightSuite): string[];
+export declare function domainEvidencePattern(keywords: string[]): RegExp;
+export declare function describeTraceInsightScope(suite: TraceInsightSuite): string;
+export declare function planTraceInsightQuestions(input: TraceInsightPromptInput): TraceInsightQuestion[];
+export declare function buildTraceInsightContext(input: TraceInsightPromptInput): TraceInsightContext;
+export declare function scoreTraceInsightReadiness(context: TraceInsightContext): TraceInsightReadiness;
+export declare function defaultTraceInsightPanel(): TraceInsightPanelRole[];
+export declare function buildTraceInsightPrompt(input: TraceInsightPromptInput): string;
+//# sourceMappingURL=insights.d.ts.map

package/dist/trace-analyst/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/insights.ts"],"names":[],"mappings":"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"}

package/dist/trace-analyst/insights.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=insights.test.d.ts.map

package/dist/trace-analyst/insights.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.test.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/insights.test.ts"],"names":[],"mappings":""}

package/dist/trace-analyst/otlp-flatten.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `flattenOtlpExportToNdjson` — flatten an `OtlpExport` (the shape
+ * `exportRunAsOtlp` produces) into the per-line JSON the analyst's
+ * `OtlpFileTraceStore` index reads. Replaces three per-consumer OTLP
+ * flatteners with one canonical projection.
+ *
+ * Pure function, no I/O — the caller does `.map(JSON.stringify).join('\n')`
+ * and writes the file (consumers want control over rotation + naming).
+ */
+import type { OtlpExport } from '../trace/otel';
+export interface OtlpFlatLine {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    kind: string;
+    start_time: string;
+    end_time: string;
+    status: {
+        code: 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR' | 'STATUS_CODE_UNSET';
+        message?: string;
+    };
+    resource: {
+        attributes: Record<string, string | number | boolean>;
+    };
+    attributes: Record<string, string | number | boolean>;
+    events?: Array<{
+        name: string;
+        timeUnixNano?: string;
+        attributes?: Record<string, unknown>;
+    }>;
+}
+export interface FlattenOtlpOptions {
+    /** `'openinference'` (default) mirrors legacy 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>>;
+}
+export declare function flattenOtlpExportToNdjson(otlpExport: OtlpExport, opts?: FlattenOtlpOptions): OtlpFlatLine[];
+//# sourceMappingURL=otlp-flatten.d.ts.map

package/dist/trace-analyst/otlp-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-flatten.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,eAAe,CAAA;AASzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE;QACN,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,GAAG,mBAAmB,CAAA;QAClE,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,CAAA;IACnE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;IACrD,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAA;CAC9F;AAED,MAAM,WAAW,kBAAkB;IACjC;;+CAE2C;IAC3C,mBAAmB,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;IAC9C,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAC1C;AA8DD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,IAAI,GAAE,kBAAuB,GAC5B,YAAY,EAAE,CAuChB"}

package/dist/trace-analyst/otlp-span.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+import type { TraceAnalystSpanKind, TraceAnalystSpanStatus } from './types';
+/**
+ * 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.
+ */
+export 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`.
+ */
+export declare function projectOtlpFlatLine(raw: Record<string, unknown>): ProjectedOtlpSpan | null;
+export declare function readOtlpStatus(raw: Record<string, unknown>): {
+    code: TraceAnalystSpanStatus;
+    message: string | undefined;
+};
+export 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.
+ */
+export declare function extractOtlpAttributes(raw: Record<string, unknown>): Record<string, unknown>;
+export declare function stringField(raw: Record<string, unknown>, key: string): string | undefined;
+export declare function asString(v: unknown): string | null;
+/** Read a numeric attribute, tolerating numeric strings; `null` if absent/NaN. */
+export declare function asNumber(v: unknown): number | null;
+/** First finite numeric value across a list of candidate attribute keys. */
+export declare function firstNumberAttr(attrs: Record<string, unknown>, keys: readonly string[]): number | null;
+/** First non-empty string value across a list of candidate attribute keys. */
+export declare function firstStringAttr(attrs: Record<string, unknown>, keys: readonly string[]): string | 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.
+ */
+export declare function spanEpochMillis(ts: string | undefined | null): number | null;
+/**
+ * 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).
+ */
+export declare function compareSpanTime(a: string, b: string): number;
+//# sourceMappingURL=otlp-span.d.ts.map

package/dist/trace-analyst/otlp-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-span.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-span.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,oBAAoB,CAAA;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,sBAAsB,CAAA;IAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAmD1F;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC5D,IAAI,EAAE,sBAAsB,CAAA;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B,CAeA;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAgBlF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB3F;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAElD;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOlD;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,GAAG,IAAI,CAMf;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,GAAG,IAAI,CAMf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/trace-analyst/otlp-span.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=otlp-span.test.d.ts.map

package/dist/trace-analyst/otlp-span.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-span.test.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-span.test.ts"],"names":[],"mappings":""}

package/dist/trace-analyst/otlp-to-run-records.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `otlpToRunRecords` — fold an OTLP traces.jsonl (one OTLP span per line;
+ * the form AppWorld / HALO emit via their OpenInference OTLP exporter, the
+ * same shape `flattenOtlpExportToNdjson` produces) into validated
+ * `RunRecord[]` — one record per `trace_id` (one trace == one task).
+ *
+ * This is the offline ingestion primitive the AppWorld proposer bench and the
+ * hosted Intelligence product both stand on: traces in, paper-grade rows
+ * out, ready for `compareProposers` / `analyzeRuns` / the promotion gate.
+ *
+ * Aggregation per trace:
+ *   - tokenUsage: sum LLM-span `input` / `output` (+ `cached` when present)
+ *     across every LLM span in the trace.
+ *   - costUsd: sum per-span LLM cost when present; else priced via
+ *     `opts.priceUsdPerToken` from the aggregated tokens; else 0 with a
+ *     loud `raw.cost_unpriced = 1` marker so a missing price is visible, not
+ *     a silent zero folded into a gate.
+ *   - failureMode: the first `STATUS_CODE_ERROR` span's normalized status
+ *     message (carries the real failure signature, not a generic class).
+ *   - model: the dominant LLM model in the trace (snapshot-padded to satisfy
+ *     `validateRunRecord` when the trace's model is a bare alias).
+ *   - outcome score: `opts.scoreForTrace` (AppWorld `world.evaluate()` →
+ *     TGC/SGC) when supplied; else 1 when the trace had no error span, 0
+ *     when it did — a defensible default the caller can override.
+ *   - prompt / completion: carried into `raw` as token-count signals and,
+ *     when the first/last LLM span exposes `input.value` / `output.value`,
+ *     the verbatim text is preserved on the optional `promptText` /
+ *     `completionText` of the returned `OtlpTraceRunRecord`.
+ *
+ * Fail-loud: an OTLP file with zero valid spans throws. A trace with no
+ * spans is impossible (a trace exists only because a span referenced it).
+ * `validateRunRecord` runs on every row — a malformed projection throws
+ * rather than silently producing a half-record.
+ */
+import { type RunRecord, type RunSplitTag, type RunTokenUsage } from '../run-record';
+export 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 `compareProposers` 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: 0` AND `raw.cost_unpriced = 1` — the zero is flagged,
+     * never silent.
+     */
+    priceUsdPerToken?: number;
+    /**
+     * Score for a trace's outcome (AppWorld `world.evaluate()` → TGC/SGC, or
+     * any [0,1] task-success signal). Keyed by `trace_id`; falls through to
+     * the error-derived default (1 = no error span, 0 = had one) when the map
+     * has no entry or the function returns undefined.
+     */
+    scoreForTrace?: (traceId: string, span: TraceAggregate) => number | undefined;
+    /**
+     * Per-record judge metadata when an external judge produced the score.
+     * Keyed by `trace_id`.
+     */
+    judgeMetadataForTrace?: (traceId: 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. */
+export 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. */
+export interface TraceAggregate {
+    traceId: string;
+    spanCount: number;
+    llmSpanCount: number;
+    toolSpanCount: number;
+    agentSpanCount: number;
+    errorSpanCount: number;
+    tokenUsage: RunTokenUsage;
+    /** First error span's normalized status message, if any. */
+    firstErrorMessage?: string;
+    model: string;
+    startTime: string;
+    endTime: string;
+    wallMs: number;
+}
+/**
+ * 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.
+ */
+export declare function otlpToRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): RunRecord[];
+/** As {@link otlpToRunRecords} but returns the prompt/completion text too. */
+export declare function otlpToTraceRunRecords(otlpJsonl: string, opts: OtlpToRunRecordsOptions): OtlpTraceRunRecord[];
+//# sourceMappingURL=otlp-to-run-records.d.ts.map

package/dist/trace-analyst/otlp-to-run-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-to-run-records.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-to-run-records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAA;AAiBtB,MAAM,WAAW,uBAAuB;IACtC,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAA;IACpB;oFACgF;IAChF,WAAW,EAAE,MAAM,CAAA;IACnB;2EACuE;IACvE,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,CAAA;IAC7E;;;OAGG;IACH,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;CACpF;AAED;;;kCAGkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAA;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,aAAa,CAAA;IACzB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,GAAG,SAAS,EAAE,CAE9F;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,uBAAuB,GAC5B,kBAAkB,EAAE,CAwEtB"}

package/dist/trace-analyst/otlp-to-run-records.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=otlp-to-run-records.test.d.ts.map

package/dist/trace-analyst/otlp-to-run-records.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-to-run-records.test.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-to-run-records.test.ts"],"names":[],"mappings":""}

package/dist/trace-analyst/otlp-to-run-records.timestamps.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=otlp-to-run-records.timestamps.test.d.ts.map

package/dist/trace-analyst/otlp-to-run-records.timestamps.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-to-run-records.timestamps.test.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/otlp-to-run-records.timestamps.test.ts"],"names":[],"mappings":""}

package/dist/trace-analyst/prompts.d.ts

@@ -0,0 +1,6 @@
+/** Ax RLM prompt for bounded trace discovery and evidence-backed analysis. */
+export declare const TRACE_ANALYST_ACTOR_DESCRIPTION = "You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the `traces` namespace.\n\nDISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol \u2014 follow exactly:\n\n1. ALWAYS call `traces.getDatasetOverview({})` FIRST without a regex_pattern. The result tells you total_traces, raw_jsonl_bytes, services, agents, models, and sample_trace_ids (real ids \u2014 never fabricate one).\n\n2. Use raw_jsonl_bytes to gauge how expensive raw scans will be. `filters.regex_pattern` is the one scan-heavy filter on getDatasetOverview / queryTraces / countTraces \u2014 narrow with indexed fields (has_errors, model_names, service_names, agent_names, time bounds) BEFORE adding a regex on a large dataset.\n\n3. To list more traces than the sample, call `traces.queryTraces({ filters?, limit, offset? })`. Each summary carries raw_jsonl_bytes \u2014 use it to choose between viewTrace and searchTrace BEFORE calling either.\n\n4. Per-trace inspection:\n   - SMALL trace (raw_jsonl_bytes well under 150_000): call `traces.viewTrace({ trace_id })`. Returns all spans. Per-attribute payloads are head-capped at ~4KB; large `input.value` / `output.value` / `llm.input_messages` will show a `[trace-analyst truncated: N bytes]` marker.\n   - LARGE trace (raw_jsonl_bytes near or above 150_000, or you saw an `oversized` response): use `traces.searchTrace({ trace_id, regex_pattern })` to get bounded SpanMatchRecords (span metadata + matched text + surrounding context). Then call `traces.viewSpans({ trace_id, span_ids: [...] })` for surgical reads (~16KB cap, 4\u00D7 higher than discovery), or `traces.searchSpan({ trace_id, span_id, regex_pattern })` for one large span. Stays bounded regardless of trace size.\n   - Useful regex patterns: `STATUS_CODE_ERROR` (failures), tool names like `grep` or `view_trace`, error strings like `MaxTurnsExceeded`, model names, attribute keys.\n\n5. ONLY call viewTrace / viewSpans / searchTrace / searchSpan with trace/span ids you have already seen in sample_trace_ids, a queryTraces page, or a previous search result. Never invent ids.\n\n5a. **Result-shape contract** \u2014 searchTrace and searchSpan return `{ trace_id, hits, total_matches, has_more }`. Iterate `result.hits` (NOT result.matches). Each hit has `{ span_id, span_name, span_kind, attribute_path, matched_text, context_before, context_after, match_offset }`. viewTrace returns `{ trace_id, spans }` (or `oversized`). viewSpans returns `{ trace_id, spans, missing_span_ids, truncated_attribute_count }`. Never assume a field name \u2014 log the result shape first if unsure.\n\n6. If viewTrace returns an `oversized` summary instead of `spans`, DO NOT retry the same call. Read the summary's top_span_names, span_count, span_response_bytes_max, error_span_count to plan a follow-up: switch to searchTrace (or searchSpan for one large span), then viewSpans on a smaller, surgical span_ids set.\n\n7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.\n\n8. If a tool errors (invalid regex, range error), STOP and reconsider \u2014 don't retry with a guessed id or argument. Use the discovery tools above to recover.\n\n9. If a ~4KB-truncated payload from viewTrace / searchTrace matters for your answer, first try viewSpans on that span id (~16KB cap). If a 16KB-truncated payload from viewSpans still matters, narrow further with searchSpan against a more specific regex rather than asking for the full payload again.\n\n10. If maxDepth > 0 and the question splits into independent semantic branches, delegate well-defined subtasks to subagents using `await llmQuery(...)`. Pass narrow context and a focused query. Examples:\n\n    const reviews = await llmQuery([\n      { query: 'Drill into trace abc123 \u2014 what tool calls preceded the failure?', context: { trace_id: 'abc123' } },\n      { query: 'Drill into trace def456 \u2014 same failure mode?', context: { trace_id: 'def456' } },\n    ]);\n\nOBSERVABILITY rules:\n- Each non-final actor turn must emit at least one `console.log(...)` for evidence. Up to 3 logs per turn is fine when correlating multiple data sources (e.g. one log for findings list, one for source-file content, one for derived analysis).\n- Do NOT combine `console.log` with `final(...)` or `askClarification(...)` in the same turn \u2014 finish gathering data first, then call final on its own turn.\n- Reuse runtime variables across turns; don't recompute.\n- When done, call `await final(answer)` with the fully-formed report. The responder rewrites the answer into output fields; if you only pass a vague summary string the responder has nothing concrete to format.\n\nCRITICAL \u2014 `final()` payload contract for evidence-grounded analysis tasks:\n- Pass a STRUCTURED object as the second arg with the actual data the responder needs to format the answer. Do NOT pass abstract instructions; pass evidence.\n- Example for per-item verdict tasks:\n  ```js\n  await final(\"Format the per-item verdict report from the evidence below.\", {\n    findings: [\n      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },\n      ...all items\n    ],\n    systemic_summary: '3 sentences I wrote based on the evidence above'\n  });\n  ```\n- Calling `final(\"answer\", {})` with no evidence is a failure mode \u2014 the responder will hallucinate or echo back the field names. Always include the gathered data.\n- Premature final after a single viewSpans call is INSUFFICIENT for per-finding analysis tasks. Read the requested attributes (e.g. `spans[i].attributes['redteam.finding.title']`), and for each one perform the requested cross-reference (e.g. read the source SPAN's `attributes['source.content']`).\n\nOUTPUT contract \u2014 your final answer must include:\n- A clear prose conclusion answering the user's question.\n- Trace ids and span ids cited as evidence for each claim.\n- Failure modes named in the user's domain language, with frequency and concrete examples.\n\nDo NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.";
+export declare const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v5-2026-05-06";
+/** Subagent prompt for focused trace-inspection subtasks. */
+export declare const TRACE_ANALYST_SUBAGENT_DESCRIPTION = "You are a trace-analyst subagent. Your parent has delegated a focused trace-inspection question. Use the same DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol but stay tightly scoped: do exactly what was asked, return a concise compact answer, do NOT spawn further subagents unless the parent's question is genuinely multi-branch.\n\nCite trace ids and span ids for every claim. Do NOT invent ids.";
+//# sourceMappingURL=prompts.d.ts.map

package/dist/trace-analyst/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/trace-analyst/prompts.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,eAAO,MAAM,+BAA+B,ujMA4DsE,CAAA;AAElH,eAAO,MAAM,uCAAuC,sCAAsC,CAAA;AAE1F,6DAA6D;AAC7D,eAAO,MAAM,kCAAkC,mZAEiB,CAAA"}