agent-inspect 1.8.0 → 2.0.0

package/docs/GETTING-STARTED.md

@@ -25,7 +25,36 @@ pnpm build
 node packages/cli/dist/index.cjs --help
 ```
 
-## 2. Basic manual trace
+## 2. Observe an existing object/class first
+
+```ts
+import { observe } from "agent-inspect";
+
+class SupportAgent {
+  async run(input: { question: string }) {
+    return {
+      answer: `Answering: ${input.question}`,
+    };
+  }
+}
+
+const agent = observe(new SupportAgent(), {
+  traceDir: "./.agent-inspect",
+});
+
+await agent.run({
+  question: "How do refunds work?",
+});
+```
+
+This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`) when the observed `run` method is called:
+
+- `run_started`, `run_completed`
+- `step_started`, `step_completed`
+
+## 3. Manually instrument custom flows
+
+Use `inspectRun` and `step` when you want explicit step names, custom nesting, or a flow that is not shaped like an object/class method.
 
 ```ts
 import { inspectRun, step } from "agent-inspect";
@@ -37,10 +66,31 @@ await inspectRun("demo-agent", async () => {
 });
 ```
 
-This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`):
+Use the root import for stable beginner APIs:
 
-- `run_started`, `run_completed`
-- `step_started`, `step_completed`
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+Use subpaths for advanced, experimental, or lower-level workflows:
+
+```ts
+import { openTrace } from "agent-inspect/readers";
+import { memoryWriter } from "agent-inspect/writers";
+import { runTraceChecks } from "agent-inspect/checks";
+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 { createInspectorRuntime } from "agent-inspect/advanced";
+```
 
 ### Always trace vs env-gated tracing
 
@@ -90,14 +140,14 @@ If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common in
 
 To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
 
-## 3. View runs
+## 4. View runs
 
 ```bash
 agent-inspect list
 agent-inspect view <runId>
 ```
 
-## 4. Clean old runs (safely)
+## 5. Clean old runs (safely)
 
 Always start with `--dry-run`:
 
@@ -106,7 +156,7 @@ agent-inspect clean --older-than 7d --dry-run
 agent-inspect clean --older-than 7d --yes
 ```
 
-## 5. Parse existing logs
+## 6. Advanced ingestion: parse existing structured logs
 
 ```bash
 agent-inspect logs fixtures/logs/proactive-json.log \
@@ -114,7 +164,7 @@ agent-inspect logs fixtures/logs/proactive-json.log \
   --config fixtures/configs/proactive-agent-inspect.logs.json
 ```
 
-## 6. Tail logs
+## 7. Tail logs
 
 For scripting/CI-style usage, `--once` reads and exits:
 
@@ -126,7 +176,7 @@ agent-inspect tail \
   --once
 ```
 
-## 7. Export a run
+## 8. Export a run
 
 ```bash
 agent-inspect export minimal-success --dir fixtures/traces --format markdown
@@ -142,7 +192,7 @@ agent-inspect export minimal-success --dir fixtures/traces \
 
 Exports are **local-only** and do not upload anywhere. Review output before sharing — see [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
-## 8. Local observability (v1.4.0+)
+## 9. Local observability (v1.4.0+)
 
 After traces exist under a directory:
 
@@ -154,17 +204,21 @@ 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/).
 
-## 9. Diff two runs
+## 10. Diff two runs
 
 ```bash
 agent-inspect diff minimal-success minimal-error --dir fixtures/traces
 ```
 
-## 9. Try recipes
+## 11. Try recipes
 
 See `examples/recipes/README.md`.
 
-## 10. Optional LangChain adapter
+## 12. Optional framework adapters
+
+See [ADAPTERS.md](./ADAPTERS.md) for AI SDK local telemetry, OpenAI Agents local-only processing, and LangChain callbacks.
+
+### LangChain
 
 `@agent-inspect/langchain` is optional and **experimental**. Events are **in-memory by default**; pass `persist: true` to write local JSONL traces inspectable by the CLI.
 
@@ -174,7 +228,7 @@ pnpm add @agent-inspect/langchain
 
 See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](./ADAPTERS.md).
 
-## 11. Optional TUI
+## 13. Optional TUI
 
 `@agent-inspect/tui` is optional and **experimental**. The CLI can invoke it with:
 
@@ -182,14 +236,16 @@ See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 agent-inspect view <runId> --tui
 ```
 
-## 12. Safety notes
+## 14. Safety notes
 
+- Nothing uploads by default; core tracing, readers, checks, and exports are local-first.
 - 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.
 
-## 13. Next docs
+## 15. Next docs
 
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)

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/LOG-TO-TREE-QUICKSTART.md

@@ -1,6 +1,6 @@
 ## Log-to-tree quickstart
 
-AgentInspect can inspect **structured logs** and render a local execution tree without requiring you to wrap every function in manual tracing.
+Advanced ingestion: use this when your app already emits structured logs. AgentInspect can inspect those logs and render a local execution tree without requiring you to wrap every function in manual tracing.
 
 ## Example JSON log lines
 
@@ -53,4 +53,3 @@ See also:
 - `docs/LOGGING-PLAYBOOK.md` (pino / log4js / NestJS examples + fixtures)
 - `docs/SCHEMA.md` (log ingest config types + confidence)
 - `examples/recipes/pino-json-logs/`, `log4js-json-layout/`, `nestjs-json-logging/`
-

package/docs/MIGRATION.md

@@ -0,0 +1,67 @@
+# Migration
+
+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
+
+Prefer the current adoption order:
+
+1. Use `observe()` for an existing object/class.
+2. Use framework adapters when you already run AI SDK, OpenAI Agents, or LangChain.
+3. Use `inspectRun` and `step` when you need explicit custom spans.
+4. Use structured log parsing as advanced ingestion when your app already emits structured logs.
+
+## Imports
+
+Use the root import for stable beginner APIs:
+
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+Use subpaths for advanced, experimental, or lower-level workflows:
+
+```ts
+import { openTrace } from "agent-inspect/readers";
+import { memoryWriter } from "agent-inspect/writers";
+import { runTraceChecks } from "agent-inspect/checks";
+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 { createInspectorRuntime } from "agent-inspect/advanced";
+```
+
+## Root and subpath imports
+
+Keep beginner workflow APIs at the root and move advanced usage to subpaths.
+
+| API area | Preferred import | Direction |
+| --- | --- | --- |
+| `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` |
+| `runTraceChecks` and check types | `agent-inspect/checks` | `/checks` |
+| `diffTraceEvents`, `diffRuns`, `renderRunDiff` | `agent-inspect/diff` | `/diff` |
+| `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson` | `agent-inspect/exporters` | `/exporters` |
+| `parseLogsToTrees`, log parsers, tree builders | `agent-inspect/logs` | `/logs` |
+| persisted conversion helpers | `agent-inspect/persisted` | `/persisted` |
+
+## Safety
+
+Nothing uploads by default. Manual metadata is redacted before disk by default, and export redaction applies to a local copy before you share it. Review traces and exports before posting them in issues, PRs, chats, or public docs.
+
+## Compatibility notes
+
+- 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.8.0",
+  "version": "2.0.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",
+    "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",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",