agent-inspect 1.4.0 → 1.6.0

package/docs/KNOWN-ISSUES.md

@@ -12,6 +12,13 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - **OpenInference** and **OTLP JSON** exports are **compatibility-oriented** and **experimental**. Validate against your target collector or backend before relying on them.
 - Exports generate **strings/files locally** only—there is **no** automatic upload.
 
+## Readers and `open`
+
+- **OpenInference** and **OTLP JSON** readers are **compatibility-oriented** and **experimental**. They normalize local JSON payloads into AgentInspect inspection trees and may warn on unsupported semantic fields.
+- `agent-inspect open` requires `--run <run-id>` when input contains multiple runs. It does not pick an arbitrary run silently.
+- Format detection is conservative. Use `--format agent-inspect-jsonl`, `--format openinference-json`, or `--format otlp-json` for known local inputs.
+- Standards JSON readers summarize bounded prompt/output-like attributes; they do not make raw prompt/output capture a default AgentInspect behavior.
+
 ## Integrations
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
@@ -31,7 +38,7 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 ## Cost / tokens
 
-- **Token counting** and **cost calculation** are **not** core features.
+- **Token counting** and **cost calculation** are **not** core features. Token usage fields (`input`, `output`, `total`, `cached`) are displayed only when supplied by user code, fixtures, or adapters.
 
 ## Confidence labels
 

package/docs/LIMITATIONS.md

@@ -16,8 +16,16 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Persisted event model (v1.2.0 foundation)
 
 - **v0.2 is not the default persisted trace file format.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL.
-- **CLI commands** (`list`, `view`, `export`, `diff`, `logs`, `tail`) still primarily operate on current v0.1 trace and log paths.
-- **v0.2 read/write integration** (dual-format storage, CLI consumption) is future work — v1.2.0 ships in-memory converters and canonical fixtures only.
+- **Dual-format inspection is a read path, not a write migration.** `list`, `view`, `timeline`, `stats`, `search`, `diff`, `export`, `what`, and `report` read v0.1/v0.2 trace files through normalization where applicable. `logs` and `tail` remain structured-log ingestion commands, not v0.2 writers.
+- **Default write path remains v0.1.** v0.2 fixtures and converters are available for adapters and migration testing, but AgentInspect does not automatically rewrite traces.
+
+## Runtime writers and universal readers (v1.6)
+
+- **Experimental APIs:** `agent-inspect/writers`, `agent-inspect/readers`, and `createInspector()` are available for local adoption, but their experimental contracts may be refined in v1.x.
+- **Explicit writer ownership:** `createInspector()` does not print terminal lifecycle output or implicitly choose a disk writer. Use `fileWriter()` / `bufferedFileWriter()` / custom writers when persistence is desired.
+- **No standards upload:** OpenInference and OTLP JSON support is local read/export compatibility only. There is no OTLP gRPC/HTTP streaming sink, collector client, or hosted ingestion behavior.
+- **Conservative detection:** `agent-inspect open` does not silently accept arbitrary JSON. Unsupported or ambiguous inputs produce errors/warnings rather than guessed traces.
+- **Large inputs:** reader inputs are bounded and read into local memory. This is not a database index or production log warehouse.
 
 ## LangChain streaming (v1.3.0)
 
@@ -47,6 +55,7 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Economics
 
 - **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
+- **Token usage is supplied metadata only**: AgentInspect may display `input`, `output`, `total`, and `cached` counts when callers/adapters provide them; core does not count tokens or infer provider billing.
 
 ## Local observability commands (v1.4.0)
 
@@ -54,6 +63,8 @@ This document states what AgentInspect **does not** provide today. It complement
 - **`search`** is deterministic exact/contains matching only — no semantic or fuzzy search.
 - **`stats`** is local file aggregation — not production fleet analytics.
 
+Visual demos: [SCREENSHOTS.md](./SCREENSHOTS.md) · [CLI.md](./CLI.md)
+
 ## Scale
 
 - Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.

package/docs/LOGS.md

@@ -7,8 +7,30 @@ AgentInspect can parse **existing logs** (line-delimited JSON, and best-effort l
 - **Production-shaped playbook**: `docs/LOGGING-PLAYBOOK.md` (pino, log4js, NestJS recipes)
 - **Field mapping and redaction**: `docs/API.md` (log ingest APIs) and `docs/SCHEMA.md`
 - **Safety constraints**: JSON logs first-class; log4js best-effort; no `eval`; no JavaScript object-literal parsing as a log interchange format (see `SECURITY.md`)
+- **Visual demos**: [SCREENSHOTS.md](./SCREENSHOTS.md#use-existing-logs)
 
 Notes:
 - Log parsing APIs are documented as **experimental** in `docs/API.md`.
 - Log-derived events include **confidence labels**; AgentInspect is conservative about inferring parent/child structure.
 
+### JSON logs → tree (visual pending)
+
+Animated demo is **pending re-record** — a staging capture showed tool/LLM summary counts that did not match displayed events. Use the canonical command below; see [assets/demos/RECORDING.md](./assets/demos/RECORDING.md).
+
+```bash
+agent-inspect logs fixtures/logs/minimal-success.json.log \
+  --format json \
+  --run-id-key runId \
+  --event-key event \
+  --timestamp-key timestamp
+```
+
+Run: [examples/06-log-to-tree](../examples/06-log-to-tree/README.md)
+
+### Live tail (visual pending)
+
+`agent-inspect tail` updates a local tree as new log lines arrive. Recording guide: [RECORDING.md](./assets/demos/RECORDING.md).
+
+### log4js (best-effort)
+
+See [examples/recipes/log4js-json-layout](../examples/recipes/log4js-json-layout/README.md). Visual pending re-record.

package/docs/SCHEMA.md

@@ -129,7 +129,7 @@ Unknown status must **not** be treated as success.
 ## 6. Metadata policy
 
 - Runs may include `metadata` on `run_started`.
-- **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). CLI list/view does not filter by correlation fields yet.
+- **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). `stats --correlation-id` and `--group-id` filter by these fields; `list` / `view` do not filter by correlation yet.
 - Steps may include `metadata` on `step_started`.
 - Manual traces intentionally avoid full prompt/output capture by default.
 - **Redaction (default on):** before disk, `inspectRun` / `step` redact sensitive keys using the shared `Redactor` defaults (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Opt out with `redact: false`.
@@ -142,6 +142,8 @@ Unknown status must **not** be treated as success.
 - Readers should ignore unknown fields where safe.
 - Breaking schema changes require a major version.
 
+**v1.5 vocabulary (kinds, token metadata, streaming attributes):** [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md)
+
 ## 8. Malformed lines
 
 Manual trace reading:
@@ -208,8 +210,9 @@ v1.2.0 introduces a **source-agnostic persisted event model** as an experimental
 | ----- | ---- |
 | Default write format | Manual traces still use **`schemaVersion: "0.1"`** (`run_started`, `step_started`, `step_completed`, `run_completed`). |
 | v0.2 role | Unified persisted shape for manual traces, log-derived events, adapter events, and future AI SDK / OTel mappings. |
-| v0.2 file writing | **Not enabled by default** in v1.2.0 — converters and fixtures only. |
-| v0.1 compatibility | v0.2 does **not** replace v0.1 in this release; existing `0.1` files remain canonical for CLI write/read today. |
+| v0.2 file writing | **Not enabled by default** — converters and fixtures only unless a caller writes v0.2 data explicitly. |
+| v0.1 compatibility | v0.2 does **not** replace v0.1 in v1.x; existing `0.1` files remain canonical for manual writing and continue to be readable. |
+| v0.2 read path | Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. |
 | Failures | Still **no** `step_failed`; use `status: "error"` on the persisted event. |
 
 Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:check`).
@@ -233,13 +236,22 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 | `attributes` | no | Shallow metadata bag (redaction-ready) |
 | `inputSummary` / `outputSummary` | no | Truncated previews when explicitly captured |
 | `error` | no | `{ name?, message, code? }` when `status: "error"` |
-| `tokenUsage` | no | `{ input?, output?, total? }` when known |
+| `tokenUsage` | no | `{ input?, output?, total?, cached? }` when supplied/known |
 | `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
 
 Programmatic helpers: see [API.md](./API.md) §11 (experimental persisted-event foundation).
 
-## 15. Migration notes
+## 15. v1.6 local reader/writer compatibility
 
-- Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
-- Migration guides (v0.1 → v0.2 file format) are future work; storage/CLI dual-read is not in the v1.2.0 foundation release.
+v1.6 adds experimental writer and reader surfaces without changing the stable manual trace schema:
+
+- `inspectRun()` / `step()` continue to write `schemaVersion: "0.1"` JSONL by default.
+- `createInspector()` can write explicit v0.2 `PersistedInspectEvent` rows when configured with a writer such as `fileWriter()` or `bufferedFileWriter()`.
+- `agent-inspect/readers` and `agent-inspect open` read local AgentInspect JSONL, OpenInference JSON, and OTLP JSON inputs through compatibility adapters.
+- OpenInference and OTLP JSON inputs are **not** a third AgentInspect persisted schema. They are local read formats normalized into inspection trees with warnings and unsupported-field reporting.
+- Reader and writer APIs perform no network upload and do not mutate source files.
 
+## 16. Migration notes
+
+- Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
+- v0.1 → v0.2 write migration guides are future work. v1.x inspection readers are dual-format; the default manual writer remains v0.1.

package/docs/SCREENSHOTS.md

@@ -1,14 +1,195 @@
-## Screenshots / GIFs (planned)
+# Visual demos
 
-This repo does not currently include screenshots or recorded GIFs in the npm package.
+Curated terminal recordings for AgentInspect **1.4.0**. They show what the local trace workbench captures and how to inspect it — without a hosted dashboard or vendor upload.
 
-Recommended captures to add (when convenient):
+**Synthetic output only:** demos use committed [fixtures](../fixtures/README.md), [examples](../examples/README.md), and recipes. No external LLM calls or API keys.
 
-- [ ] Basic trace tree (`inspectRun` + `step`)
-- [ ] Failed tool call / failed step rendering
-- [ ] `agent-inspect logs` output (JSON logs)
-- [ ] `agent-inspect diff` output
-- [ ] Optional TUI (`agent-inspect view <run-id> --tui`)
+**npm note:** GIFs live in `docs/assets/demos/` for GitHub documentation. They are **not** shipped in the `agent-inspect` npm tarball.
 
-<!-- Add screenshots after running `examples/00-quickstart-demo` locally. -->
+**Re-record guide:** [assets/demos/RECORDING.md](assets/demos/RECORDING.md)  
+**Maintainer audit:** [implementation/VISUAL-DEMO-AUDIT.md](implementation/VISUAL-DEMO-AUDIT.md)
 
+---
+
+## Start tracing
+
+Manual `inspectRun` / `step` traces written as local JSONL.
+
+### Quickstart (install → trace → view)
+
+![Quickstart: install, run a traced script, list and view the run](assets/demos/quickstart.gif)
+
+Run: [examples/00-quickstart-demo](../examples/00-quickstart-demo/README.md)  
+Also: [GETTING-STARTED.md](GETTING-STARTED.md)
+
+### Nested execution tree
+
+![Nested steps rendered as an execution tree in the terminal](assets/demos/execution-tree.gif)
+
+Run: [examples/02-nested-steps](../examples/02-nested-steps/README.md)  
+Command: `agent-inspect view <run-id> --dir <trace-dir>`
+
+### Parallel sibling steps
+
+![Parallel tool steps under one parent in the execution tree](assets/demos/parallel-execution.gif)
+
+Run: [examples/03-parallel-steps](../examples/03-parallel-steps/README.md)
+
+### Error handling
+
+![Failed step recorded on step_completed with status error](assets/demos/error-handling.gif)
+
+Run: [examples/04-error-handling](../examples/04-error-handling/README.md)
+
+### `observe()` wrapper
+
+![observe() wrapper tracing an agent-like object](assets/demos/observe-wrapper.gif)
+
+Run: [examples/05-observe-wrapper](../examples/05-observe-wrapper/README.md) · API: [API.md](API.md)
+
+### Env-gated tracing (`maybeInspectRun`)
+
+![AGENT_INSPECT=1 toggles tracing; unset leaves no trace files](assets/demos/env-gated-tracing.gif)
+
+Docs: [GETTING-STARTED.md](GETTING-STARTED.md) · [API.md](API.md) (`maybeInspectRun`)
+
+---
+
+## Use existing logs
+
+Turn structured logs you already emit into a **local** grouped timeline or tree.
+
+### JSON logs → tree
+
+**Status:** animated demo pending re-record (staging asset had summary-count mismatch).  
+**Command:**
+
+```bash
+agent-inspect logs ./your.json.log \
+  --format json \
+  --run-id-key runId \
+  --event-key event \
+  --timestamp-key timestamp
+```
+
+Run: [examples/06-log-to-tree](../examples/06-log-to-tree/README.md) · [LOGS.md](LOGS.md) · [LOG-TO-TREE-QUICKSTART.md](LOG-TO-TREE-QUICKSTART.md)
+
+### Live tail
+
+**Status:** animated demo pending re-record.  
+**Command:** `agent-inspect tail <log-file> [mapping flags]` — see [LOGS.md](LOGS.md).
+
+### log4js (best-effort)
+
+**Status:** pending re-record. Documented in [LOGS.md](LOGS.md); recipe: [log4js-json-layout](../examples/recipes/log4js-json-layout/README.md).
+
+---
+
+## Inspect and compare
+
+Read-only CLI over local JSONL traces.
+
+### Chronological timeline (`--focus slow`)
+
+![Timeline with slow-step focus highlighting longest steps](assets/demos/timeline.gif)
+
+```bash
+agent-inspect timeline <run-id> --dir fixtures/traces --focus slow
+```
+
+Docs: [CLI.md](CLI.md) § timeline
+
+### Local stats
+
+![Aggregate stats over a trace directory](assets/demos/stats.gif)
+
+```bash
+agent-inspect stats --dir fixtures/traces
+```
+
+Filter by correlation: `agent-inspect stats --correlation-id <id>` or `--group-id <id>`.  
+Docs: [CLI.md](CLI.md) § stats
+
+### Deterministic search
+
+![Search traces by status error](assets/demos/search.gif)
+
+```bash
+agent-inspect search --dir fixtures/traces --status error --limit 5
+```
+
+Docs: [CLI.md](CLI.md) § search
+
+### Diff two runs
+
+![Diff comparing success and error runs](assets/demos/diff-runs.gif)
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+```
+
+Docs: [DIFF.md](DIFF.md)
+
+### Markdown export
+
+![Export a run to Markdown locally](assets/demos/markdown-export.gif)
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces --format markdown
+```
+
+Docs: [EXPORTS.md](EXPORTS.md)
+
+### HTML / OpenInference / OTLP
+
+- **HTML:** rendered-report visual pending re-record; export command in [EXPORTS.md](EXPORTS.md).
+- **OpenInference / OTLP JSON:** compatibility-oriented local formats — see prose and `--validate` in [EXPORTS.md](EXPORTS.md), not dedicated GIFs.
+
+---
+
+## Integrations and optional UI
+
+### LangChain persistence
+
+![LangChain callback with persist true writing inspectable JSONL](assets/demos/langchain-persistence.gif)
+
+Run: [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) · [ADAPTERS.md](ADAPTERS.md)
+
+Streaming metadata (`stream: true`) demo pending re-record until `chunkCount` / `streamDurationMs` are non-null.
+
+### Optional TUI (`@agent-inspect/tui`)
+
+![Optional Ink TUI viewer for a local trace](assets/demos/tui-viewer.gif)
+
+Requires optional package: `pnpm add @agent-inspect/tui`  
+Command: `agent-inspect view <run-id> --tui`  
+Docs: [ADAPTERS.md](ADAPTERS.md)
+
+---
+
+## Safety and sharing
+
+### Default metadata redaction
+
+![Sensitive metadata keys redacted before disk](assets/demos/redaction.gif)
+
+Profiles (`local` / `share` / `strict`) and export redaction: [SAFE-TRACE-SHARING.md](SAFE-TRACE-SHARING.md)
+
+### Event size bounds
+
+Described in [LIMITATIONS.md](LIMITATIONS.md) — no GIF (static explanation preferred).
+
+### Correlation metadata
+
+Described in [API.md](API.md) — optional `correlationId`, `requestId`, `decisionId`, `groupId` on `run_started`.
+
+---
+
+## Planned checklist (completed items)
+
+- [x] Basic trace tree (`inspectRun` + `step`)
+- [x] Failed step rendering
+- [x] `agent-inspect logs` output (JSON) — **re-record pending**
+- [x] `agent-inspect diff` output
+- [x] Optional TUI (`view --tui`)
+- [x] `timeline`, `stats`, `search` (v1.4.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -25,6 +25,76 @@
         "types": "./packages/core/dist/index.d.cts",
         "default": "./packages/core/dist/index.cjs"
       }
+    },
+    "./advanced": {
+      "import": {
+        "types": "./packages/core/dist/advanced.d.ts",
+        "default": "./packages/core/dist/advanced.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/advanced.d.cts",
+        "default": "./packages/core/dist/advanced.cjs"
+      }
+    },
+    "./persisted": {
+      "import": {
+        "types": "./packages/core/dist/persisted.d.ts",
+        "default": "./packages/core/dist/persisted.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/persisted.d.cts",
+        "default": "./packages/core/dist/persisted.cjs"
+      }
+    },
+    "./logs": {
+      "import": {
+        "types": "./packages/core/dist/logs.d.ts",
+        "default": "./packages/core/dist/logs.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/logs.d.cts",
+        "default": "./packages/core/dist/logs.cjs"
+      }
+    },
+    "./exporters": {
+      "import": {
+        "types": "./packages/core/dist/exporters.d.ts",
+        "default": "./packages/core/dist/exporters.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/exporters.d.cts",
+        "default": "./packages/core/dist/exporters.cjs"
+      }
+    },
+    "./diff": {
+      "import": {
+        "types": "./packages/core/dist/diff.d.ts",
+        "default": "./packages/core/dist/diff.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/diff.d.cts",
+        "default": "./packages/core/dist/diff.cjs"
+      }
+    },
+    "./writers": {
+      "import": {
+        "types": "./packages/core/dist/writers.d.ts",
+        "default": "./packages/core/dist/writers.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/writers.d.cts",
+        "default": "./packages/core/dist/writers.cjs"
+      }
+    },
+    "./readers": {
+      "import": {
+        "types": "./packages/core/dist/readers.d.ts",
+        "default": "./packages/core/dist/readers.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/readers.d.cts",
+        "default": "./packages/core/dist/readers.cjs"
+      }
     }
   },
   "bin": {