@tangle-network/traces 0.8.0 → 0.8.11

package/README.md

@@ -17,6 +17,8 @@ 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)
+- [Session index](#session-index)
+- [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)
@@ -85,6 +87,10 @@ 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 index    --all --since 24h --out session-index.json
+traces inspect  session-index.json --out inspection-report.md
+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 +105,71 @@ 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 |
 
+## Session index
+
+`traces index` writes one general JSON catalog over the selected sessions.
+It is meant for deeper investigation and joins with other local data, not for one specific workflow.
+
+```bash
+traces index --all --since 24h --out session-index.json
+traces inspect session-index.json --out inspection-report.md
+```
+
+The index contains:
+
+- selection metadata and aggregate totals
+- one row per session with harness, session id, path, cwd, repo labels, and time bounds
+- behavior metrics: spans, LLM turns, tool calls, tool errors, tokens, models, and tools
+- signal summaries: stuck loops and tool error rate
+- nearby context files for joins: `AGENTS.md`, `CLAUDE.md`, and `.evolve` JSONL / reflection artifacts, with markdown heading/ToC and JSONL key summaries
+
+`traces inspect` reads that index back and prints ranked improvement findings over the sessions and nearby context.
+It is intentionally read-only: it points to repeated-call loops, high tool-error sessions, missing repo attribution, long docs without Contents, invalid JSONL rows, and skill-run rows that cannot be joined back to a session.
+
+## 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).
@@ -155,6 +219,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 +238,11 @@ 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` |
+| `collectSessionIndex` | `(ScanOptions) → TraceSessionIndex` | scan sessions and return a reusable JSON-ready catalog |
+| `inspectSessionIndex` | `(TraceSessionIndex) → TraceInspectionReport` | rank improvement findings from an index without rescanning sessions |
+| `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`) |