agent-inspect 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,12 +1,32 @@
 # Changelog
 
-## 1.1.0
+## 1.2.0
 
 ### Minor Changes
 
-- 21ecc6f: v1.1.0: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
+- 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.
+
+## 1.2.0 — Unreleased
+
+### Added
+
+- Added experimental `PersistedInspectEvent` model (`schemaVersion: "0.2"`) as a source-agnostic event foundation.
+- Added validator for persisted events (`isPersistedInspectEvent`).
+- Added converters from legacy `schemaVersion: "0.1"` manual trace events to persisted events.
+- Added converters between `InspectEvent` and `PersistedInspectEvent`.
+- Added in-memory helpers to build run trees from persisted events (`persistedInspectEventsToRunTrees`, `traceEventsToPersistedRunTrees`).
+- Added canonical v0.2 fixture samples under `fixtures/traces-v0.2/`.
+
+### Notes
+
+- Existing manual trace writing remains `schemaVersion: "0.1"`.
+- v0.2 is not written by default in this release.
+- CLI read/write behavior is unchanged.
+- No vendor upload, hosted dashboard, OTLP HTTP sink, replay engine, or cost engine was added.
+
+## 1.1.0
 
-## 1.1.0 — Unreleased
+Changeset `21ecc6f`: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
 
 ### Added
 
@@ -34,7 +54,7 @@
 ### Documentation
 
 - Added/updated logging playbook for structured JSON logs ([docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md)).
-- Updated public roadmap to separate completed v1.1-prep work from Now/Next/Future.
+- Updated public roadmap after the 1.1.0 release (Released recently / Now / Next / Future).
 - Updated contributor/community docs for package boundaries and optional packages.
 - Added clearer community onboarding and issue-draft guidance.
 

package/README.md

@@ -4,7 +4,7 @@
 
 agent-inspect helps you understand what happened inside an AI agent run — **locally**. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into **readable execution trees** you can inspect from the terminal.
 
-It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it **before** a hosted observability platform, **alongside** one, or as the **local debugging layer** underneath enterprise observability.
+It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it for **local TypeScript agent debugging**, **eval iteration**, and **CI trace artifacts**. It **complements** production observability platforms; it does **not** replace them.
 
 The tool starts with **manual traces** and **existing structured logs**, and extends into **optional framework callbacks** and **standards-aligned local export** — without turning the core into a SaaS or a vendor pipeline.
 
@@ -20,6 +20,8 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
+Current npm release: **1.1.0**.
+
 ```bash
 npm install agent-inspect
 ```
@@ -34,6 +36,8 @@ Verify the CLI is available:
 npx agent-inspect --help
 ```
 
+For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md).
+
 ## 60-second quickstart
 
 Create `demo.mjs`:
@@ -153,14 +157,14 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 - Debug a **failed tool call** or thrown error in a support or ops agent.
 - See **which step dominated latency** in a multi-step planner or RAG pipeline.
-- **Diff two runs** after a prompt, model, or routing change.
+- **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.
 - Keep traces **on disk** while still using enterprise observability elsewhere.
 
-## What v1.0 stabilizes
+## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.0** stabilizes the **local debugging foundation**:
+**agent-inspect 1.x** (current: **1.1.0**) stabilizes the **local debugging foundation**:
 
 - Instrument a run with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
@@ -173,7 +177,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 **Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
-**Also included in 1.0** as local-first extensions:
+**Also included in 1.x** as local-first extensions:
 
 - Structured log inspection: **`logs`**
 - Live log tailing: **`tail`**
@@ -189,7 +193,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 ### 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 is available in 1.0, but 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**. 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
@@ -257,7 +261,7 @@ The TUI is available as a separate optional package; its programmatic API is exp
 - **Manual metadata** is user-controlled. By default, common sensitive keys are **redacted before disk**; pass `redact: false` to opt out. Long metadata is truncated and events are capped at 64 KiB per JSONL line. Review traces and exports before sharing.
 - **Review exports** before sharing (especially with richer attribute flags).
 
-See [SECURITY.md](SECURITY.md).
+See [SECURITY.md](SECURITY.md) and the [safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md).
 
 ## agent-inspect comparison
 
@@ -268,6 +272,7 @@ 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)
@@ -280,11 +285,23 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.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)
 
+## Contributing
+
+AgentInspect welcomes docs, fixtures, examples, and carefully scoped CLI improvements.
+
+- **Good first issues:** [GOOD-FIRST-ISSUES.md](GOOD-FIRST-ISSUES.md) — live batches [#7–#14](https://github.com/rajudandigam/agent-inspect/issues?q=is%3Aissue+is%3Aopen) and [#18–#30](https://github.com/rajudandigam/agent-inspect/issues/18) (comment on an issue before opening a PR)
+- **Discussions:** [github.com/rajudandigam/agent-inspect/discussions](https://github.com/rajudandigam/agent-inspect/discussions) — feedback, stack survey, integration ideas
+- **Roadmap:** [ROADMAP.md](ROADMAP.md) — Now / Next / Future direction (non-committal)
+- **Contributing guide:** [CONTRIBUTING.md](CONTRIBUTING.md) — validation commands, PR expectations, scope boundaries
+
+**Security:** Traces and logs may contain secrets. **Redact before sharing** in issues, Discussions, PRs, or exports. See [SECURITY.md](SECURITY.md) and the [safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md).
+
 ## Development
 
 From a clone of this repo:

package/SECURITY.md

@@ -70,7 +70,7 @@ Important limitations:
 - Always **review exported files** before sharing them externally.
 - Avoid committing trace directories (`.agent-inspect-runs/`) to source control.
 
-For schema-level redaction notes, see `docs/SCHEMA.md` (redaction section) and `docs/API.md`.
+For a practical pre-share workflow, see `docs/SAFE-TRACE-SHARING.md`. For schema-level redaction notes, see `docs/SCHEMA.md` (redaction section) and `docs/API.md`.
 
 ## Dependency and security review process
 

package/docs/API.md

@@ -1,4 +1,4 @@
-# API (AgentInspect 1.0)
+# API (AgentInspect 1.x)
 
 This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
 
@@ -11,9 +11,9 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 
 Notes:
 
-- The core guarantee of v1.0 is **stable local debugging**: manual tracing + CLI inspection.
+- The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
 - Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
-- There are **zero production sinks** in v1.0; sink/uploader APIs are not stable.
+- There are **zero production sinks** in v1.x; sink/uploader APIs are not stable.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -124,7 +124,7 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
   - In-memory **`getEvents()`** / **`clear()`** unchanged when `persist` is false
 - Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
 
-Rationale: v1.0 includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
+Rationale: v1.x includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
 
 ## 10. Experimental `@agent-inspect/tui` APIs
 
@@ -132,23 +132,49 @@ Rationale: v1.0 includes one official adapter and **zero production sinks**, so
 
 - `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
 
-## 11. Deprecated APIs
+## 11. Experimental persisted-event foundation (v1.2.0)
 
-No deprecated APIs are declared in v1.0 Pass 1.
+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.
 
-## 12. Removal / deprecation policy
+Import from `agent-inspect`:
+
+| API | Role |
+| --- | ---- |
+| `isPersistedInspectEvent` | Runtime validator for v0.2 persisted events |
+| `traceEventToPersistedInspectEvent` | Convert one v0.1 `TraceEvent` |
+| `traceEventsToPersistedInspectEvents` | Batch v0.1 → v0.2 |
+| `inspectEventToPersistedInspectEvent` | Convert one in-memory `InspectEvent` |
+| `inspectEventsToPersistedInspectEvents` | Batch `InspectEvent` → v0.2 |
+| `persistedInspectEventToInspectEvent` | Convert one v0.2 event to `InspectEvent` |
+| `persistedInspectEventsToInspectEvents` | Batch v0.2 → `InspectEvent` |
+| `persistedInspectEventsToRunTrees` | Build `InspectRunTree[]` from v0.2 events (via `TreeBuilder`) |
+| `traceEventsToPersistedRunTrees` | v0.1 `TraceEvent[]` → persisted model → trees |
+
+Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEventStatus`, `TraceEventToPersistedOptions`, `InspectEventToPersistedOptions`, `PersistedToInspectEventOptions`, `PersistedTreeBridgeOptions`.
+
+**Notes:**
+
+- 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.
+
+## 12. Deprecated APIs
+
+No deprecated APIs are declared as of 1.1.0.
+
+## 13. 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.
 
-## 13. Backward compatibility policy
+## 14. 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.
 
-## 14. Examples
+## 15. Examples
 
 ### Minimal manual trace
 

package/docs/ARCHITECTURE.md

@@ -19,6 +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).
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 

package/docs/CLI.md

@@ -196,6 +196,53 @@ Options:
 - `--focus <all|errors|structure|outputs>`
 - `--check <all|structure|outputs|errors|timing>`
 
+Fixture examples:
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+**Simplified example output** (actual CLI formatting may differ slightly):
+
+```text
+Run diff
+Left:  minimal-success
+Right: minimal-error
+
+Summary:
+  Differences: 4
+  Errors: 0
+  Warnings: 3
+  Info: 1
+
+First divergence:
+  run-status at (run)
+    left: success
+    right: error
+
+Differences:
+  [warning] run-status
+    Run completion status differs
+    left: success
+    right: error
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 70
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added failing-step
+    Step only in right run: failing-step
+    left: (undefined)
+    right: step_fail
+```
+
+More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
+
 ## 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/DIFF.md

@@ -8,4 +8,131 @@ AgentInspect can compare two runs (manual traces) locally and render a diff summ
 Notes:
 - Programmatic diff APIs are documented as **experimental** in `docs/API.md`.
 - `diff` is read-only and does **not** rerun agents; “differences” do not necessarily imply failure (command errors do).
+- `diff` reads local trace files only. It is useful for local debugging, but it is not production APM or hosted observability.
 
+## CLI examples
+
+The examples below use the checked-in fixture traces, so they are safe to copy and run locally:
+
+```bash
+agent-inspect diff minimal-success minimal-error --dir fixtures/traces
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+If you are running from a source checkout before installing the package globally, use the built CLI path instead:
+
+```bash
+node packages/cli/dist/index.cjs diff minimal-success minimal-error --dir fixtures/traces
+```
+
+### Success run vs error run
+
+This compares a successful run with a run that ended in an error. It shows the run status change, a duration difference, and the step-level structure difference (`plan` removed, `failing-step` added).
+
+**Simplified example output** (actual CLI formatting may differ slightly):
+
+```text
+Run diff
+Left:  minimal-success
+Right: minimal-error
+
+Summary:
+  Differences: 4
+  Errors: 0
+  Warnings: 3
+  Info: 1
+
+First divergence:
+  run-status at (run)
+    left: success
+    right: error
+
+Differences:
+  [warning] run-status
+    Run completion status differs
+    left: success
+    right: error
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 70
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added failing-step
+    Step only in right run: failing-step
+    left: (undefined)
+    right: step_fail
+```
+
+### Duration-only timing check
+
+Use `--check timing` when you only want timing differences. `--duration-threshold` can hide tiny deltas.
+
+```bash
+agent-inspect diff minimal-success long-running --dir fixtures/traces --check timing --duration-threshold 1ms
+```
+
+**Simplified example output**:
+
+```text
+Run diff
+Left:  minimal-success
+Right: long-running
+
+Summary:
+  Differences: 1
+  Errors: 0
+  Warnings: 0
+  Info: 1
+
+First divergence:
+  duration at (run)
+    left: 120
+    right: 45
+
+Differences:
+  [info] duration
+    Run duration differs
+    left: 120
+    right: 45
+```
+
+### Step structure / rename-style changes
+
+When a prompt, model, or routing change renames or restructures steps, the current diff output represents that as `step-removed` plus `step-added`. Use `--ignore-duration` if the structure is what matters.
+
+```bash
+agent-inspect diff minimal-success nested-3-levels --dir fixtures/traces --check structure --ignore-duration
+```
+
+**Simplified example output**:
+
+```text
+Run diff
+Left:  minimal-success
+Right: nested-3-levels
+
+Summary:
+  Differences: 2
+  Errors: 0
+  Warnings: 2
+  Info: 0
+
+First divergence:
+  step-removed at plan
+    left: step_root
+    right: (undefined)
+
+Differences:
+  [warning] step-removed plan
+    Step only in left run: plan
+    left: step_root
+    right: (undefined)
+  [warning] step-added outer
+    Step only in right run: outer
+    left: (undefined)
+    right: step_outer
+```

package/docs/GETTING-STARTED.md

@@ -14,6 +14,8 @@ The `agent-inspect` package includes the CLI binary via its `bin` field:
 npx agent-inspect --help
 ```
 
+For a clean install verification path covering npm, pnpm, ESM import, CJS require, and CLI help, see [Clean install smoke test](./INSTALL-SMOKE-TEST.md).
+
 For local repo development (this monorepo), build and run the CLI from `packages/cli`:
 
 ```bash
@@ -33,7 +35,7 @@ await inspectRun("demo-agent", async () => {
 });
 ```
 
-This writes a local JSONL trace with stable v1.0 event names:
+This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`):
 
 - `run_started`, `run_completed`
 - `step_started`, `step_completed`
@@ -58,6 +60,10 @@ AGENT_INSPECT=1 node eval-runner.mjs
 
 Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
 
+### Install compatibility
+
+If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common install/runtime compatibility checks](./KNOWN-ISSUES.md#common-installruntime-compatibility-checks).
+
 To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
 
 ## 3. View runs
@@ -151,4 +157,3 @@ agent-inspect view <runId> --tui
 - [docs/KNOWN-ISSUES.md](./KNOWN-ISSUES.md)
 - [docs/LIMITATIONS.md](./LIMITATIONS.md)
 - [ROADMAP.md](../ROADMAP.md)
-

package/docs/KNOWN-ISSUES.md

@@ -32,3 +32,56 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - Log-derived trees carry **confidence** (`explicit`, `correlated`, `heuristic`, `unknown`). Labels explain **how** relationships were inferred—they are not semantic proof.
 
 When in doubt, treat AgentInspect as a **debugging aid**, not a compliance or billing system of record.
+
+## Common install/runtime compatibility checks
+
+Use these before filing a packaging bug. AgentInspect targets **Node.js ≥ 20**.
+
+### Quick self-check (clean temp project)
+
+```bash
+mkdir /tmp/agent-inspect-check && cd /tmp/agent-inspect-check
+npm init -y
+npm install agent-inspect@latest
+node -e "import('agent-inspect').then(m => console.log('esm', typeof m.inspectRun))"
+node -e "const m=require('agent-inspect'); console.log('cjs', typeof m.inspectRun, typeof m.maybeInspectRun)"
+npx agent-inspect --help
+```
+
+From a **repo clone** (maintainers / contributors):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm compat:smoke
+```
+
+### ESM import
+
+- Consumer `package.json` should use `"type": "module"` (or `.mjs` entry files).
+- Import: `import { inspectRun, step, maybeInspectRun } from "agent-inspect"`.
+- TypeScript: `module` / `moduleResolution` `NodeNext` or `Node16` with matching `type` field.
+
+### CJS require
+
+- Consumer `package.json` should use `"type": "commonjs"` (or `.cjs` entry files).
+- Require: `const { inspectRun, step, maybeInspectRun } = require("agent-inspect")`.
+- TypeScript: compile `.cts` with `module` / `moduleResolution` `Node16`.
+
+**Note:** `chalk@5` and `nanoid@5` are ESM-only upstream. Published `agent-inspect` bundles them into CJS output so Jest 29 / `require()` consumers do not resolve ESM-only deps at runtime. If you still see `ERR_REQUIRE_ESM`, report Node version, bundler, and full stack trace.
+
+### Jest / ts-jest (CJS)
+
+- Prefer `require("agent-inspect")` in CJS test files, or ensure your Jest config supports the package's export conditions.
+- For tracing off in unit tests: `maybeInspectRun(name, fn, { enabled: false })` or unset `AGENT_INSPECT`.
+- Fixture pattern: [test/consumer-fixtures/jest-cjs/](../../test/consumer-fixtures/jest-cjs/).
+- Full Jest runner smoke in CI is a documented follow-up — root package does not ship Jest as a devDependency.
+
+### What to include in a bug report
+
+- Node.js version (`node -v`)
+- Package manager and lockfile type (npm / pnpm / yarn)
+- ESM vs CJS vs TypeScript + ts-jest
+- Minimal repro repo or snippet
+- Full error stack (not only the top line)
+- Whether `AGENT_INSPECT` is set in the environment

package/docs/LIMITATIONS.md

@@ -9,6 +9,12 @@ This document states what AgentInspect **does not** provide today. It complement
 - **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
 - **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
 
+## Persisted event model (v1.2.0 foundation)
+
+- **v0.2 is not the default persisted trace file format.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL.
+- **CLI commands** (`list`, `view`, `export`, `diff`, `logs`, `tail`) still primarily operate on current v0.1 trace and log paths.
+- **v0.2 read/write integration** (dual-format storage, CLI consumption) is future work — v1.2.0 ships in-memory converters and canonical fixtures only.
+
 ## Data fidelity
 
 - **No full prompt/output capture by default** for manual traces (by design: safety and PII risk).

package/docs/SCHEMA.md

@@ -198,8 +198,46 @@ Always review any exported content (Markdown/HTML/OpenInference/OTLP JSON) befor
 
 See: `SECURITY.md` and `docs/API.md` (`InspectRunOptions.redact`, size bound options).
 
-## 14. Migration notes
+## 14. Persisted InspectEvent schemaVersion "0.2" — experimental foundation
+
+v1.2.0 introduces a **source-agnostic persisted event model** as an experimental foundation. It is **not** the default on-disk format.
+
+| Topic | Rule |
+| ----- | ---- |
+| 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. |
+| Failures | Still **no** `step_failed`; use `status: "error"` on the persisted event. |
+
+Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:check`).
+
+### 14.1 Field reference (compact)
+
+| Field | Required | Notes |
+| ----- | -------- | ----- |
+| `schemaVersion` | yes | `"0.2"` |
+| `eventId` | yes | Stable per-event identifier |
+| `runId` | yes | Run grouping key |
+| `parentId` | no | Explicit nesting only when present |
+| `kind` | yes | `InspectKind` (`RUN`, `LLM`, `TOOL`, `LOGIC`, …) |
+| `name` | yes | Human-readable step label |
+| `status` | no | `running` \| `ok` \| `error` \| `unknown` |
+| `timestamp` | yes | ISO-8601 string (event time) |
+| `startedAt` / `endedAt` | no | ISO-8601 bounds when known |
+| `durationMs` | no | Non-negative milliseconds when known |
+| `confidence` | yes | `explicit` \| `correlated` \| `heuristic` \| `unknown` |
+| `source` | yes | `{ type, name?, version? }` — `manual`, `json-log`, `log4js`, `adapter`, `ai-sdk`, `otel` |
+| `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 |
+| `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
+
+Programmatic helpers: see [API.md](./API.md) §15 (experimental persisted-event foundation).
+
+## 15. Migration notes
 
 - Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
-- Migration guides (v0.1 → v1.0) are out of scope for this pass, but this document is the canonical schema reference for that future guide.
+- Migration guides (v0.1 → v0.2 file format) are future work; storage/CLI dual-read is not in the v1.2.0 foundation release.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -97,6 +97,7 @@
     "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
     "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs",
+    "compat:smoke": "node scripts/compat-smoke.mjs",
     "fixtures:check": "node scripts/validate-fixtures.mjs",
     "recipes:check": "node scripts/validate-recipes.mjs",
     "perf:baseline": "node scripts/performance-baseline.mjs",