agent-inspect 2.5.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 3.0.0
+
+### Major Changes
+
+- a1f743f: v3.0 extension contracts: `@agent-inspect/adapter-sdk` with registration, conformance, privacy helpers, transform/renderer contracts, optional rebuildable indexer, and community extension registry documentation. Linked major semver bump; persisted trace schema 1.0 unchanged.
+
+## 2.6.0
+
+### Minor Changes
+
+- 57efe08: Release v2.6.0 with optional localhost viewer and read-only MCP server surfaces.
+
+  This train adds `@agent-inspect/viewer`, `agent-inspect serve`, `@agent-inspect/mcp-server` read-only trace tools, and defers IDE extension until post-v2.6 demand review. All optional surfaces are read-only with share-profile defaults.
+
 ## 2.5.0
 
 ### Minor Changes

package/README.md

@@ -438,6 +438,34 @@ await inspectRun("agent-with-mcp", async () => {
 
 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).
 
+### Local viewer (`@agent-inspect/viewer`)
+
+Optional **localhost read-only** HTTP viewer. Start from the CLI:
+
+```bash
+pnpm add agent-inspect @agent-inspect/viewer
+npx agent-inspect serve --dir ./.agent-inspect-runs
+```
+
+Binds `127.0.0.1` by default. Serves trace list, timeline, and check JSON from disk — no upload, no mutation. Recipe: [read-only viewer workflow](examples/recipes/read-only-mcp-server/) (also covers MCP server tools).
+
+### Read-only MCP server (`@agent-inspect/mcp-server`)
+
+Optional package exposing **read-only** MCP tools (`list_traces`, `read_trace`, `search_traces`, `run_checks`, `create_share_safe_report`, and analysis helpers) over a local trace directory. Distinct from `@agent-inspect/mcp` (client telemetry). Default redaction profile is `share`.
+
+```bash
+pnpm add agent-inspect @agent-inspect/mcp-server
+```
+
+```ts
+import { runReadOnlyMcpServer } from "@agent-inspect/mcp-server";
+
+// stdio MCP server — configure trace dir via AGENT_INSPECT_TRACE_DIR
+await runReadOnlyMcpServer({ redactionProfile: "share" });
+```
+
+IDE extension is **deferred** — see [docs/IDE-SURFACES.md](docs/IDE-SURFACES.md).
+
 ### TUI viewer (`@agent-inspect/tui`)
 
 Optional **Ink/React** package, installed separately. Use with an interactive terminal:
@@ -485,6 +513,9 @@ Reporter artifact behavior and API details are documented in [docs/API.md](docs/
 | [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 |
+| [examples/recipes/guardrails-basic](examples/recipes/guardrails-basic) | v2.5 deterministic guardrails |
+| [examples/recipes/circuit-breaker-basic](examples/recipes/circuit-breaker-basic) | v2.5 circuit analyzers |
+| [examples/recipes/read-only-mcp-server](examples/recipes/read-only-mcp-server) | v2.6 read-only MCP trace tools |
 
 **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).
 

package/SECURITY.md

@@ -76,5 +76,22 @@ For a practical pre-share workflow, see `docs/SAFE-TRACE-SHARING.md`. For schema
 
 - Prefer Node.js built-ins over new dependencies.
 - Do not add vendor SDKs, OpenTelemetry SDKs, or framework dependencies to the main `agent-inspect` package.
-- Keep optional integrations (`@agent-inspect/langchain`, `@agent-inspect/tui`) separate so users do not pull them in by default.
+- Keep optional integrations (`@agent-inspect/langchain`, `@agent-inspect/tui`, `@agent-inspect/viewer`, `@agent-inspect/mcp-server`) separate so users do not pull them in by default.
+
+## Optional surfaces (v2.6)
+
+### Local viewer (`agent-inspect serve`)
+
+- Binds **localhost by default** (`127.0.0.1`). Binding to all interfaces exposes local traces on the network.
+- **Read-only** HTTP routes — no trace mutation APIs.
+- Does not upload data. Review traces before sharing screenshots or exported copies.
+
+### Read-only MCP server (`@agent-inspect/mcp-server`)
+
+- Exposes **read-only** MCP tools over a configured trace directory.
+- Default tool output redaction profile is **`share`** (not `local`).
+- Does not invoke user agent tools or mutate traces.
+- Configure via `AGENT_INSPECT_TRACE_DIR` and `AGENT_INSPECT_MCP_REDACTION_PROFILE` when documented.
+
+IDE marketplace extension is **deferred** — see [docs/IDE-SURFACES.md](docs/IDE-SURFACES.md).
 

package/docs/ADAPTERS.md

@@ -453,6 +453,47 @@ Session navigation for multi-run workflows uses `agent-inspect sessions` / `sess
 
 ---
 
+## Local viewer (`@agent-inspect/viewer`)
+
+**Status:** optional package — v2.6.0 train.
+
+Read-only localhost HTTP server for browsing traces on disk. Wired through `agent-inspect serve`.
+
+| In scope | Out of scope |
+| -------- | ------------ |
+| `127.0.0.1` default bind | Cloud hosting or accounts |
+| Trace list, timeline, check JSON routes | Trace mutation or replay |
+| Reads through `agent-inspect/readers` | SQLite or remote fetch |
+
+```bash
+npm install agent-inspect @agent-inspect/viewer
+npx agent-inspect serve --dir ./.agent-inspect-runs
+```
+
+---
+
+## Read-only MCP server (`@agent-inspect/mcp-server`)
+
+**Status:** optional package — v2.6.0 train.
+
+Stdio MCP server exposing **read-only** tools (`list_traces`, `read_trace`, `search_traces`, `find_first_error`, `find_slowest_path`, `compare_runs`, `run_checks`, `create_share_safe_report`). Distinct from `@agent-inspect/mcp` (client telemetry).
+
+| In scope | Out of scope |
+| -------- | ------------ |
+| Local trace directory tools | MCP client wrapping |
+| `share` redaction default | Unredacted prompts by default |
+| Bounded JSON responses | Tool invocation on user agents |
+
+```ts
+import { runReadOnlyMcpServer } from "@agent-inspect/mcp-server";
+
+await runReadOnlyMcpServer({ redactionProfile: "share" });
+```
+
+Recipe: [examples/recipes/read-only-mcp-server](../examples/recipes/read-only-mcp-server/). IDE extension deferred: [IDE-SURFACES.md](./IDE-SURFACES.md).
+
+---
+
 ## Future adapters (not shipped)
 
 Direction only — see [ROADMAP.md](../ROADMAP.md):

package/docs/CLI.md

@@ -342,7 +342,24 @@ npx agent-inspect check trace.jsonl --circuit same-tool-repetition --circuit max
 
 Recipe: [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md)
 
-### 6.10 `eval`
+### 6.10 `serve`
+
+Start the optional **localhost read-only** trace viewer (`@agent-inspect/viewer`). Reads traces from disk only; no upload or mutation.
+
+```bash
+agent-inspect serve [options]
+```
+
+Options:
+
+- `--dir <path>`: trace directory to serve (default from `AGENT_INSPECT_TRACE_DIR` or `.agent-inspect-runs`)
+- `--host <host>`: bind host (default `127.0.0.1`)
+- `--port <number>`: bind port (default `7337`)
+- `--open`: open a browser when host is localhost
+
+Binding to `0.0.0.0` logs a warning — traces may be exposed on the network. Prefer `127.0.0.1` unless you accept that risk.
+
+### 6.11 `eval`
 
 Run deterministic local evals against an existing trace. This command reads through the same local reader pipeline as `open` and `check`; it does not rerun agents, call models, upload traces, mutate inputs, or create a hosted dataset.
 

package/docs/MIGRATION.md

@@ -65,3 +65,27 @@ Nothing uploads by default. Manual metadata is redacted before disk by default,
 - Root/core does not require optional adapter dependencies.
 - Optional adapter APIs are experimental and package-scoped.
 - No destructive migration is required for existing trace directories.
+
+## Upgrading from 2.x to 3.0
+
+v3.0 is a **linked npm major** for the public package family. **Persisted trace schema remains 1.0** — existing `.jsonl` files do not need rewriting.
+
+### What changes
+
+- New optional package [`@agent-inspect/adapter-sdk`](https://www.npmjs.com/package/@agent-inspect/adapter-sdk) for third-party adapter authoring (registration, conformance, privacy checklist, transform/renderer/indexer contracts).
+- Community extension process documented in [COMMUNITY-EXTENSION-REGISTRY.md](./COMMUNITY-EXTENSION-REGISTRY.md).
+- Extension interfaces are versioned in `@agent-inspect/adapter-sdk@3.x`; breaking extension API changes ship there, not in silent root patches.
+
+### What stays the same
+
+- Root imports (`inspectRun`, `step`, `observe`, `createInspector`, etc.) and subpath layout from v2.
+- Local-first capture, metadata-only adapter defaults, and explicit migration via `agent-inspect migrate` for schema upgrades.
+- Optional packages (`viewer`, `mcp-server`, adapters, reporters) remain opt-in peer dependencies.
+
+### Upgrade steps
+
+1. Bump linked dependencies together, e.g. `agent-inspect@^3.0.0` and matching `@agent-inspect/*` versions.
+2. Re-run your trace/check CI after bump; no trace file migration is required for 2.6 → 3.0.
+3. For new third-party adapters, use `@agent-inspect/adapter-sdk` and follow the community registry checklist.
+
+See [V3-EXTENSION-CONTRACTS.md](./proposals/V3-EXTENSION-CONTRACTS.md) and [V3.0.0-RELEASE-READINESS.md](./implementation/release-trains/V3.0.0-RELEASE-READINESS.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "2.5.0",
+  "version": "3.0.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 && pnpm exec tsup --config tsup.mcp.config.ts && pnpm exec tsup --config tsup.guardrails.config.ts && pnpm exec tsup --config tsup.circuit.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 && pnpm exec tsup --config tsup.viewer.config.ts && pnpm exec tsup --config tsup.mcp-server.config.ts && pnpm exec tsup --config tsup.adapter-sdk.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",