agent-inspect 1.9.0 → 2.1.0

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.x)
+# CLI
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -26,7 +26,10 @@ Core commands:
 - `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
+- `migrate` — convert one local AgentInspect JSONL file to schema 1.0 with dry-run or explicit output
 - `check` — run deterministic local trace checks with stable JSON and exit codes
+- `eval` — run deterministic local evals over existing traces
+- `redact` — redact a local JSON/JSONL file or trace copy
 - `scan` — best-effort local safety scan for trace capture risks
 - `verify-safe` — best-effort local trace safety verification
 - `artifacts` — create safe local CI trace artifact bundles and optional step summaries
@@ -57,6 +60,12 @@ Exception: `check` uses CI-oriented semantic exit codes:
 - **3**: trace input could not be read
 - **4**: unsupported or ambiguous trace format
 
+Exception: `eval` uses local eval semantic exit codes:
+
+- **0**: all selected eval rules passed
+- **1**: eval ran and at least one error-severity rule failed
+- **2**: invalid arguments, invalid config, unreadable input, unsupported input, ambiguous input, or run-selection errors
+
 Exception: `scan` and `verify-safe` use local safety status exit codes:
 
 - **0**: status is SAFE or SAFE WITH WARNINGS
@@ -78,6 +87,8 @@ Many commands support `--json` for scripting. JSON output is intended to be:
 - Log-derived output includes **confidence** labels and avoids inventing parent-child relationships.
 - Redaction defaults are conservative (e.g. `authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`).
 - Exported payloads are **redacted by default** unless explicitly configured otherwise.
+- `eval` is deterministic and local-only. It does not replay agents, call model providers, upload traces, or create hosted datasets.
+- `redact` writes or prints a redacted copy. It does not mutate source trace files.
 - `scan` and `verify-safe` are best-effort local checks, not compliance, privacy, security, or regulatory certifications.
 - `artifacts` renders structural summaries and check evidence only; it does not include raw prompt/output bodies, request/response bodies, headers, API keys, secrets, or full tool payloads.
 
@@ -243,7 +254,36 @@ cat packages/core/test/fixtures/openinference-basic.json | npx agent-inspect ope
 
 When a directory or payload contains multiple runs, `open` lists the run ids and exits until you pass `--run <run-id>`.
 
-### 6.8 `check`
+### 6.8 `migrate`
+
+Convert one local AgentInspect JSONL trace file to the stable schema 1.0 persisted contract. This command is local and non-destructive by default: it does not upload traces, run agents, mutate the input file, or overwrite originals.
+
+```bash
+agent-inspect migrate <input.jsonl> --to 1.0 --dry-run
+agent-inspect migrate <input.jsonl> --to 1.0 --output <output.jsonl>
+```
+
+Options:
+
+- `--to 1.0`: required target schema version
+- `--dry-run`: print deterministic counts and warnings without writing output
+- `-o, --output <path>`: write migrated schema 1.0 JSONL to a separate file
+- `--force`: accepted only for explicit output validation; input overwrite is still refused
+
+Input support:
+
+- v0.1 manual trace rows are converted to schema 1.0 persisted rows.
+- v0.2 and v1.0 persisted rows are preserved/upgraded through the shared persisted contract.
+- malformed JSON and unsupported schema rows are reported as line warnings.
+
+Examples:
+
+```bash
+npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --dry-run
+npx agent-inspect migrate fixtures/traces/minimal-success.jsonl --to 1.0 --output fixtures/traces/minimal-success.v1.jsonl
+```
+
+### 6.9 `check`
 
 Run deterministic checks against a local trace. This command is local and read-only: it does not rerun agents, call models, upload traces, or mutate input files.
 
@@ -292,7 +332,85 @@ npx agent-inspect check trace.jsonl --max-duration-ms 30000 --required-tool sear
 
 Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
 
-### 6.9 `scan` and `verify-safe`
+### 6.10 `eval`
+
+Run deterministic local evals against an existing trace. This command reads through the same local reader pipeline as `open` and `check`; it does not rerun agents, call models, upload traces, mutate inputs, or create a hosted dataset.
+
+```bash
+agent-inspect eval <trace-path-or-run-id> [options]
+```
+
+Options:
+
+- `--dir <path>`: trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit trace input format
+- `--run <run-id>`: select a run when input contains multiple runs
+- `--config <path>`: eval config (`.json`, `.js`, `.mjs`, or `.cjs`); TypeScript configs are rejected until an explicit loader is approved
+- `--json`: print deterministic JSON eval result
+- `--markdown`: print deterministic Markdown eval summary
+- `--require-success`: require the selected run to complete successfully
+- `--required-tool <name>`: require a tool name (repeatable)
+- `--forbid-tool <name>` / `--forbidden-tool <name>`: forbid a tool name (repeatable)
+- `--max-duration-ms <number>`, `--max-depth <number>`, `--max-retries <number>`, `--max-total-tokens <number>`
+- `--require-retrieval-before-generation`
+- `--required-decision-metadata <key>`: require decision metadata (repeatable)
+- `--context-overlap`, `--min-context-overlap <number>`, `--min-shared-terms <number>`
+- `--quote-overlap`
+- `--citation-presence`
+- `--required-source-id <id>`: require a source id in context or citations (repeatable)
+- `--min-answer-characters <number>`, `--max-answer-characters <number>`, `--min-answer-words <number>`, `--max-answer-words <number>`
+- `--banned-phrase <text>`: ban unsupported-answer phrasing (repeatable)
+
+Example config:
+
+```json
+{
+  "eval": {
+    "requireSuccess": true,
+    "requiredTools": ["searchDocs"],
+    "forbiddenTools": ["deleteAccount"],
+    "citationPresence": true,
+    "contextOverlap": { "minOverlap": 0.2 },
+    "requiredSourceIds": ["policy-30-day"]
+  }
+}
+```
+
+Examples:
+
+```bash
+npx agent-inspect eval fixtures/traces-v0.2/manual-basic.jsonl --require-success --json
+npx agent-inspect eval trace.jsonl --forbid-tool deleteAccount --markdown
+npx agent-inspect eval trace.jsonl --config agent-inspect.eval.json --json
+```
+
+Recipes: [eval-local-checks](../examples/recipes/eval-local-checks/README.md) and [eval-ci-artifacts](../examples/recipes/eval-ci-artifacts/README.md).
+
+### 6.11 `redact`
+
+Redact a local JSON or JSONL trace/file. The command prints or writes a redacted copy and reports bounded findings; it does not mutate the source file or upload content.
+
+```bash
+agent-inspect redact <trace-or-file> [options]
+```
+
+Options:
+
+- `--dir <path>`: trace directory for run-id lookup
+- `--profile <local|share|strict>`: redaction profile (default `share`)
+- `-o, --output <path>`: write redacted content to a file
+- `--json`: print deterministic JSON wrapper with findings
+
+Examples:
+
+```bash
+npx agent-inspect redact trace.jsonl --profile share --json
+npx agent-inspect redact trace.jsonl --profile strict -o trace.share.jsonl
+```
+
+Recipe: [redact-share-safe-file](../examples/recipes/redact-share-safe-file/README.md).
+
+### 6.12 `scan` and `verify-safe`
 
 Run best-effort local safety verification for supported trace inputs. These commands are local and read-only: they do not rerun agents, call models, upload traces, mutate input files, or certify compliance.
 
@@ -331,7 +449,7 @@ npx agent-inspect verify-safe minimal-success --dir fixtures/traces
 npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json
 ```
 
-### 6.10 `artifacts`
+### 6.13 `artifacts`
 
 Create deterministic local CI artifacts for supported trace inputs. This command is local and read-only for trace inputs: it does not rerun agents, call models, upload files, use GitHub APIs, or mutate repository state. It writes only to `--output-dir` and, when requested, a local step-summary file.
 
@@ -371,7 +489,7 @@ npx agent-inspect artifacts candidate.jsonl --baseline baseline.jsonl --output-d
 
 Recipe and sample workflow: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
 
-### 6.11 `diff`
+### 6.14 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -435,7 +553,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.12 `timeline`
+### 6.15 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -451,7 +569,7 @@ Options:
 
 ![Timeline with slow-step focus](../assets/demos/timeline.gif)
 
-### 6.13 `stats`
+### 6.16 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -471,7 +589,7 @@ Options:
 
 Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
 
-### 6.14 `search`
+### 6.17 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -501,7 +619,7 @@ npx agent-inspect search --duration ">100ms" --json
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.15 `what`
+### 6.18 `what`
 
 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).
 
@@ -530,7 +648,7 @@ Outcome: Completed successfully.
 Slowest: plan (100ms, logic)
 ```
 
-### 6.16 `report`
+### 6.19 `report`
 
 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).
 
@@ -555,7 +673,7 @@ Example:
 npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
 ```
 
-### 6.17 `explain`
+### 6.20 `explain`
 
 Explain a local trace using deterministic facts and local inference labels. This command reads through the same local reader pipeline as `open` / `check`; it does not call a model provider, upload traces, replay agents, or mutate input files.
 

package/docs/COMPARE.md

@@ -1,6 +1,6 @@
 ## Compare AgentInspect
 
-AgentInspect is a local-first execution-tree debugger for TypeScript AI agents. It’s designed for inner-loop debugging and quick inspection — not as a replacement for hosted observability, evaluation, or production monitoring platforms.
+AgentInspect is a local-first execution-tree debugger for TypeScript AI agents. It’s designed for inner-loop debugging, deterministic local eval heuristics, redaction, and quick inspection — not as a replacement for hosted observability, dataset evaluation, or production monitoring platforms.
 
 ## AgentInspect vs console.log
 
@@ -16,7 +16,7 @@ LangSmith is a hosted/platform workflow for tracing, evaluation, and observabili
 AgentInspect is local-first CLI debugging:
 
 - Use AgentInspect to debug locally before/alongside LangSmith when iterating on agent logic.
-- AgentInspect does not provide hosted dashboards, dataset/eval workflows, or production tracing pipelines.
+- AgentInspect does not provide hosted dashboards, dataset/eval management workflows, or production tracing pipelines.
 
 ## AgentInspect vs Langfuse
 
@@ -33,7 +33,7 @@ Braintrust is strong for evals, regressions, datasets, and production AI quality
 
 AgentInspect is lighter and local-first:
 
-- Use AgentInspect to understand a single run locally.
+- Use AgentInspect to understand a single run locally and run deterministic trace checks/eval heuristics before sharing artifacts.
 - Use Braintrust when you want repeatable evals, comparisons at scale, and production quality workflows.
 
 ## AgentInspect vs Phoenix / OpenInference
@@ -61,9 +61,10 @@ AgentInspect avoids SDK/collector setup for local debugging:
 | --- | --- |
 | Local agent debugging | Strong fit |
 | No-account CLI tracing | Strong fit |
+| Deterministic local eval heuristics | Good fit |
+| Share-safe local redaction copy | Good fit |
 | Production dashboards | Not the goal |
 | Hosted eval datasets | Not the goal |
 | Prompt management | Not the goal |
 | Standards-aligned local export | Partial (compatibility-oriented) |
 | Full observability platform | Use a dedicated platform |
-

package/docs/EXPORTS.md

@@ -75,7 +75,7 @@ Experimental helpers (local-only):
 - `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson`
 - `validateExport`, `validateExportContent`
 
-See [API.md](./API.md) §7.
+Import these from `agent-inspect/exporters`. See [API.md](./API.md) §7.
 
 ## What not to share
 

package/docs/GETTING-STARTED.md

@@ -70,6 +70,7 @@ Use the root import for stable beginner APIs:
 
 ```ts
 import {
+  createInspector,
   observe,
   inspectRun,
   maybeInspectRun,
@@ -88,7 +89,7 @@ import { diffTraceEvents } from "agent-inspect/diff";
 import { exportMarkdown } from "agent-inspect/exporters";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
-import { createInspector } from "agent-inspect/advanced";
+import { createInspectorRuntime } from "agent-inspect/advanced";
 ```
 
 ### Always trace vs env-gated tracing
@@ -203,17 +204,34 @@ agent-inspect search --dir ./.agent-inspect --status error --limit 10
 
 For CI artifact workflows, see [CI-ARTIFACTS.md](./CI-ARTIFACTS.md) and [github-actions-artifact recipe](../examples/recipes/github-actions-artifact/).
 
-## 10. Diff two runs
+## 10. Run local evals and redact share copies
+
+After a trace exists, run deterministic eval checks without replaying the agent or calling a model provider:
+
+```bash
+agent-inspect eval minimal-success --dir fixtures/traces --require-success --json
+agent-inspect eval trace.jsonl --forbid-tool deleteAccount --citation-presence --json
+```
+
+Before attaching a trace or JSON artifact to a PR, issue, or support thread, create a redacted local copy:
+
+```bash
+agent-inspect redact trace.jsonl --profile share --json
+```
+
+Recipes: [eval-local-checks](../examples/recipes/eval-local-checks/), [redact-share-safe-file](../examples/recipes/redact-share-safe-file/), and [eval-ci-artifacts](../examples/recipes/eval-ci-artifacts/).
+
+## 11. Diff two runs
 
 ```bash
 agent-inspect diff minimal-success minimal-error --dir fixtures/traces
 ```
 
-## 11. Try recipes
+## 12. Try recipes
 
 See `examples/recipes/README.md`.
 
-## 12. Optional framework adapters
+## 13. Optional framework adapters
 
 See [ADAPTERS.md](./ADAPTERS.md) for AI SDK local telemetry, OpenAI Agents local-only processing, and LangChain callbacks.
 
@@ -227,7 +245,7 @@ pnpm add @agent-inspect/langchain
 
 See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](./ADAPTERS.md).
 
-## 13. Optional TUI
+## 14. Optional TUI
 
 `@agent-inspect/tui` is optional and **experimental**. The CLI can invoke it with:
 
@@ -235,16 +253,17 @@ See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 agent-inspect view <runId> --tui
 ```
 
-## 14. Safety notes
+## 15. Safety notes
 
 - Nothing uploads by default; core tracing, readers, checks, and exports are local-first.
+- Eval and redaction commands read local inputs and do not call provider APIs or hosted services.
 - Redaction is on by default for log-derived attributes, **manual trace metadata (before disk)**, and exports. Pass `redact: false` to opt out of manual metadata redaction.
 - Export redaction shapes a local copy and does not mutate the source trace; review exported files before sharing.
 - Persisted events are size-bounded by default (see `docs/API.md`).
 - Confidence labels are required to keep attribution honest.
 - AgentInspect is for local debugging, not production monitoring.
 
-## 15. Next docs
+## 16. Next docs
 
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)

package/docs/KNOWN-ISSUES.md

@@ -12,6 +12,12 @@ 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.
 
+## Eval and redaction
+
+- **`agent-inspect eval` is deterministic local eval, not hosted evaluation.** Built-in rules are structural checks and grounding heuristics over existing traces. They do not call model providers, manage datasets, replay agents, or perform semantic LLM judging.
+- **TypeScript eval configs are not loaded by default.** Use `.json`, `.js`, `.mjs`, or `.cjs` until an explicit loader path is approved.
+- **`agent-inspect redact` creates a local redacted copy.** It does not mutate source traces, encrypt files, or guarantee compliance-grade detection. Review the exact output before sharing.
+
 ## 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.
@@ -23,7 +29,7 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
 - **AI SDK adapter** (`@agent-inspect/ai-sdk`) is experimental and metadata-first. It depends on explicit AI SDK telemetry configuration and requires `recordInputs: false` / `recordOutputs: false` for the documented safe path.
-- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is experimental and remains private/unpublished until the v1.8 first-publication gate. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`.
+- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is experimental and metadata-first. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`. The v1.9 package publication retry is pending maintainer-side npm auto-publish setup and is separate from v2 contract work.
 - **LangGraph support** is currently a documented boundary through `@agent-inspect/langchain`, not a dedicated package.
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
@@ -93,11 +99,17 @@ pnpm compat:smoke
 - 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.
 
-## v1.8 pre-release adoption notes
+## v2 migration notes
+
+- Advanced APIs no longer live on the root import in the v2 contract. Use `agent-inspect/readers`, `/writers`, `/checks`, `/diff`, `/exporters`, `/logs`, `/persisted`, and `/advanced`.
+- The small root value API is `createInspector`, `inspectRun`, `maybeInspectRun`, `step`, `observe`, and `getCurrentCorrelationMetadata`.
+- Use `agent-inspect migrate <trace.jsonl> --to 1.0 --dry-run` before writing migrated output. The command does not rewrite input files.
+
+## v1.8/v1.9 adoption notes
 
-- `@agent-inspect/vitest` and `@agent-inspect/jest` are private/unpublished until the v1.8 release-readiness gate completes. The [test reporter artifact recipe](../examples/recipes/test-reporter-artifacts/README.md) documents the intended config shape without requiring those packages.
 - `agent-inspect artifacts --github-summary` writes a local step-summary file only. It does not call GitHub APIs, open PR comments, upload artifacts, or mutate repository state.
 - Baseline checks compare normalized structural facts from explicit candidate and baseline inputs. They are useful for CI regression evidence, not replay or semantic eval scoring.
+- v2.1 eval/redact adoption recipes are local and deterministic: [eval-local-checks](../examples/recipes/eval-local-checks/), [redact-share-safe-file](../examples/recipes/redact-share-safe-file/), and [eval-ci-artifacts](../examples/recipes/eval-ci-artifacts/).
 
 ### What to include in a bug report
 

package/docs/LIMITATIONS.md

@@ -15,13 +15,13 @@ 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.
-- **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.
+- **Manual global tracing remains v0.1.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL for compatibility.
+- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema 1.0 persisted rows; v0.2 remains a readable compatibility foundation.
+- **Migration is explicit, not automatic.** `agent-inspect migrate <input> --to 1.0 --dry-run` reports what would change, and `--output <file>` writes a separate file. AgentInspect does not rewrite old traces in place.
 
 ## 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.
+- **Subpath APIs:** `agent-inspect/writers`, `agent-inspect/readers`, and advanced helpers are available for local adoption from their owning subpaths. `createInspector()` is part of the small root API.
 - **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.
@@ -31,7 +31,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **AI SDK integration is explicit telemetry wiring.** Use `@agent-inspect/ai-sdk` through AI SDK `experimental_telemetry.integrations`; AgentInspect does not wrap providers, patch fetch, or enable telemetry globally.
 - **AI SDK privacy settings are caller-owned.** Examples set `recordInputs: false` and `recordOutputs: false`; leaving those enabled in user code can cause the AI SDK telemetry layer to include richer data before AgentInspect receives events.
-- **OpenAI Agents JS support is experimental and not published yet.** `@agent-inspect/openai-agents` maps metadata-only runtime spans through the safe `setTraceProcessors()` boundary, remains private until the v1.8 first-publication gate, and does not capture raw payloads by default.
+- **OpenAI Agents JS support is experimental.** `@agent-inspect/openai-agents` maps metadata-only runtime spans through the safe `setTraceProcessors()` boundary and does not capture raw payloads by default. The v1.9 package publication retry is a separate maintainer npm automation task, not part of the v2 contract work.
 - **LangGraph support is a boundary decision, not a separate package.** Initial support is expected through `@agent-inspect/langchain` callbacks unless no-network fixtures prove a separate package is needed.
 - **No root/core adapter dependencies.** AI SDK, OpenAI Agents, LangGraph, OpenTelemetry, and LangChain remain outside the root/core runtime dependency graph.
 
@@ -50,6 +50,7 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Trace safety bounds
 
 - **Redaction profiles** (`local`, `share`, `strict`) are key-based presets — not compliance-grade PII detection. Review exports before sharing even with `--redaction-profile strict`.
+- **`@agent-inspect/redact` and `agent-inspect redact` create redacted copies.** They do not encrypt source traces, mutate originals, certify compliance, or guarantee every sensitive value is detected.
 - **Default metadata redaction** covers common sensitive keys only (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
 - **Metadata truncation** applies to string values and nested structures; very large metadata may be replaced with a truncation marker when `maxEventBytes` is exceeded (default 64 KiB per JSONL line).
 - **Redaction is not encryption.** Local trace files remain readable on disk; treat `.agent-inspect-runs/` like any developer artifact that may contain operational data.
@@ -57,14 +58,15 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Checks, artifacts, and test reporters
 
 - **Checks are deterministic local rules, not compliance certification.** `check`, `scan`, and `verify-safe` surface bounded findings and diagnostics over supported local inputs; they do not prove a trace is safe for every sharing context.
+- **Eval is deterministic local heuristics.** `@agent-inspect/eval` and `agent-inspect eval` do not provide LLM-as-judge scoring, hosted datasets, replay, semantic grading, or production quality analytics.
 - **Safe CI artifacts are structural summaries.** They avoid raw prompt/output/request/response/header/tool payload content by default, but teams should still review generated files before sharing.
-- **Vitest/Jest reporters are optional and unpublished until release readiness in the v1.8 train.** The recipes document config patterns and explicit associations; consumers should install the packages only after publication.
+- **Vitest/Jest reporters are optional package surfaces.** Recipes document config patterns and explicit associations; package publication is controlled by release readiness and maintainer authorization.
 
 ## Execution semantics
 
 - **No replay / fork** of past runs from traces alone.
 - **No time-travel debugging** across arbitrary runtime state.
-- **No multi-run statistical evaluation** built into core.
+- **No multi-run statistical evaluation** built into core. v2.1 eval checks are per selected trace/run unless user code aggregates results.
 
 ## Economics
 

package/docs/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration
 
-AgentInspect 1.x keeps existing global APIs and published imports working. Manual trace writing remains `schemaVersion: "0.1"`, and v0.1/v0.2 traces remain readable.
+AgentInspect keeps stable global APIs and published imports working within each major version. Manual trace writing remains `schemaVersion: "0.1"` where documented, and v0.1/v0.2 traces remain readable.
 
 ## From older 1.x docs
 
@@ -17,6 +17,7 @@ Use the root import for stable beginner APIs:
 
 ```ts
 import {
+  createInspector,
   observe,
   inspectRun,
   maybeInspectRun,
@@ -35,17 +36,16 @@ import { diffTraceEvents } from "agent-inspect/diff";
 import { exportMarkdown } from "agent-inspect/exporters";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
-import { createInspector } from "agent-inspect/advanced";
+import { createInspectorRuntime } from "agent-inspect/advanced";
 ```
 
-## v2 import preparation
+## Root and subpath imports
 
-No import changes are required for v1.x. To prepare for v2, keep beginner workflow APIs at the root and move advanced usage to subpaths now.
+Keep beginner workflow APIs at the root and move advanced usage to subpaths.
 
-| 1.x root compatibility import | Preferred 1.x import for new code | v2 direction |
+| API area | Preferred import | Direction |
 | --- | --- | --- |
-| `inspectRun`, `maybeInspectRun`, `step`, `observe`, `getCurrentCorrelationMetadata` | `agent-inspect` | stays root |
-| `createInspector` | `agent-inspect/advanced` | likely root and `/advanced` |
+| `inspectRun`, `maybeInspectRun`, `step`, `observe`, `getCurrentCorrelationMetadata`, `createInspector` | `agent-inspect` | stays root |
 | `createInspectorRuntime` | `agent-inspect/advanced` | `/advanced` |
 | `openTrace`, `readTrace`, `detectTraceFormat` | `agent-inspect/readers` | `/readers` |
 | `memoryWriter`, `fileWriter`, `bufferedFileWriter`, `compositeWriter`, `nullWriter` | `agent-inspect/writers` | `/writers` |
@@ -61,7 +61,7 @@ Nothing uploads by default. Manual metadata is redacted before disk by default,
 
 ## Compatibility notes
 
-- Existing `inspectRun`, `maybeInspectRun`, `step`, `step.llm`, `step.tool`, `observe`, and `getCurrentCorrelationMetadata` imports remain valid.
+- Existing `inspectRun`, `maybeInspectRun`, `step`, `step.llm`, `step.tool`, `observe`, `getCurrentCorrelationMetadata`, and `createInspector` imports remain valid.
 - Root/core does not require optional adapter dependencies.
 - Optional adapter APIs are experimental and package-scoped.
 - No destructive migration is required for existing trace directories.

package/docs/SCHEMA.md

@@ -1,13 +1,14 @@
-# Schema (AgentInspect 1.x)
+# Schema
 
-This document describes the **persisted manual trace JSONL schema** and the **log-derived normalized model** used by AgentInspect.
+This document describes the **persisted AgentInspect JSONL schemas** and the **log-derived normalized model** used by AgentInspect.
 
 ## 1. Overview
 
 AgentInspect has two related (but distinct) data models:
 
 1. **Manual trace JSONL** (persisted): lines of `TraceEvent` written by `inspectRun()` / `step()`.
-2. **Log-derived normalized model** (in-memory): `InspectEvent` / `InspectRunTree` built from structured logs or adapters.
+2. **Persisted InspectEvent JSONL** (persisted): schema 1.0 rows written by `createInspector()` / built-in writers and produced by explicit migration.
+3. **Log-derived normalized model** (in-memory): `InspectEvent` / `InspectRunTree` built from structured logs or adapters.
 
 Important: log-derived trees are **normalized views**, not the same persisted JSONL schema.
 
@@ -25,7 +26,7 @@ Manual trace events use:
 
 - **`schemaVersion: "0.1"`**
 
-Existing `0.1` traces remain readable across AgentInspect 1.x.
+Existing `0.1` traces remain readable across AgentInspect major versions covered by this migration path.
 
 ### 2.3 TraceEvent union
 
@@ -153,13 +154,13 @@ Manual trace reading:
 
 ## 9. Backward compatibility
 
-- v0.1 JSONL traces remain readable across AgentInspect 1.x.
-- No automatic migrations or rewriting of old files.
+- v0.1, v0.2, and v1.0 AgentInspect JSONL traces remain readable.
+- No automatic migrations or rewriting of old files. Use `agent-inspect migrate <input> --to 1.0 --dry-run` first, then `--output <file>` for explicit conversion.
 
 ## 10. Breaking change policy
 
 - Breaking changes require a major version.
-- Stable v1.x policy: avoid removing stable fields/events; prefer additive extensions.
+- Stable policy: avoid removing stable fields/events within a major version; prefer additive extensions.
 
 ## 11. Log-derived InspectEvent model
 
@@ -241,18 +242,34 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 
 Programmatic helpers: see [API.md](./API.md) §13 (experimental persisted-event foundation).
 
-## 15. v1.6 local reader/writer compatibility
+## 15. Stable persisted InspectEvent schemaVersion "1.0"
 
-v1.6 adds experimental writer and reader surfaces without changing the stable manual trace schema:
+Schema 1.0 is the v2 persisted InspectEvent contract. It evolves the v0.2 shape in place rather than introducing a third unrelated model.
+
+| Topic | Rule |
+| ----- | ---- |
+| `schemaVersion` | `"1.0"` |
+| Default writer target | `createInspector()` and built-in persisted writers emit schema 1.0 rows by default. |
+| Manual helper compatibility | `inspectRun()` / `step()` global/manual tracing continues to write `schemaVersion: "0.1"` for compatibility. |
+| Reader compatibility | AgentInspect readers accept v0.1, v0.2, v1.0, and mixed AgentInspect JSONL where safe, with warnings. |
+| Unknown optional fields | Safe unknown optional fields on v1.0 rows are preserved where possible; unsupported fields are surfaced through warnings/diagnostics rather than fabricated into relationships. |
+| Migration | `agent-inspect migrate <input> --to 1.0 --dry-run` is non-mutating; `--output <file>` writes a separate migrated file and refuses input overwrite. |
+
+Canonical samples: `fixtures/traces-v1.0/*.jsonl` (validated by `pnpm fixtures:check`).
+
+## 16. Local reader/writer compatibility
+
+Local writer and reader surfaces do not change 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()`.
+- `createInspector()` writes schema 1.0 `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.
 - v1.8 checks, safety verification, baseline comparison, safe CI artifacts, and reporter artifacts are report layers over existing trace inputs. They do not change manual trace writing, introduce a third persisted trace model, or embed raw prompt/output/request/response/header/tool payload content in their default structural outputs.
 
-## 16. Migration notes
+## 17. 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.
+- v0.1/v0.2 → v1.0 migration is explicit and local-only through `agent-inspect migrate`; automatic in-place rewrite remains out of scope.
+- The default manual writer remains v0.1; the persisted writer/runtime path targets schema 1.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.9.0",
+  "version": "2.1.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -168,7 +168,7 @@
   },
   "scripts": {
     "clean": "pnpm -r exec -- rm -rf dist",
-    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.vitest.config.ts && pnpm exec tsup --config tsup.jest.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts && pnpm exec tsup --config tsup.harness.config.ts",
+    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.vitest.config.ts && pnpm exec tsup --config tsup.jest.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts && pnpm exec tsup --config tsup.harness.config.ts && pnpm exec tsup --config tsup.redact.config.ts && pnpm exec tsup --config tsup.eval.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",