@tangle-network/traces 0.8.13 → 0.8.14

package/dist/cli.js

@@ -12,218 +12,39 @@ import {
   haloAnalyzer,
   inspectSessionIndex,
   knownHarnesses,
+  loadTracesConfig,
+  mergeTracesConfig,
   parseSession,
   parseSince,
   planUpload,
   readSessionIndexFile,
+  renderAdoption,
   renderInspectionReport,
+  renderPipelines,
+  renderReactions,
+  renderReport,
   resolveAdapter,
   runExternalAnalyzers,
   runPipelines,
+  runTraceImprovementLoop,
+  runTraceInvestigation,
+  saveReport,
   selectAdapters,
   serializePolicyEvidence,
   serializeSessionIndex,
   serializeSpans,
+  summarizeDeterministicSignals,
   watchSessions,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-PRRWLKSI.js";
+} from "./chunk-EOQY2RIK.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
 import { readFile, stat, writeFile } from "fs/promises";
-
-// src/report.ts
-var SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
-var SEVERITY_BADGE = {
-  critical: "\u{1F534} CRITICAL",
-  high: "\u{1F7E0} HIGH",
-  medium: "\u{1F7E1} MEDIUM",
-  low: "\u{1F535} LOW",
-  info: "\u2139\uFE0F  INFO"
-};
-function deterministicSummaryText(summary) {
-  const parts = [];
-  if (summary.stuckLoops > 0) parts.push(`${summary.stuckLoops} stuck loop(s)`);
-  if (summary.reactionSignals > 0) parts.push(`${summary.reactionSignals} human reaction signal(s)`);
-  if (summary.toolErrorRuns > 0) parts.push(`${summary.toolErrorRuns} tool-error run(s)`);
-  if (parts.length === 0) return "0 deterministic signals";
-  if (parts.length === 1) return parts[0];
-  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
-}
-function plural(count, singular, pluralForm = `${singular}s`) {
-  return count === 1 ? singular : pluralForm;
-}
-function summarizeDeterministicSignals(pipelines, reactions) {
-  const stuckLoops = pipelines.stuckLoops.findings.length;
-  const reactionSignals = Object.values(reactions.signals).reduce((total, count) => total + count, 0);
-  const toolErrorRuns = pipelines.toolUse.filter((run) => run.errorRate > 0).length;
-  return {
-    stuckLoops,
-    reactionSignals,
-    toolErrorRuns,
-    totalSignals: stuckLoops + reactionSignals + toolErrorRuns
-  };
-}
-function renderReport(result, meta) {
-  const lines = [];
-  const findings = [...result.findings].sort(
-    (a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9)
-  );
-  const deterministic = meta.deterministic ?? { stuckLoops: 0, reactionSignals: 0, toolErrorRuns: 0, totalSignals: 0 };
-  const findingSummary = deterministic.totalSignals > 0 ? `${findings.length} analyst ${plural(findings.length, "finding")} + ${deterministic.totalSignals} deterministic ${plural(deterministic.totalSignals, "signal")}` : `${findings.length} ${plural(findings.length, "finding")}`;
-  lines.push(`# Trace analysis \u2014 ${meta.harness}`);
-  lines.push("");
-  lines.push(
-    `${meta.sessionCount} session(s), ${meta.spanCount} spans \u2192 **${findingSummary}** across ${result.per_analyst.length} analyst(s). Cost: $${result.total_cost_usd.toFixed(4)}.`
-  );
-  lines.push("");
-  lines.push("| Analyst | Status | Findings | Latency |");
-  lines.push("|---|---|---|---|");
-  for (const s of result.per_analyst) {
-    lines.push(`| \`${s.analyst_id}\` | ${s.status} | ${s.findings_count} | ${s.latency_ms}ms |`);
-  }
-  lines.push("");
-  if (findings.length === 0 && deterministic.totalSignals === 0) {
-    lines.push("_No findings \u2014 no behavioral inefficiencies or failure modes detected._");
-  } else if (findings.length === 0) {
-    lines.push(
-      `_No analyst findings. Deterministic checks found ${deterministicSummaryText(deterministic)}; see sections below._`
-    );
-  } else {
-    const byArea = /* @__PURE__ */ new Map();
-    for (const f of findings) {
-      const arr = byArea.get(f.area) ?? [];
-      arr.push(f);
-      byArea.set(f.area, arr);
-    }
-    for (const [area, arr] of byArea) {
-      lines.push(`## ${area} (${arr.length})`);
-      lines.push("");
-      for (const f of arr) {
-        lines.push(`### ${SEVERITY_BADGE[f.severity] ?? f.severity} \u2014 ${f.claim}`);
-        lines.push("");
-        if (f.subject) lines.push(`- **Subject:** \`${f.subject}\``);
-        lines.push(`- **Confidence:** ${f.confidence}`);
-        if (f.recommended_action) lines.push(`- **Fix:** ${f.recommended_action}`);
-        for (const ev of f.evidence_refs.slice(0, 3)) {
-          const excerpt = ev.excerpt ? ` \u2014 \`${ev.excerpt.slice(0, 200)}\`` : "";
-          lines.push(`- **Evidence:** ${ev.kind} ${ev.uri}${excerpt}`);
-        }
-        lines.push("");
-      }
-    }
-  }
-  lines.push("---");
-  lines.push(`OTLP artifact: \`${meta.otlpPath}\` \u2014 run external engines with \`traces analyze --analyzer halo\`.`);
-  lines.push("");
-  return lines.join("\n");
-}
-function renderPipelines(pr) {
-  const lines = ["## loops & waste (deterministic)", ""];
-  if (pr.stuckLoops.findings.length === 0) {
-    lines.push("- **Stuck loops:** none (no tool called \u22653\xD7 with identical args).");
-  } else {
-    lines.push(`- **Stuck loops:** ${pr.stuckLoops.findings.length} (${(pr.stuckLoops.affectedRunRatio * 100).toFixed(0)}% of runs affected)`);
-    for (const f of pr.stuckLoops.findings.sort((a, b) => b.occurrences - a.occurrences).slice(0, 10)) {
-      lines.push(`  - \u{1F501} \`${f.toolName}\` \xD7${f.occurrences} with identical args over ${(f.windowMs / 1e3).toFixed(1)}s`);
-    }
-  }
-  for (const m of pr.toolUse) {
-    if (m.totalCalls === 0) continue;
-    lines.push(
-      `- **Tool use** (${m.totalCalls} calls): ${(m.duplicateRate * 100).toFixed(0)}% duplicate, ${(m.retryRate * 100).toFixed(0)}% retry, ${(m.errorRate * 100).toFixed(0)}% error`
-    );
-  }
-  lines.push("");
-  return lines.join("\n");
-}
-var REACTION_BADGE = {
-  correction: "correction",
-  frustration: "frustration",
-  jargon: "jargon-complaint",
-  structure: "structure-complaint",
-  praise: "praise"
-};
-function ratioStr(r) {
-  if (r === null) return "n/a (no reaction signals)";
-  if (!Number.isFinite(r)) return "\u221E (corrective with zero praise)";
-  return `${r.toFixed(2)}:1`;
-}
-function oneLine(s, n) {
-  const t = s.replace(/\s+/g, " ").trim();
-  return t.length > n ? `${t.slice(0, n)}\u2026` : t;
-}
-function renderReactions(rr) {
-  const lines = ["## user reactions (deterministic, human turns only)", ""];
-  const total = Object.values(rr.signals).reduce((a, b) => a + b, 0);
-  if (rr.humanReactionTurns === 0) {
-    lines.push("- No human turns followed an assistant turn (nothing to classify).");
-    lines.push("");
-    return lines.join("\n");
-  }
-  lines.push(
-    `- **Reaction turns:** ${rr.humanReactionTurns} human turn(s) followed an assistant turn; ${total} carried a reaction signal.`
-  );
-  lines.push(`- **Corrective-to-positive ratio:** ${ratioStr(rr.correctiveToPositiveRatio)}`);
-  lines.push("");
-  lines.push("| Signal | Count |");
-  lines.push("|---|---|");
-  for (const [k, v] of Object.entries(rr.signals)) {
-    if (v > 0) lines.push(`| ${REACTION_BADGE[k] ?? k} | ${v} |`);
-  }
-  lines.push("");
-  if (rr.triggerPairs.length > 0) {
-    lines.push("### top trigger pairs (assistant prose \u2192 human reaction)");
-    lines.push("");
-    for (const p of rr.triggerPairs) {
-      lines.push(`- **[${p.reactions.map((r) => REACTION_BADGE[r] ?? r).join(", ")}]**`);
-      lines.push(`  - assistant: \`${oneLine(p.assistant, 180)}\``);
-      lines.push(`  - human: \`${oneLine(p.human, 180)}\``);
-    }
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-function renderAdoption(ar) {
-  const lines = ["## skill & subagent adoption (deterministic)", ""];
-  lines.push(
-    `- **Skill penetration:** ${(ar.skillPenetration * 100).toFixed(0)}% (${ar.sessionsWithSkill}/${ar.sessionCount} session(s) invoked a skill explicitly)`
-  );
-  lines.push(
-    `- **Explicit skill invocations:** ${ar.totalSkillInvocations} (Skill tool spans)  \xB7  **Loop-dispatched runs:** ${ar.totalLoopDispatchedRuns} (from ${ar.skillRunFilesRead} \`.evolve/skill-runs.jsonl\` file(s))`
-  );
-  lines.push(
-    `- **Subagent spawns:** ${ar.totalSubagentSpawns} across ${ar.sessionsWithSubagent} session(s)`
-  );
-  lines.push("");
-  const skillRows = Object.entries(ar.skillInvocations).sort((a, b) => b[1] - a[1]);
-  const loopRows = Object.entries(ar.loopDispatchedRuns).sort((a, b) => b[1] - a[1]);
-  if (skillRows.length > 0 || loopRows.length > 0) {
-    lines.push("| Skill | Explicit invocations | Loop-dispatched runs |");
-    lines.push("|---|---|---|");
-    const names = [.../* @__PURE__ */ new Set([...skillRows.map((r) => r[0]), ...loopRows.map((r) => r[0])])].sort(
-      (a, b) => (ar.skillInvocations[b] ?? 0) + (ar.loopDispatchedRuns[b] ?? 0) - (ar.skillInvocations[a] ?? 0) - (ar.loopDispatchedRuns[a] ?? 0)
-    );
-    for (const n of names) {
-      lines.push(`| \`${n}\` | ${ar.skillInvocations[n] ?? 0} | ${ar.loopDispatchedRuns[n] ?? 0} |`);
-    }
-    lines.push("");
-  }
-  const agentRows = Object.entries(ar.subagentSpawns).sort((a, b) => b[1] - a[1]);
-  if (agentRows.length > 0) {
-    lines.push("| Subagent | Spawns |");
-    lines.push("|---|---|");
-    for (const [n, c] of agentRows) lines.push(`| \`${n}\` | ${c} |`);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
-// src/cli.ts
 function packageVersion() {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
@@ -273,6 +94,9 @@ function parseArgs(argv) {
       case "--out":
         a.out = next();
         break;
+      case "--dir":
+        a.dir = next();
+        break;
       case "--otlp":
         a.otlp = next();
         break;
@@ -285,6 +109,9 @@ function parseArgs(argv) {
       case "--model":
         a.model = next();
         break;
+      case "--config":
+        a.config = next();
+        break;
       case "--metadata":
         a.metadata = next();
         break;
@@ -561,9 +388,7 @@ ${renderPipelines(pipelines)}
 ${renderReactions(reactions)}
 ${renderAdoption(adoption)}`;
   if (args.analyzers.length > 0 && otlpPath) {
-    const engines = args.analyzers.map(
-      (spec) => spec === "halo" ? haloAnalyzer({ defaultPrompt: args.analyzerPrompt, model: args.model }) : commandAnalyzer({ name: spec, command: spec, args: (p, prompt) => prompt ? [p, prompt] : [p] })
-    );
+    const engines = externalAnalyzersFromArgs(args);
     const results = await runExternalAnalyzers(otlpPath, engines, { prompt: args.analyzerPrompt });
     for (const r of results) {
       report += `
@@ -580,6 +405,68 @@ ${r.ok ? r.output || "(no output)" : `failed: ${r.error}`}`;
     console.log(report);
   }
 }
+function externalAnalyzersFromArgs(args) {
+  return args.analyzers.map(
+    (spec) => spec === "halo" ? haloAnalyzer({ defaultPrompt: args.analyzerPrompt, model: args.model }) : commandAnalyzer({ name: spec, command: spec, args: (p, prompt) => prompt ? [p, prompt] : [p] })
+  );
+}
+async function cmdInvestigate(args) {
+  const { spans, harness, sessionCount, cwds } = await collectSpans(args);
+  if (spans.length === 0) throw new Error("no spans found for the given selection");
+  const config = await loadTracesConfig(args.config);
+  const ai = args.llm ? await buildAxService() : void 0;
+  const result = await runTraceInvestigation(mergeTracesConfig({
+    spans,
+    harness,
+    sessionCount,
+    cwds,
+    minLoopOccurrences: args.minLoop,
+    ai,
+    model: args.model,
+    budgetUsd: args.budget,
+    otlpOutPath: args.otlp,
+    externalAnalyzers: externalAnalyzersFromArgs(args),
+    analyzerPrompt: args.analyzerPrompt,
+    log: (msg) => process.stderr.write(`${msg}
+`)
+  }, config));
+  if (args.out) {
+    await saveReport(args.out, result.report);
+    console.log(`investigation report \u2192 ${args.out}  (${result.findings.length} findings, ${result.recommendations.length} recommendations, OTLP: ${result.otlpPath})`);
+  } else {
+    console.log(result.report);
+  }
+}
+async function cmdImprove(args) {
+  const { spans, harness, sessionCount, cwds } = await collectSpans(args);
+  if (spans.length === 0) throw new Error("no spans found for the given selection");
+  const config = await loadTracesConfig(args.config);
+  const ai = args.llm ? await buildAxService() : void 0;
+  const result = await runTraceImprovementLoop({
+    ...mergeTracesConfig({
+      spans,
+      harness,
+      sessionCount,
+      cwds,
+      minLoopOccurrences: args.minLoop,
+      ai,
+      model: args.model,
+      budgetUsd: args.budget,
+      otlpOutPath: args.otlp,
+      externalAnalyzers: externalAnalyzersFromArgs(args),
+      analyzerPrompt: args.analyzerPrompt,
+      log: (msg) => process.stderr.write(`${msg}
+`)
+    }, config),
+    adapter: config?.improvementAdapter,
+    outDir: args.dir ?? args.out
+  });
+  const dir = result.artifacts?.directory;
+  if (!dir) throw new Error("improve did not produce an artifact directory");
+  console.log(
+    `improvement artifacts \u2192 ${dir}  (${result.findings.length} findings, ${result.recommendations.length} recommendations, ${result.proposals.length} proposal(s), OTLP: ${result.otlpPath})`
+  );
+}
 async function cmdWatch(args) {
   const all = args.all || !args.harnessExplicit && !args.cwd;
   const controller = new AbortController();
@@ -692,6 +579,8 @@ function usage() {
 Commands:
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines, write a markdown report
+  investigate Run typed investigation flow, including BYO config + recommendations
+  improve   Write a full improvement artifact directory for review/apply/rerun
   convert   Emit OTLP-JSONL only (HALO: use analyze --analyzer halo)
   index     Emit a reusable session index JSON for later investigation
   inspect   Read a session index and print ranked improvement findings
@@ -708,12 +597,14 @@ Options:
   --cwd <dir>      Filter sessions by working directory
   --since <t>      upload: window \u2014 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
+  --dir <path>     improve: write artifacts to this directory
   --otlp <path>    OTLP artifact path (also evidence provenance / dry-run upload preview)
   --format <kind>  export: auto | policy-evidence | sandbox-events | openinference
   --metadata <json> export: attach JSON object fields as span attributes
   --attr <k=v>     export: attach one span attribute (repeatable)
   --llm            Enable agentic RLM analysts (needs OPENAI_API_KEY / OPENAI_BASE_URL)
   --model <id>     --llm model id (e.g. a router model like glm-5.2); default is agent-eval's
+  --config <path>  investigate/improve: JS config with analysts, external analyzers, or proposal adapter
   --budget <usd>   USD cap for agentic analysts
   --analyzer <cmd> analyze: also run an external engine over the OTLP (repeatable; "halo" or any command)
   --analyzer-prompt <p>  analyze: prompt passed to external analyzers (default: diagnose)
@@ -752,6 +643,12 @@ async function main() {
     case "analyze":
       await cmdAnalyze(args);
       break;
+    case "investigate":
+      await cmdInvestigate(args);
+      break;
+    case "improve":
+      await cmdImprove(args);
+      break;
     case "convert":
       await cmdConvert(args);
       break;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { ToolUseMetrics, InMemoryTraceStore } from '@tangle-network/agent-eval';
 import { StuckLoopReport } from '@tangle-network/agent-eval/pipelines';
 import { AxAIService } from '@ax-llm/ax';
-import { AnalystRegistry, buildDefaultAnalystRegistry, AnalystFinding } from '@tangle-network/agent-eval/analyst';
+import { AnalystRegistry, buildDefaultAnalystRegistry, AnalystFinding, AnalystRunResult, Analyst } from '@tangle-network/agent-eval/analyst';
 export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultAnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst';
-import { RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
+import { TraceAnalysisStore, RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
 export { DEFAULT_REDACTION_RULES, RedactionReport, RedactionRule, redactString, redactValue } from '@tangle-network/agent-eval/traces';
 import { TraceSpanEvent } from '@tangle-network/agent-eval/hosted';
 export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-network/agent-eval/hosted';
@@ -1106,6 +1106,176 @@ declare function commandRedactor(spec: {
     timeoutMs?: number;
 }): Redactor;
 
+interface TracesConfig {
+    readonly registry?: AnalystRegistry;
+    readonly analysts?: readonly Analyst[];
+    readonly externalAnalyzers?: readonly ExternalAnalyzer[];
+    readonly improvementAdapter?: ImprovementAdapter;
+}
+interface TraceInvestigationOptions {
+    readonly spans: readonly OtlpSpan[];
+    readonly harness: string;
+    readonly sessionCount: number;
+    readonly cwds?: readonly string[];
+    readonly minLoopOccurrences?: number;
+    readonly ai?: AxAIService;
+    readonly model?: string;
+    readonly budgetUsd?: number;
+    readonly registry?: AnalystRegistry;
+    readonly externalAnalyzers?: readonly ExternalAnalyzer[];
+    readonly analyzerPrompt?: string;
+    readonly otlpOutPath?: string;
+    readonly generatedAt?: string;
+    readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface TraceRecommendation {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly severity: AnalystFinding['severity'];
+    readonly title: string;
+    readonly action: string;
+    readonly rationale: string;
+    readonly evidenceRefs: readonly AnalystFinding['evidence_refs'][number][];
+    readonly findingIds: readonly string[];
+    readonly validationPlan: string;
+    readonly source: 'analyst' | 'deterministic' | 'external';
+}
+interface TraceClaim {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly severity: AnalystFinding['severity'];
+    readonly text: string;
+    readonly area: string;
+    readonly sourceFindingId: string;
+    readonly evidenceRefs: readonly AnalystFinding['evidence_refs'][number][];
+    readonly validationPlan?: string;
+}
+interface TraceEvidenceRow {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.improvement_evidence';
+    readonly findingId: string;
+    readonly severity: AnalystFinding['severity'];
+    readonly area: string;
+    readonly claim: string;
+    readonly evidence: AnalystFinding['evidence_refs'][number];
+}
+interface ImprovementProposal {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly recommendationIds: readonly string[];
+    readonly patch?: string;
+    readonly validationCommand?: string;
+    readonly evidenceRefs?: readonly AnalystFinding['evidence_refs'][number][];
+}
+interface ImprovementAdapterInput {
+    readonly findings: readonly AnalystFinding[];
+    readonly recommendations: readonly TraceRecommendation[];
+    readonly claims: readonly TraceClaim[];
+    readonly spans: readonly OtlpSpan[];
+    readonly otlpPath: string;
+}
+interface ImprovementAdapter {
+    propose(input: ImprovementAdapterInput): Promise<readonly ImprovementProposal[]>;
+}
+interface FindingStore {
+    append(runId: string, findings: readonly AnalystFinding[]): Promise<void>;
+}
+interface RecommendationWriter {
+    write(recommendations: readonly TraceRecommendation[]): Promise<void>;
+}
+interface TraceReplayProof {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.improvement_replay';
+    readonly generatedAt: string;
+    readonly status: 'proposal-only' | 'not-run';
+    readonly candidateApplied: false;
+    readonly baseline: {
+        readonly spanCount: number;
+        readonly findingCount: number;
+        readonly recommendationCount: number;
+        readonly stuckLoops: number;
+        readonly reactionSignals: number;
+        readonly toolErrorRuns: number;
+    };
+    readonly proposals: readonly ImprovementProposal[];
+    readonly note: string;
+}
+interface TraceImprovementArtifacts {
+    readonly directory: string;
+    readonly findings: string;
+    readonly recommendations: string;
+    readonly evidence: string;
+    readonly claims: string;
+    readonly report: string;
+    readonly replay: string;
+}
+interface TraceInvestigationResult {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.investigation';
+    readonly generatedAt: string;
+    readonly harness: string;
+    readonly sessionCount: number;
+    readonly spanCount: number;
+    readonly otlpPath: string;
+    readonly findings: readonly AnalystFinding[];
+    readonly recommendations: readonly TraceRecommendation[];
+    readonly claims: readonly TraceClaim[];
+    readonly pipelines: PipelineReport;
+    readonly reactions: ReactionReport;
+    readonly adoption: AdoptionReport;
+    readonly external: readonly ExternalAnalysisResult[];
+    readonly report: string;
+}
+interface TraceFindingPacket {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.finding_packet';
+    readonly generatedAt: string;
+    readonly source: string;
+    readonly findings: readonly AnalystFinding[];
+    readonly recommendations: readonly TraceRecommendation[];
+    readonly claims: readonly TraceClaim[];
+    readonly report: string;
+}
+interface BuildTraceFindingPacketOptions {
+    readonly findings: readonly AnalystFinding[];
+    readonly generatedAt?: string;
+    readonly source?: string;
+    readonly title?: string;
+}
+interface TraceStoreInvestigationOptions {
+    readonly traceStore: TraceAnalysisStore;
+    readonly registry?: AnalystRegistry;
+    readonly ai?: AxAIService;
+    readonly model?: string;
+    readonly budgetUsd?: number;
+    readonly runId?: string;
+    readonly generatedAt?: string;
+    readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface TraceStoreInvestigationResult extends Omit<TraceFindingPacket, 'kind'> {
+    readonly kind: 'traces.store_investigation';
+    readonly analystResult: AnalystRunResult;
+}
+interface TraceImprovementResult extends Omit<TraceInvestigationResult, 'kind'> {
+    readonly kind: 'traces.improvement';
+    readonly proposals: readonly ImprovementProposal[];
+    readonly replay: TraceReplayProof;
+    readonly artifacts?: TraceImprovementArtifacts;
+}
+interface TraceImprovementOptions extends TraceInvestigationOptions {
+    readonly adapter?: ImprovementAdapter;
+    readonly outDir?: string;
+}
+declare function buildTraceFindingPacket(opts: BuildTraceFindingPacketOptions): TraceFindingPacket;
+declare function loadTracesConfig(path?: string): Promise<TracesConfig | undefined>;
+declare function mergeTracesConfig(opts: TraceInvestigationOptions, config?: TracesConfig): TraceInvestigationOptions;
+declare function runTraceInvestigation(opts: TraceInvestigationOptions): Promise<TraceInvestigationResult>;
+declare function runTraceStoreInvestigation(opts: TraceStoreInvestigationOptions): Promise<TraceStoreInvestigationResult>;
+declare function writeTraceImprovementArtifacts(result: Pick<TraceImprovementResult, 'findings' | 'recommendations' | 'claims' | 'report' | 'replay'>, outDir?: string): Promise<TraceImprovementArtifacts>;
+declare function runTraceImprovementLoop(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
+declare function saveReport(path: string, report: string): Promise<void>;
+
 /**
  * Live trace observer — the reusable, event-driven core behind `traces watch`.
  *
@@ -1319,4 +1489,4 @@ interface ExecuteOptions {
 /** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, looksLikeAgentPrompt, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, sessionHash, span, stampRepoAttrs, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, type FindingStore, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type ImprovementAdapter, type ImprovementAdapterInput, type ImprovementProposal, type InspectSessionIndexOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type RecommendationWriter, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceClaim, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceRecommendation, type TraceReplayProof, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TracesConfig, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovementLoop, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, sessionHash, span, stampRepoAttrs, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };

package/dist/index.js

@@ -26,6 +26,7 @@ import {
   buildPolicyEvidenceRecord,
   buildSessionIndex,
   buildSessionIndexFromRows,
+  buildTraceFindingPacket,
   capText,
   classifyReaction,
   claudeActor,
@@ -44,7 +45,9 @@ import {
   knownHarnesses,
   listAdapters,
   loadState,
+  loadTracesConfig,
   looksLikeAgentPrompt,
+  mergeTracesConfig,
   normalizeRemote,
   parseIsoToEpochMs,
   parseSession,
@@ -59,6 +62,10 @@ import {
   runCommand,
   runExternalAnalyzers,
   runPipelines,
+  runTraceImprovementLoop,
+  runTraceInvestigation,
+  runTraceStoreInvestigation,
+  saveReport,
   saveState,
   scanSessions,
   selectAdapters,
@@ -80,8 +87,9 @@ import {
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
-  writeTraceEvidenceExportFile
-} from "./chunk-PRRWLKSI.js";
+  writeTraceEvidenceExportFile,
+  writeTraceImprovementArtifacts
+} from "./chunk-EOQY2RIK.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -136,6 +144,7 @@ export {
   buildPolicyEvidenceRecord,
   buildSessionIndex,
   buildSessionIndexFromRows,
+  buildTraceFindingPacket,
   capText,
   classifyReaction,
   claudeActor,
@@ -157,8 +166,10 @@ export {
   knownHarnesses,
   listAdapters,
   loadState,
+  loadTracesConfig,
   looksLikeAgentPrompt,
   makeFinding,
+  mergeTracesConfig,
   normalizeRemote,
   parseIsoToEpochMs,
   parseSession,
@@ -175,6 +186,10 @@ export {
   runCommand,
   runExternalAnalyzers,
   runPipelines,
+  runTraceImprovementLoop,
+  runTraceInvestigation,
+  runTraceStoreInvestigation,
+  saveReport,
   saveState,
   scanSessions,
   selectAdapters,
@@ -196,5 +211,6 @@ export {
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
-  writeTraceEvidenceExportFile
+  writeTraceEvidenceExportFile,
+  writeTraceImprovementArtifacts
 };