agent-inspect 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.6.0
+
+Released **2026-06-25**.
+
+### Added
+
+- Added experimental `agent-inspect/writers` subpath with `TraceWriter`, `fileWriter`, `bufferedFileWriter`, `compositeWriter`, `memoryWriter`, and `nullWriter` as the first v1.6 runtime foundation slice.
+- Added experimental `createInspectorRuntime()` as the low-level instance-scoped runtime foundation.
+- Added experimental `createInspector()` public instance API for isolated local tracing with explicit writers.
+- Added experimental `agent-inspect/readers` subpath with the `TraceReader` contract, deterministic format detection, `readTrace()`, and `openTrace()` for future local ingestion readers.
+- Added the default AgentInspect JSONL reader behind `readTrace()` / `openTrace()` for v0.1, v0.2, and mixed local trace files.
+- Added local OpenInference JSON and OTLP JSON readers behind `agent-inspect/readers`.
+- Added `agent-inspect open` for local AgentInspect JSONL, OpenInference JSON, OTLP JSON, directory, and stdin ingestion through the canonical reader pipeline.
+- Added deterministic runtime/universal-ingestion recipe coverage for memory writer, buffered writer, `createInspector()`, explicit formats, stdin, and safe shutdown.
+
+### Changed
+
+- Shared inspection commands now route AgentInspect JSONL loading through the canonical reader pipeline where compatible.
+
+### Fixed
+
+- Corrects the published CLI version path so `agent-inspect --version` reports the public package version.
+- Makes `list`, `stats`, and `search` use the canonical dual-format read path for v0.1 and v0.2 trace files.
+- Applies `report --redaction-profile share|strict` to the complete report, not only the execution tree section.
+- Preserves mixed v0.1/v0.2 source ordering during normalization.
+- Preserves error stack fidelity when converting persisted v0.2 events; `error.name` is no longer mapped to v0.1 `stack`.
+- Preserves supported token usage fields across converters and inspection summaries: `input`, `output`, `total`, and `cached`.
+
+### Notes
+
+- Manual trace writing remains `schemaVersion: "0.1"`.
+- v0.2 remains an experimental persisted-event foundation and dual-read input format, not the default writer.
+- No provider pricing, token counting, cost engine, vendor upload, hosted ingestion, replay, or default telemetry behavior is included.
+- This release includes corrective work accumulated after v1.5.0 plus the v1.6.0 runtime/reader foundation.
+
 ## 1.5.0
 
 Released **2026-06-24**.

package/README.md

@@ -22,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.5.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
+Current npm release: **1.6.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -111,18 +111,19 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-## What you can do today (v1.5.0)
+## What you can do today (v1.6.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`, `what`, `report`.
+- **Inspect from the CLI** — `list`, `view`, `clean`, `logs`, `tail`, `export`, `open`, `diff`, `timeline`, `stats`, `search`, `what`, `report`.
 - **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"`.
+- **Experimental v1.6.0 APIs** — `agent-inspect/writers`, `agent-inspect/readers`, `createInspector()`, and `agent-inspect open` for local AgentInspect/OpenInference/OTLP ingestion.
 
 Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
 
@@ -172,6 +173,7 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `logs` | Turn existing structured logs into a local tree/timeline |
 | `tail` | Watch structured logs while the app runs |
 | `export` | Write Markdown / HTML / OpenInference-compatible JSON / OTLP JSON **locally** |
+| `open` | Read AgentInspect JSONL, OpenInference JSON, or OTLP JSON locally |
 | `diff` | Compare two local runs (read-only) |
 | `timeline` | Chronological view of one run |
 | `stats` | Local aggregates over a trace directory |
@@ -196,7 +198,7 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.5.0**) is the **local-first trace workbench** for TypeScript AI agents:
+**agent-inspect 1.x** (current: **1.6.0**) is the **local-first trace workbench** for TypeScript AI agents:
 
 - Instrument runs with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
@@ -206,8 +208,12 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.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).
 
+**Shipped in 1.6.0:** experimental writer subpath (`agent-inspect/writers`), isolated `createInspector()` API via `agent-inspect/advanced`, local trace readers via `agent-inspect/readers`, OpenInference/OTLP JSON readers, universal `agent-inspect open`, and deterministic [runtime-and-ingestion recipe](examples/recipes/runtime-and-ingestion/). These remain local-only and do not add upload behavior. Linked release aligns all three npm packages at **1.6.0**.
+
 **Shipped in 1.5.0:** non-breaking subpath exports; `what` and `report` CLI; dual-format read path (v0.1 + v0.2 JSONL); [what-report-inspect recipe](examples/recipes/what-report-inspect/). Linked release aligns all three npm packages at **1.5.0**.
 
+**Roadmap beyond current release work:** future work continues from the local runtime and universal ingestion foundation before broadening framework adapters. See [ROADMAP.md](ROADMAP.md).
+
 **Shipped in 1.4.0:** CI artifact recipe ([docs/CI-ARTIFACTS.md](docs/CI-ARTIFACTS.md)); `timeline`, `stats`, and `search` CLI; core helpers `buildRunTimeline`, `buildTraceStats`, `searchTraces`. Linked release aligns all three npm packages at **1.4.0**.
 
 **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).
@@ -283,6 +289,8 @@ The TUI is available as a separate optional package; its programmatic API is exp
 | [examples/recipes/retry-fallback](examples/recipes/retry-fallback) | Fallback pattern |
 | [examples/recipes/parallel-tools](examples/recipes/parallel-tools) | Parallel tools |
 | [examples/recipes/github-actions-artifact](examples/recipes/github-actions-artifact) | CI trace artifacts |
+| [examples/recipes/what-report-inspect](examples/recipes/what-report-inspect/) | `what` + `report` inspection |
+| [examples/recipes/runtime-and-ingestion](examples/recipes/runtime-and-ingestion/) | v1.6 runtime writers + universal ingestion |
 
 **Recipes** are deterministic and require **no external services** by default. Index: [examples/README.md](examples/README.md), [examples/recipes/README.md](examples/recipes/README.md).
 

package/docs/API.md

@@ -9,12 +9,14 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 - **Stable**: intended to be compatible across v1.x. Breaking changes require v2.0.
 - **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration. Experimental APIs may change in v1.x.
 
-**v1.5.0 subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
+**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
 
 ```ts
 import { inspectRun, step } from "agent-inspect";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { exportMarkdown } from "agent-inspect/exporters";
+import { memoryWriter } from "agent-inspect/writers";
+import { openTrace } from "agent-inspect/readers";
 ```
 
 Notes:
@@ -172,11 +174,11 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 
 - Manual trace **writing** remains `schemaVersion: "0.1"`.
 - 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.
+- Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. v0.2 remains experimental as a persisted-event foundation and is not the default writer.
 
-## 12. Local observability helpers (v1.4.0)
+## 12. Local observability helpers (v1.4.0+)
 
-Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL. Local files only.
+Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1 manual traces remain the default writer; v0.2 persisted-event files are accepted where the shared dual-format read path is used. Local files only.
 
 - **`buildRunTimeline`**, **`renderTimeline`** — chronological run view; types `RunTimeline`, `TimelineEntry`
 - **`buildTraceStats`**, **`renderTraceStats`** — directory aggregates; type `TraceStats`
@@ -184,23 +186,137 @@ Read-only helpers for timeline, stats, and search over manual `TraceEvent` JSONL
 
 CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
 
-## 13. Deprecated APIs
+## 13. Report and what helpers (v1.5.0+)
+
+Read-only helpers for concise inspection summaries and local reports:
+
+- **`buildRunWhatSummary`**, **`renderRunWhat`** — summarize status, duration, step counts, correlation metadata, slowest step, errors, and supplied token usage.
+- **`buildRunReport`** — render Markdown or HTML reports from local trace events.
+
+Report redaction profiles are key-based safeguards applied to the complete rendered report input, not only to the tree section. Review generated reports before sharing; this is not compliance-grade DLP.
+
+## 14. Experimental trace writers (v1.6)
+
+Trace writers are the first slice of the v1.6 runtime foundation. They are experimental during v1.x and intended for tests, adapters, and future `createInspector` work.
+
+Import from `agent-inspect/writers`:
+
+```ts
+import {
+  bufferedFileWriter,
+  compositeWriter,
+  fileWriter,
+  memoryWriter,
+  nullWriter,
+} from "agent-inspect/writers";
+import type {
+  BufferedFileWriterOptions,
+  CompositeTraceWriterOptions,
+  FileTraceWriterOptions,
+  TraceWriter,
+  TraceWriterStats,
+} from "agent-inspect/writers";
+```
+
+- **`TraceWriter`**: async `write(event)`, optional `flush()`, optional `close()`, optional `getStats()`.
+- **`fileWriter({ dir?, filePath? })`**: appends v0.2 `PersistedInspectEvent` JSONL rows to local disk. By default it derives one file per `event.runId`; `filePath` writes all events to an explicit local file. Filesystem and serialization failures are reflected in writer stats instead of being thrown into application code.
+- **`bufferedFileWriter({ dir?, filePath?, maxQueueSize?, flushIntervalMs?, maxBatchSize?, overflow? })`**: buffers local JSONL writes with bounded queue behavior. Overflow supports `drop-oldest` and `drop-newest`; neither mode throws into application code.
+- **`compositeWriter([...writers])`**: fans out events to multiple explicit local/custom writers. A failing child writer does not prevent other children from receiving events; failures are reflected in composite stats.
+- **`memoryWriter()`**: stores cloned `PersistedInspectEvent` rows in memory for tests, adapter fixtures, and eval harnesses.
+- **`nullWriter()`**: accepts events without retaining them for disabled mode, overhead comparisons, and no-output tests.
+
+No network writer or vendor sink exists in this package.
+
+## 15. Experimental inspector API/runtime (v1.6)
+
+`createInspector()` is the experimental public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records v0.2 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
+
+Import from `agent-inspect/advanced`:
+
+```ts
+import { createInspector } from "agent-inspect/advanced";
+import { memoryWriter } from "agent-inspect/writers";
+
+const writer = memoryWriter();
+const inspector = createInspector({
+  writer,
+  capture: { onSuccess: "metadata-only", onError: "metadata-only" },
+});
+
+await inspector.run("support-agent", async () => {
+  await inspector.step("plan", async () => "ok");
+  await inspector.tool("retrieve-policy", async () => "policy");
+  return inspector.llm("fixture-model", async () => "done");
+});
+
+await inspector.flush();
+```
+
+Public methods:
+
+- **`run(name, fn, options?)`**: starts an isolated run context and writes run lifecycle events.
+- **`step(name, fn, options?)`**: writes nested step lifecycle events when called inside the same inspector's run context; outside a context it passes through.
+- **`tool(name, fn, options?)`** / **`llm(name, fn, options?)`**: convenience wrappers that set `type` and metadata.
+- **`observe(name, fn, options?)`**: returns an async wrapper that records the function call as an inspector step.
+- **`getDiagnostics()`**: returns instrumentation error counts and writer stats without requiring direct runtime access.
+- **`flush()`** / **`close()`**: delegate to the configured writer through the runtime.
+
+`capture` is explicit and metadata-only. `onSuccess: "metadata-only"` records safe type/length/key-count summaries in `outputSummary`; `onError: "metadata-only"` records thrown-value type/name summaries. It does not store raw return values, prompts, outputs, or thrown objects. Use `"none"` to disable a capture side.
+
+`traceDir` and `silent` on `createInspector()` are context metadata for compatibility with existing helpers. They do not configure persistence or terminal output. Prefer writer-owned output configuration such as `fileWriter({ dir })` or `fileWriter({ filePath })`.
+
+`createInspectorRuntime()` is also available from `agent-inspect/advanced` as the low-level isolation primitive. Most users should prefer `createInspector()` and `inspector.getDiagnostics()`. Root exports for the runtime remain available for 1.x compatibility, but new advanced usage should import from `agent-inspect/advanced`.
+
+These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
+
+## 16. Experimental trace readers (v1.6)
+
+`agent-inspect/readers` exposes the experimental local trace reader contract and detection pipeline. It includes AgentInspect JSONL for v0.1, v0.2, and mixed local trace files, plus local OpenInference JSON and OTLP JSON compatibility readers.
+
+Import from `agent-inspect/readers`:
+
+```ts
+import {
+  DEFAULT_TRACE_READERS,
+  agentInspectJsonlReader,
+  detectTraceFormat,
+  openInferenceJsonReader,
+  openTrace,
+  otlpJsonReader,
+  readTrace,
+} from "agent-inspect/readers";
+import type { TraceReader } from "agent-inspect/readers";
+```
+
+- **`TraceInput`**: file, directory, string, buffer, or stdin input descriptor.
+- **`TraceReader`**: experimental reader interface with `format`, `detect(input)`, and `read(input)`.
+- **`detectTraceFormat(input, { readers?, format? })`**: deterministic, conservative format detection. Explicit `format` acts as an override only when a matching reader is registered.
+- **`readTrace(input, { readers?, format? })`**: detects a reader and returns `TraceReadResult`; unsupported or ambiguous input throws `TraceReadError`.
+- **`openTrace(input, options?)`**: alias for `readTrace()` and the API path used by the universal `agent-inspect open` command.
+- **`agentInspectJsonlReader`**: built-in local AgentInspect JSONL reader for v0.1, v0.2, and mixed files/directories.
+- **`openInferenceJsonReader`**: local OpenInference JSON compatibility reader. Prompt/output-like attributes are summarized and bounded rather than stored as raw content.
+- **`otlpJsonReader`**: local OTLP/HTTP JSON trace payload reader. Resource, scope, span, status, event, and parent metadata are preserved where possible with warnings for unsupported fields.
+- **`DEFAULT_TRACE_READERS`**: ordered built-in reader registry used when no custom `readers` array is supplied.
+
+The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
+
+## 17. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 14. Removal / deprecation policy
+## 18. 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.
 
-## 15. Backward compatibility policy
+## 19. 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.
 
-## 16. Examples
+## 20. Examples
 
 ### Minimal manual trace
 
@@ -214,4 +330,3 @@ await inspectRun("demo-agent", async () => {
   return { plan, hits, answer };
 });
 ```
-

package/docs/ARCHITECTURE.md

@@ -39,6 +39,10 @@ See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
 
 See [ADAPTERS.md](./ADAPTERS.md).
 
+### Architecture proposals
+
+Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active post-v1.5 roadmap is [implementation/ROADMAP-V1.6-TO-V3.md](./implementation/ROADMAP-V1.6-TO-V3.md).
+
 ### Where to read next
 
 - New users: [GETTING-STARTED.md](./GETTING-STARTED.md)

package/docs/CLI.md

@@ -25,6 +25,7 @@ Core commands:
 - `logs` — parse structured logs into local execution trees
 - `tail` — live-tail logs into updating local trees
 - `export` — export manual traces to Markdown/HTML/OpenInference/OTLP JSON (local only)
+- `open` — read supported local trace files, directories, or stdin through the canonical reader pipeline
 - `diff` — compare two manual traces (local, read-only)
 - `timeline` — chronological view of one run (local JSONL)
 - `stats` — local aggregate stats over a trace directory
@@ -192,7 +193,36 @@ 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`
+### 6.7 `open`
+
+Open any local trace format supported by the canonical reader pipeline. This command is read-only: it does not mutate input files, upload traces, or run agents.
+
+```bash
+agent-inspect open [input] [options]
+```
+
+`input` may be a file, directory, `-` for stdin, or omitted to read stdin.
+
+Options:
+
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--json`: print structured JSON output
+- `--diagnostics`: print reader warnings and unsupported fields in human output
+
+Examples:
+
+```bash
+npx agent-inspect open fixtures/traces/minimal-success.jsonl --format agent-inspect-jsonl
+npx agent-inspect open fixtures/traces-v0.2/manual-basic.jsonl --format agent-inspect-jsonl
+npx agent-inspect open packages/core/test/fixtures/openinference-basic.json --format openinference-json
+npx agent-inspect open packages/core/test/fixtures/otlp-basic.json --format otlp-json
+cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect open - --format openinference-json --json
+```
+
+When a directory or payload contains multiple runs, `open` lists the run ids and exits until you pass `--run <run-id>`.
+
+### 6.8 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -256,7 +286,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.8 `timeline`
+### 6.9 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -272,7 +302,7 @@ Options:
 
 ![Timeline with slow-step focus](../assets/demos/timeline.gif)
 
-### 6.9 `stats`
+### 6.10 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -292,7 +322,7 @@ Options:
 
 Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
 
-### 6.10 `search`
+### 6.11 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -322,9 +352,9 @@ npx agent-inspect search --duration ">100ms" --json
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.11 `what`
+### 6.12 `what`
 
-Concise human-readable summary of one manual trace run. Read-only; uses local v0.1 JSONL (v0.2 dual-read lands in v1.5.0 Chunks 7–8). Vocabulary: [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md).
+Concise human-readable summary of one local trace run. Read-only; accepts v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path. Vocabulary: [TRACE-VOCABULARY-V1.5.md](./proposals/TRACE-VOCABULARY-V1.5.md).
 
 ```bash
 agent-inspect what <run-id> [options]
@@ -351,9 +381,9 @@ Outcome: Completed successfully.
 Slowest: plan (100ms, logic)
 ```
 
-### 6.12 `report`
+### 6.13 `report`
 
-Generate a local inspection report combining **what happened**, **timeline**, and **execution tree** sections. Read-only over v0.1 JSONL. Distinct from `export` (which targets shareable tree snapshots and standards formats).
+Generate a local inspection report combining **what happened**, **timeline**, and **execution tree** sections. The command reads local v0.1 manual JSONL and v0.2 persisted-event JSONL through the shared dual-format normalization path without mutating them. Distinct from `export` (which targets shareable tree snapshots and standards formats).
 
 ```bash
 agent-inspect report <run-id> [options]
@@ -365,10 +395,10 @@ Options:
 - `--format <markdown|html>` — default `markdown`
 - `-o, --output <path>` — write to file
 - `--json` — JSON wrapper (includes `content` when writing to stdout)
-- `--include-attributes` — bounded attributes in tree section
-- `--no-errors` — omit error details from tree section
+- `--include-attributes` — bounded attributes in the execution tree section
+- `--no-errors` — omit error details from the execution tree section
 - `--no-correlation` — omit correlation ids from what section
-- `--redaction-profile <local|share|strict>` — tree section redaction (default `local`)
+- `--redaction-profile <local|share|strict>` — key-based redaction profile applied to the complete report (default `local`); review output before sharing
 
 Example:
 
@@ -390,4 +420,3 @@ See:
 
 - `docs/KNOWN-ISSUES.md`
 - `docs/LIMITATIONS.md`
-

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 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.
+- **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)
 

package/docs/SCHEMA.md

@@ -210,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`).
@@ -235,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -75,6 +75,26 @@
         "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": {