@tangle-network/traces 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,659 @@
+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 } 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';
+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';
+
+/**
+ * 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`) AND the OpenInference
+ * OTLP form HALO consumes — so one emitted file feeds both engines.
+ *
+ * Attribute vocabulary the downstream analysts key off:
+ *   - `openinference.span.kind`  → span kind (AGENT | LLM | TOOL | CHAIN)
+ *   - `service.name`             → harness id (claude-code, codex, …)
+ *   - `agent.name`               → agent / subagent name
+ *   - `llm.model_name`           → model
+ *   - `llm.input_tokens` / `llm.output_tokens` → behavioral token trajectories
+ *   - `tool.name`                → tool histogram (monoculture / no-verify)
+ *   - `step`                     → run order (falls back to start_time)
+ */
+type OtlpSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'SPAN';
+type OtlpStatusCode = 'OK' | 'ERROR' | 'UNSET';
+interface OtlpSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    start_time: string;
+    end_time: string;
+    status: {
+        code: OtlpStatusCode;
+        message?: string;
+    };
+    attributes: Record<string, unknown>;
+}
+interface SpanInput {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string | null;
+    name: string;
+    kind: OtlpSpanKind;
+    startTime: string;
+    /** Defaults to startTime when the source has no explicit end. */
+    endTime?: string;
+    status?: OtlpStatusCode;
+    statusMessage?: string;
+    service?: string | null;
+    agent?: string | null;
+    model?: string | null;
+    tool?: string | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    /** Run-order pivot; the behavioral analyst orders trajectories by this. */
+    step?: number;
+    /** Verbatim content the agentic analysts read via regex search. */
+    content?: string | null;
+    /** Extra attributes merged last (escape hatch for harness-specific signal). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build one OTLP span line from a harness event. Only sets attribute keys
+ * that carry real signal — an absent token count is omitted, not zeroed,
+ * so the behavioral analyst's "no LLM data" case stays honest.
+ */
+declare function span(input: SpanInput): OtlpSpan;
+/** Serialize spans to OTLP-JSONL (one span per line, trailing newline). */
+declare function serializeSpans(spans: readonly OtlpSpan[]): string;
+/** Write spans to an OTLP-JSONL file (a temp file when no path is given). */
+declare function writeOtlpFile(spans: readonly OtlpSpan[], outPath?: string): Promise<string>;
+
+/**
+ * Harness trace adapter contract.
+ *
+ * Each coding-agent harness writes its session log in a different on-disk
+ * format. An adapter knows (a) where that harness stores sessions and
+ * (b) how to project one session file/dir onto normalized `OtlpSpan[]`.
+ *
+ * Adapters are the read counterpart of cli-bridge's existing per-harness
+ * `BackendModule` resume logic — they live next to the code that already
+ * locates these files.
+ */
+
+/** A single discovered session, before parsing. */
+interface SessionRef {
+    /** Harness id (matches the nix profile / backend name). */
+    harness: string;
+    /** Stable session identifier (uuid, thread id, or derived from path). */
+    sessionId: string;
+    /** Absolute path to the session file (or session root dir for split formats). */
+    path: string;
+    /** Working directory the session ran in, when recoverable. */
+    cwd: string | null;
+    /** Last-modified epoch ms — used for `--last N` recency ordering. */
+    mtimeMs: number;
+}
+interface LocateOptions {
+    /** Limit discovery to sessions whose cwd matches (exact or prefix). */
+    cwd?: string;
+    /** Only sessions modified at/after this epoch ms. */
+    sinceMs?: number;
+}
+interface HarnessTraceAdapter {
+    /** Canonical harness id this adapter handles. */
+    readonly harness: string;
+    /** Aliases that resolve to this adapter (forks / variants / ACP wrappers). */
+    readonly aliases?: readonly string[];
+    /** Discover session files for this harness on disk. */
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    /** Parse one discovered session into normalized OTLP spans. */
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Harness adapter registry — resolves a harness id (or alias) to the
+ * adapter that knows its on-disk session format.
+ *
+ * Format families collapse many harnesses onto few adapters:
+ *   - claude family (claude / claudish / openclaw / nanoclaw) share the
+ *     `~/.claude`-style transcript JSONL
+ *   - codex family (codex / codex-acp) share the rollout JSONL
+ *   - gemini (gemini-cli) and its fork qwen (qwen-code) share the chat JSON
+ *     under distinct home dirs
+ *   - factory-droids (droid) has its own `~/.factory` rollout JSONL
+ */
+
+declare function listAdapters(): readonly HarnessTraceAdapter[];
+declare function resolveAdapter(harness: string): HarnessTraceAdapter | undefined;
+declare function knownHarnesses(): string[];
+
+/**
+ * Claude Code adapter — `~/.claude/projects/<encoded-cwd>/<session>.jsonl`.
+ *
+ * Each line is one transcript event: `user`, `assistant`, `attachment`,
+ * plus metadata events we ignore. Assistant events carry `message.usage`
+ * (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
+ * `<session>/subagents/agent-*.jsonl` with a `.meta.json` carrying the
+ * spawning `toolUseId`, so we parent each subagent under its `Agent` call.
+ *
+ * Shared by the claudish / openclaw / nanoclaw forks via aliases — they
+ * write the same transcript shape.
+ */
+
+declare class ClaudeAdapter implements HarnessTraceAdapter {
+    readonly harness = "claude-code";
+    readonly aliases: readonly ["claude", "claudish", "openclaw", "nanoclaw"];
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+    /** Parse `<session>/subagents/agent-*.jsonl`, parenting each under its Agent call. */
+    private foldSubagents;
+}
+
+/**
+ * OpenAI Codex adapter — `~/.codex/sessions/<Y>/<M>/<D>/rollout-*.jsonl`.
+ *
+ * Line types: `session_meta` (id + cwd), `turn_context`, `event_msg`
+ * (carries `token_count` with per-turn `last_token_usage`), and
+ * `response_item` (the OpenAI Responses items: `message`, `reasoning`,
+ * `function_call`, `function_call_output`).
+ *
+ * Token trajectory comes from the `token_count` deltas (Codex puts usage
+ * on events, not on the message). Tools come from `function_call`, with
+ * status backfilled from the matching `function_call_output`.
+ *
+ * Shared by the codex-acp wrapper via alias (same rollout format).
+ */
+
+declare class CodexAdapter implements HarnessTraceAdapter {
+    readonly harness = "codex";
+    readonly aliases: readonly ["codex-acp"];
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * OpenCode adapter — `~/.local/share/opencode/storage/`.
+ *
+ * Split storage: `message/<sessionID>/<messageID>.json` carries role +
+ * `tokens` + `modelID` + `time`; `part/<messageID>/<partID>.json` carries
+ * the turn's parts (`text`, `reasoning`, `tool`, `step-*`). Tool parts
+ * hold `tool`, `callID`, and `state.{status,error}` — `status === 'error'`
+ * marks a failed call.
+ */
+
+declare class OpencodeAdapter implements HarnessTraceAdapter {
+    readonly harness = "opencode";
+    private storage;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Gemini CLI family — `<home>/tmp/<projectHash>/chats/session-*.json`.
+ *
+ * One JSON object per chat: `{ sessionId, projectHash, messages[] }`.
+ * Each message carries `model`, `tokens.{input,output}`, `content`, and
+ * `toolCalls[]` with `{ name, args, status, result }`.
+ *
+ * Gemini CLI only — Qwen Code forked and diverged (flat Claude-style
+ * JSONL under `~/.qwen/projects/`); it has its own adapter.
+ */
+
+interface GeminiFamilyConfig {
+    harness: string;
+    service: string;
+    /** Directory under $HOME holding `tmp/<hash>/chats/` (e.g. '.gemini', '.qwen'). */
+    homeDirName: string;
+    aliases?: readonly string[];
+}
+/** Shared base for Gemini CLI and its forks (Qwen Code). */
+declare class GeminiFamilyAdapter implements HarnessTraceAdapter {
+    readonly harness: string;
+    readonly aliases?: readonly string[];
+    private readonly service;
+    private readonly homeDirName;
+    constructor(cfg: GeminiFamilyConfig);
+    private chatsRoot;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+declare class GeminiAdapter extends GeminiFamilyAdapter {
+    constructor();
+}
+
+/**
+ * Qwen Code adapter — `~/.qwen/projects/<dashed-cwd>/chats/<sessionId>.jsonl`.
+ *
+ * Schema confirmed from QwenLM/qwen-code source (chatRecordingService.ts):
+ * flat Claude-Code-style `ChatRecord` per JSONL line — NOT the Gemini CLI
+ * wrapper. `type` ∈ user|assistant|tool_result|system; `message` is a raw
+ * `@google/genai` Content `{ role, parts[] }`; tokens use Gemini-API names
+ * in `usageMetadata`; tool calls/results are `functionCall`/`functionResponse`
+ * parts.
+ *
+ * Schema-from-source; parse unverified against local data (no `~/.qwen`
+ * sessions on this machine).
+ */
+
+declare class QwenAdapter implements HarnessTraceAdapter {
+    readonly harness = "qwen";
+    readonly aliases: readonly ["qwen-code"];
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Factory Droid adapter — `~/.factory/sessions/<encoded-cwd>/<uuid>.jsonl`
+ * plus a `<uuid>.settings.json` sidecar.
+ *
+ * Confirmed from disk + two parsers (droid-sync-plugin, tokscale): the JSONL
+ * has only `session_start` and `message` lines; `message.content[]` carries
+ * Anthropic-style blocks (`text`, `thinking`, `tool_use`, `tool_result`). The
+ * sidecar holds `model` and session-total `tokenUsage` — there is NO per-turn
+ * usage in the transcript, so token-growth can't be computed for Factory (the
+ * tool/loop signals still work). `<encoded-cwd>` is slash→dash. Tool-error
+ * flag (`is_error`) is inferred (Anthropic convention), not source-confirmed.
+ */
+
+declare class FactoryAdapter implements HarnessTraceAdapter {
+    readonly harness = "factory";
+    readonly aliases: readonly ["factory-droids", "droid"];
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Pi adapter — `~/.pi/agent/sessions/<encoded-cwd>/<ts>_<uuid>.jsonl`.
+ *
+ * Line types: `session` (id + cwd), `model_change`, `thinking_level_change`,
+ * and `message`. A `message` line wraps `message.{role, model, provider,
+ * content[], usage.{input,output}, stopReason, errorMessage}`. Tool calls
+ * ride inside `message.content[]` as tool blocks.
+ */
+
+declare class PiAdapter implements HarnessTraceAdapter {
+    readonly harness = "pi";
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Sourcegraph Amp adapter — `${XDG_DATA_HOME:-~/.local/share}/amp/threads/T-*.json`.
+ *
+ * One JSON object per thread: `{ id, created, messages[], usageLedger }`.
+ * Messages carry `role`, `usage` (camelCase on disk: `model`, `inputTokens`,
+ * `outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`) and
+ * Anthropic-style `content[]` blocks (`text`, `tool_use`, `tool_result` with
+ * `is_error`).
+ *
+ * Path/format/usage from the `tokscale` parser (high conf); content-block
+ * field names medium-conf; parse unverified against local data.
+ */
+
+declare class AmpAdapter implements HarnessTraceAdapter {
+    readonly harness = "amp";
+    private threadsRoot;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * GitHub Copilot CLI adapter — `${COPILOT_HOME:-~/.copilot}/session-state/<id>/events.jsonl`.
+ *
+ * Event envelope per line: `{ id, timestamp, parentId, type, data }`. Relevant
+ * types: `assistant.message` (`outputTokens`, `toolRequests[]`),
+ * `tool.execution_start` (`toolCallId`, `toolName`, `arguments`),
+ * `tool.execution_complete` (`toolCallId`, `success`, `error{message}`, `model`),
+ * `assistant.usage` (ephemeral: `model`, `inputTokens`, `outputTokens`).
+ *
+ * Sub-agents interleave in the same stream — tool calls/results are joined by
+ * `toolCallId`, never adjacency. Lines may contain stray newlines/separators;
+ * parse line-tolerant. Schema from GitHub docs (high conf); parse unverified
+ * against local data.
+ */
+
+declare class CopilotAdapter implements HarnessTraceAdapter {
+    readonly harness = "github-copilot";
+    readonly aliases: readonly ["copilot"];
+    private root;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Forge adapter (antinomyhq/forge) — `/dump` JSON exports.
+ *
+ * Forge's primary store is SQLite (`~/.forge/.forge.db`, `conversations.context`
+ * column). Reading it live needs a native sqlite dep, so v1 parses the
+ * dependency-free `/dump` artifact instead: `<cwd>/YYYY-MM-DD_HH-MM-SS-dump.json`,
+ * a single flattened `Context{ conversation_id, messages[] }`.
+ *
+ * Flattened message entry (from forge Rust serde, high conf): `{ text: {role,
+ * content, tool_calls?[], model?}, usage }` or `{ tool: {name, call_id?,
+ * output:{is_error, values}}, usage }`. Tokens are `TokenCount` = `{actual:N}`
+ * or `{approx:N}`. Parse unverified against local data.
+ */
+
+declare class ForgeAdapter implements HarnessTraceAdapter {
+    readonly harness = "forge";
+    readonly aliases: readonly ["forgecode"];
+    /** Directories scanned for `*-dump.json` exports. */
+    private dumpDirs;
+    locate(opts?: LocateOptions): Promise<SessionRef[]>;
+    parse(ref: SessionRef): Promise<OtlpSpan[]>;
+}
+
+/**
+ * Run agent-eval's shipped trace pipelines over normalized harness spans.
+ *
+ * These are the deterministic loop/thrash detectors that already exist in
+ * `@tangle-network/agent-eval`:
+ *   - stuckLoopView         — same tool + same args ≥ N times (the loop signal)
+ *   - computeToolUseMetrics — duplicate-call / retry / error rates per run
+ *
+ * `toolWasteView` is intentionally NOT used: its default heuristic needs
+ * verbatim tool *results* + per-turn LLM `messages`, which traces
+ * doesn't capture from harness logs (we store tool args + error status). Its
+ * signal — repeated/failed calls — is already covered by the duplicate/retry/
+ * error rates above, so adding it would only emit a misleading waste %.
+ *
+ * Both are cheap ($0, deterministic), so they're safe to run continuously in
+ * `watch` mode, over the OTLP spans traces already produces.
+ */
+
+interface PipelineReport {
+    stuckLoops: StuckLoopReport;
+    toolUse: ToolUseMetrics[];
+}
+interface PipelineOptions {
+    /** Minimum repeated identical calls to flag a loop (default 3). */
+    minLoopOccurrences?: number;
+}
+declare function runPipelines(spans: readonly OtlpSpan[], opts?: PipelineOptions): Promise<PipelineReport>;
+
+/**
+ * Project normalized `OtlpSpan[]` onto agent-eval's runtime trace store.
+ *
+ * The behavioral/agentic analysts consume the OTLP analyst store; the
+ * loop/waste pipelines (`stuckLoopView`, `toolWasteView`) and tool-use
+ * metrics consume the runtime `TraceStore` (`Span` with `toolName`/`args`/
+ * `startedAt`). This converter is the single bridge — one function, every
+ * harness — so traces reuses those shipped detectors instead of
+ * reimplementing loop/stall detection.
+ *
+ * Tool `args` is the verbatim tool input we stored on the span's `content`;
+ * `stuckLoopView` hashes it (`argHash`) so identical repeated calls collapse
+ * to one loop finding.
+ */
+
+interface RuntimeTrace {
+    store: InMemoryTraceStore;
+    runIds: string[];
+}
+declare function toRuntimeStore(spans: readonly OtlpSpan[]): Promise<RuntimeTrace>;
+
+/**
+ * Run the agent-eval analyst suite over normalized spans.
+ *
+ * Spans → OTLP-JSONL file → `OtlpFileTraceStore` → `buildDefaultAnalystRegistry`.
+ * With no Ax service the deterministic behavioral analyst runs alone (zero
+ * LLM, model-agnostic). Supply `ai` to add the agentic RLM kinds
+ * (failure-mode / knowledge-gap / knowledge-poisoning / improvement).
+ *
+ * The written OTLP file is the canonical artifact — the same file feeds HALO
+ * (`halo <file> -p "diagnose"`), so analysis is never locked to one engine.
+ */
+
+interface AnalyzeOptions {
+    /** Ax service enabling the agentic RLM kinds. Omit → deterministic only. */
+    ai?: AxAIService;
+    model?: string;
+    /** USD cap across agentic analysts. */
+    budgetUsd?: number;
+    /**
+     * Bring your own analyst suite. When set, this registry runs over the trace
+     * store INSTEAD of the built-in deterministic suite — the seam for running
+     * your own agents/detectors over sessions. Register custom `Analyst`s with
+     * `@tangle-network/agent-eval`'s `AnalystRegistry`.
+     */
+    registry?: AnalystRegistry;
+    /** Where to write the OTLP-JSONL artifact. Defaults to a temp file. */
+    otlpOutPath?: string;
+    runId?: string;
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+}
+interface AnalyzeResult {
+    /** Path to the OTLP-JSONL artifact (feeds HALO too). */
+    otlpPath: string;
+    result: Awaited<ReturnType<ReturnType<typeof buildDefaultAnalystRegistry>['run']>>;
+}
+declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
+
+/**
+ * Live trace observer — the reusable, event-driven core behind `traces watch`.
+ *
+ * `watchSessions` tails active coding-agent sessions across harnesses and emits
+ * structured events as it goes: every session's pipeline report each tick
+ * (`onReport`), and a deduped signal whenever a stuck loop first appears or
+ * grows (`onLoop`). It's read-only (never touches the agent or its harness) and
+ * cancellable via an `AbortSignal`, so a third party can subscribe to the live
+ * findings stream and feed it into any system — a dashboard, an alerter, a
+ * steering layer, or another agent — without shelling out to the CLI.
+ */
+
+/** A newly-observed (or grown) stuck loop in a live session. */
+interface ObservedLoop {
+    harness: string;
+    sessionId: string;
+    cwd: string | null;
+    toolName: string;
+    argHash: string;
+    /** Identical repeated calls observed so far. */
+    occurrences: number;
+    /** Milliseconds between the first and last call in the loop. */
+    windowMs: number;
+}
+interface ObserverOptions {
+    /** Harness ids/aliases to observe. Omit (or pass `all: true`) → every harness. */
+    harnesses?: string[];
+    all?: boolean;
+    /** Observe these adapters instead of the built-in registry — plug in your
+     *  own `HarnessTraceAdapter`s. Takes precedence over `harnesses`/`all`. */
+    adapters?: HarnessTraceAdapter[];
+    /** Only observe sessions whose cwd matches (exact/prefix). */
+    cwd?: string;
+    /** Consider sessions active within this window (ms). Default 30 min. */
+    windowMs?: number;
+    /** Poll interval (ms). Default 5 s. */
+    intervalMs?: number;
+    /** Min identical repeated calls before a loop is reported. Default 3. */
+    minLoopOccurrences?: number;
+    /** Cancel the observer; `watchSessions` resolves when this aborts. */
+    signal?: AbortSignal;
+    /** Fired once per stuck loop the first time it reaches threshold, and again
+     *  each time its occurrence count grows — deduped so you only see new signal. */
+    onLoop?: (loop: ObservedLoop) => void | Promise<void>;
+    /** Fired for every observed session each tick, with its full pipeline report
+     *  (stuck loops + tool-use metrics) — react to anything, not just loops. */
+    onReport?: (ref: SessionRef, report: PipelineReport) => void | Promise<void>;
+    /** Per-session parse/pipeline error (the observer keeps going). */
+    onError?: (error: unknown, ref?: SessionRef) => void;
+    /** Fired after each poll cycle. */
+    onTick?: (stats: {
+        sessions: number;
+    }) => void;
+}
+/**
+ * Observe active sessions until `opts.signal` aborts. Returns a promise that
+ * resolves on abort. Errors in a single session are routed to `onError` and
+ * never stop the loop.
+ */
+declare function watchSessions(opts: ObserverOptions): Promise<void>;
+
+/**
+ * Privacy redaction for trace spans before upload.
+ *
+ * Reuses agent-eval's `redactValue` + `DEFAULT_REDACTION_RULES` (email, IPs,
+ * generic secret keys, …) and layers on coding-session-specific rules that the
+ * defaults miss — GitHub tokens, cloud keys, JWTs, bearer headers, private-key
+ * blocks, and `key=secret` assignments common in shell/tool output. Redaction
+ * runs over every span attribute + status message, so what leaves the machine
+ * is already scrubbed.
+ */
+
+/** Secrets common in coding-agent traces that the substrate defaults don't cover. */
+declare const CODING_REDACTION_RULES: RedactionRule[];
+/** Defaults + coding-session rules — the rule set used for upload. */
+declare const TRACES_REDACTION_RULES: RedactionRule[];
+interface SpanRedaction {
+    spans: OtlpSpan[];
+    report: RedactionReport;
+}
+/** Redact every span's attributes + status message. Returns scrubbed spans and
+ *  an aggregate report (count + per-rule breakdown) over the whole set. */
+declare function redactSpans(spans: readonly OtlpSpan[], rules?: RedactionRule[]): SpanRedaction;
+
+/**
+ * Batch collection seam — `collectSessions` returns redacted spans per session
+ * for a time window / harness selection, so a third party can feed batches or
+ * clusters of traces into their own system (their own analysts, a vector store,
+ * a fine-tune corpus, …) without the upload/dedup machinery.
+ *
+ * Redaction is ON by default — the safe posture when traces leave the box.
+ */
+
+interface CollectOptions {
+    /** Harness ids/aliases. Omit (or `all: true`) → every harness. */
+    harnesses?: string[];
+    all?: boolean;
+    /** Collect from these adapters instead of the built-in registry. */
+    adapters?: HarnessTraceAdapter[];
+    /** Filter by working directory (exact/prefix). */
+    cwd?: string;
+    /** Only sessions modified at/after this epoch ms. */
+    sinceMs?: number;
+    /** Cap to the most-recent N sessions per harness. */
+    last?: number;
+    /** Redact PII/secrets (default true). Set false to get raw spans. */
+    redact?: boolean;
+    /** Called on a per-adapter locate/parse failure (collection continues). */
+    onError?: (error: unknown, ref?: SessionRef) => void;
+}
+interface SessionBatch {
+    ref: SessionRef;
+    spans: OtlpSpan[];
+    /** Present when redaction ran (the default). */
+    redaction?: RedactionReport;
+}
+/** Select + parse (+ redact) sessions into per-session span batches. */
+declare function collectSessions(opts?: CollectOptions): Promise<SessionBatch[]>;
+
+/**
+ * Local upload-dedup state.
+ *
+ * Persists which sessions have been uploaded (keyed by harness:sessionId →
+ * content hash) so re-running `upload` over an overlapping window doesn't
+ * re-send unchanged sessions. The hash is over the redacted span structure, so
+ * a session that has GROWN since last upload re-uploads (new spans), while an
+ * unchanged one is skipped. Pairs with the server-side `idempotency-key` for
+ * belt-and-suspenders dedup.
+ */
+
+interface UploadRecord {
+    hash: string;
+    uploadedAt: string;
+    harness: string;
+    spanCount: number;
+}
+/** Keyed by `${harness}:${sessionId}`. */
+type UploadState = Record<string, UploadRecord>;
+declare function uploadKey(harness: string, sessionId: string): string;
+/** Stable content hash of a session's (redacted) spans — changes iff the
+ *  session's span set changes, so a grown session re-uploads. */
+declare function sessionHash(spans: readonly OtlpSpan[]): string;
+declare function loadState(): Promise<UploadState>;
+declare function saveState(state: UploadState): Promise<void>;
+/** True when this session+hash has already been uploaded. */
+declare function alreadyUploaded(state: UploadState, harness: string, sessionId: string, hash: string): boolean;
+
+/**
+ * Upload local coding-session traces to the Tangle Intelligence Platform.
+ *
+ * Pipeline per session: locate (time window) → parse to OTLP spans → REDACT
+ * (PII/secrets) → augment with metadata → dedup (skip unchanged, already-sent
+ * sessions) → POST via the hosted `ingestTraces` client. The redaction happens
+ * before anything leaves the machine; the dedup is local-state + server
+ * idempotency-key.
+ *
+ * `planUpload` is read-only (select + redact + dedup); `executeUpload` does the
+ * actual send (or, with `dryRun`, writes the redacted OTLP it *would* send).
+ */
+
+interface UploadItem {
+    ref: SessionRef;
+    /** Redacted spans (safe to send). */
+    spans: OtlpSpan[];
+    redaction: RedactionReport;
+    hash: string;
+    isNew: boolean;
+}
+interface UploadPlan {
+    items: UploadItem[];
+    state: UploadState;
+    sinceMs?: number;
+}
+interface PlanOptions {
+    harness?: string;
+    all?: boolean;
+    cwd?: string;
+    sinceMs?: number;
+    /** Called on a per-adapter locate/parse failure (planning continues). */
+    onError?: (error: unknown, ref?: SessionRef) => void;
+}
+/** Read-only: select sessions in the window, redact, and mark which are new. */
+declare function planUpload(opts: PlanOptions): Promise<UploadPlan>;
+/** Map redacted OtlpSpan[] → the hosted TraceSpanEvent[] wire shape, attaching
+ *  session metadata to the root span(s). */
+declare function toTraceSpanEvents(spans: readonly OtlpSpan[], rootMeta: Record<string, string | number | boolean>): TraceSpanEvent[];
+interface UploadResult {
+    uploadedSessions: number;
+    skippedSessions: number;
+    acceptedSpans: number;
+    redactionCount: number;
+    dryRun: boolean;
+    otlpPath?: string;
+}
+/** A trace sink. The hosted client satisfies this; pass your own to route
+ *  redacted+deduped traces into a different system. */
+interface UploadBackend {
+    ingestTraces(spans: TraceSpanEvent[], idempotencyKey?: string): Promise<{
+        accepted: number;
+    }>;
+}
+interface ExecuteOptions {
+    dryRun?: boolean;
+    /** Where to write the redacted OTLP-JSONL on a dry run. */
+    otlpOut?: string;
+    /** Custom sink. Defaults to the hosted Tangle Intelligence client from env. */
+    backend?: UploadBackend;
+    log?: (msg: string) => void;
+}
+/** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
+declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
+
+export { AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, type ExecuteOptions, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type RuntimeTrace, 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, collectSessions, executeUpload, knownHarnesses, listAdapters, loadState, planUpload, redactSpans, resolveAdapter, runPipelines, saveState, serializeSpans, sessionHash, span, toRuntimeStore, toTraceSpanEvents, uploadKey, watchSessions, writeOtlpFile };