@tangle-network/agent-eval 0.86.0 → 0.90.0

package/dist/chunk-REVYNR6C.js

@@ -0,0 +1,100 @@
+import {
+  buildTrajectory
+} from "./chunk-RZTMDUO7.js";
+import {
+  TraceEmitter
+} from "./chunk-TVVP3ZZQ.js";
+import {
+  NotFoundError,
+  ValidationError
+} from "./chunk-3BFEG2F6.js";
+
+// src/counterfactual.ts
+async function runCounterfactual(store, originalRunId, mutation, runner) {
+  const originalRun = await store.getRun(originalRunId);
+  if (!originalRun) throw new NotFoundError(`counterfactual: run ${originalRunId} not found`);
+  const trajectory = await buildTrajectory(store, originalRunId);
+  if (mutation.at < 0 || mutation.at >= trajectory.steps.length) {
+    throw new ValidationError(
+      `counterfactual: mutation.at=${mutation.at} out of range [0, ${trajectory.steps.length})`
+    );
+  }
+  const targetStep = trajectory.steps[mutation.at];
+  const mutatedStep = applyMutation(targetStep, mutation);
+  const cfEmitter = new TraceEmitter(store);
+  await cfEmitter.startRun({
+    scenarioId: originalRun.scenarioId,
+    variantId: originalRun.variantId ? `${originalRun.variantId}+cf:${mutation.kind}@${mutation.at}` : `cf:${mutation.kind}@${mutation.at}`,
+    projectId: originalRun.projectId,
+    parentRunId: originalRunId,
+    layer: "meta",
+    tags: { counterfactual: "true", mutationKind: mutation.kind, mutationAt: String(mutation.at) }
+  });
+  await runner.executeFrom(
+    {
+      originalRunId,
+      originalTrajectory: trajectory,
+      prefix: trajectory.steps.slice(0, mutation.at),
+      mutation,
+      mutatedStep
+    },
+    cfEmitter
+  );
+  const counterfactual = await store.getRun(cfEmitter.runId);
+  const delta = {
+    originalOutcomeScore: originalRun.outcome?.score ?? null,
+    counterfactualOutcomeScore: counterfactual?.outcome?.score ?? null,
+    deltaScore: originalRun.outcome?.score !== void 0 && counterfactual?.outcome?.score !== void 0 ? counterfactual.outcome.score - originalRun.outcome.score : null
+  };
+  return { counterfactualRunId: cfEmitter.runId, originalRunId, mutation, delta };
+}
+function applyMutation(step, mutation) {
+  if (mutation.kind === "swap-model" && step.span.kind === "llm") {
+    const llm = step.span;
+    return { ...step, span: { ...llm, model: mutation.newModel } };
+  }
+  if (mutation.kind === "swap-tool-result" && step.span.kind === "tool") {
+    const tool = step.span;
+    return { ...step, span: { ...tool, result: mutation.newResult } };
+  }
+  if (mutation.kind === "inject-system-message" && step.span.kind === "llm") {
+    const llm = step.span;
+    return {
+      ...step,
+      span: {
+        ...llm,
+        messages: [{ role: "system", content: mutation.content }, ...llm.messages]
+      }
+    };
+  }
+  if (mutation.kind === "custom") return mutation.apply(step);
+  return step;
+}
+function attributeCounterfactuals(results) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    const arr = grouped.get(r.mutation.kind) ?? [];
+    arr.push(r);
+    grouped.set(r.mutation.kind, arr);
+  }
+  const out = [];
+  for (const [kind, items] of grouped) {
+    const deltas = items.map((i) => i.delta.deltaScore).filter((d) => typeof d === "number");
+    if (deltas.length === 0) continue;
+    const meanAbs = deltas.reduce((a, b) => a + Math.abs(b), 0) / deltas.length;
+    const meanSigned = deltas.reduce((a, b) => a + b, 0) / deltas.length;
+    out.push({
+      mutationKind: kind,
+      n: deltas.length,
+      meanAbsDelta: meanAbs,
+      meanSignedDelta: meanSigned
+    });
+  }
+  return out.sort((a, b) => b.meanAbsDelta - a.meanAbsDelta);
+}
+
+export {
+  runCounterfactual,
+  attributeCounterfactuals
+};
+//# sourceMappingURL=chunk-REVYNR6C.js.map

package/dist/chunk-REVYNR6C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/counterfactual.ts"],"sourcesContent":["/**\n * Counterfactual replay — \"what would have happened if we'd changed\n * exactly one thing at turn N?\"\n *\n * The framework does NOT drive the agent — it sets up the replay\n * context (prior spans, prior state, mutation spec) and records the\n * resulting divergence. Consumers supply an `executeFrom(ctx)` callback\n * that runs their agent starting from turn N with the mutation applied.\n *\n * Counterfactual runs are recorded as a new Run with `layer='meta'` and\n * `parentRunId = originalRunId`, so downstream diff + correlation\n * pipelines see them natively.\n */\n\nimport { NotFoundError, ValidationError } from './errors'\nimport { TraceEmitter } from './trace/emitter'\nimport type { LlmSpan, Span, ToolSpan } from './trace/schema'\nimport type { TraceStore } from './trace/store'\nimport { buildTrajectory, type Trajectory, type TrajectoryStep } from './trajectory'\n\nexport type CounterfactualMutation =\n  | { kind: 'swap-model'; at: number; newModel: string }\n  | { kind: 'swap-tool-result'; at: number; newResult: unknown }\n  | { kind: 'truncate-after'; at: number }\n  | { kind: 'inject-system-message'; at: number; content: string }\n  | {\n      kind: 'custom'\n      at: number\n      describe: string\n      apply: (step: TrajectoryStep) => TrajectoryStep\n    }\n\nexport interface CounterfactualContext {\n  originalRunId: string\n  originalTrajectory: Trajectory\n  /** Steps up to (but not including) the mutation point — the prefix the\n   *  replayed agent inherits as its prior conversation/tool history. */\n  prefix: TrajectoryStep[]\n  mutation: CounterfactualMutation\n  /** Pre-applied mutation on the step at `mutation.at`. Consumers use this\n   *  as the FIRST step the replayed agent emits (they decide whether to\n   *  re-emit it or continue from there). */\n  mutatedStep: TrajectoryStep\n}\n\nexport interface CounterfactualResult {\n  counterfactualRunId: string\n  originalRunId: string\n  mutation: CounterfactualMutation\n  /** Structured delta summary — caller can extend via scoring. */\n  delta: {\n    originalOutcomeScore: number | null\n    counterfactualOutcomeScore: number | null\n    deltaScore: number | null\n  }\n}\n\nexport interface CounterfactualRunner {\n  /**\n   * Execute the agent from `ctx.prefix` with the mutation applied.\n   * MUST emit spans into the provided emitter so they become part of\n   * the counterfactual run. MUST call emitter.endRun() with a verdict.\n   */\n  executeFrom: (ctx: CounterfactualContext, emitter: TraceEmitter) => Promise<void>\n}\n\nexport async function runCounterfactual(\n  store: TraceStore,\n  originalRunId: string,\n  mutation: CounterfactualMutation,\n  runner: CounterfactualRunner,\n): Promise<CounterfactualResult> {\n  const originalRun = await store.getRun(originalRunId)\n  if (!originalRun) throw new NotFoundError(`counterfactual: run ${originalRunId} not found`)\n  const trajectory = await buildTrajectory(store, originalRunId)\n  if (mutation.at < 0 || mutation.at >= trajectory.steps.length) {\n    throw new ValidationError(\n      `counterfactual: mutation.at=${mutation.at} out of range [0, ${trajectory.steps.length})`,\n    )\n  }\n  const targetStep = trajectory.steps[mutation.at]!\n  const mutatedStep = applyMutation(targetStep, mutation)\n\n  const cfEmitter = new TraceEmitter(store)\n  await cfEmitter.startRun({\n    scenarioId: originalRun.scenarioId,\n    variantId: originalRun.variantId\n      ? `${originalRun.variantId}+cf:${mutation.kind}@${mutation.at}`\n      : `cf:${mutation.kind}@${mutation.at}`,\n    projectId: originalRun.projectId,\n    parentRunId: originalRunId,\n    layer: 'meta',\n    tags: { counterfactual: 'true', mutationKind: mutation.kind, mutationAt: String(mutation.at) },\n  })\n\n  await runner.executeFrom(\n    {\n      originalRunId,\n      originalTrajectory: trajectory,\n      prefix: trajectory.steps.slice(0, mutation.at),\n      mutation,\n      mutatedStep,\n    },\n    cfEmitter,\n  )\n\n  const counterfactual = await store.getRun(cfEmitter.runId)\n  const delta = {\n    originalOutcomeScore: originalRun.outcome?.score ?? null,\n    counterfactualOutcomeScore: counterfactual?.outcome?.score ?? null,\n    deltaScore:\n      originalRun.outcome?.score !== undefined && counterfactual?.outcome?.score !== undefined\n        ? counterfactual.outcome.score - originalRun.outcome.score\n        : null,\n  }\n  return { counterfactualRunId: cfEmitter.runId, originalRunId, mutation, delta }\n}\n\nfunction applyMutation(step: TrajectoryStep, mutation: CounterfactualMutation): TrajectoryStep {\n  if (mutation.kind === 'swap-model' && step.span.kind === 'llm') {\n    const llm = step.span as LlmSpan\n    return { ...step, span: { ...llm, model: mutation.newModel } }\n  }\n  if (mutation.kind === 'swap-tool-result' && step.span.kind === 'tool') {\n    const tool = step.span as ToolSpan\n    return { ...step, span: { ...tool, result: mutation.newResult } }\n  }\n  if (mutation.kind === 'inject-system-message' && step.span.kind === 'llm') {\n    const llm = step.span as LlmSpan\n    return {\n      ...step,\n      span: {\n        ...llm,\n        messages: [{ role: 'system', content: mutation.content }, ...llm.messages],\n      },\n    }\n  }\n  if (mutation.kind === 'custom') return mutation.apply(step)\n  // swap-tool-result on non-tool span / swap-model on non-llm / truncate-after: no step-level change.\n  return step\n}\n\n/**\n * Aggregate a batch of counterfactuals into a simple attribution table:\n * which mutation kinds move outcomes most? (Useful when you run a grid\n * over the same trajectory — swap-model at every llm span, swap-tool\n * at every tool span — and want a ranked summary.)\n */\nexport function attributeCounterfactuals(results: CounterfactualResult[]): Array<{\n  mutationKind: CounterfactualMutation['kind']\n  n: number\n  meanAbsDelta: number\n  meanSignedDelta: number\n}> {\n  const grouped = new Map<string, CounterfactualResult[]>()\n  for (const r of results) {\n    const arr = grouped.get(r.mutation.kind) ?? []\n    arr.push(r)\n    grouped.set(r.mutation.kind, arr)\n  }\n  const out: Array<{\n    mutationKind: CounterfactualMutation['kind']\n    n: number\n    meanAbsDelta: number\n    meanSignedDelta: number\n  }> = []\n  for (const [kind, items] of grouped) {\n    const deltas = items\n      .map((i) => i.delta.deltaScore)\n      .filter((d): d is number => typeof d === 'number')\n    if (deltas.length === 0) continue\n    const meanAbs = deltas.reduce((a, b) => a + Math.abs(b), 0) / deltas.length\n    const meanSigned = deltas.reduce((a, b) => a + b, 0) / deltas.length\n    out.push({\n      mutationKind: kind as CounterfactualMutation['kind'],\n      n: deltas.length,\n      meanAbsDelta: meanAbs,\n      meanSignedDelta: meanSigned,\n    })\n  }\n  return out.sort((a, b) => b.meanAbsDelta - a.meanAbsDelta)\n}\n\n// Re-export Span type for consumer ergonomics.\nexport type { Span }\n"],"mappings":"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","names":[]}

package/dist/chunk-STGVSCDH.js

@@ -0,0 +1,202 @@
+// src/perf/integrity.ts
+function isMissing(value) {
+  return value === null || value === void 0;
+}
+function checkRecordIntegrity(records, resolveJourney) {
+  const violations = [];
+  for (const [recordIndex, record] of records.entries()) {
+    if (record.pass !== true) continue;
+    const journey = resolveJourney(record);
+    if (journey === null) continue;
+    for (const field of journey.requiredFields) {
+      if (isMissing(record[field])) {
+        violations.push({
+          recordIndex,
+          journeyId: journey.id,
+          field,
+          reason: "null-required-field",
+          detail: `required field '${field}' is ${record[field] === null ? "null" : "undefined"} on a passing '${journey.id}' record`
+        });
+      }
+    }
+    for (const field of journey.phaseFields ?? []) {
+      if (isMissing(record[field])) {
+        violations.push({
+          recordIndex,
+          journeyId: journey.id,
+          field,
+          reason: "null-required-field",
+          detail: `phase field '${field}' is ${record[field] === null ? "null" : "undefined"} on a passing '${journey.id}' record`
+        });
+      }
+    }
+    for (const { field, min } of journey.minimums ?? []) {
+      const value = record[field];
+      if (isMissing(value)) continue;
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        violations.push({
+          recordIndex,
+          journeyId: journey.id,
+          field,
+          reason: "below-minimum",
+          detail: `field '${field}' has non-numeric value ${JSON.stringify(value)} on a passing '${journey.id}' record (minimum ${min})`
+        });
+        continue;
+      }
+      if (value < min) {
+        violations.push({
+          recordIndex,
+          journeyId: journey.id,
+          field,
+          reason: "below-minimum",
+          detail: `field '${field}' is ${value}, below minimum ${min} on a passing '${journey.id}' record`
+        });
+      }
+    }
+  }
+  return { succeeded: violations.length === 0, violations };
+}
+function assertRecordIntegrity(records, resolveJourney) {
+  const result = checkRecordIntegrity(records, resolveJourney);
+  if (result.succeeded) return;
+  const lines = result.violations.map(
+    (v) => `  [record ${v.recordIndex}] ${v.journeyId}.${v.field} (${v.reason}): ${v.detail}`
+  );
+  throw new Error(
+    `Record integrity check failed with ${result.violations.length} violation(s):
+${lines.join("\n")}`
+  );
+}
+
+// src/perf/journey.ts
+function scenarioKey(journeyId, axes) {
+  const parts = Object.keys(axes).sort().map((dim) => `${dim}=${axes[dim]}`);
+  return [journeyId, ...parts].join("|");
+}
+function expandMatrix(journeys, axes, filter) {
+  const dims = Object.keys(axes).sort();
+  let combos = [{}];
+  for (const dim of dims) {
+    const values = axes[dim];
+    const next = [];
+    for (const combo of combos) {
+      for (const value of values) {
+        next.push({ ...combo, [dim]: value });
+      }
+    }
+    combos = next;
+  }
+  const scenarios = [];
+  for (const journey of journeys) {
+    for (const combo of combos) {
+      if (filter && !filter(journey.id, combo)) continue;
+      scenarios.push({ key: scenarioKey(journey.id, combo), journey, axes: combo });
+    }
+  }
+  return scenarios;
+}
+
+// src/perf/ratchet.ts
+function nearestRank(sorted, p) {
+  if (sorted.length === 0) throw new Error("nearestRank requires at least one sample");
+  const rank = Math.max(1, Math.ceil(p / 100 * sorted.length));
+  return sorted[rank - 1];
+}
+function summarizeRecords(records, keyOf, metricFields) {
+  const samples = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const key = keyOf(record);
+    if (key === null) continue;
+    let byField = samples.get(key);
+    if (!byField) {
+      byField = /* @__PURE__ */ new Map();
+      samples.set(key, byField);
+    }
+    for (const field of metricFields) {
+      const value = record[field];
+      if (typeof value !== "number" || Number.isNaN(value)) continue;
+      let values = byField.get(field);
+      if (!values) {
+        values = [];
+        byField.set(field, values);
+      }
+      values.push(value);
+    }
+  }
+  const scenarios = {};
+  for (const [key, byField] of samples) {
+    const stats = {};
+    for (const [field, values] of byField) {
+      if (values.length === 0) continue;
+      const sorted = [...values].sort((a, b) => a - b);
+      stats[field] = {
+        p50: nearestRank(sorted, 50),
+        p90: nearestRank(sorted, 90),
+        n: sorted.length
+      };
+    }
+    scenarios[key] = stats;
+  }
+  return { version: 1, scenarios };
+}
+function pctOver(currentValue, baselineValue) {
+  if (baselineValue === 0) {
+    return currentValue === 0 ? 0 : Number.POSITIVE_INFINITY;
+  }
+  return (currentValue - baselineValue) / baselineValue * 100;
+}
+function gatePerf(current, baseline, options) {
+  const tolerancePct = options?.tolerancePct ?? 10;
+  const minSamples = options?.minSamples ?? 3;
+  const regressions = [];
+  const improvements = [];
+  const missing = /* @__PURE__ */ new Set();
+  for (const [scenarioKey2, baselineStats] of Object.entries(baseline.scenarios)) {
+    const currentStats = current.scenarios[scenarioKey2];
+    if (!currentStats) {
+      missing.add(scenarioKey2);
+      continue;
+    }
+    for (const [field, baselineStat] of Object.entries(baselineStats)) {
+      const currentStat = currentStats[field];
+      if (!currentStat || currentStat.n < minSamples) {
+        missing.add(scenarioKey2);
+        continue;
+      }
+      const overBy = {
+        p50Pct: pctOver(currentStat.p50, baselineStat.p50),
+        p90Pct: pctOver(currentStat.p90, baselineStat.p90)
+      };
+      const entry = {
+        scenarioKey: scenarioKey2,
+        field,
+        baseline: baselineStat,
+        current: currentStat,
+        overBy
+      };
+      if (overBy.p50Pct > tolerancePct || overBy.p90Pct > tolerancePct) {
+        regressions.push(entry);
+      } else if (overBy.p50Pct < 0 && overBy.p90Pct < 0) {
+        improvements.push(entry);
+      }
+    }
+  }
+  const newScenarios = Object.keys(current.scenarios).filter((key) => !(key in baseline.scenarios));
+  return {
+    succeeded: regressions.length === 0,
+    regressions,
+    improvements,
+    missingScenarios: [...missing],
+    newScenarios
+  };
+}
+
+export {
+  checkRecordIntegrity,
+  assertRecordIntegrity,
+  scenarioKey,
+  expandMatrix,
+  summarizeRecords,
+  gatePerf
+};
+//# sourceMappingURL=chunk-STGVSCDH.js.map

package/dist/chunk-STGVSCDH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/perf/integrity.ts","../src/perf/journey.ts","../src/perf/ratchet.ts"],"sourcesContent":["/**\n * Record-integrity contracts for perf metric records.\n *\n * A record that claims `pass === true` must actually carry the journey's\n * required measurements — a \"passing\" provision run with a null\n * `total_ms` is a lying record, not a pass. Failed records are exempt:\n * a run that errored mid-flight legitimately has nulls.\n */\n\nimport type { JourneySpec } from './journey'\n\nexport interface IntegrityViolation {\n  recordIndex: number\n  journeyId: string\n  field: string\n  reason: 'null-required-field' | 'below-minimum'\n  detail: string\n}\n\nexport interface IntegrityResult {\n  succeeded: boolean\n  violations: IntegrityViolation[]\n}\n\nfunction isMissing(value: unknown): boolean {\n  return value === null || value === undefined\n}\n\n/**\n * Validates flat metric records (Record<string, unknown> with a boolean\n * `pass` field) against their journey contract. Only records with\n * pass === true are checked — a failed record may legitimately have nulls.\n * resolveJourney maps a record to its JourneySpec (or null to skip).\n */\nexport function checkRecordIntegrity(\n  records: ReadonlyArray<Record<string, unknown>>,\n  resolveJourney: (record: Record<string, unknown>) => JourneySpec | null,\n): IntegrityResult {\n  const violations: IntegrityViolation[] = []\n  for (const [recordIndex, record] of records.entries()) {\n    if (record.pass !== true) continue\n    const journey = resolveJourney(record)\n    if (journey === null) continue\n    for (const field of journey.requiredFields) {\n      if (isMissing(record[field])) {\n        violations.push({\n          recordIndex,\n          journeyId: journey.id,\n          field,\n          reason: 'null-required-field',\n          detail: `required field '${field}' is ${record[field] === null ? 'null' : 'undefined'} on a passing '${journey.id}' record`,\n        })\n      }\n    }\n    for (const field of journey.phaseFields ?? []) {\n      if (isMissing(record[field])) {\n        violations.push({\n          recordIndex,\n          journeyId: journey.id,\n          field,\n          reason: 'null-required-field',\n          detail: `phase field '${field}' is ${record[field] === null ? 'null' : 'undefined'} on a passing '${journey.id}' record`,\n        })\n      }\n    }\n    for (const { field, min } of journey.minimums ?? []) {\n      const value = record[field]\n      if (isMissing(value)) continue // null-ness is the required/phase fields' contract\n      if (typeof value !== 'number' || Number.isNaN(value)) {\n        violations.push({\n          recordIndex,\n          journeyId: journey.id,\n          field,\n          reason: 'below-minimum',\n          detail: `field '${field}' has non-numeric value ${JSON.stringify(value)} on a passing '${journey.id}' record (minimum ${min})`,\n        })\n        continue\n      }\n      if (value < min) {\n        violations.push({\n          recordIndex,\n          journeyId: journey.id,\n          field,\n          reason: 'below-minimum',\n          detail: `field '${field}' is ${value}, below minimum ${min} on a passing '${journey.id}' record`,\n        })\n      }\n    }\n  }\n  return { succeeded: violations.length === 0, violations }\n}\n\n/** Throws an Error listing every violation when the result fails. */\nexport function assertRecordIntegrity(\n  records: ReadonlyArray<Record<string, unknown>>,\n  resolveJourney: (record: Record<string, unknown>) => JourneySpec | null,\n): void {\n  const result = checkRecordIntegrity(records, resolveJourney)\n  if (result.succeeded) return\n  const lines = result.violations.map(\n    (v) => `  [record ${v.recordIndex}] ${v.journeyId}.${v.field} (${v.reason}): ${v.detail}`,\n  )\n  throw new Error(\n    `Record integrity check failed with ${result.violations.length} violation(s):\\n${lines.join('\\n')}`,\n  )\n}\n","/**\n * Journey × axes matrix for infra performance benchmarks.\n *\n * A journey is one measurable user path (\"provision.cold\", \"chat.ttft\");\n * axes are free-form scenario dimensions (driver, region, image…). The\n * matrix expansion is pure bookkeeping — running the scenarios and\n * recording metrics is the caller's job. This module complements the\n * judge-panel `BenchmarkRunner` (src/benchmark.ts): that one scores\n * QUALITY via judges, this one structures LATENCY / RELIABILITY runs\n * over flat metric records.\n */\n\n/** One measurable user journey (e.g. \"provision.cold\", \"chat.ttft\"). */\nexport interface JourneySpec {\n  id: string\n  description: string\n  /** Needs a real LLM call — schedule nightly, not per-PR. */\n  requiresLLM: boolean\n  /**\n   * Fields that MUST be non-null on a passing record of this journey.\n   * A \"passing\" record missing one is an integrity violation, not a pass.\n   */\n  requiredFields: ReadonlyArray<string>\n  /** Numeric floors, e.g. {field: 'event_count', min: 1} for streaming. */\n  minimums?: ReadonlyArray<{ field: string; min: number }>\n  /** Per-phase breakdown fields expected non-null (subset of requiredFields semantics, reported separately). */\n  phaseFields?: ReadonlyArray<string>\n}\n\nexport interface ScenarioAxes {\n  /** e.g. driver: ['docker','firecracker'] — every key is a free-form dimension. */\n  [dimension: string]: ReadonlyArray<string>\n}\n\nexport interface PerfScenario {\n  /** `${journeyId}|${dim1}=${v1}|${dim2}=${v2}` (dims sorted). */\n  key: string\n  journey: JourneySpec\n  axes: Record<string, string>\n}\n\n/** Stable scenario key: journey id then `dim=value` pairs in sorted-dim order. */\nexport function scenarioKey(journeyId: string, axes: Record<string, string>): string {\n  const parts = Object.keys(axes)\n    .sort()\n    .map((dim) => `${dim}=${axes[dim]}`)\n  return [journeyId, ...parts].join('|')\n}\n\n/** Cartesian expansion; `filter` lets callers drop invalid combos (e.g. firecracker×resume). */\nexport function expandMatrix(\n  journeys: ReadonlyArray<JourneySpec>,\n  axes: ScenarioAxes,\n  filter?: (journeyId: string, combo: Record<string, string>) => boolean,\n): PerfScenario[] {\n  const dims = Object.keys(axes).sort()\n  let combos: Record<string, string>[] = [{}]\n  for (const dim of dims) {\n    const values = axes[dim] as ReadonlyArray<string>\n    const next: Record<string, string>[] = []\n    for (const combo of combos) {\n      for (const value of values) {\n        next.push({ ...combo, [dim]: value })\n      }\n    }\n    combos = next\n  }\n  const scenarios: PerfScenario[] = []\n  for (const journey of journeys) {\n    for (const combo of combos) {\n      if (filter && !filter(journey.id, combo)) continue\n      scenarios.push({ key: scenarioKey(journey.id, combo), journey, axes: combo })\n    }\n  }\n  return scenarios\n}\n","/**\n * Percentile ratchet over perf metric records.\n *\n * `summarizeRecords` folds flat records into per-scenario p50/p90 stats;\n * `gatePerf` compares a current summary against a committed baseline and\n * trips on regressions beyond tolerance. Percentiles use nearest-rank on\n * sorted values. Null / non-numeric metric values are excluded from the\n * stat (n reflects only real samples); a field with zero samples is\n * omitted entirely — no fake zeros.\n */\n\nexport interface PerfStat {\n  p50: number\n  p90: number\n  n: number\n}\n\nexport interface PerfBaseline {\n  version: 1\n  /** key → metric field → stat. */\n  scenarios: Record<string, Record<string, PerfStat>>\n}\n\nexport interface PerfRegression {\n  scenarioKey: string\n  field: string\n  baseline: PerfStat\n  current: PerfStat\n  /** percent over baseline p50 / p90, whichever tripped. */\n  overBy: { p50Pct: number; p90Pct: number }\n}\n\nexport interface PerfGateResult {\n  succeeded: boolean\n  regressions: PerfRegression[]\n  /** Negative overBy: strictly better than baseline on both percentiles. */\n  improvements: PerfRegression[]\n  /** In baseline but absent (or under-sampled, n < minSamples) in current. */\n  missingScenarios: string[]\n  /** In records but absent from baseline. */\n  newScenarios: string[]\n}\n\n/** Nearest-rank percentile over a non-empty ascending-sorted array (p in (0, 100]). */\nfunction nearestRank(sorted: ReadonlyArray<number>, p: number): number {\n  if (sorted.length === 0) throw new Error('nearestRank requires at least one sample')\n  const rank = Math.max(1, Math.ceil((p / 100) * sorted.length))\n  return sorted[rank - 1] as number\n}\n\nexport function summarizeRecords(\n  records: ReadonlyArray<Record<string, unknown>>,\n  keyOf: (record: Record<string, unknown>) => string | null,\n  metricFields: ReadonlyArray<string>,\n): PerfBaseline {\n  const samples = new Map<string, Map<string, number[]>>()\n  for (const record of records) {\n    const key = keyOf(record)\n    if (key === null) continue\n    let byField = samples.get(key)\n    if (!byField) {\n      byField = new Map()\n      samples.set(key, byField)\n    }\n    for (const field of metricFields) {\n      const value = record[field]\n      if (typeof value !== 'number' || Number.isNaN(value)) continue\n      let values = byField.get(field)\n      if (!values) {\n        values = []\n        byField.set(field, values)\n      }\n      values.push(value)\n    }\n  }\n  const scenarios: Record<string, Record<string, PerfStat>> = {}\n  for (const [key, byField] of samples) {\n    const stats: Record<string, PerfStat> = {}\n    for (const [field, values] of byField) {\n      if (values.length === 0) continue\n      const sorted = [...values].sort((a, b) => a - b)\n      stats[field] = {\n        p50: nearestRank(sorted, 50),\n        p90: nearestRank(sorted, 90),\n        n: sorted.length,\n      }\n    }\n    scenarios[key] = stats\n  }\n  return { version: 1, scenarios }\n}\n\n/** Percent over baseline; baseline 0 → 0% when equal, Infinity when current grew. */\nfunction pctOver(currentValue: number, baselineValue: number): number {\n  if (baselineValue === 0) {\n    return currentValue === 0 ? 0 : Number.POSITIVE_INFINITY\n  }\n  return ((currentValue - baselineValue) / baselineValue) * 100\n}\n\nexport function gatePerf(\n  current: PerfBaseline,\n  baseline: PerfBaseline,\n  options?: { tolerancePct?: number; minSamples?: number },\n): PerfGateResult {\n  const tolerancePct = options?.tolerancePct ?? 10\n  const minSamples = options?.minSamples ?? 3\n  const regressions: PerfRegression[] = []\n  const improvements: PerfRegression[] = []\n  const missing = new Set<string>()\n\n  for (const [scenarioKey, baselineStats] of Object.entries(baseline.scenarios)) {\n    const currentStats = current.scenarios[scenarioKey]\n    if (!currentStats) {\n      missing.add(scenarioKey)\n      continue\n    }\n    for (const [field, baselineStat] of Object.entries(baselineStats)) {\n      const currentStat = currentStats[field]\n      if (!currentStat || currentStat.n < minSamples) {\n        // Under-sampled current data cannot gate — surface it instead of\n        // pretending the scenario passed.\n        missing.add(scenarioKey)\n        continue\n      }\n      const overBy = {\n        p50Pct: pctOver(currentStat.p50, baselineStat.p50),\n        p90Pct: pctOver(currentStat.p90, baselineStat.p90),\n      }\n      const entry: PerfRegression = {\n        scenarioKey,\n        field,\n        baseline: baselineStat,\n        current: currentStat,\n        overBy,\n      }\n      if (overBy.p50Pct > tolerancePct || overBy.p90Pct > tolerancePct) {\n        regressions.push(entry)\n      } else if (overBy.p50Pct < 0 && overBy.p90Pct < 0) {\n        improvements.push(entry)\n      }\n    }\n  }\n\n  const newScenarios = Object.keys(current.scenarios).filter((key) => !(key in baseline.scenarios))\n\n  return {\n    succeeded: regressions.length === 0,\n    regressions,\n    improvements,\n    missingScenarios: [...missing],\n    newScenarios,\n  }\n}\n"],"mappings":"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","names":["scenarioKey"]}

package/dist/{chunk-ZZ2HOPME.js → chunk-TWS7AZEY.js}

@@ -1,6 +1,6 @@
 import {
   confidenceInterval
-} from "./chunk-IDVBLYCY.js";
+} from "./chunk-LMZQ2Z4U.js";
 import {
   AgentEvalError
 } from "./chunk-3BFEG2F6.js";
@@ -538,4 +538,4 @@ export {
   inMemoryCampaignStorage,
   runCampaign
 };
-//# sourceMappingURL=chunk-ZZ2HOPME.js.map
+//# sourceMappingURL=chunk-TWS7AZEY.js.map

package/dist/chunk-UHMJT4T7.js

@@ -0,0 +1,200 @@
+import {
+  OtlpFileTraceStore,
+  TraceFileMissingError,
+  buildTraceAnalystTools
+} from "./chunk-QAY5UIJO.js";
+
+// src/trace-analyst/prompts.ts
+var TRACE_ANALYST_ACTOR_DESCRIPTION = `You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the \`traces\` namespace.
+
+DISCOVERY \u2192 NARROW \u2192 DEEP-READ protocol \u2014 follow exactly:
+
+1. 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).
+
+2. 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.
+
+3. 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.
+
+4. Per-trace inspection:
+   - 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.
+   - 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\xD7 higher than discovery), or \`traces.searchSpan({ trace_id, span_id, regex_pattern })\` for one large span. Stays bounded regardless of trace size.
+   - Useful regex patterns: \`STATUS_CODE_ERROR\` (failures), tool names like \`grep\` or \`view_trace\`, error strings like \`MaxTurnsExceeded\`, model names, attribute keys.
+
+5. 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.
+
+5a. **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.
+
+6. 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.
+
+7. If searchTrace or searchSpan returns has_more=true, REFINE the regex to be more specific rather than blindly raising max_matches.
+
+8. 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.
+
+9. 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.
+
+10. 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:
+
+    const reviews = await llmQuery([
+      { query: 'Drill into trace abc123 \u2014 what tool calls preceded the failure?', context: { trace_id: 'abc123' } },
+      { query: 'Drill into trace def456 \u2014 same failure mode?', context: { trace_id: 'def456' } },
+    ]);
+
+OBSERVABILITY rules:
+- 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).
+- 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.
+- Reuse runtime variables across turns; don't recompute.
+- 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.
+
+CRITICAL \u2014 \`final()\` payload contract for evidence-grounded analysis tasks:
+- 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.
+- Example for per-item verdict tasks:
+  \`\`\`js
+  await final("Format the per-item verdict report from the evidence below.", {
+    findings: [
+      { id: 'sub-1-finding-1', claim: '...', verdict: 'TRUE-POSITIVE', evidence: 'lines 42-45 of contracts/X.sol show ...' },
+      ...all items
+    ],
+    systemic_summary: '3 sentences I wrote based on the evidence above'
+  });
+  \`\`\`
+- 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.
+- 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']\`).
+
+OUTPUT contract \u2014 your final answer must include:
+- A clear prose conclusion answering the user's question.
+- Trace ids and span ids cited as evidence for each claim.
+- Failure modes named in the user's domain language, with frequency and concrete examples.
+
+Do NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.`;
+var TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v5-2026-05-06";
+var 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.
+
+Cite trace ids and span ids for every claim. Do NOT invent ids.`;
+
+// src/trace-analyst/analyst.ts
+import { AxJSRuntime, agent } from "@ax-llm/ax";
+async function analyzeTraces(input, options) {
+  if (!input.question || typeof input.question !== "string") {
+    throw new TypeError("analyzeTraces: input.question must be a non-empty string");
+  }
+  const store = typeof options.source === "string" ? new OtlpFileTraceStore({ path: options.source }) : options.source;
+  if (store instanceof OtlpFileTraceStore) {
+    await store.ensureIndexed();
+  }
+  const tools = buildTraceAnalystTools({ store });
+  const turns = [];
+  let progressFs;
+  if (options.progressLogPath) {
+    const { createWriteStream } = await import("fs");
+    const { mkdir } = await import("fs/promises");
+    const { dirname } = await import("path");
+    await mkdir(dirname(options.progressLogPath), { recursive: true });
+    progressFs = createWriteStream(options.progressLogPath, { flags: "a" });
+  }
+  const actorTurnCallback = async (turn) => {
+    const snap = {
+      turn: turn.turn,
+      isError: turn.isError,
+      code: turn.code,
+      output: turn.output,
+      thought: turn.thought
+    };
+    turns.push(snap);
+    if (progressFs) {
+      try {
+        progressFs.write(`${JSON.stringify({ ...snap, ts: Date.now() })}
+`);
+      } catch {
+      }
+    }
+    if (options.onTurn) await options.onTurn(snap);
+  };
+  const maxDepth = options.maxDepth ?? 1;
+  const maxTurns = options.maxTurns ?? 12;
+  const maxParallelSubagents = options.maxParallelSubagents ?? 2;
+  const maxRuntimeChars = options.maxRuntimeChars ?? 6e3;
+  const analyst = agent(
+    // `reasoning!` is an internal (Ax `!`) scratchpad field: generated first to
+    // force reason-before-conclude, stripped from the returned output — so the
+    // consumed shape stays { answer, findings }. Brings the trace-analyst to the
+    // same prose-first CoT ordering the kind-factory gets from its `report` field.
+    "question:string -> reasoning!:string, answer:string, findings:string[]",
+    {
+      agentIdentity: {
+        name: "TraceAnalyst",
+        description: "Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes."
+      },
+      contextFields: ["question"],
+      runtime: new AxJSRuntime({
+        permissions: [],
+        blockDynamicImport: true,
+        allowedModules: [],
+        freezeIntrinsics: true,
+        blockShadowRealm: true,
+        // RLM stdout mode relies on runtime bindings persisting across turns.
+        preventGlobalThisExtensions: false
+      }),
+      mode: maxDepth > 0 ? "advanced" : "simple",
+      recursionOptions: maxDepth > 0 ? { maxDepth } : void 0,
+      maxTurns,
+      maxRuntimeChars,
+      maxBatchedLlmQueryConcurrency: maxParallelSubagents,
+      promptLevel: "detailed",
+      // Trace analysis depends on exact prior tool results and runtime variables.
+      contextPolicy: { preset: "full", budget: "balanced" },
+      functions: { local: tools },
+      actorOptions: {
+        description: options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION,
+        ...options.model ? { model: options.model } : {},
+        // Keep actor messages tool-call/content shaped across reasoning models.
+        showThoughts: false,
+        thinkingTokenBudget: "none"
+      },
+      responderOptions: {
+        ...options.model ? { model: options.model } : {},
+        description: options.subagentDescription ?? TRACE_ANALYST_SUBAGENT_DESCRIPTION,
+        showThoughts: false
+      },
+      actorTurnCallback,
+      bubbleErrors: [TraceFileMissingError]
+    }
+  );
+  let result;
+  try {
+    result = await analyst.forward(options.ai, { question: input.question });
+  } finally {
+    if (progressFs) {
+      await new Promise((resolve) => progressFs.end(() => resolve()));
+    }
+  }
+  return {
+    answer: typeof result.answer === "string" ? result.answer : String(result.answer ?? ""),
+    findings: Array.isArray(result.findings) ? result.findings.filter((s) => typeof s === "string") : [],
+    turns,
+    turnCount: turns.length,
+    usage: normalizeRoleArrays(analyst.getUsage()),
+    chatLog: normalizeRoleArrays(analyst.getChatLog()),
+    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION
+  };
+}
+function normalizeRoleArrays(value) {
+  const record = value && typeof value === "object" ? value : {};
+  return {
+    actor: normalizeRecordArray(record.actor),
+    responder: normalizeRecordArray(record.responder)
+  };
+}
+function normalizeRecordArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(
+    (item) => item && typeof item === "object" ? { ...item } : { value: item }
+  );
+}
+
+export {
+  TRACE_ANALYST_ACTOR_DESCRIPTION,
+  TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,
+  TRACE_ANALYST_SUBAGENT_DESCRIPTION,
+  analyzeTraces
+};
+//# sourceMappingURL=chunk-UHMJT4T7.js.map

package/dist/chunk-UHMJT4T7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-analyst/prompts.ts","../src/trace-analyst/analyst.ts"],"sourcesContent":["/** Ax RLM prompt for bounded trace discovery and evidence-backed analysis. */\n\nexport 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 → NARROW → DEEP-READ protocol — 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 — 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 — 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 — 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× 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** — 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 — 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 — 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 — what tool calls preceded the failure?', context: { trace_id: 'abc123' } },\n      { query: 'Drill into trace def456 — 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 — 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 — \\`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 — 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 — 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.`\n\nexport const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = 'trace-analyst-actor-v5-2026-05-06'\n\n/** Subagent prompt for focused trace-inspection subtasks. */\nexport const TRACE_ANALYST_SUBAGENT_DESCRIPTION = `You are a trace-analyst subagent. Your parent has delegated a focused trace-inspection question. Use the same DISCOVERY → NARROW → 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.`\n","import { type AxActorTurn, type AxAIService, type AxFunction, AxJSRuntime, agent } from '@ax-llm/ax'\nimport {\n  TRACE_ANALYST_ACTOR_DESCRIPTION,\n  TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,\n  TRACE_ANALYST_SUBAGENT_DESCRIPTION,\n} from './prompts'\nimport type { TraceAnalysisStore } from './store'\nimport { OtlpFileTraceStore, TraceFileMissingError } from './store-otlp'\nimport { buildTraceAnalystTools } from './tools'\n\nexport interface AnalyzeTracesInput {\n  /** The user-facing question. Domain framing belongs here, not in the\n   *  actor description. */\n  question: string\n}\n\nexport interface AnalyzeTracesResult {\n  /** The responder's prose answer. */\n  answer: string\n  /** Bulleted findings extracted from the responder's structured output. */\n  findings: string[]\n  /** Per-actor-turn snapshots captured via `actorTurnCallback`. */\n  turns: AnalyzeTracesTurnSnapshot[]\n  /** Total turns the actor took. */\n  turnCount: number\n  /** Token usage by role. */\n  usage: TraceAnalystUsage\n  /** Full system + assistant + tool message log by role. */\n  chatLog: TraceAnalystChatLog\n  /** Prompt version that produced this run. */\n  actorPromptVersion: string\n}\n\nexport interface TraceAnalystUsage {\n  actor: TraceAnalystUsageEntry[]\n  responder: TraceAnalystUsageEntry[]\n}\n\nexport interface TraceAnalystUsageEntry {\n  [key: string]: unknown\n}\n\nexport interface TraceAnalystChatLog {\n  actor: TraceAnalystChatMessage[]\n  responder: TraceAnalystChatMessage[]\n}\n\nexport interface TraceAnalystChatMessage {\n  [key: string]: unknown\n}\n\nexport interface AnalyzeTracesTurnSnapshot {\n  turn: number\n  isError: boolean\n  /** The JS code the actor produced for this turn. */\n  code: string\n  /** The formatted action-log entry the actor sees on the next turn. */\n  output: string\n  /** Provider thought (when `actorOptions.showThoughts` is true and the\n   *  provider returns it). */\n  thought?: string\n}\n\nexport interface AnalyzeTracesOptions {\n  /** Trace data source. Pass either an OTLP-JSONL path or a custom store. */\n  source: string | TraceAnalysisStore\n  /** Caller-provided AxAIService. */\n  ai: AxAIService\n  /** Model id forwarded to actor + responder. */\n  model?: string\n  /** Recursion depth. 0 = no sub-agent dispatch. Default 1. */\n  maxDepth?: number\n  /** Maximum actor turns. Default 12. */\n  maxTurns?: number\n  /** Maximum parallel sub-agent calls in batched llmQuery. Default 2. */\n  maxParallelSubagents?: number\n  /** Override the actor description. */\n  actorDescription?: string\n  /** Override the subagent description. */\n  subagentDescription?: string\n  /** Per-turn observability hook. */\n  onTurn?: (turn: AnalyzeTracesTurnSnapshot) => void | Promise<void>\n  /** Override max runtime characters per turn. Default 6000. */\n  maxRuntimeChars?: number\n  /** When set, every turn's snapshot is appended to this JSONL file\n   *  immediately. If the analyst crashes mid-loop (provider 503,\n   *  network error, validator reject) the partial reasoning is still\n   *  on disk. Replay the file with the responder afterward to recover\n   *  evidence. */\n  progressLogPath?: string\n}\n\n/**\n * Run the trace analyst.\n *\n * Throws:\n *   - `TraceFileMissingError` if `source` is a path and doesn't exist.\n *   - `AxAgentClarificationError` if the analyst asks for clarification.\n *   - Provider errors (auth, rate limits) propagate from the AI service.\n */\nexport async function analyzeTraces(\n  input: AnalyzeTracesInput,\n  options: AnalyzeTracesOptions,\n): Promise<AnalyzeTracesResult> {\n  if (!input.question || typeof input.question !== 'string') {\n    throw new TypeError('analyzeTraces: input.question must be a non-empty string')\n  }\n\n  const store: TraceAnalysisStore =\n    typeof options.source === 'string'\n      ? new OtlpFileTraceStore({ path: options.source })\n      : options.source\n\n  // Pre-warm file stores so missing inputs fail before the RLM starts.\n  if (store instanceof OtlpFileTraceStore) {\n    await store.ensureIndexed()\n  }\n\n  const tools: AxFunction[] = buildTraceAnalystTools({ store })\n  const turns: AnalyzeTracesTurnSnapshot[] = []\n\n  // Persist each turn as JSONL so interrupted analyst runs keep useful evidence.\n  let progressFs: import('node:fs').WriteStream | undefined\n  if (options.progressLogPath) {\n    const { createWriteStream } = await import('node:fs')\n    const { mkdir } = await import('node:fs/promises')\n    const { dirname } = await import('node:path')\n    await mkdir(dirname(options.progressLogPath), { recursive: true })\n    progressFs = createWriteStream(options.progressLogPath, { flags: 'a' })\n  }\n\n  const actorTurnCallback = async (turn: AxActorTurn): Promise<void> => {\n    const snap: AnalyzeTracesTurnSnapshot = {\n      turn: turn.turn,\n      isError: turn.isError,\n      code: turn.code,\n      output: turn.output,\n      thought: turn.thought,\n    }\n    turns.push(snap)\n    if (progressFs) {\n      try {\n        progressFs.write(`${JSON.stringify({ ...snap, ts: Date.now() })}\\n`)\n      } catch {\n        // Progress logging must never fail the analyst.\n      }\n    }\n    if (options.onTurn) await options.onTurn(snap)\n  }\n\n  const maxDepth = options.maxDepth ?? 1\n  const maxTurns = options.maxTurns ?? 12\n  const maxParallelSubagents = options.maxParallelSubagents ?? 2\n  const maxRuntimeChars = options.maxRuntimeChars ?? 6000\n\n  const analyst = agent<{ question: string }, { answer: string; findings: string[] }>(\n    // `reasoning!` is an internal (Ax `!`) scratchpad field: generated first to\n    // force reason-before-conclude, stripped from the returned output — so the\n    // consumed shape stays { answer, findings }. Brings the trace-analyst to the\n    // same prose-first CoT ordering the kind-factory gets from its `report` field.\n    'question:string -> reasoning!:string, answer:string, findings:string[]',\n    {\n      agentIdentity: {\n        name: 'TraceAnalyst',\n        description:\n          'Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes.',\n      },\n      contextFields: ['question'],\n      runtime: new AxJSRuntime({\n        permissions: [],\n        blockDynamicImport: true,\n        allowedModules: [],\n        freezeIntrinsics: true,\n        blockShadowRealm: true,\n        // RLM stdout mode relies on runtime bindings persisting across turns.\n        preventGlobalThisExtensions: false,\n      }),\n      mode: maxDepth > 0 ? 'advanced' : 'simple',\n      recursionOptions: maxDepth > 0 ? { maxDepth } : undefined,\n      maxTurns,\n      maxRuntimeChars,\n      maxBatchedLlmQueryConcurrency: maxParallelSubagents,\n      promptLevel: 'detailed',\n      // Trace analysis depends on exact prior tool results and runtime variables.\n      contextPolicy: { preset: 'full', budget: 'balanced' },\n      functions: { local: tools },\n      actorOptions: {\n        description: options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION,\n        ...(options.model ? { model: options.model } : {}),\n        // Keep actor messages tool-call/content shaped across reasoning models.\n        showThoughts: false,\n        thinkingTokenBudget: 'none',\n      },\n      responderOptions: {\n        ...(options.model ? { model: options.model } : {}),\n        description: options.subagentDescription ?? TRACE_ANALYST_SUBAGENT_DESCRIPTION,\n        showThoughts: false,\n      },\n      actorTurnCallback,\n      bubbleErrors: [TraceFileMissingError],\n    },\n  )\n\n  let result: { answer: unknown; findings: unknown }\n  try {\n    result = await analyst.forward(options.ai, { question: input.question })\n  } finally {\n    if (progressFs) {\n      await new Promise<void>((resolve) => progressFs!.end(() => resolve()))\n    }\n  }\n\n  return {\n    answer: typeof result.answer === 'string' ? result.answer : String(result.answer ?? ''),\n    findings: Array.isArray(result.findings)\n      ? result.findings.filter((s): s is string => typeof s === 'string')\n      : [],\n    turns,\n    turnCount: turns.length,\n    usage: normalizeRoleArrays(analyst.getUsage()),\n    chatLog: normalizeRoleArrays(analyst.getChatLog()),\n    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,\n  }\n}\n\nfunction normalizeRoleArrays(value: unknown): {\n  actor: Record<string, unknown>[]\n  responder: Record<string, unknown>[]\n} {\n  const record = value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n  return {\n    actor: normalizeRecordArray(record.actor),\n    responder: normalizeRecordArray(record.responder),\n  }\n}\n\nfunction normalizeRecordArray(value: unknown): Record<string, unknown>[] {\n  if (!Array.isArray(value)) return []\n  return value.map((item) =>\n    item && typeof item === 'object' ? { ...(item as Record<string, unknown>) } : { value: item },\n  )\n}\n"],"mappings":"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","names":[]}