agent-inspect 1.8.0 → 2.0.0

package/CHANGELOG.md

@@ -1,7 +1,21 @@
 # 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
+
+- 309350e: Release v1.9.0 adoption leverage with the private harness workspace, explain dry-run/local analysis, promoted adapter adoption paths, and the v2 root API slimming plan.
+
 ## 1.8.0
 
+Released **2026-06-27**.
+
 ### Minor Changes
 
 - 0bee42c: Release v1.8.0 with OpenAI Agents trace processor support, optional Vitest/Jest reporter packages kept private, deterministic CI release checks, and the validated local-first reporting improvements from the v1.8 release train.

package/README.md

@@ -1,12 +1,12 @@
 # agent-inspect
 
-**Local execution trees for TypeScript AI agents.**
+**Trace, check, and safely share TypeScript AI agent runs locally.**
 
-agent-inspect helps you understand what happened inside an AI agent run — **locally**. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into **readable execution trees** you can inspect from the terminal.
+agent-inspect helps you understand what happened inside an AI agent run without sending traces to a hosted service. It turns framework events, observed objects/classes, manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into readable local execution trees.
 
 It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it for **local TypeScript agent debugging**, **eval iteration**, and **CI trace artifacts**. It **complements** production observability platforms; it does **not** replace them.
 
-The tool starts with **manual traces** and **existing structured logs**, and extends into **optional framework callbacks** and **standards-aligned local export** — without turning the core into a SaaS or a vendor pipeline.
+The default loop is local-first: capture a trace, inspect/report/diff it, run deterministic checks in CI, then export a redacted copy only when you choose to share.
 
 **No account. No cloud upload. No dashboard required.**
 
@@ -22,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.7.0** (`agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui` — 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
@@ -40,10 +40,110 @@ npx agent-inspect --help
 
 For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md).
 
-## 60-second quickstart
+## Three adoption paths
+
+Already using AI SDK, OpenAI Agents JS, LangChain, or LangGraph-through-LangChain? Start with **Path B** for framework-native local traces before adding manual instrumentation.
+
+### Path A — Observe an existing object/class
+
+Use `observe()` when you already have an agent-like object with a `run`, `execute`, or `invoke` method.
 
 Create `demo.mjs`:
 
+```js
+import { observe } from "agent-inspect";
+
+class SupportAgent {
+  async run(input) {
+    return {
+      answer: `Answering: ${input.question}`,
+    };
+  }
+}
+
+const agent = observe(new SupportAgent(), {
+  traceDir: "./.agent-inspect",
+});
+
+await agent.run({
+  question: "How do refunds work?",
+});
+```
+
+Run it, then inspect the trace:
+
+```bash
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+```
+
+### Path B — Use a framework adapter
+
+Optional adapters keep framework dependencies out of the root package and write local traces only when configured.
+
+AI SDK local telemetry:
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+await generateText({
+  model,
+  prompt,
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: "./.agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+OpenAI Agents local-only processor:
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspectProcessor({
+    traceDir: "./.agent-inspect",
+    workflowName: "support-agent",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+LangChain callback adapter:
+
+```ts
+import { AgentInspectCallback } from "@agent-inspect/langchain";
+
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
+  capture: "metadata-only",
+});
+
+await agent.invoke(input, { callbacks: [callback] });
+```
+
+See [docs/ADAPTERS.md](docs/ADAPTERS.md).
+
+No-network recipes: [ai-sdk-local-telemetry](examples/recipes/ai-sdk-local-telemetry/), [openai-agents-local-tracing](examples/recipes/openai-agents-local-tracing/), and [langgraph-callback-local](examples/recipes/langgraph-callback-local/).
+
+### Path C — Manually instrument custom flows
+
+Use `inspectRun` and `step` when you want explicit names, custom nesting, or flows that are not object/class shaped.
+
 ```js
 import { inspectRun, step } from "agent-inspect";
 
@@ -71,15 +171,6 @@ await inspectRun(
 );
 ```
 
-Run it, then inspect the trace:
-
-```bash
-node demo.mjs
-npx agent-inspect list --dir ./.agent-inspect
-npx agent-inspect view <run-id> --dir ./.agent-inspect
-npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
-```
-
 Full flow:
 
 ```bash
@@ -99,6 +190,32 @@ support-agent
 
 A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
+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";
+```
+
 **Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
 
 ```ts
@@ -111,20 +228,23 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-## What you can do today (v1.7.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"`.
-- **Experimental v1.6.0 APIs** — `agent-inspect/writers`, `agent-inspect/readers`, `createInspector()`, and `agent-inspect open` for local AgentInspect/OpenInference/OTLP ingestion.
+- **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).
 
@@ -136,7 +256,7 @@ Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_star
 
 *Synthetic demo — [examples/02-nested-steps](examples/02-nested-steps/README.md). More visuals: [SCREENSHOTS.md](docs/SCREENSHOTS.md).*
 
-## Works with structured logs you already have
+## Advanced ingestion: use this when your app already emits structured logs
 
 Many production systems already emit **line-delimited JSON** or text logs with embedded JSON (e.g. via **pino**, **winston**, **log4js**, **NestJS** loggers, job runners, or custom event streams). agent-inspect can turn those into **local grouped timelines/trees** without wrapping every function.
 
@@ -175,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 |
@@ -199,18 +320,20 @@ 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.7.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).
 
+**Shipped in 1.8.0:** experimental deterministic checks (`agent-inspect/checks` and `agent-inspect check`), safe-sharing workflows (`scan`, `verify-safe`, safe artifacts), and first public `@agent-inspect/openai-agents` package. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, and `@agent-inspect/openai-agents` at **1.8.0**.
+
 **Shipped in 1.7.0:** experimental `@agent-inspect/ai-sdk` telemetry integration for AI SDK v6 with a local no-network [ai-sdk-local-telemetry recipe](examples/recipes/ai-sdk-local-telemetry/), adapter conformance fixtures, OpenAI Agents/LangGraph support decisions, and local-first adapter docs. Examples keep `recordInputs: false`, `recordOutputs: false`, metadata-only capture, and no upload behavior. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, and `@agent-inspect/tui` at **1.7.0**.
 
 **Shipped in 1.6.0:** experimental writer subpath (`agent-inspect/writers`), isolated `createInspector()` API via `agent-inspect/advanced`, local trace readers via `agent-inspect/readers`, OpenInference/OTLP JSON readers, universal `agent-inspect open`, and deterministic [runtime-and-ingestion recipe](examples/recipes/runtime-and-ingestion/). These remain local-only and do not add upload behavior. Linked release aligns all three then-published npm packages at **1.6.0**.

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/ADAPTERS.md

@@ -4,7 +4,7 @@ AgentInspect is **framework-agnostic** at its core. Optional adapter packages in
 
 ## Vercel AI SDK (`@agent-inspect/ai-sdk`)
 
-**Status:** experimental v1.7 adapter — optional package published in the v1.7.0 linked release.
+**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
 
 The v1.8 train has hardened lifecycle identity and parallel integration isolation. The adapter remains metadata-only: `capture: "preview"` and preview-only redaction options emit diagnostics and fall back to metadata-only capture until bounded free-text previews are implemented.
 
@@ -49,6 +49,34 @@ const result = await generateText({
 
 [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/) uses AI SDK test utilities only (`MockLanguageModelV3`, `simulateReadableStream`) and writes local v0.2 adapter events for `agent-inspect open`.
 
+### Common host shapes
+
+Use the same explicit telemetry block for route handlers, streaming, and tool calls. The adapter does not wrap providers or change host-call settings.
+
+```ts
+const telemetry = {
+  isEnabled: true,
+  recordInputs: false,
+  recordOutputs: false,
+  integrations: [agentInspect({ traceDir: "./.agent-inspect", capture: "metadata-only" })],
+};
+
+// Next.js route or local handler
+await generateText({ model, prompt, experimental_telemetry: telemetry });
+
+// Streaming
+await streamText({ model, prompt, experimental_telemetry: telemetry });
+
+// Tool calls
+await generateText({ model, prompt, tools, experimental_telemetry: telemetry });
+```
+
+Review recipe output with:
+
+```bash
+npx agent-inspect open ./examples/recipes/ai-sdk-local-telemetry/.agent-inspect-runs
+```
+
 Full API: [API.md](./API.md) §11.
 
 ---
@@ -181,6 +209,8 @@ LangGraph support is expected to ride through this same `@agent-inspect/langchai
 
 Future LangGraph examples must keep the same safety defaults: explicit callback installation, metadata-only capture, no raw prompt/output/tool payload capture by default, no hosted sink, and local persistence only when `persist: true` is set.
 
+Runnable local recipe: [langgraph-callback-local](../examples/recipes/langgraph-callback-local).
+
 Decision note: [LANGGRAPH-ADAPTER-BOUNDARY.md](./proposals/LANGGRAPH-ADAPTER-BOUNDARY.md).
 
 ---
@@ -202,13 +232,13 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ## Vitest (`@agent-inspect/vitest`)
 
-**Status:** experimental v1.8 reporter — optional workspace package, private/unpublished until release readiness.
+**Status:** experimental workspace package, private/unpublished.
 
 ```bash
 npm install agent-inspect @agent-inspect/vitest vitest
 ```
 
-After publication, the reporter creates safe, structural artifacts for failed tests that explicitly attach AgentInspect trace metadata. It never guesses trace files by timestamp and does not read trace contents into artifacts.
+The reporter creates safe, structural artifacts for failed tests that explicitly attach AgentInspect trace metadata. It never guesses trace files by timestamp and does not read trace contents into artifacts.
 
 ```ts
 import { createAgentInspectVitestReporter } from "@agent-inspect/vitest";
@@ -251,13 +281,13 @@ Full API: [API.md](./API.md) §12.
 
 ## Jest (`@agent-inspect/jest`)
 
-**Status:** experimental v1.8 reporter — optional workspace package, private/unpublished until release readiness.
+**Status:** experimental workspace package, private/unpublished.
 
 ```bash
 npm install agent-inspect @agent-inspect/jest jest
 ```
 
-After publication, the reporter creates safe, structural artifacts for failed Jest assertions that explicitly attach AgentInspect trace metadata through a map or resolver. It never guesses trace files by timestamp and does not read trace contents into artifacts.
+The reporter creates safe, structural artifacts for failed Jest assertions that explicitly attach AgentInspect trace metadata through a map or resolver. It never guesses trace files by timestamp and does not read trace contents into artifacts.
 
 ```js
 module.exports = {
@@ -294,7 +324,7 @@ Full API: [API.md](./API.md) §13.
 
 ## OpenAI Agents JS (`@agent-inspect/openai-agents`)
 
-**Status:** experimental v1.8 adapter — optional workspace package remains private/unpublished until the manual first-publication gate.
+**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
 
 The safe integration boundary is documented in [OPENAI-AGENTS-JS-TRACING.md](./proposals/OPENAI-AGENTS-JS-TRACING.md). Install the AgentInspect processor by replacing processors:
 
@@ -312,6 +342,11 @@ setTraceProcessors([
 
 Do not use `addTraceProcessor()` as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The processor does not auto-install itself, does not upload, and does not add OpenAI Agents dependencies to root/core.
 
+Integration modes:
+
+- **Local-only replacement:** `setTraceProcessors([agentInspectProcessor(...)])` replaces existing processors for the current process. This is the documented safe default when you want AgentInspect to own local trace output.
+- **Additional processor:** `addTraceProcessor(agentInspectProcessor(...))` is an advanced, user-owned choice. It can preserve existing/default processors and any backend export behavior they already perform.
+
 - **No auto-install** — importing or constructing `agentInspectProcessor()` never calls `setTraceProcessors()` or `addTraceProcessor()`.
 - **No upload behavior** — the processor writes only to an explicit local writer or `traceDir`.
 - **Metadata-only by default** — records trace/span IDs, parentage, names, timing, status, errors, safe model/tool names, token counts, and bounded summaries.