@tangle-network/traces 0.9.11 → 0.9.13

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { Analyst, AnalystContext, AnalystFinding, AnalystRegistry, buildDefaultA
 import { AxAIService } from '@ax-llm/ax';
 import { ExecutionReport } from '@tangle-network/agent-eval/contract';
 import { TraceAnalysisStore, RedactionRule, RedactionReport } from '@tangle-network/agent-eval/traces';
-export { DEFAULT_REDACTION_RULES, RedactionReport, RedactionRule, redactString, redactValue } from '@tangle-network/agent-eval/traces';
+export { DEFAULT_REDACTION_RULES, ErrorCluster, RedactionReport, RedactionRule, TraceAnalysisStore, 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';
 
@@ -109,9 +109,11 @@ interface JsonlCorruptionReceipt {
 }
 type JsonlReadOptions = {
     mode?: 'strict';
+    signal?: AbortSignal;
 } | {
     mode: 'recover';
     onCorruption: (receipt: JsonlCorruptionReceipt) => void;
+    signal?: AbortSignal;
 };
 declare class JsonlParseError extends SyntaxError {
     readonly sourcePath: string;
@@ -142,7 +144,21 @@ type CorruptionMode = 'recover' | 'strict';
 interface ParseOptions {
     /** Recover valid JSONL records by default; strict rejects the first corruption. */
     corruptionMode?: CorruptionMode;
+    /** For resumed session formats, parse all turns, the latest turn, or one exact turn. */
+    taskScope?: 'all' | 'latest' | 'turn';
+    /** Stable turn identifier required when taskScope is `turn`. */
+    taskTurnId?: string;
+    /** Stop active session reads and parsing. */
+    signal?: AbortSignal;
 }
+type ParentTaskResolution = {
+    readonly kind: 'resolved';
+    readonly turnId: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: 'child-reference-not-found' | 'parent-turn-metadata-missing' | 'ambiguous';
+    readonly turnIds?: readonly string[];
+};
 interface SessionCorruptionReceipt extends JsonlCorruptionReceipt {
     harness: string;
     sessionId: string;
@@ -179,8 +195,17 @@ interface HarnessTraceAdapter {
     readonly aliases?: readonly string[];
     /** Discover session files for this harness on disk. */
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    /** Resolve all files for one stable session ID without cataloging unrelated sessions. */
+    locateBySessionId?(sessionId: string, opts?: LocateOptions): Promise<SessionRef[]>;
     /** Parse one discovered session into normalized OTLP spans. */
     parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
+    /** Every file whose bytes can affect parse output. Defaults to ref.path. */
+    sourcePaths?(ref: SessionRef, options?: Pick<ParseOptions, 'signal'>): Promise<readonly string[]>;
+    /**
+     * Resolve the exact parent task that referenced a child by stable session ID.
+     * Adapters must not infer this from names or timestamps.
+     */
+    resolveParentTask?(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode' | 'signal'>): Promise<ParentTaskResolution>;
 }
 
 /**
@@ -266,8 +291,7 @@ declare function stampSessionIdentity(spans: {
     attributes: Record<string, unknown>;
 }[], fallbackSessionId: string): void;
 
-/** Parse an ISO-8601 timestamp or an epoch-millis string to epoch ms.
- *  Returns 0 for empty/unparseable input (callers treat 0 as "unknown"). */
+/** Parse an ISO-8601 timestamp or an epoch-millis string to epoch ms. */
 declare function parseIsoToEpochMs(ts: string): number;
 /** Parse a `--since` window: `30m` / `2h` / `7d` (relative to now) or an ISO
  *  date, → epoch ms. Throws on a malformed value (fail-loud, not silent). */
@@ -316,6 +340,12 @@ interface AdapterSelection {
  *  A named harness that doesn't resolve throws rather than silently dropping. */
 declare function selectAdapters(opts: AdapterSelection): HarnessTraceAdapter[];
 
+/**
+ * Validate one normalized span batch before any consumer trusts its identity
+ * or timing. The returned array contains the original span objects.
+ */
+declare function validateOtlpSpans(input: readonly unknown[], source?: string): OtlpSpan[];
+
 /**
  * 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
@@ -340,8 +370,6 @@ interface ScanOptions extends AdapterSelection, ParseOptions {
     sinceMs?: number;
     /** Cap to the most-recent N sessions per harness. */
     last?: number;
-    /** Cancel the scan; iteration stops between sessions. */
-    signal?: AbortSignal;
     /** Handle a locate/parse failure and continue. Without this callback, failures propagate. */
     onError?: (error: unknown, ref?: SessionRef) => void;
 }
@@ -355,6 +383,115 @@ interface ScannedSession {
  *  propagate unless an explicit `onError` callback handles them. */
 declare function scanSessions(opts: ScanOptions): AsyncGenerator<ScannedSession>;
 
+type SessionRole = 'operator' | 'child' | 'unknown';
+interface SessionRelationship {
+    readonly sessionId: string;
+    readonly role: SessionRole;
+    readonly parentSessionId?: string;
+    readonly childSessionIds: readonly string[];
+    /** Child sessions created in this task. Their full history belongs to the task. */
+    readonly spawnedChildSessionIds: readonly string[];
+    /** Existing child sessions resumed or steered in this task. */
+    readonly resumedChildSessionIds: readonly string[];
+    readonly depth?: number;
+    readonly agentNickname?: string;
+    readonly agentRole?: string;
+    readonly agentPath?: string;
+    readonly taskScope?: 'all' | 'latest' | 'turn' | 'fork-current';
+    readonly turnId?: string;
+}
+type SessionWorkflowErrorCode = 'SESSION_WORKFLOW_EMPTY_SELECTION' | 'SESSION_WORKFLOW_INVALID_LIMIT' | 'SESSION_WORKFLOW_LIMIT_EXCEEDED' | 'SESSION_WORKFLOW_INVALID_RELATION' | 'SESSION_WORKFLOW_DUPLICATE_ID' | 'SESSION_WORKFLOW_TASK_CONFLICT';
+declare class SessionWorkflowError extends Error {
+    readonly code: SessionWorkflowErrorCode;
+    constructor(code: SessionWorkflowErrorCode, message: string);
+}
+/** Read stable parent/child identity from normalized spans.
+ * Worker labels and timestamps are intentionally not used as identity. */
+declare function describeSessionRelationship(ref: SessionRef, spans: readonly OtlpSpan[]): SessionRelationship;
+
+type SessionWorkflowIssue = {
+    readonly kind: 'missing-session';
+    readonly sessionId: string;
+    readonly referencedBySessionId: string;
+    readonly relation: 'parent' | 'child';
+} | {
+    readonly kind: 'ambiguous-session';
+    readonly sessionId: string;
+    readonly referencedBySessionId: string;
+    readonly relation: 'parent' | 'child';
+    readonly paths: readonly string[];
+} | {
+    readonly kind: 'parent-conflict';
+    readonly sessionId: string;
+    readonly declaredParentSessionId?: string;
+    readonly referencedParentSessionIds: readonly string[];
+} | {
+    readonly kind: 'cycle';
+    readonly sessionIds: readonly string[];
+} | {
+    readonly kind: 'unresolved-parent-task';
+    readonly parentSessionId: string;
+    readonly childSessionId: string;
+    readonly reason: 'unsupported' | 'child-reference-not-found' | 'parent-turn-metadata-missing' | 'ambiguous';
+    readonly turnIds?: readonly string[];
+};
+interface SessionWorkflowSession {
+    readonly adapter: HarnessTraceAdapter;
+    readonly ref: SessionRef;
+    readonly spans: readonly OtlpSpan[];
+    readonly relationship: SessionRelationship;
+    readonly taskScope: 'all' | 'latest' | 'turn';
+    readonly taskTurnId?: string;
+}
+interface SessionWorkflowSummary {
+    readonly seedSessionIds: readonly string[];
+    readonly complete: boolean;
+    readonly issues: readonly SessionWorkflowIssue[];
+}
+interface SessionWorkflow extends SessionWorkflowSummary {
+    readonly sessions: readonly SessionWorkflowSession[];
+}
+interface CollectSessionWorkflowOptions extends ParseOptions {
+    /** Maximum number of source files parsed for one workflow selection. */
+    readonly maxSessions?: number;
+}
+/** Expand one or more selected source files into their connected session tree.
+ * Missing or ambiguous files are returned as issues; no path is guessed. */
+declare function collectSessionWorkflow(adapter: HarnessTraceAdapter, seeds: readonly SessionRef[], options?: CollectSessionWorkflowOptions): Promise<SessionWorkflow>;
+
+interface SessionSeedGroup {
+    readonly adapter: HarnessTraceAdapter;
+    readonly refs: readonly SessionRef[];
+}
+interface SessionSelectionRow {
+    readonly adapter: HarnessTraceAdapter;
+    readonly ref: SessionRef;
+    readonly spans: readonly OtlpSpan[];
+    readonly taskScope: 'all' | 'latest' | 'turn';
+    readonly taskTurnId?: string;
+    readonly sourceSha256?: string;
+    readonly sourceFiles?: readonly SessionSourceFile[];
+}
+interface SessionSourceFile {
+    readonly path: string;
+    readonly sha256: string;
+}
+interface SessionSelection {
+    readonly rows: readonly SessionSelectionRow[];
+    readonly workflow?: SessionWorkflowSummary;
+}
+interface CollectSessionSelectionOptions {
+    readonly workflow?: boolean;
+    readonly maxWorkflowSessions?: number;
+    readonly taskScope?: 'all' | 'latest' | 'turn';
+    readonly taskTurnId?: string;
+    /** Hash and reparse every selected file so emitted evidence binds exact bytes. */
+    readonly bindSources?: boolean;
+    readonly signal?: AbortSignal;
+}
+/** Parse selected seed groups, optionally expanding and byte-binding their session tree. */
+declare function collectSessionSelection(groups: readonly SessionSeedGroup[], options?: CollectSessionSelectionOptions): Promise<SessionSelection>;
+
 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>>;
@@ -399,8 +536,10 @@ declare function stampSpanWorkdirRepoAttrs(spans: readonly OtlpSpan[]): Promise<
  * (token trajectory) and `message.content[]` tool_use blocks; tool results
  * arrive as `tool_result` blocks in the following user message or as a
  * `tool_result` attachment. Subagent runs live in a sibling
- * nested `<session>/subagents/.../agent-*.jsonl` files with a `.meta.json` carrying the
- * spawning `toolUseId`, so we parent each subagent under its `Agent` call.
+ * nested `<session>/subagents/.../agent-*.jsonl` files. Ordinary subagent
+ * metadata carries the spawning `toolUseId`. Workflow subagents instead live
+ * under `workflows/<runId>` and bind to the exact run ID and transcript
+ * directory returned by the parent `Workflow` call.
  *
  * Shared by the claudish / openclaw / nanoclaw forks via aliases — they
  * write the same transcript shape.
@@ -410,12 +549,18 @@ declare class ClaudeAdapter implements HarnessTraceAdapter {
     readonly harness = "claude-code";
     readonly aliases: readonly ["claude", "claudish", "openclaw", "nanoclaw"];
     private root;
+    sourcePaths(ref: SessionRef, options?: Pick<ParseOptions, 'signal'>): Promise<readonly string[]>;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
     parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
     /** Parse nested `subagents/.../agent-*.jsonl`, parenting each under its Agent call. */
     private foldSubagents;
 }
 
+declare class CodexTaskScopeError extends Error {
+    readonly code: 'CODEX_CHILD_TASK_AMBIGUOUS' | 'CODEX_CHILD_TASK_NOT_FOUND' | 'CODEX_LATEST_TURN_NOT_FOUND' | 'CODEX_TURN_NOT_FOUND' | 'CODEX_TURN_ID_REQUIRED';
+    constructor(code: CodexTaskScopeError['code'], message: string);
+}
+
 /**
  * OpenAI Codex adapter — `~/.codex/sessions/<Y>/<M>/<D>/rollout-*.jsonl`.
  *
@@ -436,7 +581,10 @@ declare class CodexAdapter implements HarnessTraceAdapter {
     readonly harness = "codex";
     readonly aliases: readonly ["codex-acp"];
     private root;
+    private refFromPath;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    locateBySessionId(sessionId: string, opts?: LocateOptions): Promise<SessionRef[]>;
+    resolveParentTask(ref: SessionRef, childSessionId: string, options?: Pick<ParseOptions, 'corruptionMode'>): Promise<ParentTaskResolution>;
     parse(ref: SessionRef, options?: ParseOptions): Promise<OtlpSpan[]>;
 }
 
@@ -661,12 +809,13 @@ declare function capText(raw: string): string;
  * but only some are a real human typing — the rest are the harness or another
  * agent feeding the model:
  *   - `human`          a person typed it
+ *   - `agent`          a parent agent sent it to a child session
  *   - `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';
+type Actor = 'human' | 'agent' | '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";
@@ -716,6 +865,7 @@ declare function looksLikeAgentPrompt(s: string): boolean;
  * adapter already parses, falling back to the text heuristics above.
  *
  *   isSidechain === true             → subagent-spawn
+ *   isMeta === true                  → injected
  *   userType present and !== external → injected
  *   synthetic markers in the text     → injected
  *   first-turn agent-spawn prompt     → subagent-spawn
@@ -724,6 +874,7 @@ declare function looksLikeAgentPrompt(s: string): boolean;
 declare function claudeActor(args: {
     text: string;
     isSidechain?: boolean;
+    isMeta?: boolean;
     userType?: string | null;
     isFirstUserTurn?: boolean;
 }): Actor;
@@ -836,9 +987,9 @@ declare function analyzeReactions(spans: readonly OtlpSpan[]): ReactionReport;
  *   2. per-skill invocation frequency
  *   3. subagent (Task/Agent) spawn frequency
  *
- * A repository's `.evolve/skill-runs.jsonl` is historical context, not session
- * evidence, unless a row carries the selected session ID. This keeps old runs
- * from being attributed to the current trace.
+ * A repository's `.agent/skill-runs.jsonl` (or legacy `.evolve` log) is
+ * historical context, not session evidence, unless a row carries the selected
+ * session ID. This keeps old runs from being attributed to the current trace.
  */
 
 interface AdoptionReport {
@@ -879,7 +1030,7 @@ interface AdoptionReport {
     loopDispatchedRuns: Record<string, number>;
     /** Total session-linked loop-dispatched skill runs. */
     totalLoopDispatchedRuns: number;
-    /** `.evolve/skill-runs.jsonl` files that were read. */
+    /** Current or legacy `skill-runs.jsonl` files that were read. */
     skillRunFilesRead: number;
     /** Same-repository loop history without a selected session ID. Never treat
      *  this as evidence that a selected session used a skill. */
@@ -889,8 +1040,8 @@ interface AdoptionReport {
 }
 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. */
+    /** Session cwds to probe for current and legacy skill-run logs. The CLI
+     *  passes the cwds of the analyzed sessions. */
     cwds?: readonly string[];
 }
 declare function analyzeAdoption(spans: readonly OtlpSpan[], opts?: AdoptionOptions): Promise<AdoptionReport>;
@@ -976,6 +1127,7 @@ interface AnalyzeOptions {
     /** Where to write the OTLP-JSONL artifact. Defaults to a temp file. */
     otlpOutPath?: string;
     runId?: string;
+    signal?: AbortSignal;
     log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
 interface AnalyzeResult {
@@ -1014,6 +1166,15 @@ interface PolicyEvidenceRecord {
         readonly path: string;
         readonly cwd: string | null;
         readonly mtimeMs: number;
+        readonly role?: SessionRole;
+        readonly parentSessionId?: string;
+        readonly childSessionIds?: readonly string[];
+        readonly depth?: number;
+        readonly agentNickname?: string;
+        readonly agentRole?: string;
+        readonly agentPath?: string;
+        readonly taskScope?: 'all' | 'latest' | 'turn' | 'fork-current';
+        readonly turnId?: string;
     };
     readonly repo: {
         readonly subjectKey?: string;
@@ -1200,13 +1361,13 @@ declare function serializeInspectionReport(report: TraceInspectionReport): strin
 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' | 'intelligence-spans';
+type JsonObject$1 = Record<string, unknown>;
+type TraceEvidenceInputFormat = 'policy-evidence' | 'sandbox-events' | 'openinference' | 'intelligence-spans' | 'chat-trajectory';
 type TraceEvidenceFormatOption = TraceEvidenceInputFormat | 'auto';
 interface TraceEvidenceExportOptions {
     readonly format?: TraceEvidenceFormatOption;
     readonly sourcePath?: string;
-    readonly attributes?: JsonObject;
+    readonly attributes?: JsonObject$1;
 }
 interface TraceEvidenceExportResult {
     readonly format: TraceEvidenceInputFormat;
@@ -1214,13 +1375,41 @@ interface TraceEvidenceExportResult {
     readonly redactionCount: number;
     readonly redactionsByRule: Record<string, number>;
 }
-declare function exportTraceEvidenceRows(rows: readonly unknown[], opts?: TraceEvidenceExportOptions, wrapper?: JsonObject): TraceEvidenceExportResult;
+declare function exportTraceEvidenceRows(rows: readonly unknown[], opts?: TraceEvidenceExportOptions, wrapper?: JsonObject$1): 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;
 }>;
 
+type JsonObject = Record<string, unknown>;
+interface ChatTrajectoryMessage {
+    role: string;
+    content: string;
+    timestamp?: string | number;
+    name?: string;
+    extra?: JsonObject;
+}
+interface ChatTrajectory {
+    messages: readonly ChatTrajectoryMessage[];
+    trajectory_id?: string | number;
+    traj_id?: string;
+    instance_id?: string;
+    trajectory_format?: string;
+    info?: JsonObject;
+}
+interface ChatTrajectoryOptions {
+    traceId?: string;
+    service?: string;
+    /** Use every message for datasets whose labels count transcript rows. */
+    stepMode?: 'assistant' | 'message';
+    sourcePath?: string;
+}
+declare function isChatTrajectoryMessage(value: unknown): value is ChatTrajectoryMessage;
+declare function isChatTrajectory(value: unknown): value is ChatTrajectory;
+/** Convert a generic chat trajectory into stable OpenInference-ready spans. */
+declare function chatTrajectoryToSpans(input: ChatTrajectory | readonly ChatTrajectoryMessage[], options?: ChatTrajectoryOptions): OtlpSpan[];
+
 /**
  * External-tool adapters: run analysis engines and PII scrubbers that `traces`
  * does NOT bundle. Each is a thin command adapter over a shared subprocess
@@ -1248,21 +1437,51 @@ declare function runCommand(command: string, args?: readonly string[], opts?: {
 }): Promise<RunResult>;
 interface ExternalAnalysisResult {
     analyzer: string;
+    kind: ExternalAnalysisKind;
     ok: boolean;
-    /** Raw text the engine produced (markdown/JSON/plain — engine-specific). */
+    /** Raw text the engine produced. */
     output: string;
-    /** Structured findings, when the engine emits parseable JSON. */
-    findings?: AnalystFinding[];
+    /** Confirmed findings with exact evidence. Only valid when kind is findings. */
+    findings?: readonly AnalystFinding[];
+    /** Distinctive actions that still need review. Only valid when kind is discovery. */
+    candidates?: readonly ExternalDiscoveryCandidate[];
     error?: string;
 }
+type ExternalAnalysisKind = 'report' | 'findings' | 'discovery';
+interface ExternalDiscoveryCandidate {
+    engine: string;
+    engineVersion: string;
+    status: 'needs_review';
+    group: string;
+    rank: number;
+    groupSize: number;
+    traceId: string;
+    spanId: string;
+    evidenceUri: string;
+    summary: string;
+    actionText: string;
+    metadata?: Record<string, unknown>;
+}
+type ExternalAnalysisPayload = {
+    kind: 'report';
+} | {
+    kind: 'findings';
+    findings: readonly AnalystFinding[];
+} | {
+    kind: 'discovery';
+    candidates: readonly ExternalDiscoveryCandidate[];
+};
+interface ExternalAnalyzerOptions {
+    prompt?: string;
+    signal?: AbortSignal;
+    /** Supplied by runExternalAnalyzers to avoid rereading the OTLP artifact. */
+    knownSpanUris?: ReadonlySet<string>;
+}
 /** An analysis engine that runs over the emitted OTLP-JSONL artifact — a peer to
  *  the built-in analysts, so you get many analyzers beyond our own. */
 interface ExternalAnalyzer {
     name: string;
-    analyze(otlpPath: string, opts?: {
-        prompt?: string;
-        signal?: AbortSignal;
-    }): Promise<ExternalAnalysisResult>;
+    analyze(otlpPath: string, opts?: ExternalAnalyzerOptions): Promise<ExternalAnalysisResult>;
 }
 /** Wrap any CLI that reads the OTLP file and prints analysis to stdout. `args`
  *  builds the argv from the artifact path + optional prompt. Non-zero exit →
@@ -1271,8 +1490,8 @@ declare function commandAnalyzer(spec: {
     name: string;
     command: string;
     args: (otlpPath: string, prompt?: string) => string[];
-    /** Parse stdout into structured findings; omit to keep raw output only. */
-    parse?: (stdout: string) => AnalystFinding[] | undefined;
+    /** Explicitly classify structured output; omit to keep a raw report. */
+    parse?: (stdout: string) => ExternalAnalysisPayload;
     timeoutMs?: number;
 }): ExternalAnalyzer;
 /** HALO (github.com/context-labs/halo) over the OTLP artifact: `halo <file> -p
@@ -1280,17 +1499,26 @@ declare function commandAnalyzer(spec: {
  *  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?: {
+type HaloReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+interface HaloAnalyzerOptions {
     command?: string;
     defaultPrompt?: string;
     model?: string;
+    maxDepth?: number;
+    maxTurns?: number;
+    maxParallel?: number;
+    instructions?: string;
+    reasoningEffort?: HaloReasoningEffort;
+    telemetry?: boolean;
     timeoutMs?: number;
-}): ExternalAnalyzer;
+}
+declare function haloAnalyzer(opts?: HaloAnalyzerOptions): ExternalAnalyzer;
 /** Run external analyzers over one OTLP artifact, concurrently. Never throws —
  *  a failing engine returns `ok:false`. */
 declare function runExternalAnalyzers(otlpPath: string, analyzers: readonly ExternalAnalyzer[], opts?: {
     prompt?: string;
     signal?: AbortSignal;
+    spans?: readonly OtlpSpan[];
 }): Promise<ExternalAnalysisResult[]>;
 /** An external PII/secret scrubber for free-form text — catches what regex
  *  can't (names, addresses). Use to harden upload beyond the built-in rules. */
@@ -1488,6 +1716,13 @@ interface ReportSource {
     subject: string;
     role: 'operator' | 'child' | 'unknown';
     parentSessionId?: string;
+    childSessionIds?: readonly string[];
+    depth?: number;
+    agentNickname?: string;
+    agentRole?: string;
+    agentPath?: string;
+    taskScope?: 'all' | 'latest' | 'turn' | 'fork-current';
+    turnId?: string;
     integrity?: 'complete' | 'degraded_not_lossless';
     corruptionCount?: number;
     corruptionDigest?: string;
@@ -1504,6 +1739,7 @@ interface TraceInvestigationOptions {
     readonly spans: readonly OtlpSpan[];
     readonly harness: string;
     readonly sources?: readonly ReportSource[];
+    readonly workflow?: SessionWorkflowSummary;
     readonly cwds?: readonly string[];
     readonly minLoopOccurrences?: number;
     readonly ai?: AxAIService;
@@ -1516,6 +1752,7 @@ interface TraceInvestigationOptions {
     readonly analyzerPrompt?: string;
     readonly otlpOutPath?: string;
     readonly generatedAt?: string;
+    readonly signal?: AbortSignal;
     readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
 interface TraceEvidenceRow {
@@ -1544,9 +1781,11 @@ interface TraceInvestigationResult {
     /** Traces without exactly one stable session identity. */
     readonly unassignedTraceCount: number;
     readonly sources?: readonly ReportSource[];
+    readonly workflow?: SessionWorkflowSummary;
     readonly spanCount: number;
     readonly otlpPath: string;
     readonly execution: ExecutionReport;
+    readonly analystResult: AnalystRunResult;
     readonly findings: readonly AnalystFinding[];
     readonly pipelines: PipelineReport;
     readonly reactions: ReactionReport;
@@ -1578,6 +1817,7 @@ interface TraceStoreInvestigationOptions {
     readonly budgetUsd?: number;
     readonly runId?: string;
     readonly generatedAt?: string;
+    readonly signal?: AbortSignal;
     readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
 }
 interface TraceStoreInvestigationResult extends Omit<TraceFindingPacket, 'kind'> {
@@ -1600,6 +1840,61 @@ declare function writeTraceImprovementArtifacts(result: Omit<TraceImprovementRes
 declare function runTraceImprovement(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
 declare function saveReport(path: string, report: string): Promise<void>;
 
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+interface HodoscopeMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    source?: string;
+    tool_calls?: Array<{
+        function: string;
+        arguments: Json;
+    }>;
+}
+interface HodoscopeTrajectory {
+    id: string;
+    model?: string;
+    metadata: Record<string, Json>;
+    messages: HodoscopeMessage[];
+}
+interface HodoscopeSourceMapEntry {
+    trajectoryId: string;
+    turnId: number;
+    traceId: string;
+    spanId: string;
+    evidenceUri: string;
+}
+interface HodoscopeInput {
+    directory: string;
+    trajectoryCount: number;
+    actionCount: number;
+    sourceMap: readonly HodoscopeSourceMapEntry[];
+}
+interface HodoscopeAnalyzerOptions {
+    command?: string;
+    commandArgs?: readonly string[];
+    /** Hodoscope 0.2.4 currently resolves on Python 3.11, not Python 3.13. */
+    pythonVersion?: string;
+    /** Parent directory for isolated per-run artifacts. */
+    outputDir?: string;
+    summarizeModel?: string;
+    embeddingModel?: string;
+    embeddingDimensions?: number;
+    maxWorkers?: number;
+    groupByAttribute?: string;
+    samplesPerGroup?: number;
+    projection?: 'pca' | 'tsne' | 'umap' | 'trimap' | 'pacmap';
+    timeoutMs?: number;
+}
+/** Convert OpenInference JSONL into Hodoscope's trajectory directory. */
+declare function writeHodoscopeInput(otlpPath: string, options?: {
+    directory?: string;
+    groupByAttribute?: string;
+}): Promise<HodoscopeInput>;
+/** Run Hodoscope as a behavior-discovery engine. Its output requires review. */
+declare function hodoscopeAnalyzer(options?: HodoscopeAnalyzerOptions): ExternalAnalyzer;
+
 /**
  * Live trace observer — compatibility wrapper behind `traces watch`.
  *
@@ -1805,4 +2100,4 @@ interface ExecuteOptions {
 /** Send the final, new outbound items (or write their dry-run OTLP). */
 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, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, CodexExecAdapter, CodexExecStreamError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EmptySessionError, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, type ParseOptions, PartialUploadError, 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 SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, indexSessionIdsByTrace, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, outboundHash, parseIsoToEpochMs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readJsonFile, readJsonl, readSessionIndexFile, recordSessionCorruption, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, span, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, traceAgenticKinds, traceStreamEventsFromSpans, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };
+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, type ChatTrajectory, type ChatTrajectoryMessage, type ChatTrajectoryOptions, ClaudeAdapter, CodexAdapter, CodexExecAdapter, CodexExecStreamError, CodexTaskScopeError, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, type CollectSessionSelectionOptions, type CollectSessionWorkflowOptions, CopilotAdapter, type CorruptionMode, DEFAULT_HARNESS, EmptySessionError, type ExecuteOptions, type ExternalAnalysisKind, type ExternalAnalysisPayload, type ExternalAnalysisResult, type ExternalAnalyzer, type ExternalAnalyzerOptions, type ExternalDiscoveryCandidate, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HaloAnalyzerOptions, type HaloReasoningEffort, type HarnessTraceAdapter, type HodoscopeAnalyzerOptions, type HodoscopeInput, type HodoscopeMessage, type HodoscopeSourceMapEntry, type HodoscopeTrajectory, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, JsonSourceError, type JsonlCorruptionReceipt, JsonlParseError, type JsonlReadOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, type ParentTaskResolution, type ParseOptions, PartialUploadError, 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 SessionCorruptionReceipt, type SessionIdentityConflict, type SessionIdentityIndex, type SessionIntegrity, type SessionRef, type SessionRelationship, type SessionRole, type SessionSeedGroup, type SessionSelection, type SessionSelectionRow, type SessionSourceFile, type SessionWorkflow, SessionWorkflowError, type SessionWorkflowErrorCode, type SessionWorkflowIssue, type SessionWorkflowSession, type SessionWorkflowSummary, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceAgenticRoute, type TraceAgenticRouteReason, type TraceAgenticRouteReasonCode, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceExecutionOptions, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveAction, type TraceLiveActionKind, type TraceLiveAnalysisContext, type TraceLiveAnalyst, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveLoop, type TraceLiveSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadIdentity, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, chatTrajectoryToSpans, classifyLiveActions, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessionSelection, collectSessionWorkflow, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, cwdMatchesSelection, defaultTraceLiveAnalysts, describeSessionRelationship, equivalentGitCwds, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, hodoscopeAnalyzer, indexSessionIdsByTrace, inspectSessionIndex, isChatTrajectory, isChatTrajectoryMessage, knownHarnesses, listAdapters, loadState, loadTracesConfig, locateSessions, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, outboundHash, parseIsoToEpochMs, parseSession, parseSince, planTraceAgenticRoute, planUpload, readJsonFile, readJsonl, readSessionIndexFile, recordSessionCorruption, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovement, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, sessionIdFromAttributes, sessionIntegrityAttributes, span, stampRepoAttrs, stampSessionIdentity, stampSessionIntegrity, stampSpanWorkdirRepoAttrs, streamSessions, summarizeOtlpExecution, summarizeSpanExecution, takeJsonl, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, traceAgenticKinds, traceStreamEventsFromSpans, uploadKey, userPromptSpan, validateOtlpSpans, watchSessions, writeHodoscopeInput, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };