agent-inspect 1.9.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.0.0
+
+### Major Changes
+
+- 90fa75e: Release v2.0.0 with the stable root API contract, schema 1.0 persisted InspectEvent writer path, v0.1/v0.2/v1.0 reader compatibility, and explicit trace migration workflow.
+
 ## 1.9.0
 
 ### Minor Changes

package/README.md

@@ -22,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.8.0** (`agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, `@agent-inspect/openai-agents` — all aligned).
+Current npm release line: **1.9.x** for the existing public packages. The v2 contract work on `main` is unreleased until the release-readiness gate completes. `@agent-inspect/openai-agents` v1.9 publication recovery is a separate maintainer npm setup item and is not retried by the v2 train.
 
 ```bash
 npm install agent-inspect
@@ -194,6 +194,7 @@ Use the root import for stable beginner APIs:
 
 ```ts
 import {
+  createInspector,
   observe,
   inspectRun,
   maybeInspectRun,
@@ -212,7 +213,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";
 ```
 
 **Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
@@ -227,20 +228,22 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-## What you can do today (v1.8.0)
+## What you can do today
 
 - **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.
+- **Use an isolated inspector** with `createInspector()` and explicit local writers for tests/adapters.
 - **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`, `open`, `diff`, `timeline`, `stats`, `search`, `what`, `report`.
+- **Inspect from the CLI** — `list`, `view`, `clean`, `logs`, `tail`, `export`, `open`, `migrate`, `diff`, `timeline`, `stats`, `search`, `what`, `report`.
+- **Migrate explicitly** with `agent-inspect migrate <trace.jsonl> --to 1.0 --dry-run` or `--output <file>`; originals are never overwritten by default.
 - **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 AI SDK adapter** — experimental `@agent-inspect/ai-sdk` telemetry integration for AI SDK v6; metadata-only by default with `recordInputs: false` and `recordOutputs: false`.
 - **Optional OpenAI Agents adapter** — experimental `@agent-inspect/openai-agents` trace processor for local OpenAI Agents JS trace processing.
 - **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"`.
+- **Persisted-event foundation** — v0.1/v0.2/v1.0 AgentInspect JSONL remains readable; `createInspector()` and built-in writers use the schema 1.0 persisted path.
 - **Experimental subpaths** — `agent-inspect/readers`, `/writers`, `/checks`, `/diff`, `/exporters`, `/logs`, `/persisted`, and `/advanced` for advanced local workflows.
 
 Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
@@ -292,6 +295,7 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `tail` | Watch structured logs while the app runs |
 | `export` | Write Markdown / HTML / OpenInference-compatible JSON / OTLP JSON **locally** |
 | `open` | Read AgentInspect JSONL, OpenInference JSON, or OTLP JSON locally |
+| `migrate` | Convert a local AgentInspect JSONL file to schema 1.0 with dry-run or explicit output |
 | `diff` | Compare two local runs (read-only) |
 | `timeline` | Chronological view of one run |
 | `stats` | Local aggregates over a trace directory |
@@ -316,15 +320,15 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 - **Export** a run to Markdown for a PR, postmortem, or internal thread — use `--redaction-profile share` for share-safe copies, then review before sharing.
 - Keep traces **on disk** while still using enterprise observability elsewhere.
 
-## Stable foundation (AgentInspect 1.x)
+## Stable foundation
 
-**agent-inspect 1.x** (current: **1.8.0**) is the **local-first trace workbench** for TypeScript AI agents:
+AgentInspect 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)
+- Write and read **local JSONL traces** (`schemaVersion: "0.1"` manual traces remain readable; schema 1.0 persisted rows are the v2 writer target)
 - Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**, **`timeline`**, **`stats`**, **`search`**
 
-**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`, `getCurrentCorrelationMetadata()`.
+**Stable root APIs:** `createInspector()`, `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`, `getCurrentCorrelationMetadata()`.
 
 Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` to toggle tracing in eval or CI — see [docs/API.md](docs/API.md).
 

package/docs/ADAPTER-CONFORMANCE.md

@@ -22,7 +22,7 @@ Executable shared assertions live in `packages/core/test/adapter-executable-conf
 | --- | --- | --- | --- | --- |
 | AI SDK | `@agent-inspect/ai-sdk` | implemented experimental; v1.8 correctness hardening pending | 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` | implemented experimental; private until first publication gate | `setTraceProcessors()` replacement | optional package peer dependency |
+| OpenAI Agents JS | `@agent-inspect/openai-agents` | implemented experimental; public package, with v1.9 publication recovery tracked separately | `setTraceProcessors()` replacement | optional package peer dependency |
 | LangGraph | `@agent-inspect/langchain` | fixture-backed through LangChain callback | explicit LangChain callback | existing LangChain adapter first |
 
 ## Required defaults

package/docs/API.md

@@ -1,4 +1,4 @@
-# API (AgentInspect 1.x)
+# API
 
 This document describes the **public TypeScript API surface** of AgentInspect and classifies each area as **stable** or **experimental**.
 
@@ -6,13 +6,14 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 
 ## 1. Stability policy
 
-- **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.
+- **Stable**: intended to stay compatible within the current major version.
+- **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration.
 
 Use the root import for stable beginner APIs. Use subpaths for advanced, experimental, or lower-level workflows.
 
 ```ts
 import {
+  createInspector,
   observe,
   inspectRun,
   maybeInspectRun,
@@ -21,7 +22,7 @@ import {
 } from "agent-inspect";
 ```
 
-**v1.9 root API direction:** do not add new root exports casually. Existing root imports keep working through v1.x for compatibility, but new advanced examples should use the subpath where the API lives. The intended stable root set for v2 is:
+**v2 root API contract:** do not add new root exports casually. Advanced, experimental, and lower-level helpers belong on the subpath where the API lives. The stable root value set is:
 
 ```ts
 import {
@@ -34,7 +35,7 @@ import {
 } from "agent-inspect";
 ```
 
-**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`, `/checks`) 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).
+**Subpath exports:** Subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`, `/checks`) narrow the import surface for experimental and advanced APIs. Design history: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
 
 ```ts
 import { parseLogsToTrees } from "agent-inspect/logs";
@@ -44,15 +45,15 @@ import { openTrace } from "agent-inspect/readers";
 import { runTraceChecks } from "agent-inspect/checks";
 import { diffTraceEvents } from "agent-inspect/diff";
 import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
-import { createInspector } from "agent-inspect/advanced";
+import { createInspectorRuntime } from "agent-inspect/advanced";
 ```
 
 Notes:
 
-- The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
+- The core guarantee 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.x; sink/uploader APIs are not stable.
-- Advanced root exports in v1.x are compatibility aliases. Prefer `agent-inspect/advanced`, `agent-inspect/readers`, `agent-inspect/writers`, `agent-inspect/checks`, `agent-inspect/diff`, `agent-inspect/exporters`, `agent-inspect/logs`, and `agent-inspect/persisted` for new code.
+- There are **zero production sinks**; sink/uploader APIs are not stable.
+- Advanced APIs are available from `agent-inspect/advanced`, `agent-inspect/readers`, `agent-inspect/writers`, `agent-inspect/checks`, `agent-inspect/diff`, `agent-inspect/exporters`, `agent-inspect/logs`, and `agent-inspect/persisted`.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -78,14 +79,14 @@ import {
   - **`maxEventBytes`**: max UTF-8 bytes per serialized JSONL event (default `65536`). Oversized events are truncated; instrumentation never throws into user code.
   - **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` strings. When set, they are written on `run_started.metadata` (not on every step). Top-level correlation options override the same keys in `options.metadata`. Useful for eval cases, CI job IDs, request tracing, and `stats --correlation-id` / `--group-id`. They are **metadata only** — they do not replace `runId`. Treat sensitive IDs as trace data before sharing exports.
 - **`maybeInspectRun(name, fn, options?)`**: same as `inspectRun` when tracing is enabled; otherwise passthrough. Enablement: explicit **`options.enabled`** wins; when omitted, reads **`AGENT_INSPECT`** (`1`, `true`, `yes`, `on`, `enabled` — case-insensitive). Unset or other values disable tracing. Use in eval harnesses, CI, or jobs where tracing should be toggled by environment.
-- **`isAgentInspectEnabled(value?)`**: returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
+- **`isAgentInspectEnabled(value?)`**: advanced helper available from `agent-inspect/advanced`; returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
 - **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`). Step `metadata` inherits the parent run's redaction and size-bound settings.
   - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
   - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
 - **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
 - **`getCurrentCorrelationMetadata()`**: returns active run correlation fields (`correlationId`, `requestId`, `decisionId`, `groupId`) inside `inspectRun` / `maybeInspectRun`; `undefined` outside a traced run or when none were set.
 - **`RedactionProfile`**: `"local" | "share" | "strict"` — see `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
-- **`resolveRedactionProfile(profile?)`**: resolves profile extra keys and metadata caps (for advanced integrations).
+- **`resolveRedactionProfile(profile?)`**: advanced helper available from `agent-inspect/advanced`; resolves profile extra keys and metadata caps for integrations.
 
 ## 3. Stable local inspection APIs
 
@@ -328,29 +329,29 @@ The processor records local v0.2 persisted events for trace/run, agent, generati
 
 ## 15. 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.
+These helpers expose the **source-agnostic `PersistedInspectEvent` model**. They are **local-only** and support v0.2 compatibility plus the stable schema 1.0 persisted contract.
 
 Import from `agent-inspect/persisted`:
 
 | API | Role |
 | --- | ---- |
-| `isPersistedInspectEvent` | Runtime validator for v0.2 persisted events |
+| `isPersistedInspectEvent` | Runtime validator for supported 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`) |
+| `inspectEventsToPersistedInspectEvents` | Batch `InspectEvent` → persisted events |
+| `persistedInspectEventToInspectEvent` | Convert one persisted event to `InspectEvent` |
+| `persistedInspectEventsToInspectEvents` | Batch persisted events → `InspectEvent` |
+| `persistedInspectEventsToRunTrees` | Build `InspectRunTree[]` from persisted 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.
-- 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.
+- Manual global trace **writing** remains `schemaVersion: "0.1"`.
+- `createInspector()` and built-in persisted writer paths target schema 1.0 rows.
+- Inspection read paths normalize v0.1, v0.2, and v1.0 JSONL for local CLI/API use. v0.2 remains a compatibility foundation.
 
 ## 16. Local observability helpers (v1.4.0+)
 
@@ -373,7 +374,7 @@ Report redaction profiles are key-based safeguards applied to the complete rende
 
 ## 18. 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.
+Trace writers are the local persistence contract for tests, adapters, and `createInspector()` workflows.
 
 Import from `agent-inspect/writers`:
 
@@ -395,7 +396,7 @@ import type {
 ```
 
 - **`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.
+- **`fileWriter({ dir?, filePath? })`**: appends `PersistedInspectEvent` JSONL rows to local disk. `createInspector()` emits schema 1.0 rows by default; compatibility adapters may still pass readable v0.2 rows. 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.
@@ -405,12 +406,12 @@ No network writer or vendor sink exists in this package.
 
 ## 19. 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.
+`createInspector()` is the public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records schema 1.0 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
 
-Import from `agent-inspect/advanced`:
+Import from `agent-inspect`:
 
 ```ts
-import { createInspector } from "agent-inspect/advanced";
+import { createInspector } from "agent-inspect";
 import { memoryWriter } from "agent-inspect/writers";
 
 const writer = memoryWriter();
@@ -441,9 +442,9 @@ Public methods:
 
 `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`.
+`createInspectorRuntime()` is available from `agent-inspect/advanced` as the low-level isolation primitive. Most users should prefer `createInspector()` and `inspector.getDiagnostics()`.
 
-These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
+The low-level runtime helpers remain on `agent-inspect/advanced`. These APIs do not add a default network writer or vendor sink.
 
 ## 20. Experimental trace readers (v1.6)
 
@@ -503,7 +504,7 @@ Recipes: [deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/R
 Import from `agent-inspect`:
 
 ```ts
-import { buildLocalExplanation } from "agent-inspect";
+import { buildLocalExplanation } from "agent-inspect/advanced";
 ```
 
 - **`buildLocalExplanation(run, options?)`**:
@@ -553,7 +554,7 @@ No deprecated APIs are declared as of 1.4.0.
 
 ## 25. Removal / deprecation policy
 
-- Stable APIs are not removed in v1.x.
+- Stable APIs are not removed within the current major version.
 - 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.
 
 ## 26. Backward compatibility policy

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.x)
+# CLI
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -26,6 +26,7 @@ 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
 - `scan` — best-effort local safety scan for trace capture risks
 - `verify-safe` — best-effort local trace safety verification
@@ -243,7 +244,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 +322,7 @@ 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 `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 +361,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.11 `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 +401,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.12 `diff`
 
 Compare two manual trace runs. Diff is **local** and **read-only** (does not rerun agents).
 
@@ -435,7 +465,7 @@ Differences:
 
 More examples, including timing-only and structure-only diffs, are in `docs/DIFF.md`.
 
-### 6.12 `timeline`
+### 6.13 `timeline`
 
 Chronological step list for one manual trace. Read-only; does not mutate JSONL files.
 
@@ -451,7 +481,7 @@ Options:
 
 ![Timeline with slow-step focus](../assets/demos/timeline.gif)
 
-### 6.13 `stats`
+### 6.14 `stats`
 
 Local aggregate statistics over trace files in a directory. Read-only.
 
@@ -471,7 +501,7 @@ Options:
 
 Use `--correlation-id` or `--group-id` to filter runs by `run_started` metadata (see [API.md](./API.md)).
 
-### 6.14 `search`
+### 6.15 `search`
 
 Deterministic search over local traces (substring / exact filters). No semantic search.
 
@@ -501,7 +531,7 @@ npx agent-inspect search --duration ">100ms" --json
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.15 `what`
+### 6.16 `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 +560,7 @@ Outcome: Completed successfully.
 Slowest: plan (100ms, logic)
 ```
 
-### 6.16 `report`
+### 6.17 `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 +585,7 @@ Example:
 npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
 ```
 
-### 6.17 `explain`
+### 6.18 `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/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

package/docs/KNOWN-ISSUES.md

@@ -23,7 +23,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,9 +93,14 @@ 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.
 

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.
 
@@ -58,7 +58,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **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.
 - **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
 

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.