@tangle-network/traces 0.8.5 → 0.8.12

package/dist/cli.js

@@ -4,28 +4,36 @@ import {
   analyzeReactions,
   analyzeSpans,
   buildPolicyEvidenceRecord,
+  buildSessionIndexFromRows,
   commandAnalyzer,
   commandRedactor,
   executeUpload,
   exportTraceEvidenceFile,
   haloAnalyzer,
+  inspectSessionIndex,
   knownHarnesses,
   parseSession,
   parseSince,
   planUpload,
+  readSessionIndexFile,
+  renderInspectionReport,
   resolveAdapter,
   runExternalAnalyzers,
   runPipelines,
   selectAdapters,
   serializePolicyEvidence,
+  serializeSessionIndex,
   serializeSpans,
   watchSessions,
+  writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
+  writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-D5OMTM4S.js";
+} from "./chunk-PRRWLKSI.js";
 
 // src/cli.ts
+import { readFileSync } from "fs";
 import { readFile, stat, writeFile } from "fs/promises";
 
 // src/report.ts
@@ -187,6 +195,11 @@ function renderAdoption(ar) {
 }
 
 // src/cli.ts
+function packageVersion() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
+  return pkg.version;
+}
 function parseArgs(argv) {
   const a = {
     command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
@@ -357,7 +370,8 @@ async function collectSpans(args) {
       cwd: args.cwd ?? null,
       mtimeMs: st.mtimeMs
     };
-    return { spans: await parseSession(adapter, ref), harness: adapter.harness, sessionCount: 1, cwds: ref.cwd ? [ref.cwd] : [] };
+    const spans2 = await parseSession(adapter, ref);
+    return { spans: spans2, harness: adapter.harness, sessionCount: 1, cwds: ref.cwd ? [ref.cwd] : [] };
   }
   const groups = await discover({ ...args, last: args.last || 1 });
   const spans = [];
@@ -421,6 +435,39 @@ async function cmdEvidence(args) {
     process.stdout.write(serializePolicyEvidence(records));
   }
 }
+async function cmdIndex(args) {
+  const rows = (await collectSessionRows(args)).filter((row) => row.spans.length > 0);
+  if (rows.length === 0) throw new Error("no spans found for the given selection");
+  const index = await buildSessionIndexFromRows(rows, {
+    minLoopOccurrences: args.minLoop,
+    selection: {
+      command: "index",
+      harness: args.harnessExplicit ? args.harness : void 0,
+      all: args.all || void 0,
+      last: args.last || void 0,
+      session: args.session,
+      cwd: args.cwd,
+      since: args.since
+    }
+  });
+  if (args.out) {
+    const path = await writeSessionIndexFile(index, args.out);
+    console.log(`session index \u2192 ${path}  (${index.totals.sessions} session rows)`);
+  } else {
+    process.stdout.write(serializeSessionIndex(index));
+  }
+}
+async function cmdInspect(args) {
+  if (!args.input) throw new Error("inspect needs an index file; run `traces index --out session-index.json` first");
+  const index = await readSessionIndexFile(args.input);
+  const report = inspectSessionIndex(index);
+  if (args.out) {
+    const path = await writeInspectionReportFile(report, args.out);
+    console.log(`inspection report \u2192 ${path}  (${report.totals.findings} finding(s), high ${report.totals.high})`);
+  } else {
+    process.stdout.write(renderInspectionReport(report));
+  }
+}
 async function cmdExport(args) {
   if (!args.input) throw new Error("export needs an input file; run `traces export --help` for examples");
   const format = args.format ?? "auto";
@@ -616,6 +663,8 @@ Commands:
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines, write a markdown report
   convert   Emit OTLP-JSONL only (HALO: use analyze --analyzer halo)
+  index     Emit a reusable session index JSON for later investigation
+  inspect   Read a session index and print ranked improvement findings
   export    Convert evidence/events files to OpenInference JSONL for HALO
   evidence  Emit compact session-evidence JSONL for downstream policy miners
   watch     Online observer: tail active sessions, notify on stuck loops (read-only)
@@ -645,12 +694,18 @@ Options:
   --no-content     upload: strip prompt/response text \u2014 send metadata only
   --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
   --yes, -y        upload: skip the confirmation prompt
+  --version, -v    Print the installed traces version
   --help, -h       Show help (use \`traces export --help\` for export examples)
 
 Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), TANGLE_TENANT_ID`);
 }
 async function main() {
-  const args = parseArgs(process.argv.slice(2));
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "--version" || rawArgs[0] === "-v" || rawArgs[0] === "version") {
+    console.log(`traces ${packageVersion()}`);
+    return;
+  }
+  const args = parseArgs(rawArgs);
   if (args.help) {
     if (args.command === "export" || args.command === "help" && args.input === "export") usageExport();
     else usage();
@@ -670,6 +725,12 @@ async function main() {
     case "convert":
       await cmdConvert(args);
       break;
+    case "index":
+      await cmdIndex(args);
+      break;
+    case "inspect":
+      await cmdInspect(args);
+      break;
     case "export":
       await cmdExport(args);
       break;

package/dist/index.d.ts

@@ -158,6 +158,8 @@ declare const ATTR: {
     readonly GIT_BRANCH_NAME: "git.branch";
     /** HEAD short sha at conversion time. */
     readonly GIT_COMMIT: "git.commit";
+    /** How traces resolved the session cwd: recorded cwd, repaired cwd, or span path. */
+    readonly REPO_RESOLUTION_SOURCE: "traces.repo_resolution_source";
     readonly GIT_BRANCH: "tangle.git_branch";
     readonly HOST: "tangle.host";
     /** Basename of the session file. (Renamed from the ambiguous `tangle.source`,
@@ -239,8 +241,17 @@ interface ScannedSession {
  *  errors route to `onError` and skip that adapter/session, never aborting. */
 declare function scanSessions(opts: ScanOptions): AsyncGenerator<ScannedSession>;
 
+type RepoResolutionSource = 'none' | 'ref-cwd' | 'repaired-cwd' | 'span-path' | 'span-workdir';
 /** Resource-attribute keys this resolver may stamp. */
-type RepoAttrs = Partial<Record<typeof ATTR.SUBJECT_KEY | typeof ATTR.GIT_REPOSITORY | typeof ATTR.GIT_BRANCH_NAME | typeof ATTR.GIT_COMMIT | typeof ATTR.CWD, string>>;
+type RepoAttrs = Partial<Record<typeof ATTR.SUBJECT_KEY | typeof ATTR.GIT_REPOSITORY | typeof ATTR.GIT_BRANCH_NAME | typeof ATTR.GIT_COMMIT | typeof ATTR.CWD, string>> & Partial<Record<typeof ATTR.REPO_RESOLUTION_SOURCE, RepoResolutionSource>>;
+interface RepoResolution {
+    /** Resource attributes to stamp onto spans. */
+    attrs: RepoAttrs;
+    /** Best-known cwd/repo directory after repair or span-path inference. */
+    cwd: string | null;
+    /** Which signal produced the selected cwd. */
+    source: RepoResolutionSource;
+}
 /**
  * Normalize a git remote url to `host/owner/repo`, dropping scheme, auth, the
  * `.git` suffix, and any trailing slash. Handles both `https://` and the
@@ -252,6 +263,7 @@ declare function normalizeRemote(url: string): string | null;
  * Fail-safe and never throws; see the module doc for the derivation contract.
  */
 declare function resolveRepoAttrs(cwd: string | null | undefined): Promise<RepoAttrs>;
+declare function resolveSessionRepoAttrs(cwd: string | null | undefined, spans: readonly OtlpSpan[]): Promise<RepoResolution>;
 /**
  * Stamp resolved repo attrs onto every span's attributes (so they land in the
  * OTLP resource attributes via `toOpenInferenceSpan`). Additive — existing
@@ -351,6 +363,11 @@ declare class GeminiFamilyAdapter implements HarnessTraceAdapter {
     private readonly homeDirName;
     constructor(cfg: GeminiFamilyConfig);
     private chatsRoot;
+    /** `<home>/projects.json` maps `{ <absolute-cwd>: <projectName> }`. The session
+     *  dir name (`tmp/<projectHash>/`) is that projectName for registered projects,
+     *  so inverting the map recovers cwd. (Unregistered/older dirs are opaque cwd
+     *  digests and stay null.) Loaded once per locate(). */
+    private loadProjectCwds;
     locate(opts?: LocateOptions): Promise<SessionRef[]>;
     parse(ref: SessionRef): Promise<OtlpSpan[]>;
 }
@@ -806,6 +823,7 @@ interface PolicyEvidenceRecord {
         readonly branch?: string;
         readonly commit?: string;
         readonly cwd?: string;
+        readonly resolutionSource?: string;
     };
     readonly metrics: {
         readonly spanCount: number;
@@ -847,6 +865,138 @@ declare function collectPolicyEvidence(opts: CollectPolicyEvidenceOptions): Prom
 declare function serializePolicyEvidence(records: readonly PolicyEvidenceRecord[]): string;
 declare function writePolicyEvidenceFile(records: readonly PolicyEvidenceRecord[], outPath?: string): Promise<string>;
 
+interface TraceSessionIndexRow {
+    readonly session: PolicyEvidenceRecord['session'];
+    readonly repo: PolicyEvidenceRecord['repo'];
+    readonly time: {
+        readonly firstSpanAt: string | null;
+        readonly lastSpanAt: string | null;
+    };
+    readonly metrics: {
+        readonly spanCount: number;
+        readonly llmTurnCount: number;
+        readonly toolCallCount: number;
+        readonly erroredToolCallCount: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly toolErrorRate: number;
+    };
+    readonly models: readonly string[];
+    readonly tools: PolicyEvidenceRecord['metrics']['tools'];
+    readonly signals: PolicyEvidenceRecord['signals'];
+}
+interface TraceIndexedFile {
+    readonly kind: 'instruction-doc' | 'evolve-jsonl' | 'evolve-json' | 'reflection' | 'handoff' | 'other';
+    readonly path: string;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+    readonly lines?: number;
+    readonly jsonlRows?: number;
+    readonly markdown?: {
+        readonly headings: number;
+        readonly hasToc: boolean;
+    };
+    readonly jsonl?: {
+        readonly rows: number;
+        readonly invalidRows: number;
+        readonly keys: Record<string, number>;
+    };
+}
+interface TraceContextRoot {
+    readonly root: string;
+    readonly files: readonly TraceIndexedFile[];
+}
+interface TraceContextIndex {
+    readonly totals: {
+        readonly roots: number;
+        readonly files: number;
+        readonly instructionDocs: number;
+        readonly evolveFiles: number;
+        readonly jsonlRows: number;
+        readonly invalidJsonlRows: number;
+    };
+    readonly roots: readonly TraceContextRoot[];
+}
+interface TraceSessionIndex {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.session_index';
+    readonly generatedAt: string;
+    readonly selection?: Record<string, unknown>;
+    readonly totals: {
+        readonly sessions: number;
+        readonly spans: number;
+        readonly llmTurns: number;
+        readonly toolCalls: number;
+        readonly erroredToolCalls: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly stuckLoopSessions: number;
+        readonly stuckLoops: number;
+        readonly harnesses: readonly string[];
+        readonly repos: readonly string[];
+        readonly models: readonly string[];
+        readonly tools: readonly string[];
+    };
+    readonly context?: TraceContextIndex;
+    readonly sessions: readonly TraceSessionIndexRow[];
+}
+interface BuildSessionIndexOptions extends Pick<BuildPolicyEvidenceOptions, 'generatedAt' | 'minLoopOccurrences'> {
+    readonly selection?: Record<string, unknown>;
+    /** Index nearby local docs/artifacts for joins. Defaults to true in scan paths. */
+    readonly includeContext?: boolean;
+}
+interface CollectSessionIndexOptions extends ScanOptions, BuildSessionIndexOptions {
+}
+declare function buildSessionIndex(records: readonly PolicyEvidenceRecord[], opts?: BuildSessionIndexOptions & {
+    context?: TraceContextIndex;
+}): TraceSessionIndex;
+declare function buildSessionIndexFromRows(rows: readonly {
+    ref: SessionRef;
+    spans: readonly OtlpSpan[];
+}[], opts?: BuildSessionIndexOptions): Promise<TraceSessionIndex>;
+declare function collectSessionIndex(opts?: CollectSessionIndexOptions): Promise<TraceSessionIndex>;
+declare function serializeSessionIndex(index: TraceSessionIndex): string;
+declare function writeSessionIndexFile(index: TraceSessionIndex, outPath?: string): Promise<string>;
+
+type TraceInspectionSeverity = 'high' | 'medium' | 'low';
+type TraceInspectionArea = 'index' | 'session' | 'repo' | 'context';
+interface TraceInspectionFinding {
+    readonly id: string;
+    readonly severity: TraceInspectionSeverity;
+    readonly area: TraceInspectionArea;
+    readonly title: string;
+    readonly impact: number;
+    readonly evidence: readonly string[];
+    readonly next: string;
+    readonly refs?: readonly string[];
+}
+interface TraceInspectionReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.inspection_report';
+    readonly generatedAt: string;
+    readonly source: {
+        readonly indexGeneratedAt?: string;
+        readonly sessions: number;
+        readonly contextFiles: number;
+    };
+    readonly totals: {
+        readonly findings: number;
+        readonly high: number;
+        readonly medium: number;
+        readonly low: number;
+    };
+    readonly findings: readonly TraceInspectionFinding[];
+}
+interface InspectSessionIndexOptions {
+    readonly generatedAt?: string;
+    readonly maxFindings?: number;
+}
+declare function inspectSessionIndex(index: TraceSessionIndex, opts?: InspectSessionIndexOptions): TraceInspectionReport;
+declare function renderInspectionReport(report: TraceInspectionReport): string;
+declare function serializeInspectionReport(report: TraceInspectionReport): string;
+declare function readSessionIndexFile(path: string): Promise<TraceSessionIndex>;
+declare function writeInspectionReportFile(report: TraceInspectionReport, outPath?: string): Promise<string>;
+
 type JsonObject = Record<string, unknown>;
 type TraceEvidenceInputFormat = 'policy-evidence' | 'sandbox-events' | 'openinference';
 type TraceEvidenceFormatOption = TraceEvidenceInputFormat | 'auto';
@@ -1169,4 +1319,4 @@ interface ExecuteOptions {
 /** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, knownHarnesses, listAdapters, loadState, looksLikeAgentPrompt, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, redactSpans, resolveAdapter, resolveRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, saveState, scanSessions, selectAdapters, serializePolicyEvidence, serializeSpans, sessionHash, span, stampRepoAttrs, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeOtlpFile, writePolicyEvidenceFile, writeTraceEvidenceExportFile };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type InspectSessionIndexOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceSessionIndex, type TraceSessionIndexRow, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, looksLikeAgentPrompt, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, sessionHash, span, stampRepoAttrs, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile };

package/dist/index.js

@@ -24,11 +24,14 @@ import {
   analyzeSpans,
   applyRedactor,
   buildPolicyEvidenceRecord,
+  buildSessionIndex,
+  buildSessionIndexFromRows,
   capText,
   classifyReaction,
   claudeActor,
   codexActor,
   collectPolicyEvidence,
+  collectSessionIndex,
   commandAnalyzer,
   commandRedactor,
   countSkillRunsJsonl,
@@ -37,6 +40,7 @@ import {
   exportTraceEvidenceRows,
   exportTraceEvidenceText,
   haloAnalyzer,
+  inspectSessionIndex,
   knownHarnesses,
   listAdapters,
   loadState,
@@ -46,16 +50,21 @@ import {
   parseSession,
   parseSince,
   planUpload,
+  readSessionIndexFile,
   redactSpans,
+  renderInspectionReport,
   resolveAdapter,
   resolveRepoAttrs,
+  resolveSessionRepoAttrs,
   runCommand,
   runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
   selectAdapters,
+  serializeInspectionReport,
   serializePolicyEvidence,
+  serializeSessionIndex,
   serializeSpans,
   sessionHash,
   span,
@@ -67,10 +76,12 @@ import {
   uploadKey,
   userPromptSpan,
   watchSessions,
+  writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
+  writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-D5OMTM4S.js";
+} from "./chunk-PRRWLKSI.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -123,11 +134,14 @@ export {
   applyRedactor,
   buildDefaultAnalystRegistry,
   buildPolicyEvidenceRecord,
+  buildSessionIndex,
+  buildSessionIndexFromRows,
   capText,
   classifyReaction,
   claudeActor,
   codexActor,
   collectPolicyEvidence,
+  collectSessionIndex,
   collectSessions,
   commandAnalyzer,
   commandRedactor,
@@ -139,6 +153,7 @@ export {
   exportTraceEvidenceText,
   haloAnalyzer,
   hostedClientFromEnv,
+  inspectSessionIndex,
   knownHarnesses,
   listAdapters,
   loadState,
@@ -149,18 +164,23 @@ export {
   parseSession,
   parseSince,
   planUpload,
+  readSessionIndexFile,
   redactSpans,
   redactString,
   redactValue,
+  renderInspectionReport,
   resolveAdapter,
   resolveRepoAttrs,
+  resolveSessionRepoAttrs,
   runCommand,
   runExternalAnalyzers,
   runPipelines,
   saveState,
   scanSessions,
   selectAdapters,
+  serializeInspectionReport,
   serializePolicyEvidence,
+  serializeSessionIndex,
   serializeSpans,
   sessionHash,
   span,
@@ -172,7 +192,9 @@ export {
   uploadKey,
   userPromptSpan,
   watchSessions,
+  writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
+  writeSessionIndexFile,
   writeTraceEvidenceExportFile
 };

package/install.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="@tangle-network/traces"
+VERSION="${TRACES_VERSION:-latest}"
+PREFIX="${TRACES_PREFIX:-}"
+
+usage() {
+  cat <<'USAGE'
+Install the traces CLI from npm.
+
+Usage:
+  curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
+  ./install.sh [--version <version>] [--prefix <dir>]
+
+Environment:
+  TRACES_VERSION   npm version or tag to install (default: latest)
+  TRACES_PREFIX    npm global prefix to use when the default is not writable
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --version)
+      [ "${2:-}" ] || { echo "missing value for --version" >&2; exit 2; }
+      VERSION="$2"
+      shift 2
+      ;;
+    --prefix)
+      [ "${2:-}" ] || { echo "missing value for --prefix" >&2; exit 2; }
+      PREFIX="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Node.js >=22 is required before installing traces." >&2
+  exit 1
+fi
+
+node_version="$(node -e "process.stdout.write(process.versions.node)")"
+node_major="${node_version%%.*}"
+if [ "$node_major" -lt 22 ]; then
+  echo "Node.js >=22 is required; found v$node_version." >&2
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "npm is required before installing traces." >&2
+  exit 1
+fi
+
+install_args=(install -g "${PACKAGE}@${VERSION}")
+npm_prefix="$(npm prefix -g)"
+install_prefix="$npm_prefix"
+
+if [ -n "$PREFIX" ]; then
+  mkdir -p "$PREFIX"
+  install_args+=(--prefix "$PREFIX")
+  install_prefix="$PREFIX"
+else
+  if [ ! -w "$npm_prefix" ]; then
+    install_prefix="$HOME/.local"
+    mkdir -p "$install_prefix"
+    install_args+=(--prefix "$install_prefix")
+    echo "npm global prefix is not writable; installing into $install_prefix"
+  fi
+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
+  traces_cmd="traces"
+else
+  echo "Installed ${PACKAGE}@${VERSION}, but the traces binary was not found at $bin_dir/traces or on PATH." >&2
+  echo "Add this to PATH: $bin_dir" >&2
+  exit 1
+fi
+
+version_output="$("$traces_cmd" --version 2>/dev/null || true)"
+case "$version_output" in
+  traces\ [0-9]*.[0-9]*.[0-9]*) echo "$version_output" ;;
+  *) echo "traces installed: $traces_cmd" ;;
+esac
+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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.8.5",
+  "version": "0.8.12",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
   },
   "files": [
     "dist",
+    "install.sh",
     "README.md"
   ],
   "engines": {
@@ -56,6 +57,7 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "build": "tsup src/index.ts src/cli.ts --format esm --target node22 --clean --dts",
+    "check:package": "node scripts/check-package-bin.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"