agent-inspect 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.7.0
+
+### Minor Changes
+
+- 94a7220: Release v1.7.0 framework-native adoption with the experimental AI SDK telemetry adapter, adapter conformance coverage, and local-first adapter documentation.
+
 ## 1.6.0
 
 Released **2026-06-25**.

package/README.md

@@ -210,6 +210,8 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 **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 npm packages at **1.6.0**.
 
+**In progress for 1.7.0 on main:** 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/). Examples keep `recordInputs: false`, `recordOutputs: false`, metadata-only capture, and no upload behavior.
+
 **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:** future work continues from the local runtime and universal ingestion foundation before broadening framework adapters. See [ROADMAP.md](ROADMAP.md).

package/docs/ADAPTER-CONFORMANCE.md

@@ -0,0 +1,35 @@
+# Adapter conformance
+
+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:
+
+- run lifecycle
+- generic steps
+- tools
+- LLM calls
+- errors
+- streaming metadata
+- metadata bounds and privacy controls
+
+## Current matrix
+
+| Adapter | Package | Status | Default install mode | Boundary |
+| --- | --- | --- | --- | --- |
+| AI SDK | `@agent-inspect/ai-sdk` | implemented experimental | 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` | scaffold only | `setTraceProcessors()` replacement | optional package peer dependency |
+| LangGraph | `@agent-inspect/langchain` | decision only | explicit LangChain callback | existing LangChain adapter first |
+
+## Required defaults
+
+- No network behavior.
+- No default upload behavior.
+- No root/core dependency on framework SDKs.
+- Metadata-only capture by default.
+- Raw prompts, messages, outputs, tool payloads, headers, request bodies, and response bodies must not be persisted by default.
+- Framework-specific fixtures must be no-network and dependency-isolated.
+
+## Before claiming support
+
+An adapter can be documented as supported only after no-network fixtures cover run, step, tool, LLM, error, streaming, and metadata-bound expectations for that framework path.

package/docs/ADAPTERS.md

@@ -2,6 +2,54 @@
 
 AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
+## Vercel AI SDK (`@agent-inspect/ai-sdk`)
+
+**Status:** experimental v1.7 train — optional workspace package; publication waits for v1.7 release readiness.
+
+### Install
+
+```bash
+npm install agent-inspect @agent-inspect/ai-sdk ai
+```
+
+### Local telemetry integration
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+const result = await generateText({
+  model,
+  prompt,
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: "./.agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+- **No monkey-patching** — pass the integration explicitly through AI SDK telemetry.
+- **No upload behavior** — the adapter writes only to an explicit local writer or `traceDir`.
+- **Metadata-only by default** — records model, finish reason, token usage, timing, and safe counts/summaries.
+- **Required safe telemetry settings** — set `recordInputs: false` and `recordOutputs: false` on every AI SDK call using this adapter.
+- **No raw payload capture by default** — prompts, messages, generated text, stream chunks, tool inputs/outputs, headers, request bodies, and response bodies are not persisted.
+
+### Local no-network recipe
+
+[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`.
+
+Full API: [API.md](./API.md) §11.
+
+---
+
 ## LangChain.js (`@agent-inspect/langchain`)
 
 **Status:** experimental — programmatic API may evolve independently of stable core tracing.
@@ -114,6 +162,14 @@ Full API: [API.md](./API.md) §9.
 
 [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 
+### LangGraph boundary
+
+LangGraph support is expected to ride through this same `@agent-inspect/langchain` callback boundary first. A dedicated LangGraph package is deferred until no-network 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.
+
+Decision note: [LANGGRAPH-ADAPTER-BOUNDARY.md](./proposals/LANGGRAPH-ADAPTER-BOUNDARY.md).
+
 ---
 
 ## TUI (`@agent-inspect/tui`)
@@ -131,11 +187,32 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ---
 
+## OpenAI Agents JS (`@agent-inspect/openai-agents`)
+
+**Status:** scaffolded for v1.7 train — optional workspace package; runtime mapping is not implemented yet.
+
+The safe integration boundary is documented in [OPENAI-AGENTS-JS-TRACING.md](./proposals/OPENAI-AGENTS-JS-TRACING.md). Future examples must install the AgentInspect processor by replacing processors:
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspectProcessor({
+    traceDir: "./.agent-inspect",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The scaffold does not auto-install a processor, does not upload, and does not add OpenAI Agents dependencies to root/core.
+
+---
+
 ## Future adapters (not shipped)
 
 Direction only — see [ROADMAP.md](../ROADMAP.md):
 
-- **Vercel AI SDK** — optional callback-style adapter (metadata-first, no vendor sink)
 - **NestJS / logging bridges** — deeper recipes or helper patterns beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
 
 No automatic universal instrumentation. Integrations remain explicit and opt-in.
@@ -145,5 +222,6 @@ No automatic universal instrumentation. Integrations remain explicit and opt-in.
 ## Related docs
 
 - [API.md](./API.md) — adapter options and stability policy
+- [ADAPTER-CONFORMANCE.md](./ADAPTER-CONFORMANCE.md) — no-network fixture matrix and shared expectations
 - [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — review exports before sharing
 - [LIMITATIONS.md](./LIMITATIONS.md) — LangChain streaming and metadata boundaries

package/docs/API.md

@@ -150,7 +150,66 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 - `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
 
-## 11. Experimental persisted-event foundation (v1.2.0)
+## 11. Experimental `@agent-inspect/ai-sdk` APIs
+
+`@agent-inspect/ai-sdk` is an optional v1.7 adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental during the v1.7 train and remains private until release readiness.
+
+Import from `@agent-inspect/ai-sdk`:
+
+```ts
+import { agentInspect } from "@agent-inspect/ai-sdk";
+```
+
+- **`agentInspect(options?)`**: returns an AI SDK `TelemetryIntegration` bound with `bindTelemetryIntegration()`.
+  - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
+  - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
+  - **`runName`**: optional local run name.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"` (reserved for explicit bounded capture).
+  - **`redactionProfile`** and **`maxPreviewChars`**: reserved for bounded/redacted future preview behavior.
+  - **`getDiagnostics()`**: exposes isolated adapter write failures without throwing into AI SDK callbacks.
+
+Every AI SDK call using the adapter must keep telemetry local and metadata-only:
+
+```ts
+experimental_telemetry: {
+  isEnabled: true,
+  recordInputs: false,
+  recordOutputs: false,
+  integrations: [agentInspect({ traceDir: "./.agent-inspect" })],
+}
+```
+
+The adapter records local v0.2 persisted events for run, LLM step, and tool lifecycle metadata. By default it does not persist raw prompts, messages, generated text, stream chunks, tool inputs, tool outputs, headers, request bodies, response bodies, or user `experimental_context`.
+
+No network writer, OpenTelemetry exporter, provider wrapper, or global monkey-patch is part of this package.
+
+Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/).
+
+## 12. Experimental `@agent-inspect/openai-agents` APIs
+
+`@agent-inspect/openai-agents` is an optional v1.7 scaffold for future OpenAI Agents JS tracing processor integration. Runtime span mapping is not implemented yet.
+
+Import from `@agent-inspect/openai-agents`:
+
+```ts
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+```
+
+- **`agentInspectProcessor(options?)`**: returns a local-only scaffold object with diagnostics.
+  - **`installMode`**: always `"setTraceProcessors"` to document the safe replacement install path.
+  - **`localOnly`**: always `true`; the scaffold performs no network I/O and does not install itself globally.
+  - **`writer`**, **`traceDir`**, **`workflowName`**, **`capture`**, **`redactionProfile`**, and **`maxPreviewChars`** are reserved for the later runtime mapping chunk.
+  - **`getDiagnostics()`**: exposes scaffold diagnostics and reports `runtimeMappingImplemented: false`.
+
+Safe future usage must replace processors explicitly:
+
+```ts
+setTraceProcessors([agentInspectProcessor({ traceDir: "./.agent-inspect" })]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that leaves existing/default processors in place and can preserve backend export behavior in server runtimes.
+
+## 13. 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.
 
@@ -176,7 +235,7 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 - 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.
 
-## 12. Local observability helpers (v1.4.0+)
+## 14. Local observability helpers (v1.4.0+)
 
 Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1 manual traces remain the default writer; v0.2 persisted-event files are accepted where the shared dual-format read path is used. Local files only.
 
@@ -186,7 +245,7 @@ Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1
 
 CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
 
-## 13. Report and what helpers (v1.5.0+)
+## 15. Report and what helpers (v1.5.0+)
 
 Read-only helpers for concise inspection summaries and local reports:
 
@@ -195,7 +254,7 @@ Read-only helpers for concise inspection summaries and local reports:
 
 Report redaction profiles are key-based safeguards applied to the complete rendered report input, not only to the tree section. Review generated reports before sharing; this is not compliance-grade DLP.
 
-## 14. Experimental trace writers (v1.6)
+## 16. 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.
 
@@ -227,7 +286,7 @@ import type {
 
 No network writer or vendor sink exists in this package.
 
-## 15. Experimental inspector API/runtime (v1.6)
+## 17. 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.
 
@@ -269,7 +328,7 @@ Public methods:
 
 These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
 
-## 16. Experimental trace readers (v1.6)
+## 18. Experimental trace readers (v1.6)
 
 `agent-inspect/readers` exposes the experimental local trace reader contract and detection pipeline. It includes AgentInspect JSONL for v0.1, v0.2, and mixed local trace files, plus local OpenInference JSON and OTLP JSON compatibility readers.
 
@@ -300,23 +359,23 @@ import type { TraceReader } from "agent-inspect/readers";
 
 The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
 
-## 17. Deprecated APIs
+## 19. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 18. Removal / deprecation policy
+## 20. Removal / deprecation policy
 
 - Stable APIs are not removed in v1.x.
 - 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.
 
-## 19. Backward compatibility policy
+## 21. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.
 - Breaking changes require a major version.
 - Unknown fields should be ignored where safe.
 
-## 20. Examples
+## 22. Examples
 
 ### Minimal manual trace
 

package/docs/KNOWN-ISSUES.md

@@ -22,6 +22,9 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 ## Integrations
 
 - **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 scaffold-only in the v1.7 train. Runtime span mapping is not implemented, and the safe future path is `setTraceProcessors()` rather than `addTraceProcessor()`.
+- **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.
 - **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.

package/docs/LIMITATIONS.md

@@ -27,6 +27,14 @@ This document states what AgentInspect **does not** provide today. It complement
 - **Conservative detection:** `agent-inspect open` does not silently accept arbitrary JSON. Unsupported or ambiguous inputs produce errors/warnings rather than guessed traces.
 - **Large inputs:** reader inputs are bounded and read into local memory. This is not a database index or production log warehouse.
 
+## Framework adapters (v1.7)
+
+- **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 scaffold-only.** `@agent-inspect/openai-agents` documents the safe `setTraceProcessors()` boundary but does not map runtime spans yet and is not part of the v1.7 published package set.
+- **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.
+
 ## LangChain streaming (v1.3.0)
 
 - **Metadata-focused only** — `stream: true` records chunk counts, timing, and optional bounded previews; it is **not** a replay/cassette system.

package/docs/SCHEMA.md

@@ -239,7 +239,7 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 | `tokenUsage` | no | `{ input?, output?, total?, cached? }` when supplied/known |
 | `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
 
-Programmatic helpers: see [API.md](./API.md) §11 (experimental persisted-event foundation).
+Programmatic helpers: see [API.md](./API.md) §13 (experimental persisted-event foundation).
 
 ## 15. v1.6 local reader/writer compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -119,6 +119,7 @@
     "docs/EXPORTS.md",
     "docs/DIFF.md",
     "docs/ADAPTERS.md",
+    "docs/ADAPTER-CONFORMANCE.md",
     "docs/COMPARE.md",
     "docs/LOG-TO-TREE-QUICKSTART.md",
     "docs/SCREENSHOTS.md"
@@ -157,7 +158,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",
+    "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.openai-agents.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",

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 = "1.6.0";
+var version = "1.7.0";
 
 // packages/core/src/types.ts
 var STEP_TYPES = [