agent-inspect 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.4.0
+
+### Minor Changes
+
+- 483168d: Release v2.4.0 with sessions workflow navigation and MCP client telemetry.
+
+  This train adds multi-run session indexing on `agent-inspect/advanced`, `sessions` / `session` CLI, session-aware `search` and `check`, and the new `@agent-inspect/mcp` package for local MCP client `tools/list` and `tools/call` tracing. No schema break, no MCP gateway/server, and no default network behavior.
+
+## 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 +26,22 @@
 
 ## Unreleased
 
-### Draft v2.2.0 Notes
+### Draft v2.4.0 Notes
+
+- Added session/workflow causality model and `agent-inspect/advanced` session index helpers (`buildSessionIndex`, scope/cohort helpers, session fixtures).
+- Added `agent-inspect sessions` and `agent-inspect session` CLI for multi-run handoff/retry navigation with timeline, critical-path, diagnostics, and JSON output.
+- Added session-aware `search --session` and `check --session` / `--group` with aggregated per-run evidence.
+- Added public optional `@agent-inspect/mcp` for local MCP **client** `tools/list` and `tools/call` telemetry with bounded summaries and `source.type: mcp-client` metadata.
+- No schema version change, no MCP gateway/server, no timestamp-only causality inference, and no root/core dependency on MCP SDKs.
+
+### 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

@@ -22,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release line: **2.1.x** for the existing public packages. v2.1.0 adds deterministic local eval and reusable redaction utilities on top of the stable v2 trace contract: small root API, schema 1.0 persisted writer path, v0.1/v0.2/v1.0 read compatibility, and explicit non-destructive migration workflow.
+Current npm release line: **2.3.x** for the existing public packages. **v2.4.0** (release prep) adds multi-run **session** navigation (`sessions` / `session` CLI), session-aware `search` and `check`, and optional **`@agent-inspect/mcp`** client telemetry — all local-first on top of the stable v2 trace contract.
 
 ```bash
 npm install agent-inspect
@@ -334,12 +334,18 @@ AgentInspect is the **local-first trace workbench** for TypeScript AI agents:
 
 - Instrument runs with `inspectRun` and `step`
 - 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`**
+- Inspect with **`list`**, **`view`**, **`clean`**, **`logs`**, **`tail`**, **`export`**, **`diff`**, **`timeline`**, **`stats`**, **`search`**, **`sessions`**, **`session`**
 
 **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).
 
+**v2.4 train status:** session/workflow causality helpers ship on `agent-inspect/advanced` (`buildSessionIndex`, scope/cohort helpers). CLI adds `sessions`, `session`, `search --session`, and `check --session` / `--group`. Optional `@agent-inspect/mcp` wraps MCP client `tools/list` and `tools/call` as local tool steps with bounded summaries — no gateway or server product.
+
+**v2.3 shipped:** adapter hardening for AI SDK, OpenAI Agents JS, and LangChain/LangGraph with 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 +360,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.5 guardrails/circuit patterns, 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 +376,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.
@@ -398,6 +414,30 @@ const events = callback.getEvents();
 
 See [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](docs/ADAPTERS.md).
 
+### MCP client telemetry (`@agent-inspect/mcp`)
+
+Optional package for **local MCP client** tracing only. Wrap `tools/list` and `tools/call` so they emit tool steps with `source.type: mcp-client`, bounded argument summaries, server identity, and optional `sessionId` metadata.
+
+```bash
+pnpm add agent-inspect @agent-inspect/mcp
+```
+
+```ts
+import { inspectRun } from "agent-inspect";
+import { wrapMcpClient } from "@agent-inspect/mcp";
+
+const traced = wrapMcpClient(mcpClient, {
+  serverName: "docs-server",
+  sessionId: "sess-123",
+});
+
+await inspectRun("agent-with-mcp", async () => {
+  await traced.callTool({ name: "search", arguments: { query: "sessions" } });
+});
+```
+
+No-network recipe: [mcp-client-tracing](examples/recipes/mcp-client-tracing/). This is **not** an MCP server, gateway, or hosted broker — see [docs/ADAPTERS.md](docs/ADAPTERS.md).
+
 ### TUI viewer (`@agent-inspect/tui`)
 
 Optional **Ink/React** package, installed separately. Use with an interactive terminal:
@@ -411,7 +451,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).
 
@@ -444,6 +484,9 @@ Reporter artifact behavior and API details are documented in [docs/API.md](docs/
 | [examples/recipes/test-reporter-artifacts](examples/recipes/test-reporter-artifacts) | Vitest/Jest reporter artifact patterns |
 | [examples/recipes/what-report-inspect](examples/recipes/what-report-inspect/) | `what` + `report` inspection |
 | [examples/recipes/runtime-and-ingestion](examples/recipes/runtime-and-ingestion/) | v1.6 runtime writers + universal ingestion |
+| [examples/recipes/mcp-client-tracing](examples/recipes/mcp-client-tracing) | v2.4 MCP client tool-call tracing |
+
+**Multi-run sessions:** set `sessionId` (and optional handoff/retry metadata) on `run_started`, then browse with `npx agent-inspect sessions` and `npx agent-inspect session <id> --timeline`. See [SESSIONS-AND-WORKFLOW-CAUSALITY](docs/proposals/SESSIONS-AND-WORKFLOW-CAUSALITY.md).
 
 **Recipes** are deterministic and require **no external services** by default. Index: [examples/README.md](examples/README.md), [examples/recipes/README.md](examples/recipes/README.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,85 @@ 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.
+
+---
+
+## MCP client telemetry (`@agent-inspect/mcp`)
+
+**Status:** experimental optional package — v2.4.0 train.
+
+`@agent-inspect/mcp` traces **MCP client** `tools/list` and `tools/call` as local AgentInspect tool steps. It records server identity (name + URL hash), tool name, bounded argument/result summaries, duration, errors, and optional session metadata (`sessionId`, `toolCallId`, `mcpToolCallId`).
+
+### Install
+
+```bash
+npm install agent-inspect @agent-inspect/mcp
+```
+
+### Wrap a client
+
+```ts
+import { inspectRun } from "agent-inspect";
+import { wrapMcpClient } from "@agent-inspect/mcp";
+
+const traced = wrapMcpClient(mcpClient, {
+  serverName: "docs-server",
+  serverUrl: process.env.MCP_SERVER_URL,
+  sessionId: "sess-123",
+});
+
+await inspectRun("support-agent", async () => {
+  await traced.listTools?.();
+  await traced.callTool({ name: "search", arguments: { query: "refund policy" } });
+});
+```
+
+`wrapMcpClient` accepts any object matching the documented `McpClientLike` shape. It does **not** require `@modelcontextprotocol/sdk` at runtime.
+
+### Boundaries (v2.4)
+
+| In scope | Out of scope |
+| -------- | ------------ |
+| Client-side `tools/list` and `tools/call` wrapping | MCP **server** implementation |
+| Bounded summaries on tool step metadata | Gateway, proxy, or hosted MCP broker |
+| `source.type: mcp-client` on tool steps | Invoking tools on behalf of the user from AgentInspect |
+| Session metadata attachment when provided | Default trace upload |
+
+Recipe: [examples/recipes/mcp-client-tracing](../examples/recipes/mcp-client-tracing/).
+
+Session navigation for multi-run workflows uses `agent-inspect sessions` / `session` and optional `search --session` / `check --session` — see [CLI.md](./CLI.md) and [SESSIONS-AND-WORKFLOW-CAUSALITY.md](./proposals/SESSIONS-AND-WORKFLOW-CAUSALITY.md).
+
+---
+
 ## 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/docs/CLI.md

@@ -38,6 +38,8 @@ Core commands:
 - `timeline` — chronological view of one run (local JSONL)
 - `stats` — local aggregate stats over a trace directory
 - `search` — deterministic local search over traces
+- `sessions` — list workflow sessions from trace metadata
+- `session` — inspect one session (handoffs, retries, optional timeline)
 - `what` — concise summary of a single run (local JSONL)
 - `report` — markdown or HTML inspection report for a single run
 - `explain` — deterministic local facts/inferences for a trace, with dry-run payloads
@@ -305,6 +307,9 @@ Options:
 - `--max-duration-ms <number>`: add `run.duration`
 - `--required-tool <name>` / `--forbidden-tool <name>`: add `tool.usage`
 - `--allowed-model <model>` / `--max-total-tokens <number>`: add `llm.usage`
+- `--session <id>`: check all runs in a workflow session (uses `--dir`; target may be `.`)
+- `--group <id>`: check all runs sharing a `groupId` metadata value
+- `--correlate-group`: when using `--session`, also match synthetic `group:` session keys
 
 By default, `check` runs `run.status`. Additional built-in rules can be selected with `--rule` or config when their options are available.
 
@@ -329,6 +334,7 @@ Examples:
 npx agent-inspect check fixtures/traces-v0.2/manual-basic.jsonl --json
 npx agent-inspect check minimal-success --dir fixtures/traces --rule run.status
 npx agent-inspect check trace.jsonl --max-duration-ms 30000 --required-tool search_docs --json
+npx agent-inspect check . --dir ./.agent-inspect --session sess-handoff-001 --json
 ```
 
 Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
@@ -634,6 +640,8 @@ Options:
 - `--tool <query>` — substring on tool step name or `metadata.toolName`
 - `--duration <expr>` — e.g. `>5s`, `>=500ms`
 - `--limit <number>` — default 50
+- `--session <id>` — limit to runs in one workflow session
+- `--correlate-group` — when using `--session`, also match synthetic `group:` keys
 - `--json`
 
 Examples:
@@ -642,11 +650,56 @@ Examples:
 npx agent-inspect search --status error --dir ./.agent-inspect
 npx agent-inspect search --kind tool --name search
 npx agent-inspect search --duration ">100ms" --json
+npx agent-inspect search --session sess-retry-001 --dir ./.agent-inspect
 ```
 
 ![Search traces by status error](../assets/demos/search.gif)
 
-### 6.19 `what`
+### 6.19 `sessions`
+
+List workflow sessions grouped from local trace metadata (`sessionId`, optional `groupId` correlation). Read-only; no network.
+
+```bash
+agent-inspect sessions [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--correlate-group` — treat shared `groupId` as a synthetic session when `sessionId` is absent
+- `--json` — `SessionIndex` JSON (`sessions`, `unscopedRunIds`, `warnings`)
+
+Example:
+
+```bash
+npx agent-inspect sessions --dir ./.agent-inspect
+npx agent-inspect sessions --json
+```
+
+### 6.20 `session`
+
+Inspect one workflow session: runs, handoffs, retries, and optional per-run timelines. Uses the same session index as `sessions`.
+
+```bash
+agent-inspect session <session-id> [options]
+```
+
+Options:
+
+- `--dir <path>`
+- `--timeline` — include per-run timelines (human or JSON `timelines`)
+- `--critical-path` — include critical path section
+- `--diagnostics` — include ambiguity warnings for the session
+- `--json` — structured session view
+
+Example:
+
+```bash
+npx agent-inspect session sess-handoff-001 --timeline
+npx agent-inspect session sess-retry-001 --critical-path --json
+```
+
+### 6.21 `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).
 

package/docs/SCHEMA.md

@@ -131,6 +131,7 @@ Unknown status must **not** be treated as success.
 
 - Runs may include `metadata` on `run_started`.
 - **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). `stats --correlation-id` and `--group-id` filter by these fields; `list` / `view` do not filter by correlation yet.
+- **Session and workflow metadata (v2.4.0+, additive):** optional fields for multi-run causality — see [SESSIONS-AND-WORKFLOW-CAUSALITY.md](./proposals/SESSIONS-AND-WORKFLOW-CAUSALITY.md). Recommended placement: `run_started.metadata` (manual v0.1) or persisted `attributes` (v0.2/v1.0). Common keys: `sessionId`, `conversationId`, `parentGroupId`, `attempt`, `retryOf`, `handoffFrom`, `handoffTo`, `subAgentId`, `subAgentName`, `jobId`, `queueName`, `workflowName`, `workflowStep`, `toolCallId`, `mcpToolCallId`, `linkedStepId`. All optional; missing keys mean unknown. Readers must not infer handoff/retry links from timestamps alone. Existing traces without these fields remain fully readable.
 - Steps may include `metadata` on `step_started`.
 - Manual traces intentionally avoid full prompt/output capture by default.
 - **Redaction (default on):** before disk, `inspectRun` / `step` redact sensitive keys using the shared `Redactor` defaults (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Opt out with `redact: false`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -178,7 +178,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 && pnpm exec tsup --config tsup.harness.config.ts && pnpm exec tsup --config tsup.redact.config.ts && pnpm exec tsup --config tsup.eval.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 && pnpm exec tsup --config tsup.redact.config.ts && pnpm exec tsup --config tsup.eval.config.ts && pnpm exec tsup --config tsup.mcp.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",