agent-inspect 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.5.0
+
+### Minor Changes
+
+- 11edf90: Release v2.5.0 with deterministic guardrails and circuit utilities.
+
+  This train adds `@agent-inspect/guardrails` and `@agent-inspect/circuit`, optional `check --guardrails` / `check --circuit` flags, eval safety rule factories, and recipes. No compliance claims, no remote policy engine, and no default enforcement.
+
+## 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 +34,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.4.0** for the linked public packages (`agent-inspect`, adapters, reporters, redact, eval, mcp). **v2.4.0** adds multi-run **session** navigation (`sessions` / `session` CLI), session-aware `search` and `check`, and optional **`@agent-inspect/mcp`** client telemetry.
 
 ```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 shipped:** sessions/MCP client telemetry on `main@2.4.0`. All ten linked packages published at `2.4.0` including `@agent-inspect/mcp`.
+
+**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,11 @@ 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
+- `--guardrails <rule>`: optional deterministic guardrail rules (`banned-phrase`, `pii-leak`, `prompt-injection`, …); repeatable
+- `--circuit <rule>`: optional circuit analyzers (`same-tool-repetition`, `max-retries`, …); repeatable
 
 By default, `check` runs `run.status`. Additional built-in rules can be selected with `--rule` or config when their options are available.
 
@@ -329,6 +336,8 @@ 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 trace.jsonl --guardrails pii-leak --guardrails prompt-injection --json
+npx agent-inspect check trace.jsonl --circuit same-tool-repetition --circuit max-retries --json
 ```
 
 Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
@@ -634,6 +643,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 +653,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/LIMITATIONS.md

@@ -55,6 +55,12 @@ This document states what AgentInspect **does not** provide today. It complement
 - **Metadata truncation** applies to string values and nested structures; very large metadata may be replaced with a truncation marker when `maxEventBytes` is exceeded (default 64 KiB per JSONL line).
 - **Redaction is not encryption.** Local trace files remain readable on disk; treat `.agent-inspect-runs/` like any developer artifact that may contain operational data.
 
+## Guardrails and circuits (v2.5 planning)
+
+- **Guardrails and circuits are deterministic local utilities, not compliance certification.** `@agent-inspect/guardrails` and `@agent-inspect/circuit` (planned v2.5) evaluate text, JSON, and trace patterns with bounded evidence; they do not prove safety for every sharing context or replace human review.
+- **No LLM judge or remote policy engine.** Built-in rules use pattern lists, redact findings, and structural heuristics only.
+- **No automatic remediation by default.** Results are advisory unless caller code maps failures to errors, trace events, or enforcement.
+
 ## Checks, artifacts, and test reporters
 
 - **Checks are deterministic local rules, not compliance certification.** `check`, `scan`, and `verify-safe` surface bounded findings and diagnostics over supported local inputs; they do not prove a trace is safe for every sharing context.

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.5.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 && pnpm exec tsup --config tsup.guardrails.config.ts && pnpm exec tsup --config tsup.circuit.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",