@tangle-network/traces 0.8.5 → 0.8.12

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)
+- [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)
@@ -27,9 +28,12 @@ It reads the transcripts your harness leaves on disk, reconstructs the run as sp
 ## Install
 
 ```bash
-npm i -g @tangle-network/traces     # the `traces` CLI
-npx @tangle-network/traces analyze  # or run without installing
-npm i @tangle-network/traces        # or use it as a library
+curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
+traces --version
+
+npx --yes @tangle-network/traces@latest analyze --harness claude-code --last 1  # run without installing
+npm i -g @tangle-network/traces                                           # install manually
+npm i @tangle-network/traces                                              # use it as a library
 ```
 
 Requires Node ≥ 22.
@@ -86,6 +90,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 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
@@ -110,6 +116,27 @@ traces upload   --since 24h                        # upload last day to the Inte
 | `--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.
@@ -203,6 +230,7 @@ Merging to `main` publishes a patch release automatically:
 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.
+5. `pnpm check:package` proves the npm tarball contains the `traces` binary before 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.
 
@@ -214,6 +242,8 @@ 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 |