agent-inspect 1.3.0 → 1.5.0

package/docs/EXPORTS.md

@@ -1,26 +1,97 @@
-## Exports
+# Exports
 
-AgentInspect supports local-only exports from run trees and traces. Exports are intended for **compatibility and sharing**, but should be reviewed before sending to others.
+AgentInspect exports are **local-only**: they produce strings or files on disk. Nothing uploads to a vendor, collector, or hosted dashboard.
 
-- **CLI usage**: `docs/CLI.md` (`export`)
-- **Schema + compatibility guarantees**: `docs/SCHEMA.md`
-- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
+Use exports to share run summaries in PRs, postmortems, or internal threads — **after reviewing** the output. See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
-## Share-safe exports (v1.3.0+)
+## CLI
 
-Use `--redaction-profile share` (PRs, issues, internal threads) or `strict` (external sharing) when generating an export copy:
+```bash
+agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]
+```
+
+Full flags: [CLI.md](./CLI.md) §6.6.
+
+## Formats
+
+| Format | Purpose |
+| ------ | ------- |
+| `markdown` | Human-readable tree for PRs, issues, docs |
+| `html` | Standalone HTML snapshot for local viewing |
+| `openinference` | OpenInference-compatible JSON (compatibility-oriented) |
+| `otlp-json` | OTLP JSON shape (experimental; validate per backend) |
+
+All formats are **compatibility-oriented** for local inspection and handoff — not guaranteed to match every vendor schema version.
+
+### Markdown export
+
+![Export a run to Markdown locally](assets/demos/markdown-export.gif)
 
 ```bash
-agent-inspect export <run-id> --format markdown --redaction-profile share
+agent-inspect export minimal-success --dir fixtures/traces --format markdown
 ```
 
-- Profiles are **key-based** redaction presets — not compliance-grade PII detection.
-- Export redaction operates on a **copy** of the run tree; original JSONL traces on disk are **not mutated**.
-- **Review** every export before posting — especially when `--include-attributes` is set.
+### HTML, OpenInference, OTLP
+
+- **HTML:** export writes a local file; a rendered-report visual is pending re-record ([RECORDING.md](./assets/demos/RECORDING.md)). Use `agent-inspect export <run-id> --format html -o report.html` and open the file locally.
+- **OpenInference / OTLP JSON:** compatibility-oriented shapes for local handoff — validate with `--validate` before sharing. No dedicated GIF; see format tables below.
+
+## Common options
+
+| Flag | Notes |
+| ---- | ----- |
+| `--dir <path>` | Trace directory (default from `AGENT_INSPECT_TRACE_DIR` or `.agent-inspect`) |
+| `-o, --output <path>` | Write to file instead of stdout |
+| `--json` | JSON wrapper output (includes content when not writing to file) |
+| `--validate` | Validate exported payload shape before writing |
+| `--include-attributes` | Include bounded attributes — **review before sharing** |
+| `--no-metadata` | Omit summary/metadata sections |
+| `--no-errors` | Omit error sections |
+| `--redaction-profile <local\|share\|strict>` | Key-based redaction on the **export copy** (v1.3.0+) |
+
+## Redaction profiles (share-safe exports)
+
+Profiles apply to the **exported copy** only. Original JSONL traces on disk are **not mutated**.
+
+| Profile | Typical use |
+| ------- | ------------- |
+| `local` | Default — same key-based defaults as trace writing |
+| `share` | PRs, GitHub issues, internal Slack/email threads |
+| `strict` | External or public sharing — also redacts prompt/output/message-like keys |
+
+```bash
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+npx agent-inspect export <run-id> --format openinference --redaction-profile share --validate
+```
+
+Redaction profiles are **key-based safeguards**, not compliance-grade PII detection. Always review exports manually.
+
+## Programmatic API
+
+Experimental helpers (local-only):
+
+- `exportRunTree`, `redactRunTreeForExport`
+- `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson`
+- `validateExport`, `validateExportContent`
+
+See [API.md](./API.md) §7.
+
+## What not to share
+
+Even with `--redaction-profile strict`, review exports for:
+
+- API keys, tokens, cookies, session IDs
+- Customer IDs, emails, phone numbers, internal hostnames
+- Full prompts, completions, tool I/O (especially with `--include-attributes`)
+- File paths that expose usernames or internal project names
 
-See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
+Prefer the smallest useful artifact — a summary or synthetic reproduction beats a full production trace.
 
-Notes:
-- Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.
-- AgentInspect does **not** upload anywhere; exports write local strings/files only.
+## Related docs
 
+- [CLI.md](./CLI.md) — `export` command reference
+- [SCHEMA.md](./SCHEMA.md) — trace event model and redaction notes
+- [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — checklist before posting
+- [API.md](./API.md) — `ExportOptions`, experimental export APIs
+- [LIMITATIONS.md](./LIMITATIONS.md) — compatibility and boundary notes

package/docs/GETTING-STARTED.md

@@ -2,6 +2,8 @@
 
 AgentInspect is a **local-first execution-tree debugger** for TypeScript AI agents. It helps you produce and inspect an execution tree of steps, safely and deterministically, without uploading data anywhere.
 
+**Visual demos:** [SCREENSHOTS.md](./SCREENSHOTS.md)
+
 ## 1. Install
 
 ```bash
@@ -58,8 +60,30 @@ await maybeInspectRun("eval-case-42", async () => {
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
+![Env-gated tracing with maybeInspectRun](../assets/demos/env-gated-tracing.gif)
+
+*When `AGENT_INSPECT` is unset, no trace files are written.*
+
 Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
 
+### Correlation metadata (v1.3.0+)
+
+Attach optional correlation fields to `run_started` metadata — useful for eval cases, CI job IDs, and future stats views. They are **metadata only**, not run IDs. Review before sharing exports.
+
+```ts
+await inspectRun(
+  "support-agent",
+  async () => runAgent(),
+  {
+    correlationId: "eval-suite-2026-06",
+    requestId: "req-abc123",
+    groupId: "ci-job-42",
+  }
+);
+```
+
+Inside a traced run, adapters can read active fields via `getCurrentCorrelationMetadata()`.
+
 ### Install compatibility
 
 If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common install/runtime compatibility checks](./KNOWN-ISSUES.md#common-installruntime-compatibility-checks).
@@ -109,9 +133,28 @@ agent-inspect export minimal-success --dir fixtures/traces --format markdown
 agent-inspect export minimal-success --dir fixtures/traces --format openinference --validate
 ```
 
-Exports are **local-only** and do not upload anywhere.
+Share-safe copy for a PR or issue (v1.3.0+):
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces \
+  --format markdown --redaction-profile share
+```
+
+Exports are **local-only** and do not upload anywhere. Review output before sharing — see [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
+
+## 8. Local observability (v1.4.0+)
+
+After traces exist under a directory:
+
+```bash
+agent-inspect timeline <run-id> --dir ./.agent-inspect
+agent-inspect stats --dir ./.agent-inspect --since 7d
+agent-inspect search --dir ./.agent-inspect --status error --limit 10
+```
+
+For CI artifact workflows, see [CI-ARTIFACTS.md](./CI-ARTIFACTS.md) and [github-actions-artifact recipe](../examples/recipes/github-actions-artifact/).
 
-## 8. Diff two runs
+## 9. Diff two runs
 
 ```bash
 agent-inspect diff minimal-success minimal-error --dir fixtures/traces
@@ -151,6 +194,9 @@ agent-inspect view <runId> --tui
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)
 - [docs/SCHEMA.md](./SCHEMA.md)
+- [docs/EXPORTS.md](./EXPORTS.md)
+- [docs/SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md)
+- [docs/ADAPTERS.md](./ADAPTERS.md)
 - [docs/LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
 - [docs/COMPARE.md](./COMPARE.md)
 - [docs/LOG-TO-TREE-QUICKSTART.md](./LOG-TO-TREE-QUICKSTART.md)

package/docs/KNOWN-ISSUES.md

@@ -16,6 +16,12 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
+- **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
+- **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.
+
+## Structured log parsing
+
+- Ingest requires **line-delimited JSON** or a **recoverable JSON payload** in the log line (log4js-style is best-effort). Arbitrary printf-style text without JSON is not supported.
 
 ## UI / replay
 

package/docs/LIMITATIONS.md

@@ -9,15 +9,15 @@ This document states what AgentInspect **does not** provide today. It complement
 - **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
 - **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
 
-## Correlation metadata (v1.3.0 chunk 1)
+## Correlation metadata (v1.3.0)
 
-- **No CLI filter/query** by `correlationId`, `requestId`, `decisionId`, or `groupId` yet — fields are written to `run_started.metadata` and available via persisted converters; list/view/export filtering is future work.
+- **`list` / `view` / `export`** do not filter by correlation fields yet — `stats --correlation-id` / `--group-id` and `search` provide targeted read paths; full CLI filtering remains incremental.
 
 ## 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.
+- **v0.2 read integration** — inspection CLI reads v0.2 JSONL via dual-format normalization (v1.5.0). Default **write** path remains v0.1; `list` metadata for v0.2-only files may be limited.
 
 ## LangChain streaming (v1.3.0)
 
@@ -48,6 +48,14 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
 
+## Local observability commands (v1.4.0)
+
+- **`timeline`**, **`stats`**, and **`search`** scan local JSONL files — no database index; large directories may be slow.
+- **`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

@@ -1,4 +1,4 @@
-# Schema (AgentInspect 1.0)
+# Schema (AgentInspect 1.x)
 
 This document describes the **persisted manual trace JSONL schema** and the **log-derived normalized model** used by AgentInspect.
 
@@ -25,7 +25,7 @@ Manual trace events use:
 
 - **`schemaVersion: "0.1"`**
 
-Existing `0.1` traces remain readable in v1.0.
+Existing `0.1` traces remain readable across AgentInspect 1.x.
 
 ### 2.3 TraceEvent union
 
@@ -129,10 +129,11 @@ 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`.
+- **Redaction profiles (v1.3.0+):** optional `redactionProfile` (`local`, `share`, `strict`) adds preset extra keys and tighter metadata bounds for trace writing. Key-based only — not compliance-grade DLP. `export --redaction-profile` applies profiles to export copies without mutating source JSONL.
 - **Size bounds:** long string values are truncated (`maxMetadataValueLength`, default 2000; preview-like keys use `maxPreviewLength`, default 500). Serialized events are capped at `maxEventBytes` (default 65536 UTF-8 bytes). If still too large, `metadata` may be replaced with `{ truncated: true, reason: "maxEventBytes", originalApproxBytes: number }`. Required event fields are never removed.
 
 ## 7. Additive fields and unknown fields
@@ -141,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:
@@ -150,7 +153,7 @@ Manual trace reading:
 
 ## 9. Backward compatibility
 
-- v0.1 JSONL traces remain readable in v1.0.
+- v0.1 JSONL traces remain readable across AgentInspect 1.x.
 - No automatic migrations or rewriting of old files.
 
 ## 10. Breaking change policy
@@ -235,7 +238,7 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 | `tokenUsage` | no | `{ input?, output?, total? }` when known |
 | `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
 
-Programmatic helpers: see [API.md](./API.md) §15 (experimental persisted-event foundation).
+Programmatic helpers: see [API.md](./API.md) §11 (experimental persisted-event foundation).
 
 ## 15. Migration notes
 

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.3.0",
+  "version": "1.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -25,6 +25,56 @@
         "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"
+      }
     }
   },
   "bin": {