agent-inspect 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.7.0
+
+### Minor Changes
+
+- 94a7220: Release v1.7.0 framework-native adoption with the experimental AI SDK telemetry adapter, adapter conformance coverage, and local-first adapter documentation.
+
+## 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,14 @@ 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**.
+
+**In progress for 1.7.0 on main:** experimental `@agent-inspect/ai-sdk` telemetry integration for AI SDK v6 with a local no-network [ai-sdk-local-telemetry recipe](examples/recipes/ai-sdk-local-telemetry/). Examples keep `recordInputs: false`, `recordOutputs: false`, metadata-only capture, and no upload behavior.
+
 **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 +291,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/ADAPTER-CONFORMANCE.md

@@ -0,0 +1,35 @@
+# Adapter conformance
+
+AgentInspect optional framework adapters must stay local-first, dependency-isolated, and metadata-only by default.
+
+The machine-readable matrix lives at [docs/implementation/adapter-conformance-matrix.json](./implementation/adapter-conformance-matrix.json). It tracks expected coverage for:
+
+- run lifecycle
+- generic steps
+- tools
+- LLM calls
+- errors
+- streaming metadata
+- metadata bounds and privacy controls
+
+## Current matrix
+
+| Adapter | Package | Status | Default install mode | Boundary |
+| --- | --- | --- | --- | --- |
+| AI SDK | `@agent-inspect/ai-sdk` | implemented experimental | AI SDK telemetry integration | optional package peer dependency |
+| LangChain | `@agent-inspect/langchain` | implemented experimental | explicit callback | optional package peer dependency |
+| OpenAI Agents JS | `@agent-inspect/openai-agents` | scaffold only | `setTraceProcessors()` replacement | optional package peer dependency |
+| LangGraph | `@agent-inspect/langchain` | decision only | explicit LangChain callback | existing LangChain adapter first |
+
+## Required defaults
+
+- No network behavior.
+- No default upload behavior.
+- No root/core dependency on framework SDKs.
+- Metadata-only capture by default.
+- Raw prompts, messages, outputs, tool payloads, headers, request bodies, and response bodies must not be persisted by default.
+- Framework-specific fixtures must be no-network and dependency-isolated.
+
+## Before claiming support
+
+An adapter can be documented as supported only after no-network fixtures cover run, step, tool, LLM, error, streaming, and metadata-bound expectations for that framework path.

package/docs/ADAPTERS.md

@@ -2,6 +2,54 @@
 
 AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
+## Vercel AI SDK (`@agent-inspect/ai-sdk`)
+
+**Status:** experimental v1.7 train — optional workspace package; publication waits for v1.7 release readiness.
+
+### Install
+
+```bash
+npm install agent-inspect @agent-inspect/ai-sdk ai
+```
+
+### Local telemetry integration
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+const result = await generateText({
+  model,
+  prompt,
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: "./.agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+- **No monkey-patching** — pass the integration explicitly through AI SDK telemetry.
+- **No upload behavior** — the adapter writes only to an explicit local writer or `traceDir`.
+- **Metadata-only by default** — records model, finish reason, token usage, timing, and safe counts/summaries.
+- **Required safe telemetry settings** — set `recordInputs: false` and `recordOutputs: false` on every AI SDK call using this adapter.
+- **No raw payload capture by default** — prompts, messages, generated text, stream chunks, tool inputs/outputs, headers, request bodies, and response bodies are not persisted.
+
+### Local no-network recipe
+
+[examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/) uses AI SDK test utilities only (`MockLanguageModelV3`, `simulateReadableStream`) and writes local v0.2 adapter events for `agent-inspect open`.
+
+Full API: [API.md](./API.md) §11.
+
+---
+
 ## LangChain.js (`@agent-inspect/langchain`)
 
 **Status:** experimental — programmatic API may evolve independently of stable core tracing.
@@ -114,6 +162,14 @@ Full API: [API.md](./API.md) §9.
 
 [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 
+### LangGraph boundary
+
+LangGraph support is expected to ride through this same `@agent-inspect/langchain` callback boundary first. A dedicated LangGraph package is deferred until no-network fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.
+
+Future LangGraph examples must keep the same safety defaults: explicit callback installation, metadata-only capture, no raw prompt/output/tool payload capture by default, no hosted sink, and local persistence only when `persist: true` is set.
+
+Decision note: [LANGGRAPH-ADAPTER-BOUNDARY.md](./proposals/LANGGRAPH-ADAPTER-BOUNDARY.md).
+
 ---
 
 ## TUI (`@agent-inspect/tui`)
@@ -131,11 +187,32 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ---
 
+## OpenAI Agents JS (`@agent-inspect/openai-agents`)
+
+**Status:** scaffolded for v1.7 train — optional workspace package; runtime mapping is not implemented yet.
+
+The safe integration boundary is documented in [OPENAI-AGENTS-JS-TRACING.md](./proposals/OPENAI-AGENTS-JS-TRACING.md). Future examples must install the AgentInspect processor by replacing processors:
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspectProcessor({
+    traceDir: "./.agent-inspect",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The scaffold does not auto-install a processor, does not upload, and does not add OpenAI Agents dependencies to root/core.
+
+---
+
 ## 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.
@@ -145,5 +222,6 @@ No automatic universal instrumentation. Integrations remain explicit and opt-in.
 ## Related docs
 
 - [API.md](./API.md) — adapter options and stability policy
+- [ADAPTER-CONFORMANCE.md](./ADAPTER-CONFORMANCE.md) — no-network fixture matrix and shared expectations
 - [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

@@ -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:
@@ -148,7 +150,66 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 - `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
 
-## 11. Experimental persisted-event foundation (v1.2.0)
+## 11. Experimental `@agent-inspect/ai-sdk` APIs
+
+`@agent-inspect/ai-sdk` is an optional v1.7 adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental during the v1.7 train and remains private until release readiness.
+
+Import from `@agent-inspect/ai-sdk`:
+
+```ts
+import { agentInspect } from "@agent-inspect/ai-sdk";
+```
+
+- **`agentInspect(options?)`**: returns an AI SDK `TelemetryIntegration` bound with `bindTelemetryIntegration()`.
+  - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
+  - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
+  - **`runName`**: optional local run name.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"` (reserved for explicit bounded capture).
+  - **`redactionProfile`** and **`maxPreviewChars`**: reserved for bounded/redacted future preview behavior.
+  - **`getDiagnostics()`**: exposes isolated adapter write failures without throwing into AI SDK callbacks.
+
+Every AI SDK call using the adapter must keep telemetry local and metadata-only:
+
+```ts
+experimental_telemetry: {
+  isEnabled: true,
+  recordInputs: false,
+  recordOutputs: false,
+  integrations: [agentInspect({ traceDir: "./.agent-inspect" })],
+}
+```
+
+The adapter records local v0.2 persisted events for run, LLM step, and tool lifecycle metadata. By default it does not persist raw prompts, messages, generated text, stream chunks, tool inputs, tool outputs, headers, request bodies, response bodies, or user `experimental_context`.
+
+No network writer, OpenTelemetry exporter, provider wrapper, or global monkey-patch is part of this package.
+
+Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/).
+
+## 12. Experimental `@agent-inspect/openai-agents` APIs
+
+`@agent-inspect/openai-agents` is an optional v1.7 scaffold for future OpenAI Agents JS tracing processor integration. Runtime span mapping is not implemented yet.
+
+Import from `@agent-inspect/openai-agents`:
+
+```ts
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+```
+
+- **`agentInspectProcessor(options?)`**: returns a local-only scaffold object with diagnostics.
+  - **`installMode`**: always `"setTraceProcessors"` to document the safe replacement install path.
+  - **`localOnly`**: always `true`; the scaffold performs no network I/O and does not install itself globally.
+  - **`writer`**, **`traceDir`**, **`workflowName`**, **`capture`**, **`redactionProfile`**, and **`maxPreviewChars`** are reserved for the later runtime mapping chunk.
+  - **`getDiagnostics()`**: exposes scaffold diagnostics and reports `runtimeMappingImplemented: false`.
+
+Safe future usage must replace processors explicitly:
+
+```ts
+setTraceProcessors([agentInspectProcessor({ traceDir: "./.agent-inspect" })]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that leaves existing/default processors in place and can preserve backend export behavior in server runtimes.
+
+## 13. Experimental persisted-event foundation (v1.2.0)
 
 These helpers expose the **source-agnostic `PersistedInspectEvent` model** (`schemaVersion: "0.2"`). They are **local-only**, **in-memory**, and **do not change** storage write/read or CLI behavior in v1.2.0.
 
@@ -172,11 +233,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)
+## 14. 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 +245,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
+## 15. 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.
+
+## 16. 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.
+
+## 17. 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.
+
+## 18. 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.
+
+## 19. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 14. Removal / deprecation policy
+## 20. 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
+## 21. 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
+## 22. Examples
 
 ### Minimal manual trace
 
@@ -214,4 +389,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`
-