agent-inspect 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,12 +1,49 @@
 # Changelog
 
-## 1.2.0
+## 1.4.0
+
+### Added
+
+- Added `docs/CI-ARTIFACTS.md` and `examples/recipes/github-actions-artifact/` for CI trace artifact workflows.
+- Added `agent-inspect timeline <runId>` — chronological local run view (`--json`, `--focus slow`).
+- Added `agent-inspect stats` — local aggregate stats (`--since`, `--correlation-id`, `--group-id`, `--json`).
+- Added `agent-inspect search` — deterministic local trace search (`--status`, `--kind`, `--name`, `--tool`, `--duration`, `--json`).
+- Added core helpers: `buildRunTimeline`, `buildTraceStats`, `searchTraces`.
+
+### Notes
+
+- CI artifact upload is configured in user CI (e.g. GitHub Actions `upload-artifact`) — AgentInspect does not upload.
+- Search is exact/contains matching only — no semantic search or index database.
+- Stats/search scan local files linearly — intended for developer-machine scale.
+- No Vitest/Jest reporter package in this release.
+- Manual trace writing remains `schemaVersion: "0.1"`.
+- Linked release aligns `@agent-inspect/tui` with `agent-inspect` and `@agent-inspect/langchain` (all **1.4.0**).
+
+## 1.3.0
 
-### Minor Changes
+Released **2026-06-12**.
 
-- 5a7f785: v1.2.0: experimental persisted-event foundation (`PersistedInspectEvent` schemaVersion 0.2), validators, TraceEvent/InspectEvent converters, in-memory tree bridge, v0.2 fixtures, and docs. Manual trace writing remains schemaVersion 0.1; no storage or CLI behavior change.
+### Added
+
+- Added correlation metadata on `inspectRun` / `maybeInspectRun` (`correlationId`, `requestId`, `decisionId`, `groupId`) and `getCurrentCorrelationMetadata()`.
+- Added redaction profiles (`local`, `share`, `strict`) for trace safety and share-safe exports.
+- Added `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- Added `--redaction-profile` to `agent-inspect export`.
+- Added LangChain streaming metadata support (`stream: true`) for token chunk counts and duration.
+- Added bounded preview behavior for preview capture mode (`maxStreamPreviewChars`).
+
+### Notes
+
+- LangChain `capture: "metadata-only"` remains default; full stream text is not captured by default.
+- LangChain streaming does not emit per-token JSONL events.
+- Redaction profiles are key-based safeguards, not compliance-grade PII detection.
+- Export redaction does not upload anywhere and does not mutate original traces.
+- No vendor upload, hosted dashboard, or OTLP HTTP sink was added.
+- Manual trace writing remains `schemaVersion: "0.1"`; v0.2 is not written by default.
+
+## 1.2.0
 
-## 1.2.0 — Unreleased
+Released **2026-06-11**. Changeset `5a7f785`.
 
 ### Added
 

package/README.md

@@ -20,7 +20,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.1.0**.
+Current npm release: **1.3.0** (`agent-inspect`, `@agent-inspect/langchain`; `@agent-inspect/tui` is **1.2.1** — patch-only alignment release).
 
 ```bash
 npm install agent-inspect
@@ -109,6 +109,21 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
+## What you can do today (v1.3.0)
+
+- **Trace manually** with `inspectRun`, `step`, `step.llm`, `step.tool`, and `observe` — local JSONL under `.agent-inspect/` by default.
+- **Toggle tracing** with `maybeInspectRun` and `AGENT_INSPECT=1` in eval harnesses or CI.
+- **Correlate runs** with optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started` metadata.
+- **Redact before disk** with default key-based redaction, or choose `redactionProfile`: `local`, `share`, or `strict`.
+- **Inspect from the CLI** — `list`, `view`, `clean`, `logs`, `tail`, `export`, `diff`, `timeline`, `stats`, `search`.
+- **Export share-safe copies** — `export --redaction-profile share` (or `strict`) writes local Markdown/HTML/OpenInference/OTLP JSON only.
+- **Parse structured logs** you already emit (JSON first-class; log4js best-effort).
+- **Optional LangChain adapter** — metadata-only by default; optional `persist: true` and `stream: true` streaming metadata (no full token capture by default).
+- **Optional TUI** — `view --tui` when `@agent-inspect/tui` is installed.
+- **Persisted-event foundation (v1.2.0+)** — in-memory `PersistedInspectEvent` converters; manual writing stays `schemaVersion: "0.1"`.
+
+Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
+
 ## What the trace shows
 
 Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_started` / `step_completed`, with **nested steps**, **tool/LLM** types where you use `step.tool` / `step.llm`, and **durations** on completed steps. Failures are recorded on `step_completed` with `status: "error"` (there is no separate `step_failed` event). See [docs/SCHEMA.md](docs/SCHEMA.md).
@@ -150,6 +165,9 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `tail` | Watch structured logs while the app runs |
 | `export` | Write Markdown / HTML / OpenInference-compatible JSON / OTLP JSON **locally** |
 | `diff` | Compare two local runs (read-only) |
+| `timeline` | Chronological view of one run |
+| `stats` | Local aggregates over a trace directory |
+| `search` | Deterministic search over local traces |
 
 Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
@@ -159,41 +177,36 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 - See **which step dominated latency** in a multi-step planner or RAG pipeline.
 - **Diff two runs** after a prompt, model, or routing change (see [diff examples](docs/DIFF.md)).
 - Point **`logs`** / **`tail`** at existing job or service logs to get a **local execution view** without shipping data upstream.
-- **Export** a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.
+- **Export** a run to Markdown for a PR, postmortem, or internal thread — use `--redaction-profile share` for share-safe copies, then review before sharing.
 - Keep traces **on disk** while still using enterprise observability elsewhere.
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.1.0**) stabilizes the **local debugging foundation**:
+**agent-inspect 1.x** (current: **1.3.0**) is the **local-first trace workbench** for TypeScript AI agents:
 
-- Instrument a run with `inspectRun` and `step`
+- Instrument runs with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
-- Inspect runs with **`list`** and **`view`**
-- Safely remove old trace files with **`clean`**
+- Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**
 
-**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`, `getCurrentCorrelationMetadata()`.
 
-Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` (or `true` / `yes` / `on` / `enabled`) to toggle tracing in eval or CI jobs — see [docs/API.md](docs/API.md).
+Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` to toggle tracing in eval or CI — see [docs/API.md](docs/API.md).
 
-**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
+**Shipped in 1.3.0:** correlation metadata; redaction profiles (`local` / `share` / `strict`); `export --redaction-profile`; LangChain `stream: true` metadata (chunk counts, duration — no full token capture by default).
 
-**Also included in 1.x** as local-first extensions:
+**Also in 1.x** (local-first extensions):
 
-- Structured log inspection: **`logs`**
-- Live log tailing: **`tail`**
-- Local exports: **`export`** (Markdown, HTML, OpenInference-compatible JSON, OTLP JSON — files only)
-- Local run comparison: **`diff`**
-- Optional **`@agent-inspect/langchain`** callback adapter
-- Optional **`@agent-inspect/tui`** terminal viewer
-- **Fixtures** and **recipes** for deterministic checks and adoption patterns
+- **v1.2.0** — experimental persisted-event foundation (`PersistedInspectEvent`, converters, in-memory tree bridge). Manual writing remains **`schemaVersion: "0.1"`**; v0.2 is **not written by default**.
+- Optional **`@agent-inspect/langchain`** and **`@agent-inspect/tui`**
+- **Fixtures** and **recipes** for deterministic adoption patterns
 
-**Honest boundaries:** programmatic log parsing, export, and diff APIs; LangChain and TUI programmatic surfaces; and OpenInference/OTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.
+**Honest boundaries:** log parsing, export, diff, LangChain/TUI programmatic APIs, and OpenInference/OTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.
 
 ## Optional packages
 
 ### LangChain callback adapter (`@agent-inspect/langchain`)
 
-Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
+Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. Optional **`stream: true`** records chunk counts and stream duration **without storing full token text by default**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
 
 ```bash
 pnpm add agent-inspect @agent-inspect/langchain @langchain/core
@@ -271,25 +284,15 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 
 ## Documentation
 
-- [Getting started](docs/GETTING-STARTED.md)
-- [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md)
-- [API stability & experimental surfaces](docs/API.md)
-- [CLI reference](docs/CLI.md)
-- [Schema (`schemaVersion: "0.1"`)](docs/SCHEMA.md)
-- [Architecture (links to deeper design notes)](docs/ARCHITECTURE.md)
-- [Logs & tail](docs/LOGS.md)
-- [Log-to-tree quickstart](docs/LOG-TO-TREE-QUICKSTART.md)
-- [Logging playbook](docs/LOGGING-PLAYBOOK.md)
-- [Exports](docs/EXPORTS.md)
-- [Diff](docs/DIFF.md)
-- [Adapters](docs/ADAPTERS.md)
-- [Compare with other tools](docs/COMPARE.md)
-- [Security](SECURITY.md)
-- [Safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md)
-- [Changelog](CHANGELOG.md)
-- [Known issues](docs/KNOWN-ISSUES.md)
-- [Limitations](docs/LIMITATIONS.md)
-- [Screenshot checklist (planned assets)](docs/SCREENSHOTS.md)
+| Start here | Reference | Safety & boundaries |
+| ---------- | --------- | ------------------- |
+| [Getting started](docs/GETTING-STARTED.md) | [API](docs/API.md) | [Safe trace sharing](docs/SAFE-TRACE-SHARING.md) |
+| [Install smoke test](docs/INSTALL-SMOKE-TEST.md) | [CLI](docs/CLI.md) | [Security](SECURITY.md) |
+| [Log-to-tree quickstart](docs/LOG-TO-TREE-QUICKSTART.md) | [Schema](docs/SCHEMA.md) | [Limitations](docs/LIMITATIONS.md) |
+| [Logging playbook](docs/LOGGING-PLAYBOOK.md) | [Exports](docs/EXPORTS.md) | [Known issues](docs/KNOWN-ISSUES.md) |
+| [Examples](examples/README.md) | [Adapters](docs/ADAPTERS.md) | [Compare with other tools](docs/COMPARE.md) |
+
+Also: [Architecture](docs/ARCHITECTURE.md) · [Logs & tail](docs/LOGS.md) · [Diff](docs/DIFF.md) · [Changelog](CHANGELOG.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Good first issues](GOOD-FIRST-ISSUES.md)
 
 ## Contributing
 

package/docs/ADAPTERS.md

@@ -1,26 +1,38 @@
-## Adapters
+# Adapters
 
-AgentInspect is framework-agnostic at its core, but can optionally integrate with frameworks via adapter packages.
+AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
-- **LangChain.js adapter** (optional): `@agent-inspect/langchain`
-  - Documented as **experimental** in `docs/API.md`
-  - Requires `@langchain/core` as a peer dependency
-  - **In-memory by default** (`getEvents()` / `clear()`)
-  - **Optional JSONL persistence** (`persist: true`) maps callback lifecycle to schemaVersion `"0.1"` manual events (`run_started`, `step_started`, `step_completed`, `run_completed`) so `list` / `view` / `export` / `diff` work without a separate schema
-  - **Metadata-only capture by default**; `capture: "preview"` is opt-in with truncation
-  - **No monkey-patching**, **no vendor sinks**, **no network upload**
-- **Interactive TUI** (optional): `@agent-inspect/tui`
-  - Documented as **experimental** in `docs/API.md`
-  - Intended for CLI integration; programmatic TUI APIs may change
+## LangChain.js (`@agent-inspect/langchain`)
 
-### LangChain persistence model (Strategy A)
+**Status:** experimental — programmatic API may evolve independently of stable core tracing.
 
-When `persist: true`:
+### Install
 
-1. **Standalone callback session** — one AgentInspect run per `AgentInspectCallback` instance until the root LangChain run completes.
-2. **Inside `inspectRun`** — callback steps append to the active manual run (no extra `run_started` / `run_completed`).
-3. **Parent mapping** — LangChain `parentRunId` maps to AgentInspect `parentId` when the parent step was already persisted; unknown parents stay at run root (no invented hierarchy).
-4. **Step types** — `LLM` → `llm`, `TOOL` → `tool`, `DECISION` → `decision`, other kinds → `logic`.
+```bash
+npm install agent-inspect @agent-inspect/langchain @langchain/core
+```
+
+### Basic callback (in-memory)
+
+```ts
+import { AgentInspectCallback } from "@agent-inspect/langchain";
+
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  capture: "metadata-only", // default
+});
+
+await agent.invoke(input, { callbacks: [callback] });
+
+const events = callback.getEvents();
+callback.clear();
+```
+
+- **No monkey-patching** — pass the callback explicitly to LangChain.
+- **Metadata-only by default** — does not capture full prompts/outputs unless you opt into `capture: "preview"`.
+- **No vendor sink** — events stay in memory unless you set `persist: true`.
+
+### Persist to local JSONL
 
 ```ts
 const callback = new AgentInspectCallback({
@@ -29,14 +41,103 @@ const callback = new AgentInspectCallback({
   persist: true,
   capture: "metadata-only",
 });
+
+await agent.invoke(input, { callbacks: [callback] });
 ```
 
 ```bash
 npx agent-inspect list --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
 ```
 
-See also:
-- `docs/MIGRATION.md` (what changed from early versions)
-- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `traceDir`)
+**Persistence model (Strategy A):**
+
+1. **Standalone session** — one AgentInspect run per callback instance until the root LangChain run completes.
+2. **Inside `inspectRun`** — callback steps append to the active manual run (no extra `run_started` / `run_completed`).
+3. **Parent mapping** — LangChain `parentRunId` maps to AgentInspect `parentId` when the parent step was persisted; unknown parents stay at run root.
+4. **Step types** — `LLM` → `llm`, `TOOL` → `tool`, `DECISION` → `decision`, other kinds → `logic`.
+
+Written events use `schemaVersion: "0.1"` manual trace names.
+
+### Capture modes
+
+| `capture` | Behavior |
+| --------- | -------- |
+| `none` | Minimal metadata |
+| `metadata-only` | **Default** — model names, token usage, timing; no full text |
+| `preview` | Truncated previews via `maxPreviewChars` — review before sharing |
+
+### Streaming metadata (v1.3.0+)
+
+```ts
+const callback = new AgentInspectCallback({
+  stream: true,
+  capture: "metadata-only",
+  persist: true,
+});
+```
+
+When `stream: true`:
+
+- `handleLLMNewToken` updates **in-memory stats only** — no per-token JSONL lines.
+- On LLM end/error: `chunkCount`, `firstChunkAt`, `lastChunkAt`, `streamDurationMs`, `streamedCharCount`.
+- **`capture: "metadata-only"`** does **not** store raw token text.
+- **`capture: "preview"`** may include bounded `streamPreview` via `maxStreamPreviewChars`.
+- With **`persist: true`**, streaming metadata is written on the LLM step at completion (deferred write for streaming LLM steps).
+
+Streaming metadata is for **local inspection and timing** — not replay or cassette playback.
+
+### Correlation inside `inspectRun`
+
+When the callback runs inside `inspectRun` / `maybeInspectRun`, correlation fields from `getCurrentCorrelationMetadata()` attach to LLM lifecycle events.
+
+### Options reference
+
+| Option | Default | Notes |
+| ------ | ------- | ----- |
+| `persist` | `false` | Write local JSONL |
+| `runName` | `"langchain-agent"` | Standalone persisted run name |
+| `traceDir` | from env / `.agent-inspect` | |
+| `capture` | `"metadata-only"` | |
+| `stream` | `false` | Streaming lifecycle metadata |
+| `maxStreamPreviewChars` | `maxPreviewChars` | Bounds preview when `capture: "preview"` |
+| `redact` | — | Custom `RedactionRule[]` before disk |
+
+Full API: [API.md](./API.md) §9.
+
+### Example
+
+[examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
+
+---
+
+## TUI (`@agent-inspect/tui`)
+
+**Status:** experimental programmatic API; CLI integration is the intended usage.
+
+```bash
+npm install agent-inspect @agent-inspect/tui
+npx agent-inspect view <run-id> --tui
+```
+
+Requires an interactive terminal. See [API.md](./API.md) §10.
+
+---
+
+## Future adapters (not shipped)
+
+Direction only — see [ROADMAP.md](../ROADMAP.md):
+
+- **Vercel AI SDK** — optional callback-style adapter (metadata-first, no vendor sink)
+- **NestJS / logging bridges** — deeper recipes or helper patterns beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+
+No automatic universal instrumentation. Integrations remain explicit and opt-in.
+
+---
+
+## Related docs
 
+- [API.md](./API.md) — adapter options and stability policy
+- [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — review exports before sharing
+- [LIMITATIONS.md](./LIMITATIONS.md) — LangChain streaming and metadata boundaries

package/docs/API.md

@@ -26,16 +26,21 @@ import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
 ```
 
 - **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
-  - **`redact`**: default `true` — redacts sensitive metadata keys before disk (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Pass `false` to persist metadata as-is. Pass `{ rules?: RedactionRule[] }` for custom rules (defaults still apply).
+  - **`redact`**: default `true` — redacts sensitive metadata keys before disk (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Pass `false` to persist metadata as-is. Pass `{ rules?: RedactionRule[] }` for custom rules (defaults still apply). **`redact: false` wins** over `redactionProfile` for trace writing.
+  - **`redactionProfile`**: optional preset — `local` (default), `share`, or `strict`. Adds extra key-based redaction and tighter metadata string bounds for trace writing. Key-based only — not compliance-grade DLP.
   - **`maxMetadataValueLength`**: max string length for metadata values (default `2000`).
   - **`maxPreviewLength`**: max string length for preview-like keys containing `preview` (default `500`).
   - **`maxEventBytes`**: max UTF-8 bytes per serialized JSONL event (default `65536`). Oversized events are truncated; instrumentation never throws into user code.
+  - **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` strings. When set, they are written on `run_started.metadata` (not on every step). Top-level correlation options override the same keys in `options.metadata`. Useful for eval cases, CI job IDs, request tracing, and future stats/cohort views. They are **metadata only** — they do not replace `runId`. Treat sensitive IDs as trace data before sharing exports.
 - **`maybeInspectRun(name, fn, options?)`**: same as `inspectRun` when tracing is enabled; otherwise passthrough. Enablement: explicit **`options.enabled`** wins; when omitted, reads **`AGENT_INSPECT`** (`1`, `true`, `yes`, `on`, `enabled` — case-insensitive). Unset or other values disable tracing. Use in eval harnesses, CI, or jobs where tracing should be toggled by environment.
 - **`isAgentInspectEnabled(value?)`**: returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
 - **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`). Step `metadata` inherits the parent run's redaction and size-bound settings.
   - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
   - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
 - **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
+- **`getCurrentCorrelationMetadata()`**: returns active run correlation fields (`correlationId`, `requestId`, `decisionId`, `groupId`) inside `inspectRun` / `maybeInspectRun`; `undefined` outside a traced run or when none were set.
+- **`RedactionProfile`**: `"local" | "share" | "strict"` — see `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- **`resolveRedactionProfile(profile?)`**: resolves profile extra keys and metadata caps (for advanced integrations).
 
 ## 3. Stable local inspection APIs
 
@@ -95,7 +100,8 @@ The CLI `tail` workflow is supported. The programmatic accumulator is experiment
 
 Exports are **read-only**, **local-only**, and **compatibility-oriented**. They do not upload, stream, or integrate vendor SDKs.
 
-- **`exportRunTree`**
+- **`exportRunTree`**, **`redactRunTreeForExport`**
+- **`ExportOptions.redactionProfile`**: `local` (default), `share`, or `strict` — applies key-based redaction to an exported copy without mutating the source tree.
 - **`exportMarkdown`**, **`exportHtml`**
 - **`exportOpenInference`** (OpenInference-compatible JSON)
 - **`exportOtlpJson`** (OTLP JSON, experimental until verified per backend)
@@ -119,6 +125,8 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
   - **`runName`**: default `"langchain-agent"` for standalone persisted runs
   - **`traceDir`**: defaults via `resolveTraceDir` / `AGENT_INSPECT_TRACE_DIR`
   - **`capture`**: `"none"` | `"metadata-only"` (default) | `"preview"` (truncated previews, opt-in)
+  - **`stream`**: default `false` — when `true`, records streaming lifecycle metadata (`chunkCount`, `streamDurationMs`, etc.) on LLM end/error; does **not** capture full token text by default
+  - **`maxStreamPreviewChars`**: bounds `streamPreview` when `capture: "preview"` and `stream: true` (defaults to `maxPreviewChars`)
   - **`redact`**: custom `RedactionRule[]` applied before disk (core defaults still apply via shared redactor)
   - **`runId`**: optional id for standalone persisted runs
   - In-memory **`getEvents()`** / **`clear()`** unchanged when `persist` is false
@@ -158,23 +166,33 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 - v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
 - Storage dual-read and CLI integration are future work.
 
-## 12. Deprecated APIs
+## 12. Local observability helpers (v1.4.0)
 
-No deprecated APIs are declared as of 1.1.0.
+Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL. Local files only.
 
-## 13. Removal / deprecation policy
+- **`buildRunTimeline`**, **`renderTimeline`** — chronological run view; types `RunTimeline`, `TimelineEntry`
+- **`buildTraceStats`**, **`renderTraceStats`** — directory aggregates; type `TraceStats`
+- **`searchTraces`**, **`parseDurationFilter`**, **`loadTraceMetadataList`** — deterministic search; types `TraceSearchResult`, `TraceSearchOptions`
+
+CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
+
+## 13. Deprecated APIs
+
+No deprecated APIs are declared as of 1.4.0.
+
+## 14. Removal / deprecation policy
 
 - Stable APIs are not removed in v1.x.
 - If removal is necessary, the API should be **deprecated** first, documented, and kept for a reasonable window (target: at least one minor line) unless security requires faster action.
 
-## 14. Backward compatibility policy
+## 15. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.
 - Breaking changes require a major version.
 - Unknown fields should be ignored where safe.
 
-## 15. Examples
+## 16. Examples
 
 ### Minimal manual trace
 

package/docs/ARCHITECTURE.md

@@ -19,7 +19,7 @@ Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consume
 - Manual traces use **`schemaVersion: "0.1"`** JSONL events (`run_started`, `step_started`, `step_completed`, `run_completed`).
 - Failures use `step_completed` with `status: "error"` — there is no `step_failed` event.
 - Log-derived runs use confidence labels (`explicit`, `correlated`, `heuristic`, `unknown`) and conservative tree-building rules.
-- **v1.2.0 persisted-event foundation (release-readiness):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are future work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.2.0-RELEASE-READINESS.md](./implementation/V1.2.0-RELEASE-READINESS.md).
+- **v1.2.0 persisted-event foundation (released):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are v1.3+ / post-foundation work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.3.0-RELEASE-TRAIN.md](./implementation/V1.3.0-RELEASE-TRAIN.md).
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.0)
+# CLI (AgentInspect 1.x)
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -26,6 +26,9 @@ Core commands:
 - `tail` — live-tail logs into updating local trees
 - `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
 - `diff` — compare two manual traces (local, read-only)
+- `timeline` — chronological view of one run (local JSONL)
+- `stats` — local aggregate stats over a trace directory
+- `search` — deterministic local search over traces
 
 ## 2. Environment variables
 
@@ -162,7 +165,7 @@ Important: `tail` is a local developer tool, not a production monitor.
 
 ### 6.6 `export`
 
-Export a manual trace run to local formats. **No upload**.
+Export a manual trace run to local formats. **No upload.** Export redaction operates on a **copy** of the run tree — original JSONL files are not modified. Review every export before sharing, even with `--redaction-profile strict`.
 
 ```bash
 agent-inspect export <run-id> --format <markdown|html|openinference|otlp-json> [options]
@@ -178,6 +181,14 @@ Options:
 - `--include-attributes`: include bounded attributes (review before sharing)
 - `--no-metadata`: omit summary/metadata sections
 - `--no-errors`: omit error sections
+- `--redaction-profile <profile>`: redaction profile for exported copies — `local` (default), `share`, or `strict`. Key-based safety only; review exports before sharing.
+
+Examples:
+
+```bash
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+```
 
 ### 6.7 `diff`
 
@@ -243,6 +254,64 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
+### 6.8 `timeline`
+
+Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
+
+```bash
+agent-inspect timeline <run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--json` — structured `RunTimeline` JSON
+- `--focus slow` — show only the slowest steps by duration (top N)
+
+### 6.9 `stats`
+
+Local aggregate statistics over trace files in a directory. Read-only.
+
+```bash
+agent-inspect stats [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--since <duration>` — e.g. `7d`, `24h`
+- `--correlation-id <id>` — filter by `run_started.metadata.correlationId`
+- `--group-id <id>` — filter by `run_started.metadata.groupId`
+- `--json`
+
+### 6.10 `search`
+
+Deterministic search over local traces (substring / exact filters). No semantic search.
+
+```bash
+agent-inspect search [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--since <duration>`
+- `--status <success|error|running|unknown>`
+- `--kind <kind>` / `--type <type>` — manual step type (`llm`, `tool`, `logic`, …)
+- `--name <query>` — substring on run or step name
+- `--tool <query>` — substring on tool step name or `metadata.toolName`
+- `--duration <expr>` — e.g. `>5s`, `>=500ms`
+- `--limit <number>` — default 50
+- `--json`
+
+Examples:
+
+```bash
+npx agent-inspect search --status error --dir ./.agent-inspect
+npx agent-inspect search --kind tool --name search
+npx agent-inspect search --duration ">100ms" --json
+```
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

package/docs/EXPORTS.md

@@ -1,12 +1,84 @@
-## 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).
 
-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.
+## CLI
 
+```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.
+
+## 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
+
+Prefer the smallest useful artifact — a summary or synthetic reproduction beats a full production trace.
+
+## 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