@tangle-network/traces 0.23.1 → 1.0.0

package/examples/custom-analyst.ts

@@ -4,17 +4,20 @@
  *
  *   pnpm tsx examples/custom-analyst.ts
  *   pnpm tsx examples/custom-analyst.ts --fixture
+ *
+ * Each name comes from its owner: the analyst contract from agent-eval, the
+ * span builders from agent-trace-contract, and reading and analysis from
+ * traces. The fixture is what a producer you control would emit: contract
+ * spans, written as OTLP-JSONL and read back the way `traces analyze <file>`
+ * reads them.
  */
-import {
-  AnalystRegistry,
-  type Analyst,
-  analyzeSpans,
-  collectSessions,
-  makeFinding,
-  type OtlpSpan,
-  span,
-  type TraceAnalysisStore,
-} from '@tangle-network/traces'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { type Analyst, AnalystRegistry, makeFinding } from '@tangle-network/agent-eval/analyst'
+import type { TraceAnalysisStore } from '@tangle-network/agent-eval/traces'
+import { type ContractSpan, contractSpan, toolSpan } from '@tangle-network/agent-trace-contract'
+import { analyzeSpans, type OtlpSpan, readOtlpInput, scanSessions } from '@tangle-network/traces'
 
 export const failedToolAnalyst: Analyst<TraceAnalysisStore> = {
   id: 'failed-tool-clusters',
@@ -56,116 +59,104 @@ export const failedToolAnalyst: Analyst<TraceAnalysisStore> = {
   },
 }
 
-export function knownBadSpans(): OtlpSpan[] {
+const service = { 'service.name': 'example' }
+
+export function knownBadSpans(): ContractSpan[] {
+  const traceId = 'fixture-three-failures'
   const root = 'fixture-root'
   return [
-    span({
-      traceId: 'fixture-three-failures',
-      spanId: root,
-      name: 'session',
-      kind: 'AGENT',
-      startTime: '2026-01-01T00:00:00.000Z',
-      service: 'example',
-    }),
+    contractSpan({ traceId, spanId: root, name: 'session', kind: 'AGENT', startTime: '2026-01-01T00:00:00.000Z', attributes: service }),
     ...[1, 2, 3].map((attempt) =>
-      span({
-        traceId: 'fixture-three-failures',
+      toolSpan({
+        traceId,
         spanId: `failed-${attempt}`,
         parentSpanId: root,
         name: 'tool.exec',
-        kind: 'TOOL',
+        toolName: 'exec',
         startTime: `2026-01-01T00:00:0${attempt}.000Z`,
         endTime: `2026-01-01T00:00:0${attempt}.100Z`,
-        status: 'ERROR',
-        statusMessage: `Command failed with exit code 127 on attempt ${attempt}`,
-        service: 'example',
-        tool: 'exec',
-        step: attempt,
-        extra: { 'input.value': JSON.stringify({ command: 'missing-command' }) },
+        status: { code: 'STATUS_CODE_ERROR', message: `Command failed with exit code 127 on attempt ${attempt}` },
+        attributes: { ...service, 'input.value': JSON.stringify({ command: 'missing-command' }) },
       }),
     ),
-    span({
-      traceId: 'fixture-three-failures',
+    contractSpan({
+      traceId,
       spanId: 'unsupported-claim',
       parentSpanId: root,
       name: 'message.assistant',
       kind: 'CHAIN',
       startTime: '2026-01-01T00:00:04.000Z',
-      service: 'example',
-      step: 4,
-      content: 'Implemented successfully. Everything works.',
+      attributes: { ...service, content: 'Implemented successfully. Everything works.' },
     }),
   ]
 }
 
-export function knownGoodSpans(): OtlpSpan[] {
+export function knownGoodSpans(): ContractSpan[] {
+  const traceId = 'fixture-verified-change'
   const root = 'fixture-root'
   return [
-    span({
-      traceId: 'fixture-verified-change',
-      spanId: root,
-      name: 'session',
-      kind: 'AGENT',
-      startTime: '2026-01-01T00:00:00.000Z',
-      service: 'example',
-    }),
-    span({
-      traceId: 'fixture-verified-change',
+    contractSpan({ traceId, spanId: root, name: 'session', kind: 'AGENT', startTime: '2026-01-01T00:00:00.000Z', attributes: service }),
+    toolSpan({
+      traceId,
       spanId: 'edit-1',
       parentSpanId: root,
       name: 'tool.apply_patch',
-      kind: 'TOOL',
+      toolName: 'apply_patch',
       startTime: '2026-01-01T00:00:01.000Z',
       endTime: '2026-01-01T00:00:01.100Z',
-      service: 'example',
-      tool: 'apply_patch',
-      step: 1,
-      extra: { 'input.value': 'change code' },
+      status: { code: 'STATUS_CODE_OK' },
+      attributes: { ...service, 'input.value': 'change code' },
     }),
-    span({
-      traceId: 'fixture-verified-change',
+    toolSpan({
+      traceId,
       spanId: 'verify-1',
       parentSpanId: root,
       name: 'tool.exec',
-      kind: 'TOOL',
+      toolName: 'exec',
       startTime: '2026-01-01T00:00:02.000Z',
       endTime: '2026-01-01T00:00:02.100Z',
-      service: 'example',
-      tool: 'exec',
-      step: 2,
-      extra: {
-        'input.value': 'pnpm test',
-        'output.value': '12 tests passed',
-      },
+      status: { code: 'STATUS_CODE_OK' },
+      attributes: { ...service, 'input.value': 'pnpm test', 'output.value': '12 tests passed' },
     }),
-    span({
-      traceId: 'fixture-verified-change',
+    contractSpan({
+      traceId,
       spanId: 'answer-1',
       parentSpanId: root,
       name: 'message.assistant',
       kind: 'CHAIN',
       startTime: '2026-01-01T00:00:03.000Z',
-      service: 'example',
-      step: 3,
-      content: 'Implemented the change. pnpm test passed: 12/12.',
+      attributes: { ...service, content: 'Implemented the change. pnpm test passed: 12/12.' },
     }),
   ]
 }
 
+/** Contract spans as traces reads them: written as OTLP-JSONL, then read back. */
+async function readEmitted(spans: readonly ContractSpan[]): Promise<readonly OtlpSpan[]> {
+  const dir = await mkdtemp(join(tmpdir(), 'traces-custom-analyst-'))
+  try {
+    const path = join(dir, 'spans.otlp.jsonl')
+    await writeFile(path, `${spans.map((item) => JSON.stringify(item)).join('\n')}\n`, 'utf8')
+    return (await readOtlpInput(path)).spans
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+/** The most recent session of the first harness on this machine that has one. */
+async function newestSession(): Promise<readonly OtlpSpan[]> {
+  for await (const session of scanSessions({ last: 1 })) return session.spans
+  throw new Error('no recent sessions found')
+}
+
 async function main(): Promise<void> {
   const registry = new AnalystRegistry()
   registry.register(failedToolAnalyst)
 
-  let spans: readonly OtlpSpan[]
-  if (process.argv.includes('--fixture')) {
-    spans = knownBadSpans()
-  } else if (process.argv.includes('--good-fixture')) {
-    spans = knownGoodSpans()
-  } else {
-    const [session] = await collectSessions({ all: true, last: 1, redact: false })
-    if (!session) throw new Error('no recent sessions found')
-    spans = session.spans
-  }
+  const spans = process.argv.includes('--fixture')
+    ? await readEmitted(knownBadSpans())
+    : process.argv.includes('--good-fixture')
+      ? await readEmitted(knownGoodSpans())
+      : await newestSession()
 
   const { result } = await analyzeSpans(spans, { registry })
   console.log(JSON.stringify(result.findings, null, 2))

package/install.sh

@@ -77,9 +77,29 @@ else
   fi
 fi
 
+bin_dir="$install_prefix/bin"
+
+# Never overwrite another program's `traces`: npm links ours into lib/node_modules/@tangle-network/traces.
+existing="$bin_dir/traces"
+if [ -e "$existing" ] || [ -L "$existing" ]; then
+  target="$(readlink "$existing" 2>/dev/null || true)"
+  case "$target" in
+    */lib/node_modules/@tangle-network/traces/*) ;;
+    *)
+      owner="${target:-a plain file, not the npm link to ${PACKAGE}}"
+      {
+        echo "$existing belongs to another program ($owner); traces will not overwrite it."
+        echo "Either remove that program and run this again (Homebrew's traces: brew uninstall market-dot-dev/tap/traces),"
+        echo "or install into another prefix and put its bin first on PATH, e.g. in ~/.zshenv:"
+        echo "  ./install.sh --prefix \"\$HOME/.local\"   then   export PATH=\"\$HOME/.local/bin:\$PATH\""
+      } >&2
+      exit 1
+      ;;
+  esac
+fi
+
 npm "${install_args[@]}"
 
-bin_dir="$install_prefix/bin"
 if [ -x "$bin_dir/traces" ]; then
   traces_cmd="$bin_dir/traces"
 elif command -v traces >/dev/null 2>&1; then
@@ -99,4 +119,4 @@ case ":$PATH:" in
   *":$bin_dir:"*) ;;
   *) echo "Add this to PATH for future shells: $bin_dir" ;;
 esac
-echo "Run: traces analyze --harness claude-code --last 1"
+echo "Run: traces list --last 5"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.23.1",
-  "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, \u2026) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite \u2014 observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
+  "version": "1.0.0",
+  "description": "What your coding agents did, where they wasted time, and whether a run passes: exact facts, ranked findings, one CI gate and a live view over Claude Code, Codex, OpenCode, Pi, Kimi and Factory sessions and any OTLP spans. CLI and SDK.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,9 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "bench:audit": "tsx bench/audit/cli.ts",
-    "build": "tsup src/index.ts src/cli.ts --format esm --target node22 --clean --dts",
+    "bench:corrections": "tsx bench/corrections/score.ts",
+    "bench:parity": "tsx bench/parity/score.ts",
+    "build": "tsup",
     "check:package": "node scripts/check-package-bin.mjs",
     "check:source": "node scripts/check-source-text.mjs",
     "prepare": "node scripts/check-source-text.mjs",
@@ -61,12 +63,11 @@
     "prepublishOnly": "pnpm check:source && pnpm build && pnpm check:package"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "0.213.0",
+    "@tangle-network/agent-eval": "0.221.3",
     "@tangle-network/agent-interface": "5.2.0",
     "@tangle-network/agent-runtime": "0.318.0",
-    "@tangle-network/agent-trace-contract": "2.0.0",
-    "@tangle-network/harness-sessions": "0.1.3",
-    "@tangle-network/sandbox": "0.60.49"
+    "@tangle-network/agent-trace-contract": "2.1.0",
+    "@tangle-network/harness-sessions": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^22.20.4",

package/skills/inspect-agent-traces/SKILL.md

@@ -1,119 +1,56 @@
 ---
 name: inspect-agent-traces
-description: Inspect real agent workflows with the published Traces CLI and export cited local findings.
+description: Use for any question about a Claude Code or Codex session, its session file, or a trace.
 ---
-
-# Inspect agent traces
-
-Use the deterministic CLI first; keep inspection local and read-only.
-
-## Choose the way in
-
-Read conforming OTLP directly, including `@tangle-network/agent-trace-contract` exports.
-
-```bash
-traces validate spans.otlp.jsonl          # exit 1 on error findings
-traces analyze --otlp spans.otlp.jsonl --out .traces/current.md
-traces analyze --otlp results/sessions --out .traces/all.md   # a directory of exports
-```
-
-Use `--harness` for native coding-agent formats; integrate systems you own through OTLP.
-
-Directories read only OTLP files, preferring an `otlp/` subdirectory; other JSONL logs are listed separately.
-
-Report `Inputs incomplete` values as uncaptured, never zero spend.
-The `trace conformance` section lists missing capabilities.
-
-For loops, inspect `round-over-round convergence` and `steering chain` before judging progress.
-
-## Select the workflow
-
-```bash
-traces --version
-traces list --harness codex --cwd "$PWD"
-traces facts --harness codex --current --latest-turn --workflow \
-  --format text --out .traces/current-facts.txt
-```
-
-- Use `--current` for the active Codex session.
-- Use `--session <id-or-path>` to pin a listed session.
-- Use `--latest-turn` for the current task in a resumed Codex or Claude Code session.
-- Use `--workflow` to include workers linked by stable parent and child IDs.
-- Use `--max-workflow-sessions <n>` only when the default 100-file bound is too small.
-- For Claude Code, use `--harness claude-code --session <path> --latest-turn`; nested subagents are included.
-
-Never join agents by display name or timestamp when Traces reports missing or conflicting IDs.
-Read facts before full transcripts or analysis.
-Check parent and worker counts against the task being investigated.
-Run `analyze` only for questions the facts sheet cannot answer:
-
-```bash
-traces analyze --harness codex --current --latest-turn --workflow \
-  --out .traces/current.md
-```
-
-For moved evidence, keep byte-identical transcripts and record their source paths and hashes.
-Preserve Claude's `<session UUID>/subagents/workflows/<run ID>` subtree beside the copied parent JSONL file.
-Restore missing child files from the source; rewriting recorded paths loses the original evidence.
-Check current branches, edits, commits, and PRs before reporting unfinished work; transcripts describe past actions.
-
-## Export
-
-Write normalized OpenInference spans for another tool:
-
-```bash
-traces convert --harness codex --current --latest-turn --workflow \
-  --otlp-out .traces/current.otlp.jsonl
-```
-
-Write the complete deterministic review packet:
-
-```bash
-traces improve --harness codex --current --latest-turn --workflow \
-  --dir .traces/improvement
-```
-
-`improve` writes findings, evidence, a report, and spans.
-It edits no agent, repository, memory store, or knowledge base.
-
-Preserve a session for later inspection:
-
-```bash
-traces bundle --harness claude-code --session <id-or-path> --out .traces/bundle
+Run traces; never parse session stores yourself. Everything except `ask` is exact, local and $0.
+A ref is a session id or 8+ char prefix, a session file, an OTLP file or dir, a run dir or a bundle dir.
+
+## Any question about one session
+1. Run `traces facts <ref>` first. Its sheet is at most 25 lines: harness, cwd, times and parent;
+   human turns; tools by name with failures; commands by program with failures and runs inside
+   Codex code-mode scripts; subagents, their types and tool calls; tokens; PRs; changed files;
+   first failure; final message.
+   When the sheet holds the answer, answer.
+2. For one field the sheet summarizes, print only that field:
+   `traces facts <ref> --format json | jq '<path>'` with a path below.
+   Never print the whole JSON: it is tens of KB of span ids.
+3. To list commands, typed turns or agent messages by text: `traces facts <ref> --match '<re>'`.
+   It prints the count first, then one line per hit, a command's with `ok`, `failed` or `?`,
+   and under it the record's `file:line` and its output's `last:` line; a program's run count is on the sheet.
+4. To quote or cite, use `record` on a turn, the first failure, a command row, a non-zero exit or a
+   changed file: cite `<recordFile>:<line>` (`.sessions[0].recordFile`; a subagent's record names its own `file`).
+   Never `find` or `grep` the store for it.
+
+```text
+.sessions[0].firstFailure | {name, message, at, record}                      first failure, its output
+.sessions[0].measurements.tools[] | {name, calls, failed: .outcomes.error}   tool calls by name, failures
+.sessions[0].commands.value[] | {command, runs, failed, inScripts, record}    programs, latest run's record
+.sessions[0].commands.value[].nonZeroExits[] | {code, inScript, at, record}   each non-zero exit and its code
+.sessions[0].pullRequests.value | {created: [.created[] | {number, at}], merged: [.merged[] | {number, at}]}
+.sessions[0].humanTurns.value[] | {at, text, record, signals}                typed turns, in order
+.sessions[0] | {tokens, cost}                                                tokens and cost
+.sessions[0].subagents.value[] | {taskName, agentType, status}               subagents spawned, refused ones ERROR
+.sessions[0].changedFiles.value[] | {path, operations, record}            files changed, the call that changed each
+.sessions[0] | {first: .firstRecordAt.value, last: .lastRecordAt.value}      first and last record
+.sessions[0] | {parentSessionId, rel: .measurements.relationship}            parent, agent path, own task start, children
 ```
 
-`bundle` copies transcripts, report, spans, and session-window `.evolve` rows with per-file SHA-256 hashes.
-It uses no model calls.
-Missing transcripts stop assembly; optional missing inputs appear in `manifest.absent`.
-
-## Pick the view for the reader
-
-The full bundle includes transcripts containing prior reports, even when report files are removed.
-For a writer who must not see earlier conclusions, project an evidence-only copy:
-
-```bash
-traces bundle-view .traces/bundle --view evidence-only --out .traces/writer
-```
+A count in a command's `failed` is a known non-zero exit; a run `inScripts` has no exit code of its own.
 
-This retains the session index, evidence JSONL, and structured ledger records.
-It excludes transcripts, reports, spans, prose ledgers, and files repeating an eight-word passage from excluded prose.
-Check `manifest.view` and the rules and hashes in `manifest.excluded`.
+## Other jobs
+| Question | Command |
+|---|---|
+| This session, or the one that just ended here | `traces facts --current`, or `traces list --cwd . --last 5` |
+| Where it churned, what failed, what it cost | `traces analyze <ref>` |
+| Where two runs split | `traces diff <a> <b>` |
+| Gate a PR or eval on the path a run took | `traces check <ref> --contract <file>` |
+| Is this safe to share | `traces check <path> --share-safe` |
+| Watch workers live | `traces watch <run-dir> --once` |
+| A judgment question with checked citations ($) | `traces ask <ref> --question '<q>' --budget 1` |
+| Keep a session's evidence before a move | `traces bundle <ref> --out <dir>` |
 
-## Ask your own question
-
-`traces ask --last 1 --question "<text>" --budget 2 --dir .traces/ask` spends model calls and resolves answer citations.
-
-## Report
-
-- State the source (`--otlp <path>` or the harness), selected task boundary, session and span counts, and integrity warnings.
-- Name missing capabilities and analyses affected by them.
-- Cite each finding with its exact `trace://` reference.
-- Mark missing outcome, cost, token, skill, or relationship data unknown.
-- Do not infer task success from a completion message.
-- Do not infer skill use from reading a `SKILL.md`.
-- Do not upload traces unless explicitly requested.
+Report the ref, cite `record` as `file:line` (else span ids), and say "unknown" where traces returns null.
+Do not infer success from a completion message. Upload only when asked.
 
 ## Then consider
-
-- Use `build-trace-analyst` when deterministic findings cannot answer a repeated trace question.
-- Use `autopsy` when the result is empty, surprising, or suspiciously strong.
+A question you ask twice becomes a `--questions` bank file or a `check --contract`.