agent-inspect 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.3.0
+
+### Minor Changes
+
+- 22cad5a: Release v2.3.0 with hardened framework adapter paths.
+
+  This train strengthens the official AI SDK, OpenAI Agents JS, and LangChain/LangGraph integrations with no-network fixtures, clearer local-only defaults, adapter conformance evidence, and adoption-ready recipes. Mastra and NestJS framework packages remain demand-gated; NestJS stays on the structured-log ingestion recipe path for this release.
+
 ## 2.2.0
 
 ### Minor Changes
@@ -10,11 +18,14 @@
 
 ## Unreleased
 
-### Draft v2.2.0 Notes
+### Draft v2.3.0 Notes
 
-- Prepared the v2.2 reporter and CI workflow release notes for local Vitest/Jest reporter artifacts, the shared `agent-inspect/reporters` manifest helpers, and `agent-inspect ci-summary`.
-- Reporter artifacts remain local-only and metadata-bounded. `ci-summary` reads reporter manifest JSON only, validates relative artifact paths, and does not read trace contents, upload artifacts, call GitHub APIs, or mutate repository state.
-- `@agent-inspect/vitest` and `@agent-inspect/jest` remain private/unpublished until maintainer first-publication setup is explicitly cleared before release prep.
+- Hardened the official adapter paths for AI SDK, OpenAI Agents JS, and LangChain/LangGraph with no-network recipes, local-only defaults, clearer lifecycle coverage, and executable adapter conformance evidence.
+- AI SDK coverage now includes route-style telemetry factory guidance, per-request integration isolation, tool/stream/error/parallel fixtures, token metadata, and the required `recordInputs: false` / `recordOutputs: false` host settings.
+- OpenAI Agents JS documentation and fixtures distinguish local-only replacement via `setTraceProcessors()` from advanced additional processor usage.
+- LangGraph support remains through `@agent-inspect/langchain`, with graph/node identity, subgraphs, checkpoint/session IDs, stream modes, handoffs, and parallel branch hints covered through callback metadata.
+- Mastra and NestJS framework packages remain explicitly deferred. NestJS support stays on structured-log ingestion unless future demand proves a narrow local-only helper is worth maintaining.
+- No root/core framework dependency, hosted upload, provider call, schema change, or public breaking change is added in this train.
 
 ## 2.1.0
 

package/README.md

@@ -340,6 +340,10 @@ AgentInspect is the **local-first trace workbench** for TypeScript AI agents:
 
 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).
 
+**v2.3 train status:** adapter hardening is ready for release prep. AI SDK, OpenAI Agents JS, and LangChain/LangGraph paths have no-network recipes and executable conformance coverage. Mastra and NestJS framework packages remain demand-gated; NestJS is covered through structured-log ingestion.
+
+**Shipped in 2.2.0:** public optional Vitest/Jest reporter packages, shared `agent-inspect/reporters` helpers, and `agent-inspect ci-summary` for deterministic local reporter artifact summaries. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, `@agent-inspect/openai-agents`, `@agent-inspect/redact`, `@agent-inspect/eval`, `@agent-inspect/vitest`, and `@agent-inspect/jest` at **2.2.0**.
+
 **Shipped in 2.1.0:** deterministic local eval and redaction utilities. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, `@agent-inspect/openai-agents`, `@agent-inspect/redact`, and `@agent-inspect/eval` at **2.1.0**.
 
 **Shipped in 2.0.0:** stable root API contract, schema 1.0 persisted writer path, v0.1/v0.2/v1.0 read compatibility, and explicit trace migration workflow. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, and `@agent-inspect/openai-agents` at **2.0.0**.
@@ -354,7 +358,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 **Shipped in 1.5.0:** non-breaking subpath exports; `what` and `report` CLI; dual-format read path (v0.1 + v0.2 JSONL); [what-report-inspect recipe](examples/recipes/what-report-inspect/). Linked release aligns all three npm packages at **1.5.0**.
 
-**Roadmap beyond current release work:** v2.2 prepares test reporters and CI workflows, followed by adapter hardening, sessions/MCP telemetry, guardrails, optional viewer/IDE surfaces, and conditional v3 extensibility. See [ROADMAP.md](ROADMAP.md).
+**Roadmap beyond current release work:** v2.4 adds sessions/MCP telemetry, followed by guardrails, optional viewer/IDE surfaces, and conditional v3 extensibility. See [ROADMAP.md](ROADMAP.md).
 
 **Shipped in 1.4.0:** CI artifact recipe ([docs/CI-ARTIFACTS.md](docs/CI-ARTIFACTS.md)); `timeline`, `stats`, and `search` CLI; core helpers `buildRunTimeline`, `buildTraceStats`, `searchTraces`. Linked release aligns all three npm packages at **1.4.0**.
 
@@ -370,6 +374,16 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 ## Optional packages
 
+### Framework adapters (`@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, `@agent-inspect/langchain`)
+
+Official framework adapters are optional packages and stay explicit, local-first, and metadata-only by default:
+
+- **AI SDK:** pass `agentInspect(...)` through AI SDK telemetry with `recordInputs: false` and `recordOutputs: false`.
+- **OpenAI Agents JS:** use `setTraceProcessors([agentInspectProcessor(...)])` for the documented local-only replacement path.
+- **LangChain/LangGraph:** pass `new AgentInspectCallback(...)` through callbacks; LangGraph support rides through the LangChain callback boundary.
+
+No-network recipes: [ai-sdk-local-telemetry](examples/recipes/ai-sdk-local-telemetry/), [ai-sdk-next-route](examples/recipes/ai-sdk-next-route/), [openai-agents-local-tracing](examples/recipes/openai-agents-local-tracing/), and [langgraph-callback-local](examples/recipes/langgraph-callback-local/). Conformance and limits are documented in [docs/ADAPTERS.md](docs/ADAPTERS.md) and [docs/ADAPTER-CONFORMANCE.md](docs/ADAPTER-CONFORMANCE.md).
+
 ### LangChain callback adapter (`@agent-inspect/langchain`)
 
 Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. Optional **`stream: true`** records chunk counts and stream duration **without storing full token text by default**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
@@ -411,7 +425,7 @@ The TUI is available as a separate optional package; its programmatic API is exp
 
 ### Test reporter artifacts (`@agent-inspect/vitest`, `@agent-inspect/jest`)
 
-Optional Vitest/Jest reporter packages are implemented in the workspace for local failure artifacts, but remain private/unpublished until the maintainer clears first-publication setup for a v2.2 release. They write shared `schemaVersion: "0.1"` reporter manifests with safe relative artifact paths and bounded structural metadata. Use `agent-inspect ci-summary` to summarize those local manifests in CI without reading trace contents or calling GitHub APIs.
+Optional Vitest/Jest reporter packages are public as of v2.2. They write shared `schemaVersion: "0.1"` reporter manifests with safe relative artifact paths and bounded structural metadata. Use `agent-inspect ci-summary` to summarize those local manifests in CI without reading trace contents or calling GitHub APIs.
 
 Reporter artifact behavior and API details are documented in [docs/API.md](docs/API.md) and [docs/CI-ARTIFACTS.md](docs/CI-ARTIFACTS.md).
 

package/docs/ADAPTER-CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 AgentInspect optional framework adapters must stay local-first, dependency-isolated, and metadata-only by default.
 
-The machine-readable matrix lives at [docs/implementation/adapter-conformance-matrix.json](./implementation/adapter-conformance-matrix.json). It tracks expected coverage for:
+The machine-readable matrix lives at [docs/implementation/adapter-conformance-matrix.json](./implementation/adapter-conformance-matrix.json). The release-evidence fixture manifest lives at [docs/implementation/adapter-conformance-fixtures.json](./implementation/adapter-conformance-fixtures.json). These files track expected coverage for:
 
 - run lifecycle
 - generic steps
@@ -12,19 +12,39 @@ The machine-readable matrix lives at [docs/implementation/adapter-conformance-ma
 - streaming metadata
 - metadata bounds and privacy controls
 
-The v1.7 matrix is declarative coverage guidance. v1.8 makes conformance executable and requires canonical-reader round trips before adapter output is used by checks.
+The v1.7 matrix began as declarative coverage guidance. v1.8 made the core conformance path executable and requires canonical-reader round trips before adapter output is used by checks. v2.3 uses that foundation to harden official adapters without adding shallow new adapter packages.
 
 Executable shared assertions live in `packages/core/test/adapter-executable-conformance.test.ts` and `packages/core/test/adapter-conformance-utils.ts`. Adapter-specific suites may add deeper fixture coverage, but the shared suite owns the cross-adapter defaults: local-only execution, no raw payload persistence, lifecycle identity, parentage, streaming summaries, token usage where exposed, and reader round trips.
 
+Release evidence gate:
+
+```bash
+pnpm exec vitest run packages/core/test/adapter-executable-conformance.test.ts packages/core/test/adapter-conformance-matrix.test.ts
+```
+
+This is an internal official-adapter gate, not a third-party certification program.
+
 ## Current matrix
 
 | Adapter | Package | Status | Default install mode | Boundary |
 | --- | --- | --- | --- | --- |
-| 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; public package, with v1.9 publication recovery tracked separately | `setTraceProcessors()` replacement | optional package peer dependency |
+| AI SDK | `@agent-inspect/ai-sdk` | implemented experimental; v2.3 priority 1 | AI SDK telemetry integration | optional package peer dependency |
+| OpenAI Agents JS | `@agent-inspect/openai-agents` | implemented experimental; v2.3 priority 2 | `setTraceProcessors()` replacement | optional package peer dependency |
+| LangChain | `@agent-inspect/langchain` | implemented experimental; v2.3 priority 3 | explicit callback | optional package peer dependency |
 | LangGraph | `@agent-inspect/langchain` | fixture-backed through LangChain callback | explicit LangChain callback | existing LangChain adapter first |
 
+## v2.3 scorecard
+
+| Adapter path | Current coverage | Hardening gap | Decision |
+| ------------ | ---------------- | ------------- | -------- |
+| AI SDK | Shared conformance marks run, step, tool, LLM, error, streaming, and metadata bounds covered. | More adoption-grade fixtures for `generateText`, `streamText`, tool calls, Next.js route usage, parallel calls, abort/error lifecycle, and token metadata. | Harden first. |
+| OpenAI Agents JS | Shared conformance covers run, step, tool, LLM, error, metadata bounds, and local-only replacement metadata; adapter fixtures cover agents, generations, tools, handoffs, guardrails, response, MCP tools, custom, transcription, and speech shapes without provider calls. | Streaming remains planned in the matrix; `addTraceProcessor()` remains documented only as an advanced user-owned additional mode. | Hardened second. |
+| LangChain/LangGraph | LangChain and LangGraph-through-LangChain fixtures cover shared signals plus graph/node identity, subgraphs, checkpoint/session IDs, stream modes, handoffs, and parallel branch hints through callback metadata. | Callback-surface limits remain documented; no separate package is justified yet. | Hardened third. |
+| Mastra | No official package, no conformance fixture, no root dependency. | Demand and extension-point evidence are not yet sufficient for local-only useful traces. | Defer. |
+| NestJS | Structured-log recipe exists; no official framework adapter or conformance fixture. | Current evidence supports log ingestion. Demand may justify a narrow harness/bootstrap helper, not a broad monkey-patching adapter. | Defer package; keep recipe/helper gate. |
+
+`@agent-inspect/vitest` and `@agent-inspect/jest` are public reporter packages, not framework trace adapters. Their artifact-manifest behavior is covered by reporter tests and CI-summary tests rather than this adapter conformance matrix.
+
 ## Required defaults
 
 - No network behavior.

package/docs/ADAPTERS.md

@@ -2,11 +2,25 @@
 
 AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
+## v2.3 hardening scorecard
+
+v2.3 hardens existing official adapters before adding new ones. Priority is based on the current package set, open issue/adoption signals, conformance coverage, and how directly a framework can produce useful local traces without root/core dependencies.
+
+| Priority | Adapter path | Decision | v2.3 focus |
+| -------- | ------------ | -------- | ---------- |
+| 1 | AI SDK (`@agent-inspect/ai-sdk`) | Harden first | Improve low-friction `generateText`, `streamText`, tool-call, parallel-call, abort/error, token metadata, and Next.js route coverage while keeping `recordInputs: false` and `recordOutputs: false` as required host controls. |
+| 2 | OpenAI Agents JS (`@agent-inspect/openai-agents`) | Harden second | Make local-only replacement vs additional processor modes unmistakable, with fixtures for agents, generations, tools, handoffs, guardrails, and no default upload confusion. |
+| 3 | LangChain/LangGraph (`@agent-inspect/langchain`) | Harden third | Improve LangGraph-through-LangChain mapping for node identity, subgraphs, checkpoints, stream modes, branches, handoffs, and session/thread IDs without adding a separate package unless the callback surface proves insufficient. |
+| Defer | Mastra | No package in v2.3 | Current evidence does not justify an official package. Revisit only when there is explicit user demand and a verified extension point that avoids hidden monkey-patching, hosted sinks, or root dependencies. |
+| Defer | NestJS | No framework adapter in v2.3 | Keep the supported path at structured-log ingestion via the existing NestJS JSON logging recipe. Revisit a narrow harness/bootstrap helper only with concrete demand; do not add a package only to wrap app bootstrap. |
+
+Reporters (`@agent-inspect/vitest` and `@agent-inspect/jest`) are public packages as of v2.2, but they are CI/test artifact reporters rather than framework trace adapters. They stay outside the v2.3 adapter-hardening priority order.
+
 ## Vercel AI SDK (`@agent-inspect/ai-sdk`)
 
-**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
+**Status:** experimental adapter — optional package published in the aligned v2.2.0 package set and hardened in the v2.3 adapter train.
 
-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.
+The adapter has hardened lifecycle identity and parallel integration isolation. It 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.
 
 ### Install
 
@@ -49,9 +63,11 @@ 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`.
 
+[examples/recipes/ai-sdk-next-route](../examples/recipes/ai-sdk-next-route/) shows a route-style telemetry factory that creates one AgentInspect integration per request while keeping the same no-network, metadata-only defaults.
+
 ### 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.
+Use the same explicit telemetry block shape for route handlers, streaming, and tool calls. Create a fresh `agentInspect(...)` integration per concurrent request/generation. The adapter does not wrap providers or change host-call settings.
 
 ```ts
 const telemetry = {
@@ -83,7 +99,7 @@ Full API: [API.md](./API.md) §11.
 
 ## LangChain.js (`@agent-inspect/langchain`)
 
-**Status:** experimental — programmatic API may evolve independently of stable core tracing.
+**Status:** experimental adapter — optional package published in the aligned v2.2.0 package set; programmatic API may evolve independently of stable core tracing.
 
 ### Install
 
@@ -209,7 +225,7 @@ Full API: [API.md](./API.md) §9.
 
 ### LangGraph boundary
 
-LangGraph support is expected to ride through this same `@agent-inspect/langchain` callback boundary first. v1.8 adds executable no-network fixtures before claiming broader LangGraph support. A dedicated LangGraph package remains deferred until fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.
+LangGraph support rides through this same `@agent-inspect/langchain` callback boundary first. The v2.3 fixtures cover graph/node identity, subgraphs, checkpoint/session IDs, stream modes, handoffs, and parallel branch hints without adding a separate package. A dedicated LangGraph package remains deferred until fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.
 
 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.
 
@@ -236,7 +252,7 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ## Vitest (`@agent-inspect/vitest`)
 
-**Status:** experimental workspace package, private/unpublished.
+**Status:** experimental reporter package — optional package published in the aligned v2.2.0 package set.
 
 ```bash
 npm install agent-inspect @agent-inspect/vitest vitest
@@ -285,7 +301,7 @@ Full API: [API.md](./API.md) §12.
 
 ## Jest (`@agent-inspect/jest`)
 
-**Status:** experimental workspace package, private/unpublished.
+**Status:** experimental reporter package — optional package published in the aligned v2.2.0 package set.
 
 ```bash
 npm install agent-inspect @agent-inspect/jest jest
@@ -328,7 +344,7 @@ Full API: [API.md](./API.md) §13.
 
 ## OpenAI Agents JS (`@agent-inspect/openai-agents`)
 
-**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
+**Status:** experimental adapter — optional package published in the aligned v2.2.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:
 
@@ -348,14 +364,15 @@ Do not use `addTraceProcessor()` as the default AgentInspect path; that preserve
 
 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.
+- **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 and avoid preserving the SDK default exporter.
+- **Additional processor:** `addTraceProcessor(agentInspectProcessor(...))` is an advanced, user-owned choice. It can preserve existing/default processors and any backend export behavior they already perform; use it only when that is intentional.
 
 - **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.
 - **No raw payload capture by default** — prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, and hosted tool payloads are not persisted.
 - **Preview capture is not enabled yet** — `capture: "preview"`, `redactionProfile`, and `maxPreviewChars` are diagnosed through `getDiagnostics()` and do not persist raw previews.
+- **Fixture-backed lifecycle coverage** — local tests and the recipe cover agent, generation, function tool, handoff, guardrail, response, MCP tools, custom, transcription, and speech span shapes without provider calls.
 
 Full API: [API.md](./API.md) §14.
 
@@ -363,11 +380,38 @@ Runnable local recipe: [openai-agents-local-tracing](../examples/recipes/openai-
 
 ---
 
+## Demand-gated framework decisions
+
+### Mastra
+
+**v2.3 decision:** no official package, recipe, or conformance fixture.
+
+The v2.3 evidence review found no open adapter request and no verified extension point in this repository that would produce useful local AgentInspect traces without hidden framework patching or new root/core dependencies. A future Mastra path must first prove:
+
+- explicit user demand, such as an issue, design-partner request, or retained external recipe;
+- a stable, framework-native callback/export hook;
+- metadata-only local trace output with no hosted upload or provider calls by default;
+- no dependency leakage into `agent-inspect` root or `@agent-inspect/core`;
+- no raw prompt, output, tool payload, header, or request/response capture by default.
+
+Until those are true, Mastra stays outside the official adapter set rather than shipping a shallow package.
+
+### NestJS
+
+**v2.3 decision:** no official framework adapter package.
+
+NestJS remains covered through structured-log ingestion, not app bootstrap wrapping. The supported recipe is [examples/recipes/nestjs-json-logging](../examples/recipes/nestjs-json-logging), which maps Nest-shaped JSON lines into local execution trees without importing `@nestjs/*`, starting an HTTP server, or changing application behavior.
+
+A future Nest helper remains demand-gated and must be narrower than a framework adapter. Acceptable evidence would be a repeated need to reduce logging/harness setup friction while preserving explicit opt-in, local-only output, and zero root/core Nest dependency. Broad interceptors, automatic module scanning, monkey-patching, request body capture, or default telemetry upload remain out of scope.
+
+---
+
 ## Future adapters (not shipped)
 
 Direction only — see [ROADMAP.md](../ROADMAP.md):
 
-- **NestJS / logging bridges** — deeper recipes or helper patterns beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+- **NestJS helper patterns** — only if demand proves a narrow harness/bootstrap helper is worth maintaining beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md) and the current NestJS logging recipe.
+- **Mastra** — deferred until demand and extension-point evidence justify a narrow explicit integration.
 
 No automatic universal instrumentation. Integrations remain explicit and opt-in.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",

package/packages/cli/dist/index.cjs

@@ -23,7 +23,7 @@ var process2__default = /*#__PURE__*/_interopDefault(process2);
 var tty__default = /*#__PURE__*/_interopDefault(tty);
 
 // package.json
-var version = "2.2.0";
+var version = "2.3.0";
 
 // packages/core/src/correlation-metadata.ts
 var TRACE_CORRELATION_KEYS = [