agent-inspect 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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
@@ -18,6 +26,14 @@
 
 ## Unreleased
 
+### 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
 
 - 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.

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,13 +334,15 @@ 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.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.
+**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**.
 
@@ -358,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.4 adds sessions/MCP telemetry, followed by 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**.
 
@@ -412,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:
@@ -458,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/ADAPTERS.md

@@ -406,6 +406,53 @@ A future Nest helper remains demand-gated and must be narrower than a framework
 
 ---
 
+## 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):

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.3.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",