@tangle-network/traces 0.19.0 → 0.20.0

package/README.md

@@ -1,6 +1,6 @@
 # traces
 
-> Point `traces` at any agent trace — OTLP spans your own system emits, or the session logs Claude Code, Codex, OpenCode and Gemini already write to disk. Get failure-mode and efficiency findings, plus a straight answer about what the trace cannot tell you. A CLI *and* an SDK.
+> Point `traces` at any agent trace — OTLP spans your own system emits, or the session logs Claude Code, Codex, OpenCode, Pi, Kimi, Factory and Gemini already write to disk. Get failure-mode and efficiency findings, plus a straight answer about what the trace cannot tell you. A CLI *and* an SDK.
 
 ![traces analyzing a real Claude Code session](https://raw.githubusercontent.com/tangle-network/traces/main/docs/demo.gif)
 
@@ -33,6 +33,7 @@ Emitting the contract is the supported way to integrate a new system. The adapte
 - [Improvement engine](#improvement-engine)
 - [Ask questions](#ask-questions)
 - [Session facts](#session-facts)
+- [Skill usage](#skill-usage)
 - [Diff two runs](#diff-two-runs)
 - [MCP server](#mcp-server)
 - [Session index](#session-index)
@@ -261,20 +262,22 @@ not the way to integrate a system you own — for that, [emit the contract](#int
 | `claude-code` (`claude`, `claudish`, `openclaw`, `nanoclaw`) | `~/.claude/projects/<cwd>/*.jsonl` (+ subagent sidechains), or an explicit `claude -p --output-format stream-json --verbose` JSONL file | verified |
 | `codex` (`codex-acp`) | `~/.codex/sessions/**/rollout-*.jsonl` | verified |
 | `codex-exec` (`codex-json`) | explicit `codex exec --json` JSONL file | fixture |
-| `opencode` | `~/.local/share/opencode/storage/` | verified |
+| `opencode` | `~/.local/share/opencode/opencode.db` (shared reader), plus historical `storage/` JSON sessions (legacy reader) | verified |
 | `gemini` (`gemini-cli`) | `~/.gemini/tmp/<hash>/chats/session-*.json` | verified |
 | `pi` | `~/.pi/agent/sessions/<cwd>/*.jsonl` | verified |
-| `factory` (`factory-droids`, `droid`) | `~/.factory/sessions/<cwd>/*.jsonl` + `.settings.json` sidecar | locate verified, parse fixture |
+| `kimi` (`kimi-code`) | `~/.kimi/sessions/<cwd hash>/<session id>/wire.jsonl` | verified |
+| `factory` (`factory-droids`, `droid`) | `~/.factory/sessions/<cwd>/*.jsonl` + `.settings.json` sidecar | verified |
 | `qwen` (`qwen-code`) | `~/.qwen/projects/<cwd>/chats/*.jsonl` | fixture |
 | `amp` | `~/.local/share/amp/threads/T-*.json` | fixture |
 | `github-copilot` (`copilot`) | `~/.copilot/session-state/<id>/events.jsonl` | fixture |
 | `forge` (`forgecode`) | `/dump` JSON exports | fixture |
 
 Every adapter captures the conversation stored in one session file: the **user's prompt** and the **assistant's response** text, plus tool calls/results and token usage.
+Claude Code, Codex, current OpenCode, Pi, Kimi, and Factory read native records through [`@tangle-network/harness-sessions`](https://github.com/tangle-network/agent-sdk/tree/main/packages/harness-sessions); traces adds conversation and workflow spans over its model and tool calls. Historical OpenCode JSON sessions remain readable through the older adapter because their IDs do not overlap the SQLite store. Kimi's wire log has no served-model field, so its model remains unknown rather than being guessed.
 Claude Code's nested subagent files are folded into the parent trace.
 Claude Code's stream-json output also records the tools the harness offered the model and whether the run failed.
 The root span keeps them as `gen_ai.tool.definitions` and `run.status`, so a trace contract can check what the harness enforced.
-Claude source UUIDs remain searchable in `traces.claude.source_*` attributes, while exported OTLP IDs use deterministic `deriveHexId` values.
+Exported native-session span IDs derive deterministically from the session and record IDs.
 The Claude transcript proves turns and tool calls, but does not prove loop iterations or causal links, so those fields remain absent.
 Codex stores each worker in a separate session file; add `--workflow` to resolve the connected coordinator and worker files.
 `github-copilot` is the one exception: its log format carries no user prompt.
@@ -294,6 +297,7 @@ traces investigate --all --last 10 --out report.md  # explicit investigation ali
 traces improve --all --last 10 --dir .traces/improvement
 traces ask --harness codex --session <id> --question "Which commands failed?"
 traces facts --harness codex --session <id>        # the deterministic facts sheet, $0
+traces skills --since 30d                          # skill use across every local session, incremental, $0
 traces diff  run-a.otlp.jsonl run-b.otlp.jsonl      # where two runs of one task first diverge
 traces mcp   --otlp spans.otlp.jsonl                # read-only trace tools for an MCP client
 traces analyze  --all --since 2026-06-18 --out report.md
@@ -632,6 +636,37 @@ Three rules hold for every field:
 
 The same sheet reaches the model-backed analysts as prepared context, before their first model call — see [Trace analysts](docs/trace-analysts.md#session-facts-as-prepared-context).
 
+## Skill usage
+
+`traces skills` indexes skill records in Claude Code, Codex, and Kimi Code sessions on this machine.
+It makes no model call.
+
+```bash
+traces skills                     # every stored event, with the installed catalog joined
+traces skills --since 30d         # one window
+traces skills --unused            # installed skills with no use in the window, one per line
+traces skills --format json       # rows, unused skills, refresh cost and sweep exclusions
+traces skills --no-refresh        # answer from the store without reading transcripts
+```
+
+A run reads only transcript bytes appended since the previous run.
+It parses only lines that can carry a skill record and stores the events in `~/.local/state/traces/skill-usage.json` (`--store`).
+The first run reads the whole corpus: about two minutes for 41 GB on an M-series Mac.
+Later runs take seconds, mostly to stat every session file.
+Stored events survive a harness deleting old transcripts.
+
+| Column | Harness | Counted record |
+| --- | --- | --- |
+| `model` | Claude Code | A Skill tool result that loaded a skill. A failed call does not count. |
+| `slash` | Claude Code | A `/name` command whose next record is its expanded prompt. Built-in commands such as `/clear` do not expand and do not count. |
+| `read` | Codex | A completed command that reads `<skill>/SKILL.md`. Codex records no skill event, so a read is the closest observable act. It does not show that the skill shaped the outcome. |
+| `read` | Kimi Code | A successful `ReadFile` call or shell command that reads `<skill>/SKILL.md`, including streamed arguments. Kimi records no dedicated skill event. |
+
+Each event is keyed by its record ID, so a resumed session that copies earlier records counts once.
+One Codex or Kimi command that reads three or more skills (`--sweep`) is a catalog sweep, such as an audit; its reads are excluded and reported separately.
+`installed` names the harnesses whose catalog lists the skill now: `~/.claude/skills` and enabled plugins for Claude Code, and `~/.codex/skills` and `~/.agents/skills` for Codex.
+OpenCode, Pi, Gemini, Factory, and other harnesses are not indexed.
+
 ## Diff two runs
 
 `traces diff` pairs the steps of two runs of the same task and marks where they first stop agreeing.