@tangle-network/traces 0.8.0 → 0.8.11

package/dist/index.d.ts

@@ -11,13 +11,12 @@ export { HostedClient, createHostedClient, hostedClientFromEnv } from '@tangle-n
 /**
  * OTLP-flat-line emitter — the canonical normalized trace shape.
  *
- * Every harness adapter projects its native session log onto `OtlpSpan[]`
- * and we serialize one span per JSONL line. This is the exact wire shape
- * `@tangle-network/agent-eval`'s `OtlpFileTraceStore` indexes
- * (`projectOtlpFlatLine` + `extractOtlpAttributes`). It is a flat subset, NOT
- * canonical OpenInference (kind lives in attributes; no resource/scope; root
- * parent is null) — external OpenInference engines like HALO need the canonical
- * form, which `external.ts` `toCanonicalOpenInference` produces.
+ * Every harness adapter projects its native session log onto `OtlpSpan[]`.
+ * `serializeSpans` emits one COMPLETE OpenInference span per JSONL line
+ * (top-level `kind`, `resource`, `scope`, string `parent_span_id`, plus the
+ * `openinference.span.kind` attribute). One standard artifact feeds three
+ * consumers unchanged: `@tangle-network/agent-eval`'s `OtlpFileTraceStore`
+ * (which reads the attribute vocabulary), HALO, and any OpenInference tool.
  *
  * Attribute vocabulary the downstream analysts key off:
  *   - `openinference.span.kind`  → span kind (AGENT | LLM | TOOL | CHAIN)
@@ -149,6 +148,18 @@ declare const ATTR: {
     readonly INGEST_SOURCE: "tangle.ingest_source";
     readonly HARNESS: "tangle.harness";
     readonly CWD: "tangle.cwd";
+    /** THE per-session grouping key the spine derives subjects from
+     *  (`deriveSubjectKey` reads `tangle.subject.key` first). Resolves to the git
+     *  remote (host/owner/repo) when readable, else the cwd path basename. */
+    readonly SUBJECT_KEY: "tangle.subject.key";
+    /** Normalized git remote (e.g. `github.com/tangle-network/agent-dev-container`). */
+    readonly GIT_REPOSITORY: "git.repository";
+    /** Current branch at conversion time. */
+    readonly GIT_BRANCH_NAME: "git.branch";
+    /** HEAD short sha at conversion time. */
+    readonly GIT_COMMIT: "git.commit";
+    /** How traces resolved the session cwd: recorded cwd, repaired cwd, or span path. */
+    readonly REPO_RESOLUTION_SOURCE: "traces.repo_resolution_source";
     readonly GIT_BRANCH: "tangle.git_branch";
     readonly HOST: "tangle.host";
     /** Basename of the session file. (Renamed from the ambiguous `tangle.source`,
@@ -201,6 +212,13 @@ interface AdapterSelection {
  *  A named harness that doesn't resolve throws rather than silently dropping. */
 declare function selectAdapters(opts: AdapterSelection): HarnessTraceAdapter[];
 
+/**
+ * Parse one session to spans and stamp per-session repo/git resource attrs
+ * (`tangle.subject.key` etc.) derived from the ref's cwd. Every OTLP-producing
+ * path funnels through here so the spine can group by repo. Repo resolution is
+ * computed ONCE per session; it is fail-safe and never throws.
+ */
+declare function parseSession(adapter: HarnessTraceAdapter, ref: SessionRef): Promise<OtlpSpan[]>;
 interface ScanOptions extends AdapterSelection {
     /** Filter by working directory (exact/prefix). */
     cwd?: string;
@@ -223,6 +241,37 @@ interface ScannedSession {
  *  errors route to `onError` and skip that adapter/session, never aborting. */
 declare function scanSessions(opts: ScanOptions): AsyncGenerator<ScannedSession>;
 
+type RepoResolutionSource = 'none' | 'ref-cwd' | 'repaired-cwd' | 'span-path' | 'span-workdir';
+/** Resource-attribute keys this resolver may stamp. */
+type RepoAttrs = Partial<Record<typeof ATTR.SUBJECT_KEY | typeof ATTR.GIT_REPOSITORY | typeof ATTR.GIT_BRANCH_NAME | typeof ATTR.GIT_COMMIT | typeof ATTR.CWD, string>> & Partial<Record<typeof ATTR.REPO_RESOLUTION_SOURCE, RepoResolutionSource>>;
+interface RepoResolution {
+    /** Resource attributes to stamp onto spans. */
+    attrs: RepoAttrs;
+    /** Best-known cwd/repo directory after repair or span-path inference. */
+    cwd: string | null;
+    /** Which signal produced the selected cwd. */
+    source: RepoResolutionSource;
+}
+/**
+ * Normalize a git remote url to `host/owner/repo`, dropping scheme, auth, the
+ * `.git` suffix, and any trailing slash. Handles both `https://` and the
+ * `git@host:owner/repo.git` SCP-style forms. Returns null when unparseable.
+ */
+declare function normalizeRemote(url: string): string | null;
+/**
+ * Resolve per-session repo/git resource attributes from a session's cwd.
+ * Fail-safe and never throws; see the module doc for the derivation contract.
+ */
+declare function resolveRepoAttrs(cwd: string | null | undefined): Promise<RepoAttrs>;
+declare function resolveSessionRepoAttrs(cwd: string | null | undefined, spans: readonly OtlpSpan[]): Promise<RepoResolution>;
+/**
+ * Stamp resolved repo attrs onto every span's attributes (so they land in the
+ * OTLP resource attributes via `toOpenInferenceSpan`). Additive — existing
+ * `service.name` / `agent.name` are untouched. Mutates in place and returns the
+ * same array for ergonomic chaining. A no-op when `attrs` is empty.
+ */
+declare function stampRepoAttrs(spans: readonly OtlpSpan[], attrs: RepoAttrs): readonly OtlpSpan[];
+
 /**
  * Claude Code adapter — `~/.claude/projects/<encoded-cwd>/<session>.jsonl`.
  *
@@ -314,6 +363,11 @@ declare class GeminiFamilyAdapter implements HarnessTraceAdapter {
     private readonly homeDirName;
     constructor(cfg: GeminiFamilyConfig);
     private chatsRoot;
+    /** `<home>/projects.json` maps `{ <absolute-cwd>: <projectName> }`. The session
+     *  dir name (`tmp/<projectHash>/`) is that projectName for registered projects,
+     *  so inverting the map recovers cwd. (Unregistered/older dirs are opaque cwd
+     *  digests and stay null.) Loaded once per locate(). */
+    private loadProjectCwds;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
     parse(ref: SessionRef): Promise<OtlpSpan[]>;
 }
@@ -461,6 +515,20 @@ declare const CONTENT_CAP = 8000;
  *  visible `… [+N chars]` marker is appended so analysts (and readers) know the
  *  content was truncated rather than silently lost. */
 declare function capText(raw: string): string;
+/**
+ * Who produced a `user.prompt` turn. The trace records every "user" message,
+ * but only some are a real human typing — the rest are the harness or another
+ * agent feeding the model:
+ *   - `human`          a person typed it
+ *   - `subagent-spawn` a parent agent spawned a subagent with this prompt
+ *   - `injected`       a synthetic harness prompt (benchmark task, memory, …)
+ *   - `tool-result`    a tool result surfaced as a user turn (rare)
+ * Analysts that measure human reactions must filter to `human` only.
+ */
+type Actor = 'human' | 'subagent-spawn' | 'injected' | 'tool-result';
+/** Span attribute key for {@link Actor}. New (additive) — not part of the
+ *  `tangle.sessionId`/`tangle.ingest_source` wire contract. */
+declare const ACTOR_ATTR = "tangle.actor";
 interface UserPromptInput {
     traceId: string;
     spanId: string;
@@ -471,12 +539,70 @@ interface UserPromptInput {
     service?: string | null;
     agent?: string | null;
     step?: number;
+    /** Who produced this turn. Defaults to `human` when the adapter can't tell. */
+    actor?: Actor;
 }
 /** The canonical `user.prompt` span. Every adapter emits the human's turn the
  *  same way — a CHAIN span, because a user message is not an LLM call — so
- *  analysts see one consistent shape regardless of harness. */
+ *  analysts see one consistent shape regardless of harness. The `actor`
+ *  attribute lets analysts separate real human turns from agent-to-agent or
+ *  injected prompts. */
 declare function userPromptSpan(o: UserPromptInput): OtlpSpan;
 
+/**
+ * Actor + reaction classification — ported from the proven trace-audit
+ * `extract.py` classifier so the CLI and the offline audit agree on what
+ * counts as a real human turn and how a human reaction is labelled.
+ *
+ * Two jobs:
+ *   1. {@link claudeActor} / {@link textIsSynthetic} — decide whether a "user"
+ *      turn is a real human or an injected / agent-spawned prompt. Adapters use
+ *      the harness's structural signals first (sidechain / userType) and fall
+ *      back to these text heuristics.
+ *   2. {@link classifyReaction} — label a human turn as
+ *      correction / frustration / praise / jargon / structure complaint, using
+ *      extract.py's regexes verbatim. The user-reaction analyst keys off this.
+ */
+
+/** Synthetic harness prompt? (Checks only the head, as extract.py does.) */
+declare function textIsSynthetic(s: string): boolean;
+/** First-turn heuristic: does this read like an agent/subagent spawn prompt
+ *  (long, or starts with an imperative "you are…/your task…") rather than a
+ *  person? Ported from extract.py looks_like_agent_prompt. */
+declare function looksLikeAgentPrompt(s: string): boolean;
+/**
+ * Derive the actor for a Claude Code user turn from the structural signals the
+ * adapter already parses, falling back to the text heuristics above.
+ *
+ *   isSidechain === true             → subagent-spawn
+ *   userType present and !== external → injected
+ *   synthetic markers in the text     → injected
+ *   first-turn agent-spawn prompt     → subagent-spawn
+ *   otherwise                         → human
+ */
+declare function claudeActor(args: {
+    text: string;
+    isSidechain?: boolean;
+    userType?: string | null;
+    isFirstUserTurn?: boolean;
+}): Actor;
+/**
+ * Derive the actor for a Codex user message. Codex has no sidechain/userType,
+ * so it's text-only: synthetic markers → injected, first-turn agent-spawn
+ * brief → injected, otherwise human.
+ */
+declare function codexActor(args: {
+    text: string;
+    isFirstUserTurn?: boolean;
+}): Actor;
+type Reaction = 'correction' | 'frustration' | 'praise' | 'jargon' | 'structure';
+/** Label a human turn with every reaction signal it matches. Mirrors
+ *  extract.py classify() — lowercased match, multi-label. */
+declare function classifyReaction(text: string): Reaction[];
+/** Reactions that signal the agent did something wrong (the numerator of the
+ *  corrective-to-positive ratio). `praise` is the positive denominator. */
+declare const CORRECTIVE_REACTIONS: readonly Reaction[];
+
 /**
  * Run agent-eval's shipped trace pipelines over normalized harness spans.
  *
@@ -505,6 +631,113 @@ interface PipelineOptions {
 }
 declare function runPipelines(spans: readonly OtlpSpan[], opts?: PipelineOptions): Promise<PipelineReport>;
 
+/**
+ * User-reaction analyst — deterministic, $0, no API key.
+ *
+ * For every real human turn (`actor === 'human'` on a `user.prompt` span) that
+ * FOLLOWS an assistant turn, classify the human's reaction (correction /
+ * frustration / praise / jargon / structure complaint) with the trace-audit
+ * classifier, then roll up:
+ *   - per-session + corpus signal counts
+ *   - the corrective-to-positive ratio (how often the human pushed back vs
+ *     praised)
+ *   - the top "trigger pairs": the assistant prose that drew the strongest
+ *     human reaction
+ *
+ * Findings only consider `actor === 'human'` turns — that's why the actor tag
+ * (feature 1) is a hard dependency. An agent-to-agent or injected prompt is not
+ * a human reaction and must not pollute the counts.
+ */
+
+/** Reaction labels in stable render order. */
+declare const REACTIONS: readonly Reaction[];
+interface TriggerPair {
+    /** The assistant prose immediately preceding the human reaction. */
+    assistant: string;
+    /** The human's reacting turn. */
+    human: string;
+    /** Signals matched on the human turn. */
+    reactions: Reaction[];
+    sessionId: string;
+}
+interface ReactionSessionReport {
+    sessionId: string;
+    /** Human turns that followed an assistant turn (the denominator). */
+    humanReactionTurns: number;
+    signals: Record<Reaction, number>;
+}
+interface ReactionReport {
+    sessions: ReactionSessionReport[];
+    /** Corpus signal totals. */
+    signals: Record<Reaction, number>;
+    /** Human turns that followed an assistant turn, corpus-wide. */
+    humanReactionTurns: number;
+    /** corrective signals / praise signals. Infinity when praise is 0 but
+     *  corrective > 0; NaN-safe (null) when there are no signals at all. */
+    correctiveToPositiveRatio: number | null;
+    /** Highest-signal assistant→reaction pairs, most-corrective first. */
+    triggerPairs: TriggerPair[];
+}
+/**
+ * Build the user-reaction report from normalized spans. Spans may span multiple
+ * sessions (corpus run); reactions are scoped per `trace_id`.
+ */
+declare function analyzeReactions(spans: readonly OtlpSpan[]): ReactionReport;
+
+/**
+ * Skill + subagent adoption metrics — deterministic.
+ *
+ * Reports three things:
+ *   1. skill penetration — % of sessions that invoked any skill
+ *   2. per-skill invocation frequency
+ *   3. subagent (Task/Agent) spawn frequency
+ *
+ * CRITICAL undercount fix: the trace-level `Skill` tool-use count only sees
+ * skills a session invoked *interactively*. Skills dispatched inside an
+ * automation loop (e.g. `/evolve`, `/converge`) are logged to
+ * `.evolve/skill-runs.jsonl` under the session's cwd and never surface as a
+ * `Skill` tool span — historically ~370× more runs than the trace count. So we
+ * read those files too and report "explicit invocations" and "loop-dispatched
+ * runs" SEPARATELY, so neither silently reads as zero.
+ */
+
+interface AdoptionReport {
+    sessionCount: number;
+    /** Sessions that invoked ≥1 skill (explicitly, via the Skill tool). */
+    sessionsWithSkill: number;
+    /** sessionsWithSkill / sessionCount (0 when no sessions). */
+    skillPenetration: number;
+    /** Explicit `Skill` tool invocations per skill name, corpus-wide. */
+    skillInvocations: Record<string, number>;
+    /** Total explicit `Skill` tool invocations. */
+    totalSkillInvocations: number;
+    /** Subagent spawns per subagent type (from Task/Agent tool spans). */
+    subagentSpawns: Record<string, number>;
+    /** Total subagent spawns. */
+    totalSubagentSpawns: number;
+    /** Sessions that spawned ≥1 subagent. */
+    sessionsWithSubagent: number;
+    /** Loop-dispatched skill runs per skill, read from `.evolve/skill-runs.jsonl`
+     *  (NOT visible at trace level — counted separately to avoid silent zeros). */
+    loopDispatchedRuns: Record<string, number>;
+    /** Total loop-dispatched skill runs. */
+    totalLoopDispatchedRuns: number;
+    /** `.evolve/skill-runs.jsonl` files that were read. */
+    skillRunFilesRead: number;
+}
+/**
+ * Count loop-dispatched skill runs from a `.evolve/skill-runs.jsonl` file's raw
+ * contents. Each line records one or more skills under `skills` (array) or
+ * `skill` (string) — the schema varies across producers, so accept both.
+ */
+declare function countSkillRunsJsonl(raw: string): Record<string, number>;
+interface AdoptionOptions {
+    /** Session cwds to probe for `.evolve/skill-runs.jsonl`. The CLI passes the
+     *  cwds of the analyzed sessions. */
+    cwds?: readonly string[];
+}
+declare function analyzeAdoption(spans: readonly OtlpSpan[], opts?: AdoptionOptions): Promise<AdoptionReport>;
+
 /**
  * Project normalized `OtlpSpan[]` onto agent-eval's runtime trace store.
  *
@@ -534,10 +767,9 @@ declare function toRuntimeStore(spans: readonly OtlpSpan[]): Promise<RuntimeTrac
  * LLM, model-agnostic). Supply `ai` to add the agentic RLM kinds
  * (failure-mode / knowledge-gap / knowledge-poisoning / improvement).
  *
- * The written OTLP file is the artifact our pipeline reads. External engines can
- * analyze it too: HALO needs canonical OpenInference, so `--analyzer halo`
- * converts it first (see external.ts `toCanonicalOpenInference`) — analysis is
- * never locked to one engine.
+ * The written file is canonical OpenInference (see otlp.ts), so it feeds our
+ * analysts AND external engines directly — `--analyzer halo` runs HALO over the
+ * same artifact, no conversion. Analysis is never locked to one engine.
  */
 
 interface AnalyzeOptions {
@@ -565,6 +797,227 @@ interface AnalyzeResult {
 }
 declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 
+interface PolicyEvidenceToolSummary {
+    readonly name: string;
+    readonly calls: number;
+    readonly errors: number;
+}
+interface PolicyEvidenceLoopSummary {
+    readonly toolName: string;
+    readonly occurrences: number;
+}
+interface PolicyEvidenceRecord {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.policy_evidence.session';
+    readonly generatedAt: string;
+    readonly session: {
+        readonly harness: string;
+        readonly sessionId: string;
+        readonly path: string;
+        readonly cwd: string | null;
+        readonly mtimeMs: number;
+    };
+    readonly repo: {
+        readonly subjectKey?: string;
+        readonly repository?: string;
+        readonly branch?: string;
+        readonly commit?: string;
+        readonly cwd?: string;
+        readonly resolutionSource?: string;
+    };
+    readonly metrics: {
+        readonly spanCount: number;
+        readonly llmTurnCount: number;
+        readonly toolCallCount: number;
+        readonly erroredToolCallCount: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly models: readonly string[];
+        readonly tools: readonly PolicyEvidenceToolSummary[];
+        readonly firstSpanAt: string | null;
+        readonly lastSpanAt: string | null;
+    };
+    readonly signals: {
+        readonly stuckLoopCount: number;
+        readonly affectedRunRatio: number;
+        readonly stuckLoops: readonly PolicyEvidenceLoopSummary[];
+        readonly stuckLoopsOmitted: number;
+        readonly toolErrorRate: number;
+    };
+    readonly provenance: {
+        readonly source: 'traces';
+        readonly evidenceKind: 'session-summary';
+        readonly otlpPath?: string;
+        readonly notCampaignCell: true;
+        readonly note: string;
+    };
+}
+interface BuildPolicyEvidenceOptions {
+    readonly generatedAt?: string;
+    readonly minLoopOccurrences?: number;
+    readonly maxLoopExamples?: number;
+    readonly otlpPath?: string;
+}
+interface CollectPolicyEvidenceOptions extends ScanOptions, BuildPolicyEvidenceOptions {
+}
+declare function buildPolicyEvidenceRecord(ref: SessionRef, spans: readonly OtlpSpan[], opts?: BuildPolicyEvidenceOptions): Promise<PolicyEvidenceRecord>;
+declare function collectPolicyEvidence(opts: CollectPolicyEvidenceOptions): Promise<PolicyEvidenceRecord[]>;
+declare function serializePolicyEvidence(records: readonly PolicyEvidenceRecord[]): string;
+declare function writePolicyEvidenceFile(records: readonly PolicyEvidenceRecord[], outPath?: string): Promise<string>;
+
+interface TraceSessionIndexRow {
+    readonly session: PolicyEvidenceRecord['session'];
+    readonly repo: PolicyEvidenceRecord['repo'];
+    readonly time: {
+        readonly firstSpanAt: string | null;
+        readonly lastSpanAt: string | null;
+    };
+    readonly metrics: {
+        readonly spanCount: number;
+        readonly llmTurnCount: number;
+        readonly toolCallCount: number;
+        readonly erroredToolCallCount: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly toolErrorRate: number;
+    };
+    readonly models: readonly string[];
+    readonly tools: PolicyEvidenceRecord['metrics']['tools'];
+    readonly signals: PolicyEvidenceRecord['signals'];
+}
+interface TraceIndexedFile {
+    readonly kind: 'instruction-doc' | 'evolve-jsonl' | 'evolve-json' | 'reflection' | 'handoff' | 'other';
+    readonly path: string;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+    readonly lines?: number;
+    readonly jsonlRows?: number;
+    readonly markdown?: {
+        readonly headings: number;
+        readonly hasToc: boolean;
+    };
+    readonly jsonl?: {
+        readonly rows: number;
+        readonly invalidRows: number;
+        readonly keys: Record<string, number>;
+    };
+}
+interface TraceContextRoot {
+    readonly root: string;
+    readonly files: readonly TraceIndexedFile[];
+}
+interface TraceContextIndex {
+    readonly totals: {
+        readonly roots: number;
+        readonly files: number;
+        readonly instructionDocs: number;
+        readonly evolveFiles: number;
+        readonly jsonlRows: number;
+        readonly invalidJsonlRows: number;
+    };
+    readonly roots: readonly TraceContextRoot[];
+}
+interface TraceSessionIndex {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.session_index';
+    readonly generatedAt: string;
+    readonly selection?: Record<string, unknown>;
+    readonly totals: {
+        readonly sessions: number;
+        readonly spans: number;
+        readonly llmTurns: number;
+        readonly toolCalls: number;
+        readonly erroredToolCalls: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly stuckLoopSessions: number;
+        readonly stuckLoops: number;
+        readonly harnesses: readonly string[];
+        readonly repos: readonly string[];
+        readonly models: readonly string[];
+        readonly tools: readonly string[];
+    };
+    readonly context?: TraceContextIndex;
+    readonly sessions: readonly TraceSessionIndexRow[];
+}
+interface BuildSessionIndexOptions extends Pick<BuildPolicyEvidenceOptions, 'generatedAt' | 'minLoopOccurrences'> {
+    readonly selection?: Record<string, unknown>;
+    /** Index nearby local docs/artifacts for joins. Defaults to true in scan paths. */
+    readonly includeContext?: boolean;
+}
+interface CollectSessionIndexOptions extends ScanOptions, BuildSessionIndexOptions {
+}
+declare function buildSessionIndex(records: readonly PolicyEvidenceRecord[], opts?: BuildSessionIndexOptions & {
+    context?: TraceContextIndex;
+}): TraceSessionIndex;
+declare function buildSessionIndexFromRows(rows: readonly {
+    ref: SessionRef;
+    spans: readonly OtlpSpan[];
+}[], opts?: BuildSessionIndexOptions): Promise<TraceSessionIndex>;
+declare function collectSessionIndex(opts?: CollectSessionIndexOptions): Promise<TraceSessionIndex>;
+declare function serializeSessionIndex(index: TraceSessionIndex): string;
+declare function writeSessionIndexFile(index: TraceSessionIndex, outPath?: string): Promise<string>;
+
+type TraceInspectionSeverity = 'high' | 'medium' | 'low';
+type TraceInspectionArea = 'index' | 'session' | 'repo' | 'context';
+interface TraceInspectionFinding {
+    readonly id: string;
+    readonly severity: TraceInspectionSeverity;
+    readonly area: TraceInspectionArea;
+    readonly title: string;
+    readonly impact: number;
+    readonly evidence: readonly string[];
+    readonly next: string;
+    readonly refs?: readonly string[];
+}
+interface TraceInspectionReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.inspection_report';
+    readonly generatedAt: string;
+    readonly source: {
+        readonly indexGeneratedAt?: string;
+        readonly sessions: number;
+        readonly contextFiles: number;
+    };
+    readonly totals: {
+        readonly findings: number;
+        readonly high: number;
+        readonly medium: number;
+        readonly low: number;
+    };
+    readonly findings: readonly TraceInspectionFinding[];
+}
+interface InspectSessionIndexOptions {
+    readonly generatedAt?: string;
+    readonly maxFindings?: number;
+}
+declare function inspectSessionIndex(index: TraceSessionIndex, opts?: InspectSessionIndexOptions): TraceInspectionReport;
+declare function renderInspectionReport(report: TraceInspectionReport): string;
+declare function serializeInspectionReport(report: TraceInspectionReport): string;
+declare function readSessionIndexFile(path: string): Promise<TraceSessionIndex>;
+declare function writeInspectionReportFile(report: TraceInspectionReport, outPath?: string): Promise<string>;
+
+type JsonObject = Record<string, unknown>;
+type TraceEvidenceInputFormat = 'policy-evidence' | 'sandbox-events' | 'openinference';
+type TraceEvidenceFormatOption = TraceEvidenceInputFormat | 'auto';
+interface TraceEvidenceExportOptions {
+    readonly format?: TraceEvidenceFormatOption;
+    readonly sourcePath?: string;
+    readonly attributes?: JsonObject;
+}
+interface TraceEvidenceExportResult {
+    readonly format: TraceEvidenceInputFormat;
+    readonly spans: OtlpSpan[];
+    readonly redactionCount: number;
+    readonly redactionsByRule: Record<string, number>;
+}
+declare function exportTraceEvidenceRows(rows: readonly unknown[], opts?: TraceEvidenceExportOptions, wrapper?: JsonObject): TraceEvidenceExportResult;
+declare function exportTraceEvidenceText(text: string, opts?: TraceEvidenceExportOptions): TraceEvidenceExportResult;
+declare function exportTraceEvidenceFile(inputPath: string, opts?: TraceEvidenceExportOptions): Promise<TraceEvidenceExportResult>;
+declare function writeTraceEvidenceExportFile(inputPath: string, outPath?: string, opts?: TraceEvidenceExportOptions): Promise<TraceEvidenceExportResult & {
+    path: string;
+}>;
+
 /**
  * External-tool adapters: run analysis engines and PII scrubbers that `traces`
  * does NOT bundle. Each is a thin command adapter over a shared subprocess
@@ -619,20 +1072,11 @@ declare function commandAnalyzer(spec: {
     parse?: (stdout: string) => AnalystFinding[] | undefined;
     timeoutMs?: number;
 }): ExternalAnalyzer;
-/** Convert our OTLP-JSONL (the flat shape our pipeline reads) into the canonical
- *  OpenInference span schema HALO's `SpanRecord` requires: top-level `kind`,
- *  `resource`, `scope`, and a string (never null) `parent_span_id`. Our own
- *  writer keeps the simpler shape for the agent-eval reader; this is the bridge
- *  to OpenInference consumers. Input + output are JSONL strings (one span/line). */
-declare function toCanonicalOpenInference(otlpJsonl: string, opts?: {
-    service?: string;
-    scopeName?: string;
-}): string;
-/** HALO (github.com/context-labs/halo) over the OTLP artifact. HALO requires
- *  canonical OpenInference, so this converts our OTLP to a `<path>.halo.jsonl`
- *  first, then runs `halo <file> -p <prompt> [-m <model>]`. Install HALO yourself
- *  and configure its LLM provider (it uses the OpenAI client — `OPENAI_BASE_URL`
- *  / `OPENAI_API_KEY`); this just drives it. */
+/** HALO (github.com/context-labs/halo) over the OTLP artifact: `halo <file> -p
+ *  <prompt> [-m <model>]`. Our `serializeSpans` already emits canonical
+ *  OpenInference, so HALO reads the artifact directly — no conversion. Install
+ *  HALO yourself and configure its LLM provider (it uses the OpenAI client —
+ *  `OPENAI_BASE_URL` / `OPENAI_API_KEY`); this just drives it. */
 declare function haloAnalyzer(opts?: {
     command?: string;
     defaultPrompt?: string;
@@ -875,4 +1319,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 { ATTR, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, CONTENT_CAP, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type Redactor, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, alreadyUploaded, analyzeSpans, applyRedactor, capText, collectSessions, commandAnalyzer, commandRedactor, executeUpload, haloAnalyzer, knownHarnesses, listAdapters, loadState, parseIsoToEpochMs, parseSince, planUpload, redactSpans, resolveAdapter, runCommand, runExternalAnalyzers, runPipelines, saveState, scanSessions, selectAdapters, serializeSpans, sessionHash, span, toCanonicalOpenInference, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile };
+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 };