@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/analyst/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/analyst/adapters.ts","../../src/analyst/steer-firewall.ts"],"sourcesContent":["/**\n * Adapter factories — lift each existing agent-eval primitive into the\n * Analyst contract without re-implementing it.\n *\n * Five primitives, five factories. Each one:\n *   - Builds an Analyst with a stable id (caller chooses; defaults\n *     given), a sensible default `inputKind`, a version derived from\n *     the wrapped primitive's version + an adapter revision, and an\n *     `analyze()` that calls the primitive and lifts its output to\n *     AnalystFinding[] using `makeFinding()`.\n *   - Maps severities: the existing `Severity` ('critical' | 'major' |\n *     'minor' | 'info') projects onto AnalystSeverity ('critical' |\n *     'high' | 'medium' | 'low' | 'info'); 'major' → 'high', 'minor' →\n *     'medium'. Domain analysts that want finer-grained mapping override.\n *\n * Adapters never own state. Calling the same factory twice with the\n * same primitive instance is safe.\n */\n\nimport { CostLedger } from '../cost-ledger'\nimport type {\n  Finding as LayerFinding,\n  Severity as LayerSeverity,\n  MultiLayerVerifier,\n  VerifyOptions,\n} from '../multi-layer-verifier'\nimport { RunCritic, type RunTrace } from '../run-critic'\nimport {\n  runSemanticConceptJudge,\n  SEMANTIC_CONCEPT_JUDGE_VERSION,\n  type SemanticConceptJudgeInput,\n  type SemanticConceptJudgeOptions,\n  type SemanticConceptJudgeResult,\n} from '../semantic-concept-judge'\nimport type { JudgeFn, JudgeInput, JudgeScore } from '../types'\nimport type { ChatClient } from './chat-client'\nimport type { Analyst, AnalystFinding, AnalystSeverity } from './types'\nimport { makeFinding } from './types'\nimport { settleUsageReceiptFromCostLedger, validateUsageSettlementTimeout } from './usage-receipt'\n\nconst ADAPTER_REV = '1'\n\n// ── Severity bridges ───────────────────────────────────────────────\n\nexport function liftSeverity(s: LayerSeverity): AnalystSeverity {\n  switch (s) {\n    case 'critical':\n      return 'critical'\n    case 'major':\n      return 'high'\n    case 'minor':\n      return 'medium'\n    case 'info':\n      return 'info'\n  }\n}\n\n// ── 1. MultiLayerVerifier → Analyst ─────────────────────────────────\n\nexport interface VerifierAdapterOpts<Env> {\n  id?: string\n  area?: string\n  verifier: MultiLayerVerifier<Env>\n  /**\n   * The verifier expects an `env` per run. Adapters take it from\n   * `AnalystRunInputs.custom[<id>]` via the registry's 'custom' routing.\n   */\n  options?: Omit<VerifyOptions<Env>, 'env'>\n}\n\nexport function createVerifierAdapter<Env>(opts: VerifierAdapterOpts<Env>): Analyst<Env> {\n  const id = opts.id ?? 'multi-layer-verifier'\n  const area = opts.area ?? 'verification'\n  return {\n    id,\n    description:\n      \"Runs a MultiLayerVerifier and lifts each layer's findings into the analyst envelope.\",\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `verifier-${ADAPTER_REV}`,\n    async analyze(env, ctx) {\n      const report = await opts.verifier.run({ env, ...opts.options })\n      const out: AnalystFinding[] = []\n      for (const layer of report.layers) {\n        for (const finding of layer.findings) {\n          out.push(liftLayerFinding(id, area, layer.layer, finding))\n        }\n        // Layer-level signal: a failed/error layer is itself a finding\n        // even if it didn't emit per-finding rows.\n        if (layer.status === 'fail' || layer.status === 'error' || layer.status === 'timeout') {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: layer.layer,\n              claim: `layer \"${layer.layer}\" ${layer.status}: ${layer.reason ?? 'no reason given'}`,\n              severity:\n                layer.status === 'error' ? 'high' : layer.status === 'timeout' ? 'medium' : 'high',\n              confidence: 1,\n              evidence_refs: [],\n              metadata: {\n                layer_status: layer.status,\n                duration_ms: layer.durationMs,\n                score: layer.score,\n                diagnostics: layer.diagnostics,\n              },\n            }),\n          )\n        }\n      }\n      ctx.log?.('verifier complete', {\n        layers: report.layers.length,\n        blended: report.blendedScore,\n        all_pass: report.allPass,\n      })\n      return out\n    },\n  }\n}\n\nfunction liftLayerFinding(\n  analyst_id: string,\n  area: string,\n  layer: string,\n  f: LayerFinding,\n): AnalystFinding {\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: f.layer ?? layer,\n    claim: f.message,\n    severity: liftSeverity(f.severity),\n    confidence: 0.85,\n    evidence_refs: f.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }]\n      : [],\n    metadata: f.detail,\n  })\n}\n\n// ── 2. RunCritic → Analyst ──────────────────────────────────────────\n\nexport interface RunCriticAdapterOpts {\n  id?: string\n  area?: string\n  critic?: RunCritic\n  /** Optional threshold below which a dimension is reported as a finding. Default 0.5. */\n  threshold?: number\n}\n\nexport function createRunCriticAdapter(opts: RunCriticAdapterOpts = {}): Analyst<RunTrace> {\n  const id = opts.id ?? 'run-critic'\n  const area = opts.area ?? 'run-quality'\n  const critic = opts.critic ?? new RunCritic()\n  const threshold = opts.threshold ?? 0.5\n  return {\n    id,\n    description:\n      'Scores a single run across success / grounding / drift / tool-quality and surfaces below-threshold dimensions.',\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `run-critic-${ADAPTER_REV}`,\n    async analyze(trace) {\n      const score = critic.scoreTrace(trace)\n      const out: AnalystFinding[] = []\n      const dims: Array<[keyof typeof score, AnalystSeverity, string]> = [\n        ['success', 'critical', 'run did not complete successfully'],\n        ['goalProgress', 'high', 'goal progress is low'],\n        ['repoGroundedness', 'high', 'output is poorly grounded in the repository'],\n        ['toolUseQuality', 'medium', 'tool use quality is low'],\n        ['patchQuality', 'medium', 'no real patch/edit evidence'],\n        ['testReality', 'high', 'no real test/build evidence'],\n        ['finalGate', 'critical', 'final gate is blocking'],\n      ]\n      for (const [dim, sev, msg] of dims) {\n        const value = score[dim] as number\n        if (typeof value === 'number' && value < threshold) {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: dim,\n              claim: msg,\n              rationale: `${dim}=${value.toFixed(2)} below threshold ${threshold}`,\n              severity: sev,\n              confidence: 1,\n              evidence_refs: [],\n              metadata: { dimension: dim, value, threshold, run_id: trace.run.runId },\n            }),\n          )\n        }\n      }\n      // Drift penalty is high → surface as a finding (inverse threshold).\n      if (score.driftPenalty > 1 - threshold) {\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: 'drift',\n            claim: 'agent output drifted from repository signal',\n            rationale: `driftPenalty=${score.driftPenalty.toFixed(2)}`,\n            severity: 'medium',\n            confidence: 0.9,\n            evidence_refs: [],\n            metadata: { drift_penalty: score.driftPenalty, notes: score.notes },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n\n// ── 3. JudgeFn → Analyst ────────────────────────────────────────────\n\nexport interface JudgeAdapterOpts {\n  id?: string\n  area?: string\n  judge: JudgeFn\n  /** Chat client passed to the JudgeFn. */\n  chat: ChatClient\n  /** Optional cost classification — most judges call an LLM. */\n  cost?: Analyst['cost']\n  /** Optional threshold below which a JudgeScore becomes a finding. Default 6 (on 0-10 scale). */\n  threshold?: number\n}\n\nexport function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput> {\n  const id = opts.id ?? 'judge'\n  const area = opts.area ?? 'judge'\n  const threshold = opts.threshold ?? 6\n  return {\n    id,\n    description:\n      'Wraps an agent-eval JudgeFn into an analyst; below-threshold dimensions surface as findings.',\n    inputKind: 'judge-input',\n    cost: opts.cost ?? { kind: 'llm' },\n    version: `judge-${ADAPTER_REV}`,\n    async analyze(input) {\n      const scores = await opts.judge(opts.chat, input)\n      return scores\n        .filter((s) => normalize10(s.score) < threshold)\n        .map((s) => liftJudgeScore(id, area, s))\n    },\n  }\n}\n\nfunction normalize10(s: number): number {\n  // JudgeScore convention is 0-10 but some judges emit 0-1. Coerce to 0-10.\n  return s <= 1 ? s * 10 : s\n}\n\nfunction liftJudgeScore(analyst_id: string, area: string, s: JudgeScore): AnalystFinding {\n  const score10 = normalize10(s.score)\n  const severity: AnalystSeverity =\n    score10 < 3 ? 'critical' : score10 < 5 ? 'high' : score10 < 7 ? 'medium' : 'low'\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: s.dimension,\n    claim: `${s.judgeName}/${s.dimension} scored ${score10.toFixed(1)}/10`,\n    rationale: s.reasoning,\n    severity,\n    confidence: 0.8,\n    evidence_refs: s.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: s.evidence }]\n      : [],\n    // Provenance: this finding IS a judge verdict (an acceptance score), not an\n    // observation of behavior. The steer firewall (assertNoJudgeVerdict) rejects\n    // it from steering — even when it cites an artifact above — because letting a\n    // verdict steer the next attempt is the held-out judge leaking into the loop.\n    derived_from_judge: true,\n    metadata: { judge_name: s.judgeName, dimension: s.dimension, score_10: score10 },\n  })\n}\n\n// ── 4. SemanticConceptJudge → Analyst ──────────────────────────────\n\nexport interface SemanticConceptJudgeAdapterOpts {\n  id?: string\n  area?: string\n  /** Registry context owns cancellation and the per-analyst cost ledger. */\n  options?: Omit<SemanticConceptJudgeOptions, 'costLedger' | 'signal'>\n  /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */\n  settlementTimeoutMs?: number\n}\n\nexport function createSemanticConceptJudgeAdapter(\n  opts: SemanticConceptJudgeAdapterOpts = {},\n): Analyst<SemanticConceptJudgeInput> {\n  const id = opts.id ?? 'semantic-concept-judge'\n  const area = opts.area ?? 'concept-coverage'\n  const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs)\n  return {\n    id,\n    description:\n      'Runs the semantic-concept judge and surfaces missing / weak concepts as findings.',\n    inputKind: 'custom',\n    cost: {\n      kind: 'llm',\n      models: opts.options?.model ? [opts.options.model] : undefined,\n      settlement_timeout_ms: settlementTimeoutMs,\n    },\n    version: `${SEMANTIC_CONCEPT_JUDGE_VERSION}-adapter-${ADAPTER_REV}`,\n    async analyze(input, ctx) {\n      const costLedger = new CostLedger(ctx.budgetUsd)\n      let result: SemanticConceptJudgeResult\n      try {\n        result = await runSemanticConceptJudge(input, {\n          ...opts.options,\n          costLedger,\n          signal: ctx.signal,\n        })\n      } finally {\n        const usage = await settleUsageReceiptFromCostLedger(costLedger, {\n          channel: 'judge',\n          timeoutMs: settlementTimeoutMs,\n        })\n        if (!usage.settled) {\n          ctx.log?.('semantic-concept judge provider settlement timed out', {\n            pending_calls: usage.pendingCalls,\n            timeout_ms: settlementTimeoutMs,\n          })\n        }\n        ctx.recordUsage?.(usage.receipt)\n      }\n      if (!result.available) {\n        return [\n          makeFinding({\n            analyst_id: id,\n            area,\n            claim: 'semantic-concept judge unavailable',\n            rationale: result.error,\n            severity: 'info',\n            confidence: 1,\n            evidence_refs: [],\n            metadata: { reason: result.error },\n          }),\n        ]\n      }\n      const out: AnalystFinding[] = []\n      for (const f of result.findings) {\n        // Only surface gaps: missing concepts or low scores. Concepts at\n        // 7+/10 with present=true are not findings — they're successes.\n        if (f.present && f.score >= 7) continue\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: f.concept,\n            claim: f.present\n              ? `concept \"${f.concept}\" is weak (${f.score}/10)`\n              : `concept \"${f.concept}\" is missing`,\n            rationale: f.evidence,\n            severity: liftSeverity(f.severity),\n            confidence: 0.85,\n            evidence_refs: [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }],\n            metadata: {\n              concept: f.concept,\n              present: f.present,\n              score_10: f.score,\n            },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n","// The realness-oracle firewall (docs/learning-flywheel.md, \"The steer is f(trace)\").\n//\n// A realness/authenticity signal has TWO legitimate roles that must stay\n// separated by a firewall:\n//   (a) anchor judge J — write-only: scores the chosen output, gates promotion,\n//       NEVER seen by the worker/optimizer mid-run (else the loop games it).\n//   (b) steer f(trace) — an analyst observes the agent's OWN behavior in the\n//       trace (\"imported a stub\", \"used a non-crypto PRNG where encryption was\n//       required\") and steers the next attempt. Legitimate, because it is derived\n//       from OBSERVABLE BEHAVIOR, not from J's held-out verdict.\n//\n// The correct discriminator is PROVENANCE, not evidence presence. A judge verdict\n// lifted into a finding (createJudgeAdapter → liftJudgeScore) is a verdict even\n// when it cites an artifact; an evidence-less trace-analyst bullet is an\n// observation even though it cites nothing. So the firewall keys on\n// `AnalystFinding.derived_from_judge` (set at the judge lift site), NOT on whether\n// evidence_refs is populated. The instant a verdict steers the next attempt it is\n// a back-channel for J and the loop Goodharts realness exactly as it would\n// Goodhart pass-rate.\n\nimport type { AnalystFinding, EvidenceRef } from './types'\n\n/** Evidence grounded in the agent's OWN execution: OTLP trace elements\n *  (`span`/`event`) or the artifact it produced (`artifact`). */\nconst OBSERVABLE_KINDS: ReadonlySet<EvidenceRef['kind']> = new Set<EvidenceRef['kind']>([\n  'span',\n  'event',\n  'artifact',\n])\n\n/** DESCRIPTIVE predicate: does the finding cite at least one observable\n *  (span/event/artifact) evidence ref. Useful for ranking evidence quality or\n *  rendering — it is NOT the steer gate. Evidence presence is the WRONG\n *  discriminator for steering: a legitimate trace-analyst observation may cite\n *  nothing (it would be wrongly rejected), and a judge verdict may cite an\n *  artifact (it would be wrongly admitted). Use `assertNoJudgeVerdict` to gate\n *  steering; use this only where \"is this grounded in observable evidence\" is the\n *  literal question. */\nexport function isTraceObservable(finding: AnalystFinding): boolean {\n  return finding.evidence_refs.some((ref) => OBSERVABLE_KINDS.has(ref.kind))\n}\n\n/** True iff the finding is a JUDGE VERDICT (an acceptance score lifted into a\n *  finding), identified by provenance set at the lift site — independent of\n *  whatever evidence it cites. */\nexport function isJudgeVerdict(finding: AnalystFinding): boolean {\n  return finding.derived_from_judge === true\n}\n\n/**\n * THE steer firewall. Fail-loud guard for any path that admits analyst findings\n * as STEERING input (the `f(trace)` role): rejects — naming the offenders — any\n * finding whose provenance is a judge verdict, rather than let `J` leak into the\n * loop. Returns the findings unchanged for chaining.\n *\n * Call this at the chokepoint where a detector that ALSO scores/gates has its\n * findings turned into a steer (the judge-and-steer dual-role case). It keys on\n * provenance, so it correctly admits evidence-less trace-analyst observations and\n * correctly rejects an artifact-citing judge verdict — the cases an evidence\n * check gets backwards.\n *\n * It is necessary, not sufficient: it stops PROVENANCE-tagged verdicts. A judge\n * whose output is laundered through a hand-built finding with no provenance flag\n * is out of its reach — provenance must be honestly set at every judge→finding\n * lift (today: createJudgeAdapter). That is why the integrity rule lives at the\n * lift site, and why ProposeContext.judgeScores?: never is the complementary\n * compile-time tripwire on the obvious direct channel.\n */\nexport function assertNoJudgeVerdict(\n  findings: ReadonlyArray<AnalystFinding>,\n  context = 'steer',\n): ReadonlyArray<AnalystFinding> {\n  const leaks = findings.filter(isJudgeVerdict)\n  if (leaks.length > 0) {\n    throw new Error(\n      `${context}: a judge verdict cannot be admitted as steering input — that is the ` +\n        `held-out judge leaking into the loop. Offending judge-derived findings: [${leaks\n          .map((f) => f.finding_id)\n          .join(', ')}]. Steering consumes observations of behavior, never acceptance verdicts.`,\n    )\n  }\n  return findings\n}\n"],"mappings":"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","names":[]}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/analyst/adapters.ts","../../src/analyst/steer-firewall.ts"],"sourcesContent":["/**\n * Adapter factories — lift each existing agent-eval primitive into the\n * Analyst contract without re-implementing it.\n *\n * Five primitives, five factories. Each one:\n *   - Builds an Analyst with a stable id (caller chooses; defaults\n *     given), a sensible default `inputKind`, a version derived from\n *     the wrapped primitive's version + an adapter revision, and an\n *     `analyze()` that calls the primitive and lifts its output to\n *     AnalystFinding[] using `makeFinding()`.\n *   - Maps severities: the existing `Severity` ('critical' | 'major' |\n *     'minor' | 'info') projects onto AnalystSeverity ('critical' |\n *     'high' | 'medium' | 'low' | 'info'); 'major' → 'high', 'minor' →\n *     'medium'. Domain analysts that want finer-grained mapping override.\n *\n * Adapters never own state. Calling the same factory twice with the\n * same primitive instance is safe.\n */\n\nimport { CostLedger } from '../cost-ledger'\nimport type {\n  Finding as LayerFinding,\n  Severity as LayerSeverity,\n  MultiLayerVerifier,\n  VerifyOptions,\n} from '../multi-layer-verifier'\nimport { RunCritic, type RunTrace } from '../run-critic'\nimport {\n  runSemanticConceptJudge,\n  SEMANTIC_CONCEPT_JUDGE_VERSION,\n  type SemanticConceptJudgeInput,\n  type SemanticConceptJudgeOptions,\n  type SemanticConceptJudgeResult,\n} from '../semantic-concept-judge'\nimport type { JudgeFn, JudgeInput, JudgeScore } from '../types'\nimport type { ChatClient } from './chat-client'\nimport type { Analyst, AnalystFinding, AnalystSeverity } from './types'\nimport { makeFinding } from './types'\nimport { settleUsageReceiptFromCostLedger, validateUsageSettlementTimeout } from './usage-receipt'\n\nconst ADAPTER_REV = '1'\n\n// ── Severity bridges ───────────────────────────────────────────────\n\nexport function liftSeverity(s: LayerSeverity): AnalystSeverity {\n  switch (s) {\n    case 'critical':\n      return 'critical'\n    case 'major':\n      return 'high'\n    case 'minor':\n      return 'medium'\n    case 'info':\n      return 'info'\n  }\n}\n\n// ── 1. MultiLayerVerifier → Analyst ─────────────────────────────────\n\nexport interface VerifierAdapterOpts<Env> {\n  id?: string\n  area?: string\n  verifier: MultiLayerVerifier<Env>\n  /**\n   * The verifier expects an `env` per run. Adapters take it from\n   * `AnalystRunInputs.custom[<id>]` via the registry's 'custom' routing.\n   */\n  options?: Omit<VerifyOptions<Env>, 'env'>\n}\n\nexport function createVerifierAdapter<Env>(opts: VerifierAdapterOpts<Env>): Analyst<Env> {\n  const id = opts.id ?? 'multi-layer-verifier'\n  const area = opts.area ?? 'verification'\n  return {\n    id,\n    description:\n      \"Runs a MultiLayerVerifier and lifts each layer's findings into the analyst envelope.\",\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `verifier-${ADAPTER_REV}`,\n    async analyze(env, ctx) {\n      const report = await opts.verifier.run({ env, ...opts.options })\n      const out: AnalystFinding[] = []\n      for (const layer of report.layers) {\n        for (const finding of layer.findings) {\n          out.push(liftLayerFinding(id, area, layer.layer, finding))\n        }\n        // Layer-level signal: a failed/error layer is itself a finding\n        // even if it didn't emit per-finding rows.\n        if (layer.status === 'fail' || layer.status === 'error' || layer.status === 'timeout') {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: layer.layer,\n              claim: `layer \"${layer.layer}\" ${layer.status}: ${layer.reason ?? 'no reason given'}`,\n              severity:\n                layer.status === 'error' ? 'high' : layer.status === 'timeout' ? 'medium' : 'high',\n              confidence: 1,\n              evidence_refs: [],\n              metadata: {\n                layer_status: layer.status,\n                duration_ms: layer.durationMs,\n                score: layer.score,\n                diagnostics: layer.diagnostics,\n              },\n            }),\n          )\n        }\n      }\n      ctx.log?.('verifier complete', {\n        layers: report.layers.length,\n        blended: report.blendedScore,\n        all_pass: report.allPass,\n      })\n      return out\n    },\n  }\n}\n\nfunction liftLayerFinding(\n  analyst_id: string,\n  area: string,\n  layer: string,\n  f: LayerFinding,\n): AnalystFinding {\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: f.layer ?? layer,\n    claim: f.message,\n    severity: liftSeverity(f.severity),\n    confidence: 0.85,\n    evidence_refs: f.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }]\n      : [],\n    metadata: f.detail,\n  })\n}\n\n// ── 2. RunCritic → Analyst ──────────────────────────────────────────\n\nexport interface RunCriticAdapterOpts {\n  id?: string\n  area?: string\n  critic?: RunCritic\n  /** Optional threshold below which a dimension is reported as a finding. Default 0.5. */\n  threshold?: number\n}\n\nexport function createRunCriticAdapter(opts: RunCriticAdapterOpts = {}): Analyst<RunTrace> {\n  const id = opts.id ?? 'run-critic'\n  const area = opts.area ?? 'run-quality'\n  const critic = opts.critic ?? new RunCritic()\n  const threshold = opts.threshold ?? 0.5\n  return {\n    id,\n    description:\n      'Scores a single run across success / grounding / drift / tool-quality and surfaces below-threshold dimensions.',\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `run-critic-${ADAPTER_REV}`,\n    async analyze(trace) {\n      const score = critic.scoreTrace(trace)\n      const out: AnalystFinding[] = []\n      const dims: Array<[keyof typeof score, AnalystSeverity, string]> = [\n        ['success', 'critical', 'run did not complete successfully'],\n        ['goalProgress', 'high', 'goal progress is low'],\n        ['repoGroundedness', 'high', 'output is poorly grounded in the repository'],\n        ['toolUseQuality', 'medium', 'tool use quality is low'],\n        ['patchQuality', 'medium', 'no real patch/edit evidence'],\n        ['testReality', 'high', 'no real test/build evidence'],\n        ['finalGate', 'critical', 'final gate is blocking'],\n      ]\n      for (const [dim, sev, msg] of dims) {\n        const value = score[dim] as number\n        if (typeof value === 'number' && value < threshold) {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: dim,\n              claim: msg,\n              rationale: `${dim}=${value.toFixed(2)} below threshold ${threshold}`,\n              severity: sev,\n              confidence: 1,\n              evidence_refs: [],\n              metadata: { dimension: dim, value, threshold, run_id: trace.run.runId },\n            }),\n          )\n        }\n      }\n      // Drift penalty is high → surface as a finding (inverse threshold).\n      if (score.driftPenalty > 1 - threshold) {\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: 'drift',\n            claim: 'agent output drifted from repository signal',\n            rationale: `driftPenalty=${score.driftPenalty.toFixed(2)}`,\n            severity: 'medium',\n            confidence: 0.9,\n            evidence_refs: [],\n            metadata: { drift_penalty: score.driftPenalty, notes: score.notes },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n\n// ── 3. JudgeFn → Analyst ────────────────────────────────────────────\n\nexport interface JudgeAdapterOpts {\n  id?: string\n  area?: string\n  judge: JudgeFn\n  /** Chat client passed to the JudgeFn. */\n  chat: ChatClient\n  /** Optional cost classification — most judges call an LLM. */\n  cost?: Analyst['cost']\n  /** Optional threshold below which a JudgeScore becomes a finding. Default 6 (on 0-10 scale). */\n  threshold?: number\n}\n\nexport function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput> {\n  const id = opts.id ?? 'judge'\n  const area = opts.area ?? 'judge'\n  const threshold = opts.threshold ?? 6\n  return {\n    id,\n    description:\n      'Wraps an agent-eval JudgeFn into an analyst; below-threshold dimensions surface as findings.',\n    inputKind: 'judge-input',\n    cost: opts.cost ?? { kind: 'llm' },\n    version: `judge-${ADAPTER_REV}`,\n    async analyze(input) {\n      const scores = await opts.judge(opts.chat, input)\n      return scores\n        .filter((s) => normalize10(s.score) < threshold)\n        .map((s) => liftJudgeScore(id, area, s))\n    },\n  }\n}\n\nfunction normalize10(s: number): number {\n  // JudgeScore convention is 0-10 but some judges emit 0-1. Coerce to 0-10.\n  return s <= 1 ? s * 10 : s\n}\n\nfunction liftJudgeScore(analyst_id: string, area: string, s: JudgeScore): AnalystFinding {\n  const score10 = normalize10(s.score)\n  const severity: AnalystSeverity =\n    score10 < 3 ? 'critical' : score10 < 5 ? 'high' : score10 < 7 ? 'medium' : 'low'\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: s.dimension,\n    claim: `${s.judgeName}/${s.dimension} scored ${score10.toFixed(1)}/10`,\n    rationale: s.reasoning,\n    severity,\n    confidence: 0.8,\n    evidence_refs: s.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: s.evidence }]\n      : [],\n    // Provenance: this finding IS a judge verdict (an acceptance score), not an\n    // observation of behavior. The steer firewall (assertNoJudgeVerdict) rejects\n    // it from steering — even when it cites an artifact above — because letting a\n    // verdict steer the next attempt is the held-out judge leaking into the loop.\n    derived_from_judge: true,\n    metadata: { judge_name: s.judgeName, dimension: s.dimension, score_10: score10 },\n  })\n}\n\n// ── 4. SemanticConceptJudge → Analyst ──────────────────────────────\n\nexport interface SemanticConceptJudgeAdapterOpts {\n  id?: string\n  area?: string\n  /** Registry context owns cancellation and the per-analyst cost ledger. */\n  options?: Omit<SemanticConceptJudgeOptions, 'costLedger' | 'signal'>\n  /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */\n  settlementTimeoutMs?: number\n}\n\nexport function createSemanticConceptJudgeAdapter(\n  opts: SemanticConceptJudgeAdapterOpts = {},\n): Analyst<SemanticConceptJudgeInput> {\n  const id = opts.id ?? 'semantic-concept-judge'\n  const area = opts.area ?? 'concept-coverage'\n  const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs)\n  return {\n    id,\n    description:\n      'Runs the semantic-concept judge and surfaces missing / weak concepts as findings.',\n    inputKind: 'custom',\n    cost: {\n      kind: 'llm',\n      models: opts.options?.model ? [opts.options.model] : undefined,\n      settlement_timeout_ms: settlementTimeoutMs,\n    },\n    version: `${SEMANTIC_CONCEPT_JUDGE_VERSION}-adapter-${ADAPTER_REV}`,\n    async analyze(input, ctx) {\n      const costLedger = new CostLedger(ctx.budgetUsd)\n      let result: SemanticConceptJudgeResult\n      try {\n        result = await runSemanticConceptJudge(input, {\n          ...opts.options,\n          costLedger,\n          signal: ctx.signal,\n        })\n      } finally {\n        const usage = await settleUsageReceiptFromCostLedger(costLedger, {\n          channel: 'judge',\n          timeoutMs: settlementTimeoutMs,\n        })\n        if (!usage.settled) {\n          ctx.log?.('semantic-concept judge provider settlement timed out', {\n            pending_calls: usage.pendingCalls,\n            timeout_ms: settlementTimeoutMs,\n          })\n        }\n        ctx.recordUsage?.(usage.receipt)\n      }\n      if (!result.available) {\n        return [\n          makeFinding({\n            analyst_id: id,\n            area,\n            claim: 'semantic-concept judge unavailable',\n            rationale: result.error,\n            severity: 'info',\n            confidence: 1,\n            evidence_refs: [],\n            metadata: { reason: result.error },\n          }),\n        ]\n      }\n      const out: AnalystFinding[] = []\n      for (const f of result.findings) {\n        // Only surface gaps: missing concepts or low scores. Concepts at\n        // 7+/10 with present=true are not findings — they're successes.\n        if (f.present && f.score >= 7) continue\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: f.concept,\n            claim: f.present\n              ? `concept \"${f.concept}\" is weak (${f.score}/10)`\n              : `concept \"${f.concept}\" is missing`,\n            rationale: f.evidence,\n            severity: liftSeverity(f.severity),\n            confidence: 0.85,\n            evidence_refs: [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }],\n            metadata: {\n              concept: f.concept,\n              present: f.present,\n              score_10: f.score,\n            },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n","// The realness-oracle firewall (docs/learning-flywheel.md, \"The steer is f(trace)\").\n//\n// A realness/authenticity signal has TWO legitimate roles that must stay\n// separated by a firewall:\n//   (a) anchor judge J — write-only: scores the chosen output, gates promotion,\n//       NEVER seen by the worker/optimizer mid-run (else the loop games it).\n//   (b) steer f(trace) — an analyst observes the agent's OWN behavior in the\n//       trace (\"imported a stub\", \"used a non-crypto PRNG where encryption was\n//       required\") and steers the next attempt. Legitimate, because it is derived\n//       from OBSERVABLE BEHAVIOR, not from J's held-out verdict.\n//\n// The correct discriminator is PROVENANCE, not evidence presence. A judge verdict\n// lifted into a finding (createJudgeAdapter → liftJudgeScore) is a verdict even\n// when it cites an artifact; an evidence-less trace-analyst bullet is an\n// observation even though it cites nothing. So the firewall keys on\n// `AnalystFinding.derived_from_judge` (set at the judge lift site), NOT on whether\n// evidence_refs is populated. The instant a verdict steers the next attempt it is\n// a back-channel for J and the loop Goodharts realness exactly as it would\n// Goodhart pass-rate.\n\nimport type { AnalystFinding, EvidenceRef } from './types'\n\n/** Evidence grounded in the agent's OWN execution: OTLP trace elements\n *  (`span`/`event`) or the artifact it produced (`artifact`). */\nconst OBSERVABLE_KINDS: ReadonlySet<EvidenceRef['kind']> = new Set<EvidenceRef['kind']>([\n  'span',\n  'event',\n  'artifact',\n])\n\n/** DESCRIPTIVE predicate: does the finding cite at least one observable\n *  (span/event/artifact) evidence ref. Useful for ranking evidence quality or\n *  rendering — it is NOT the steer gate. Evidence presence is the WRONG\n *  discriminator for steering: a legitimate trace-analyst observation may cite\n *  nothing (it would be wrongly rejected), and a judge verdict may cite an\n *  artifact (it would be wrongly admitted). Use `assertNoJudgeVerdict` to gate\n *  steering; use this only where \"is this grounded in observable evidence\" is the\n *  literal question. */\nexport function isTraceObservable(finding: AnalystFinding): boolean {\n  return finding.evidence_refs.some((ref) => OBSERVABLE_KINDS.has(ref.kind))\n}\n\n/** True iff the finding is a JUDGE VERDICT (an acceptance score lifted into a\n *  finding), identified by provenance set at the lift site — independent of\n *  whatever evidence it cites. */\nexport function isJudgeVerdict(finding: AnalystFinding): boolean {\n  return finding.derived_from_judge === true\n}\n\n/**\n * THE steer firewall. Fail-loud guard for any path that admits analyst findings\n * as STEERING input (the `f(trace)` role): rejects — naming the offenders — any\n * finding whose provenance is a judge verdict, rather than let `J` leak into the\n * loop. Returns the findings unchanged for chaining.\n *\n * Call this at the chokepoint where a detector that ALSO scores/gates has its\n * findings turned into a steer (the judge-and-steer dual-role case). It keys on\n * provenance, so it correctly admits evidence-less trace-analyst observations and\n * correctly rejects an artifact-citing judge verdict — the cases an evidence\n * check gets backwards.\n *\n * It is necessary, not sufficient: it stops PROVENANCE-tagged verdicts. A judge\n * whose output is laundered through a hand-built finding with no provenance flag\n * is out of its reach — provenance must be honestly set at every judge→finding\n * lift (today: createJudgeAdapter). That is why the integrity rule lives at the\n * lift site, and why ProposeContext.judgeScores?: never is the complementary\n * compile-time tripwire on the obvious direct channel.\n */\nexport function assertNoJudgeVerdict(\n  findings: ReadonlyArray<AnalystFinding>,\n  context = 'steer',\n): ReadonlyArray<AnalystFinding> {\n  const leaks = findings.filter(isJudgeVerdict)\n  if (leaks.length > 0) {\n    throw new Error(\n      `${context}: a judge verdict cannot be admitted as steering input — that is the ` +\n        `held-out judge leaking into the loop. Offending judge-derived findings: [${leaks\n          .map((f) => f.finding_id)\n          .join(', ')}]. Steering consumes observations of behavior, never acceptance verdicts.`,\n    )\n  }\n  return findings\n}\n"],"mappings":"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"}

package/dist/analyst-BkTS3C58.d.ts

@@ -0,0 +1,89 @@
+import { t as TraceAnalysisStore } from "./store-CxJry_cs.js";
+import { AxAIService, AxAgentActorTurnCallbackArgs } from "@ax-llm/ax";
+//#region src/trace-analyst/analyst.d.ts
+interface AnalyzeTracesInput {
+  /** The user-facing question. Domain framing belongs here, not in the
+   *  actor description. */
+  question: string;
+}
+interface AnalyzeTracesResult {
+  /** The actor's submitted prose answer. */
+  answer: string;
+  /** Bulleted findings from the actor's structured completion. */
+  findings: string[];
+  /** Per-turn snapshots captured via `actorTurnCallback`. */
+  turns: AnalyzeTracesTurnSnapshot[];
+  /** Total turns the actor took. */
+  turnCount: number;
+  /** Token usage by role. */
+  usage: TraceAnalystUsage;
+  /** Full system + assistant + tool message log by role. */
+  chatLog: TraceAnalystChatLog;
+  /** Prompt version that produced this run. */
+  actorPromptVersion: string;
+}
+interface TraceAnalystUsage {
+  actor: TraceAnalystUsageEntry[];
+  responder: TraceAnalystUsageEntry[];
+}
+interface TraceAnalystUsageEntry {
+  [key: string]: unknown;
+}
+interface TraceAnalystChatLog {
+  actor: TraceAnalystChatMessage[];
+  responder: TraceAnalystChatMessage[];
+}
+interface TraceAnalystChatMessage {
+  [key: string]: unknown;
+}
+interface AnalyzeTracesTurnSnapshot {
+  stage: AxAgentActorTurnCallbackArgs['stage'];
+  turn: number;
+  isError: boolean;
+  /** The JS code the actor produced for this turn. */
+  code: string;
+  /** The formatted action-log entry the actor sees on the next turn. */
+  output: string;
+  /** Provider thought (when `executorOptions.showThoughts` is true and the
+   *  provider returns it). */
+  thought?: string;
+}
+interface AnalyzeTracesOptions {
+  /** Trace data source. Pass either an OTLP-JSONL path or a custom store. */
+  source: string | TraceAnalysisStore;
+  /** Caller-provided AxAIService. */
+  ai: AxAIService;
+  /** Model id forwarded to the actor. */
+  model?: string;
+  /** Maximum model subqueries. 0 disables model fan-out. Default 4. */
+  maxSubqueries?: number;
+  /** Maximum actor turns. Default 12. */
+  maxTurns?: number;
+  /** Maximum parallel model subqueries. Default 2. */
+  maxParallelSubqueries?: number;
+  /** Cancels in-flight model and tool work. */
+  signal?: AbortSignal;
+  /** Override the actor description. */
+  actorDescription?: string;
+  /** Per-turn observability hook. */
+  onTurn?: (turn: AnalyzeTracesTurnSnapshot) => void | Promise<void>;
+  /** Override max runtime characters per turn. Default 6000. */
+  maxRuntimeChars?: number;
+  /** When set, every turn's snapshot is appended to this JSONL file
+   *  immediately. If the analyst crashes mid-loop (provider 503,
+   *  network error, validator reject) the partial reasoning is still
+   *  on disk for diagnosis and recovery. */
+  progressLogPath?: string;
+}
+/**
+ * Run the trace analyst.
+ *
+ * Throws:
+ *   - `TraceFileMissingError` if `source` is a path and doesn't exist.
+ *   - `AxAgentClarificationError` if the analyst asks for clarification.
+ *   - Provider errors (auth, rate limits) propagate from the AI service.
+ */
+declare function analyzeTraces(input: AnalyzeTracesInput, options: AnalyzeTracesOptions): Promise<AnalyzeTracesResult>;
+//#endregion
+export { analyzeTraces as a, AnalyzeTracesTurnSnapshot as i, AnalyzeTracesOptions as n, AnalyzeTracesResult as r, AnalyzeTracesInput as t };
+//# sourceMappingURL=analyst-BkTS3C58.d.ts.map

package/dist/analyst-BkTS3C58.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyst-BkTS3C58.d.ts","names":[],"sources":["../src/trace-analyst/analyst.ts"],"mappings":";;;UAOiB;;;EAGf;;UAGe;;EAEf;;EAEA;;EAEA,OAAO;;EAEP;;EAEA,OAAO;;EAEP,SAAS;;EAET;;UAGe;EACf,OAAO;EACP,WAAW;;UAGI;GACd;;UAGc;EACf,OAAO;EACP,WAAW;;UAGI;GACd;;UAGc;EACf,OAAO;EACP;EACA;;EAEA;;EAEA;;;EAGA;;UAGe;;EAEf,iBAAiB;;EAEjB,IAAI;;EAEJ;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;EAET;;EAEA,UAAU,MAAM,qCAAqC;;EAErD;;;;;EAKA;;;;;;;;;;iBAWoB,cACpB,OAAO,oBACP,SAAS,uBACR,QAAQ"}

package/dist/analyst-LsnNpSkm.js

@@ -0,0 +1,152 @@
+import { i as OtlpFileTraceStore, r as runTraceAnalysisLoop, t as buildTraceAnalystTools } from "./tools-BmuN627J.js";
+//#region src/trace-analyst/prompts.ts
+/** Ax RLM prompt for bounded trace discovery and evidence-backed analysis. */
+const TRACE_ANALYST_ACTOR_DESCRIPTION = `You answer questions about an OTLP-shaped JSONL trace dataset using the trace tools provided in the \`traces\` namespace.
+
+DISCOVERY → NARROW → DEEP-READ protocol — 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 — 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 — 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 — 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× 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** — 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.
+
+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 — 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 the question splits into independent reasoning branches, use bounded \`llmQuery(...)\` calls over evidence you already loaded. Subqueries cannot inspect the trace store, so pass the exact trace excerpts they need. Example:
+
+    const reviews = await llmQuery([
+      { query: 'Classify the failure mechanism in this excerpt.', context: traceAbcExcerpt },
+      { query: 'Classify the failure mechanism in this excerpt.', context: traceDefExcerpt },
+    ]);
+
+OBSERVABILITY rules:
+- Each discovery turn must emit at least one concise \`console.log(...)\` showing what evidence was learned.
+- Finish gathering evidence before submitting the analysis.
+- Reuse runtime variables across turns; don't recompute.
+
+OUTPUT contract — 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.
+- A concise findings array containing only claims supported by inspected evidence.
+
+Do NOT invent trace ids, span ids, error messages, or model names. Every fact must be traceable to a tool result.`;
+const TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION = "trace-analyst-actor-v6-2026-07-14";
+//#endregion
+//#region src/trace-analyst/analyst.ts
+/**
+* Run the trace analyst.
+*
+* Throws:
+*   - `TraceFileMissingError` if `source` is a path and doesn't exist.
+*   - `AxAgentClarificationError` if the analyst asks for clarification.
+*   - Provider errors (auth, rate limits) propagate from the AI service.
+*/
+async function analyzeTraces(input, options) {
+	if (!input.question || typeof input.question !== "string") throw new TypeError("analyzeTraces: input.question must be a non-empty string");
+	rejectRemovedOptions(options);
+	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("node:fs");
+		const { mkdir } = await import("node:fs/promises");
+		const { dirname } = await import("node:path");
+		await mkdir(dirname(options.progressLogPath), { recursive: true });
+		progressFs = createWriteStream(options.progressLogPath, { flags: "a" });
+	}
+	const actorTurnCallback = async (turn) => {
+		const snap = {
+			stage: turn.stage,
+			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()
+			})}\n`);
+		} catch {}
+		if (options.onTurn) await options.onTurn(snap);
+	};
+	const maxSubqueries = options.maxSubqueries ?? 4;
+	const maxTurns = options.maxTurns ?? 12;
+	const maxParallelSubqueries = options.maxParallelSubqueries ?? 2;
+	const maxRuntimeChars = options.maxRuntimeChars ?? 6e3;
+	let completed;
+	try {
+		completed = await runTraceAnalysisLoop({
+			id: "TraceAnalyst",
+			description: "Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes.",
+			prompt: `${options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION}
+
+The report must answer the user's question, and findings must be an array of concise evidence-backed strings.`,
+			question: input.question,
+			ai: options.ai,
+			...options.model ? { model: options.model } : {},
+			tools,
+			findingType: "string",
+			maxSubqueries,
+			maxParallelSubqueries,
+			maxTurns,
+			maxRuntimeChars,
+			...options.signal ? { signal: options.signal } : {},
+			onTurn: actorTurnCallback
+		});
+	} finally {
+		if (progressFs) await new Promise((resolve) => progressFs.end(() => resolve()));
+	}
+	return {
+		answer: completed.report,
+		findings: completed.findings,
+		turns,
+		turnCount: turns.length,
+		usage: {
+			actor: normalizeRecordArray(completed.usage),
+			responder: []
+		},
+		chatLog: {
+			actor: normalizeRecordArray(completed.chatLog),
+			responder: []
+		},
+		actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION
+	};
+}
+function rejectRemovedOptions(options) {
+	const supplied = options;
+	for (const [removed, replacement] of [
+		["maxDepth", "maxSubqueries"],
+		["maxParallelSubagents", "maxParallelSubqueries"],
+		["subagentDescription", "actorDescription"]
+	]) if (removed in supplied) throw new TypeError(`analyzeTraces: '${removed}' is unsupported; use '${replacement}'`);
+}
+function normalizeRecordArray(value) {
+	if (!Array.isArray(value)) return [];
+	return value.map((item) => item && typeof item === "object" ? { ...item } : { value: item });
+}
+//#endregion
+export { TRACE_ANALYST_ACTOR_DESCRIPTION as n, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION as r, analyzeTraces as t };
+
+//# sourceMappingURL=analyst-LsnNpSkm.js.map

package/dist/analyst-LsnNpSkm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyst-LsnNpSkm.js","names":[],"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 the question splits into independent reasoning branches, use bounded \\`llmQuery(...)\\` calls over evidence you already loaded. Subqueries cannot inspect the trace store, so pass the exact trace excerpts they need. Example:\n\n    const reviews = await llmQuery([\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceAbcExcerpt },\n      { query: 'Classify the failure mechanism in this excerpt.', context: traceDefExcerpt },\n    ]);\n\nOBSERVABILITY rules:\n- Each discovery turn must emit at least one concise \\`console.log(...)\\` showing what evidence was learned.\n- Finish gathering evidence before submitting the analysis.\n- Reuse runtime variables across turns; don't recompute.\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- A concise findings array containing only claims supported by inspected evidence.\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-v6-2026-07-14'\n","import type { AxAgentActorTurnCallbackArgs, AxAIService, AxFunction } from '@ax-llm/ax'\nimport { runTraceAnalysisLoop, type TraceAnalysisLoopResult } from './loop'\nimport { TRACE_ANALYST_ACTOR_DESCRIPTION, TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION } from './prompts'\nimport type { TraceAnalysisStore } from './store'\nimport { OtlpFileTraceStore } 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 actor's submitted prose answer. */\n  answer: string\n  /** Bulleted findings from the actor's structured completion. */\n  findings: string[]\n  /** Per-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  stage: AxAgentActorTurnCallbackArgs['stage']\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 `executorOptions.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 the actor. */\n  model?: string\n  /** Maximum model subqueries. 0 disables model fan-out. Default 4. */\n  maxSubqueries?: number\n  /** Maximum actor turns. Default 12. */\n  maxTurns?: number\n  /** Maximum parallel model subqueries. Default 2. */\n  maxParallelSubqueries?: number\n  /** Cancels in-flight model and tool work. */\n  signal?: AbortSignal\n  /** Override the actor description. */\n  actorDescription?: 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 for diagnosis and recovery. */\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  rejectRemovedOptions(options)\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: AxAgentActorTurnCallbackArgs): Promise<void> => {\n    const snap: AnalyzeTracesTurnSnapshot = {\n      stage: turn.stage,\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 maxSubqueries = options.maxSubqueries ?? 4\n  const maxTurns = options.maxTurns ?? 12\n  const maxParallelSubqueries = options.maxParallelSubqueries ?? 2\n  const maxRuntimeChars = options.maxRuntimeChars ?? 6000\n  let completed: TraceAnalysisLoopResult<string>\n  try {\n    completed = await runTraceAnalysisLoop({\n      id: 'TraceAnalyst',\n      description:\n        'Analyzes OTLP-shaped JSONL traces using bounded discovery tools to identify systemic failure modes.',\n      prompt: `${options.actorDescription ?? TRACE_ANALYST_ACTOR_DESCRIPTION}\n\nThe report must answer the user's question, and findings must be an array of concise evidence-backed strings.`,\n      question: input.question,\n      ai: options.ai,\n      ...(options.model ? { model: options.model } : {}),\n      tools,\n      findingType: 'string',\n      maxSubqueries,\n      maxParallelSubqueries,\n      maxTurns,\n      maxRuntimeChars,\n      ...(options.signal ? { signal: options.signal } : {}),\n      onTurn: actorTurnCallback,\n    })\n  } finally {\n    if (progressFs) {\n      await new Promise<void>((resolve) => progressFs!.end(() => resolve()))\n    }\n  }\n\n  return {\n    answer: completed.report,\n    findings: completed.findings,\n    turns,\n    turnCount: turns.length,\n    usage: { actor: normalizeRecordArray(completed.usage), responder: [] },\n    chatLog: { actor: normalizeRecordArray(completed.chatLog), responder: [] },\n    actorPromptVersion: TRACE_ANALYST_ACTOR_DESCRIPTION_VERSION,\n  }\n}\n\nfunction rejectRemovedOptions(options: AnalyzeTracesOptions): void {\n  const supplied = options as unknown as Record<string, unknown>\n  const migrations = [\n    ['maxDepth', 'maxSubqueries'],\n    ['maxParallelSubagents', 'maxParallelSubqueries'],\n    ['subagentDescription', 'actorDescription'],\n  ] as const\n  for (const [removed, replacement] of migrations) {\n    if (removed in supplied) {\n      throw new TypeError(`analyzeTraces: '${removed}' is unsupported; use '${replacement}'`)\n    }\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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"}