@tangle-network/traces 0.7.0 → 0.8.5

package/README.md

@@ -17,6 +17,7 @@ It reads the transcripts your harness leaves on disk, reconstructs the run as sp
 - [What it finds](#what-it-finds)
 - [Supported harnesses](#supported-harnesses)
 - [CLI reference](#cli-reference)
+- [Policy-mining evidence](#policy-mining-evidence)
 - [Upload to the Intelligence Platform](#upload-to-the-intelligence-platform)
 - [External engines (bring your own)](#external-engines-bring-your-own)
 - [Library (SDK)](#library-sdk)
@@ -43,7 +44,7 @@ That's the command in the demo above. The **deterministic pass** — stuck loops
 
 Add `--llm` for the **agentic analysts** (failure-mode / knowledge-gap / knowledge-poisoning / improvement); they call OpenAI and respect `--budget <usd>`.
 
-Every run also writes an **OTLP-JSONL artifact**, and you can run external engines like [HALO](https://github.com/context-labs/halo) over it with `--analyzer halo` (traces converts our spans to the canonical OpenInference shape HALO needs) — see [External engines](#external-engines-bring-your-own). Analysis is never locked to one engine.
+Every run also writes a **canonical OpenInference JSONL artifact**, so you can run external engines like [HALO](https://github.com/context-labs/halo) over it directly with `--analyzer halo` — see [External engines](#external-engines-bring-your-own). Analysis is never locked to one engine.
 
 ## What it finds
 
@@ -85,6 +86,8 @@ traces list     --harness claude-code --last 20    # discover sessions
 traces analyze  --harness codex --last 1           # $0 deterministic report
 traces analyze  --all --since 2026-06-18 --out report.md
 traces convert  --harness claude-code --last 1 --otlp spans.jsonl   # OTLP only
+traces evidence --harness codex --last 20 --out policy-evidence.jsonl
+traces export   policy-evidence.jsonl --out spans.openinference.jsonl
 traces watch    --all                              # live observer; notify on stuck loops
 traces upload   --since 1h --dry-run               # redact + dedup + preview, no network
 traces upload   --since 24h                        # upload last day to the Intelligence Platform
@@ -99,13 +102,50 @@ traces upload   --since 24h                        # upload last day to the Inte
 | `--cwd <dir>` | Filter by working directory |
 | `--since <t>` | `upload`: window — `30m`/`2h`/`7d` or ISO (default 24h); `analyze`: ISO cutoff |
 | `--out <path>` | Write the report to a file |
-| `--otlp <path>` | OTLP artifact path (also the dry-run upload preview) |
+| `--otlp <path>` | OTLP artifact path (also evidence provenance / dry-run upload preview) |
+| `--format <kind>` | `export`: `auto`, `policy-evidence`, `sandbox-events`, or `openinference` |
 | `--llm` / `--budget <usd>` | Enable agentic analysts (needs `OPENAI_API_KEY`) / cap their spend |
 | `--interval <s>` / `--window <m>` | `watch`: poll seconds (default 5) / active-session window minutes (default 30) |
 | `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
 | `--no-content` | `upload`: send metadata only — strip all prompt/response text |
 | `--dry-run` / `--yes` | `upload`: preview without sending / skip the confirm prompt |
 
+## Policy-mining evidence
+
+`traces` does **not** emit benchmark campaign cells. It emits normalized coding-agent session evidence that another system can mine.
+
+```bash
+traces evidence --all --since 24h --out policy-evidence.jsonl --otlp spans.otlp.jsonl
+```
+
+Each JSONL row is one session:
+
+- session provenance: harness, session id, cwd, path, mtime
+- repo labels: `tangle.subject.key`, `git.repository`, branch, commit
+- behavior metrics: span counts, LLM turns, tool calls, errored tool calls, tokens, models, tool histogram
+- mining signals: stuck loops and tool error rate
+- provenance marker: `notCampaignCell: true`
+
+That boundary matters. `agent-lab` campaign `cells.jsonl` says "arm X beat arm Y on task Z." `traces evidence` says "this real agent session had this repo/model/tool/failure shape." A downstream policy compiler can cluster these rows, propose candidate policies, then validate those policies in a separate eval campaign.
+
+### Export existing evidence/events to OpenInference
+
+If you already have compact evidence or Sandbox/OpenCode event captures on disk, convert them to the same OpenInference JSONL shape that `traces analyze --analyzer halo` uses:
+
+```bash
+traces export policy-evidence.jsonl --out spans.openinference.jsonl
+traces export sandbox-events.json --format sandbox-events --out spans.openinference.jsonl
+halo spans.openinference.jsonl --prompt "Analyze this trace slice" --max-turns 1
+```
+
+`traces export` accepts:
+
+- compact `traces.policy_evidence.session` JSONL from `traces evidence`
+- Sandbox/OpenCode JSON arrays with `start`, `raw`, `result`, `done`, and `error` events
+- existing OpenInference JSONL, rewritten through the local redaction path
+
+Run `traces export --help` for the full command reference.
+
 ## Upload to the Intelligence Platform
 
 `upload` **redacts locally before anything leaves the machine**, dedups against already-uploaded sessions, and tags each with metadata (harness, cwd, git branch, host).
@@ -142,7 +182,7 @@ traces analyze --last 1 --analyzer halo --analyzer-prompt "find token waste"
 traces analyze --last 1 --analyzer halo --analyzer my-engine    # repeatable
 ```
 
-HALO needs canonical OpenInference, so `--analyzer halo` converts our spans automatically (`toCanonicalOpenInference`). HALO runs its *own* LLM (OpenAI client — set `OPENAI_BASE_URL` / `OPENAI_API_KEY`, or use HALO's provider); `--model` is forwarded to it. traces supplies the trace and drives the CLI; it doesn't pay for or configure HALO's model.
+Our OTLP artifact is **canonical OpenInference** (top-level `kind`, `resource`, `scope`), so HALO reads it directly — no conversion. HALO runs its *own* LLM (OpenAI client — set `OPENAI_BASE_URL` / `OPENAI_API_KEY`, or use HALO's provider); `--model` is forwarded to it. traces supplies the trace and drives the CLI; it doesn't pay for or configure HALO's model.
 
 **Redactors** scrub prompt/response prose with an external PII model (catching names/addresses the regex pass can't), running *after* the built-in redaction:
 
@@ -155,6 +195,17 @@ In the SDK these are the `ExternalAnalyzer` and `Redactor` interfaces (`haloAnal
 
 > For the built-in agentic analysts (`--llm`), set `OPENAI_API_KEY` — or point at any OpenAI-compatible gateway with `OPENAI_BASE_URL` (e.g. an internal router) to use a non-OpenAI key.
 
+## Release automation
+
+Merging to `main` publishes a patch release automatically:
+
+1. The Publish workflow bumps `package.json` from `X.Y.Z` to `X.Y.(Z+1)`.
+2. It commits `chore(release): vX.Y.(Z+1) [skip release]` back to `main`.
+3. It pushes the matching `vX.Y.(Z+1)` tag.
+4. The same workflow verifies the tag, builds, publishes to npm, and creates a GitHub release.
+
+Minor releases are manual. Run the Publish workflow from GitHub Actions and choose `minor`; it publishes `X.(Y+1).0`. Use manual `patch` only when you need a patch release without merging a new code change.
+
 ## Library (SDK)
 
 The CLI is a thin consumer of these exports.
@@ -163,6 +214,9 @@ The CLI is a thin consumer of these exports.
 |---|---|---|
 | `analyzeSpans` | `(spans, { registry?, ai?, budgetUsd? }) → AnalyzeResult` | run analysts — built-in, or **your own** via `registry` |
 | `watchSessions` | `(ObserverOptions) → Promise<void>` | live observer; `onLoop` / `onReport` / `signal` / `adapters` |
+| `buildPolicyEvidenceRecord` | `(ref, spans, opts?) → PolicyEvidenceRecord` | summarize one session for downstream policy mining |
+| `collectPolicyEvidence` | `(ScanOptions) → PolicyEvidenceRecord[]` | scan harness sessions and emit policy-evidence rows |
+| `exportTraceEvidenceFile` | `(path, opts?) → { format, spans, redactionCount }` | convert compact evidence/events/OpenInference files to redacted OpenInference spans |
 | `scanSessions` | `(ScanOptions) → AsyncIterable<ScannedSession>` | the shared locate→parse iterator |
 | `collectSessions` | `(CollectOptions) → SessionBatch[]` | redacted per-session batches for your own pipeline |
 | `redactSpans` | `(spans, rules?) → { spans, report }` | PII/secret redaction (`TRACES_REDACTION_RULES`) |