agent-inspect 6.18.0 → 6.19.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.19.1
+
+### Patch Changes
+
+- e23b94b: 6.19.1 trust restoration: redact free-text credentials in persisted error messages before disk, refresh shipped docs to match 6.19.0 reality, and enforce all 18 fixed-group package READMEs (including root `agent-inspect`) via `package-readmes:check`.
+
+## 6.19.0
+
+### Minor Changes
+
+- 07358f2: Add custom TraceReader authoring guidance with a synthetic foreign-session recipe, additive derived failure roles on TraceFacts (MCP/Evidence counts), architectural-intent interop docs/recipe, and bounded priorContextReferences convention.
+
 ## 6.18.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,8 @@
   <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js 20 or newer"></a>
 </p>
 
+**Support level:** Stable — see [SUPPORT-LEVELS.md](docs/SUPPORT-LEVELS.md). Network behavior: [NETWORK-BEHAVIOR.md](docs/NETWORK-BEHAVIOR.md).
+
 ```bash
 npm install agent-inspect
 ```
@@ -210,7 +212,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.18.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.19.1** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
 Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 

package/SECURITY.md

@@ -82,6 +82,8 @@ For a practical pre-share workflow, see `docs/SAFE-TRACE-SHARING.md`. For schema
 
 Pull requests run GitHub **Dependency review** (`.github/workflows/dependency-review.yml`) and fail on newly introduced **high** or **critical** advisory severity. Routine unit/typecheck/size CI also exercises redaction, path containment, and Evidence safety tests. These scanners do **not** replace manual review of share profiles or Evidence packages before you disclose traces.
 
+For synthetic fixtures, dynamic-import boundaries, and an explicit “what scanners verify vs not” table, see [docs/SECURITY-SCANNERS.md](docs/SECURITY-SCANNERS.md).
+
 ## Optional surfaces (v2.6)
 
 ### Local viewer (`agent-inspect serve`)

package/docs/API.md

@@ -514,6 +514,7 @@ import type { TraceReader } from "agent-inspect/readers";
 - **`openInferenceJsonReader`**: local OpenInference JSON compatibility reader. Prompt/output-like attributes are summarized and bounded rather than stored as raw content.
 - **`otlpJsonReader`**: local OTLP/HTTP JSON trace payload reader. Resource, scope, span, status, event, and parent metadata are preserved where possible with warnings for unsupported fields.
 - **`DEFAULT_TRACE_READERS`**: ordered built-in reader registry used when no custom `readers` array is supplied.
+- **Custom readers**: implement `TraceReader` and pass `{ readers: [myReader, ...DEFAULT_TRACE_READERS] }` — see [CUSTOM-TRACE-READER.md](./CUSTOM-TRACE-READER.md).
 
 The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies. See also [PROGRAMMATIC-TRACE-ANALYSIS.md](./PROGRAMMATIC-TRACE-ANALYSIS.md).
 
@@ -536,7 +537,7 @@ import type { TraceCheckRule, TraceCheckResult, TraceFacts } from "agent-inspect
 ```
 
 - **`runTraceChecks({ read }, { rules?, select?, runId? })`**: executes provided rules against a `TraceReadResult` from `agent-inspect/readers`.
-- **`buildTraceFacts(read | events)`**: experimental TraceFacts over logical projection; accepts `TraceReadResult` or normalized `PersistedInspectEvent[]`.
+- **`buildTraceFacts(read | events)`**: experimental TraceFacts over logical projection; accepts `TraceReadResult` or normalized `PersistedInspectEvent[]`. Additive 6.19 fields: `failureFacts`, `failuresByRole`, `summary.failureRoleCounts`.
 - **`defineTraceContract` / `evaluateTraceContract` / `evaluateTraceContractRead`**: experimental contract helpers; `evaluateTraceContractRead(read, contract)` wraps `{ read }`.
 - **`formatProgrammaticDiagnostic` / `PROGRAMMATIC_DIAGNOSTIC_SPECS`**: stable `AI_*` codes with remediation hints.
 - **Built-in rule factories**: run, tool, LLM, structure, retrieval, guardrail, decision, safety, and baseline helpers including `createRunStatusRule`, `createToolUsageRule`, `createLlmUsageRule`, `createStructureOrphanRule`, `createStructureCycleRule`, `createStructureRelationshipRule`, `createRetrievalRule`, `createGuardrailRule`, `createDecisionRule`, `createSafetyRawContentRule`, `createSafetySecretPatternRule`, and `createBaselineRegressionRule`.

package/docs/ARCHITECTURE.md

@@ -1,27 +1,41 @@
 ## Architecture
 
-> **Adoption-focused overview:** see [TECHNICAL-GUIDE.md](./TECHNICAL-GUIDE.md) for a comprehensive technical guide (v3.5.5) suitable for blogs and outreach.
+> **Adoption-focused overview:** see [TECHNICAL-GUIDE.md](./TECHNICAL-GUIDE.md) for a comprehensive technical guide suitable for blogs and outreach.
 
-AgentInspect is a **local-first execution-tree debugger**: manual traces and log ingest produce inspectable step trees stored as JSONL on disk (default `.agent-inspect-runs/`), with a CLI for list/view/clean/logs/tail/export/diff workflows.
+AgentInspect is a **local-first execution-tree debugger and trajectory-test toolkit** for TypeScript AI agents: framework-native capture and manual traces produce inspectable step trees as local JSONL (default `.agent-inspect`), with CLI, TraceContract / TraceFacts checks, Evidence v2 packaging, and optional read-only MCP.
 
 ### Package layout
 
 | Package | Published? | Role |
 | -------- | ---------- | ---- |
 | `agent-inspect` | Yes | Public tarball: core tracing APIs + CLI (`agent-inspect` binary) |
-| `@agent-inspect/core` | No (private) | Tracing, storage, log parsing, export, diff |
+| `@agent-inspect/core` | No (private) | Tracing, storage, readers/writers, checks, export, diff |
 | `@agent-inspect/cli` | No (private) | Commander CLI implementation |
-| `@agent-inspect/langchain` | Yes (optional) | LangChain.js callback adapter (experimental) |
-| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer (experimental) |
-
-Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy dependencies (LangChain, Ink/React) stay in optional packages.
+| `@agent-inspect/redact` | Yes | Standalone redaction engine (also used by CLI `redact`) |
+| `@agent-inspect/ai-sdk` | Yes (optional) | Vercel AI SDK telemetry integration |
+| `@agent-inspect/openai-agents` | Yes (optional) | OpenAI Agents JS `setTraceProcessors()` adapter |
+| `@agent-inspect/langchain` | Yes (optional) | LangChain.js / LangGraph callback adapter |
+| `@agent-inspect/mcp` | Yes (optional) | MCP client `tools/list` / `tools/call` tracing |
+| `@agent-inspect/adapter-sdk` | Yes (optional) | Shared adapter helpers / plugin surface |
+| `@agent-inspect/vitest` / `@agent-inspect/jest` | Yes (optional) | Test reporters and TraceContract matchers |
+| `@agent-inspect/eval` | Yes (optional) | Deterministic local eval heuristics |
+| `@agent-inspect/guardrails` / `@agent-inspect/circuit` | Yes (optional) | Local guardrail and circuit utilities |
+| `@agent-inspect/harness` | Yes (optional) | Lightweight local harness helpers |
+| `@agent-inspect/viewer` | Yes (optional) | Local HTML/viewer surface |
+| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer |
+| `@agent-inspect/mcp-server` | Yes (optional) | Read-only local MCP server over traces |
+| `@agent-inspect/index-sqlite` | Yes (optional) | Optional local SQLite metadata index |
+| `@agent-inspect/studio` | Yes (optional) | Local studio CLI / ingest surfaces |
+
+Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy framework dependencies stay in optional packages.
 
 ### Event model and schema
 
-- Manual traces use **`schemaVersion: "0.1"`** JSONL events (`run_started`, `step_started`, `step_completed`, `run_completed`).
-- Failures use `step_completed` with `status: "error"` — there is no `step_failed` event.
+- Manual global helpers (`inspectRun()` / `step()`) still write **`schemaVersion: "0.1"`** JSONL for compatibility (`run_started`, `step_started`, `step_completed`, `run_completed`).
+- Failures use `step_completed` / `run_completed` with `status: "error"` — there is no `step_failed` event.
+- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema **1.0** persisted rows; v0.1 and v0.2 remain readable.
 - Log-derived runs use confidence labels (`explicit`, `correlated`, `heuristic`, `unknown`) and conservative tree-building rules.
-- **v1.2.0 persisted-event foundation (released):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are v1.3+ / post-foundation work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.3.0-RELEASE-TRAIN.md](./implementation/V1.3.0-RELEASE-TRAIN.md).
+- Migration is explicit (`agent-inspect migrate …`); AgentInspect does not rewrite old traces in place.
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 
@@ -29,21 +43,19 @@ See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for publ
 
 - Instrumentation must **not throw into user code**; trace safety failures degrade gracefully.
 - **Manual metadata** is redacted before disk by default; `redact: false` opts out.
+- **Error messages** also run high-confidence free-text credential detectors before disk (provider keys, bearer tokens, JWTs, and related patterns), unless `redact: false`.
 - **Size bounds** cap persisted event and metadata size.
 - Log ingest: JSON first-class; log4js best-effort; no `eval` or JS object-literal parsing.
 
 See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
 
-### Optional adapters
-
-- **`@agent-inspect/langchain`**: in-memory by default; `persist: true` writes local JSONL. Experimental.
-- **`@agent-inspect/tui`**: interactive viewer; isolated from root deps. Experimental.
+### Optional adapters and surfaces
 
-See [ADAPTERS.md](./ADAPTERS.md).
+Official adapters (`@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, `@agent-inspect/langchain`) share a bounded preview-capture contract. MCP client tracing, reporters, eval, redact, viewer/TUI, studio, and read-only MCP are separate optional packages — see [ADAPTERS.md](./ADAPTERS.md) and [SUPPORT-LEVELS.md](./SUPPORT-LEVELS.md).
 
 ### Architecture proposals
 
-Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active post-v1.5 roadmap is [implementation/ROADMAP-V1.6-TO-V3.md](./implementation/ROADMAP-V1.6-TO-V3.md).
+Maintainer-owned RFCs and planning proposals are indexed in [proposals/README.md](./proposals/README.md). The active roadmap is [implementation/ROADMAP.md](./implementation/ROADMAP.md).
 
 ### Where to read next
 

package/docs/KNOWN-ISSUES.md

@@ -28,10 +28,10 @@ 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 experimental and metadata-first. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`. The v1.9 package publication retry is pending maintainer-side npm auto-publish setup and is separate from v2 contract work.
+- **AI SDK adapter** (`@agent-inspect/ai-sdk`) is Supported and metadata-first by default. It depends on explicit AI SDK telemetry configuration and requires `recordInputs: false` / `recordOutputs: false` for the documented safe path. Opt-in `capture: "preview"` uses the shared bounded preview helper.
+- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is Supported and metadata-first. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`. Bounded `capture: "preview"` parity ships with the other official adapters.
 - **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 adapter** (`@agent-inspect/langchain`) is Supported; it captures **metadata-oriented** signals by default and shares the same preview contract when `capture: "preview"` is set.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
 - **Deep swarm / nested RunnableSequence (6.14.2+):** capture resolves parents before registering child indexes and rejects `parentId === stepId`. Legacy traces that still contain self-parent edges are normalized in logical projection (`AI_LOGICAL_SELF_PARENT_REMOVED`) and rendered with visibility-first, cycle-safe trees so nested LLM/tool steps remain visible.
 - **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

@@ -13,10 +13,10 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **`list` / `view` / `export`** do not filter by correlation fields yet — `stats --correlation-id` / `--group-id` and `search` provide targeted read paths; full CLI filtering remains incremental.
 
-## Persisted event model (v1.2.0 foundation)
+## Persisted event model
 
 - **Manual global tracing remains v0.1.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL for compatibility.
-- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema 1.0 persisted rows; v0.2 remains a readable compatibility foundation.
+- **Persisted writer/runtime output targets schema 1.0.** `createInspector()` with built-in writers emits schema 1.0 persisted rows; v0.1 and v0.2 remain readable.
 - **Migration is explicit, not automatic.** `agent-inspect migrate <input> --to 1.0 --dry-run` reports what would change, and `--output <file>` writes a separate file. AgentInspect does not rewrite old traces in place.
 
 ## Runtime writers and universal readers (v1.6)
@@ -32,7 +32,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **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 experimental.** `@agent-inspect/openai-agents` maps metadata-only runtime spans through the safe `setTraceProcessors()` boundary and does not capture raw payloads by default. The v1.9 package publication retry is a separate maintainer npm automation task, not part of the v2 contract work.
+- **OpenAI Agents JS support is Supported (metadata-first).** `@agent-inspect/openai-agents` maps runtime spans through the safe `setTraceProcessors()` boundary and does not capture raw payloads by default. Bounded `capture: "preview"` is available through the shared adapter capture contract.
 - **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.
 - **Preview capture is bounded, not sanitized.** `capture: "preview"` persists truncated, key-redacted previews of framework-provided input/output fields. Key-based redaction cannot detect a secret embedded in free text, and there is no full-content capture mode. Fields the framework never exposes are reported as `AI_CAPTURE_FIELD_UNAVAILABLE` rather than reconstructed.
@@ -53,7 +53,8 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **Redaction profiles** (`local`, `share`, `strict`) are key-based presets — not compliance-grade PII detection. Review exports before sharing even with `--redaction-profile strict`.
 - **`@agent-inspect/redact` and `agent-inspect redact` create redacted copies.** They do not encrypt source traces, mutate originals, certify compliance, or guarantee every sensitive value is detected.
-- **Default metadata redaction** covers common sensitive keys only (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
+- **Default metadata redaction** covers common sensitive keys (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
+- **Error-message free text** also runs high-confidence credential detectors before disk (provider API keys, bearer tokens, JWTs, GitHub tokens, PEM private keys, and high-confidence `key=value` secrets). This is still not compliance-grade detection; `redact: false` opts out.
 - **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.
 

package/docs/PERFORMANCE.md

@@ -30,7 +30,7 @@ npx agent-inspect stats --dir fixtures/performance
 
 All three are validated by `pnpm fixtures:check` and small enough for git (the largest is well under 1 MB).
 
-## Comfortable ranges (v3.4)
+## Comfortable ranges
 
 | Workload | Comfortable | Warning | Not designed for |
 | -------- | ----------- | ------- | ---------------- |

package/docs/SUPPORT-LEVELS.md

@@ -49,7 +49,8 @@ shows). `pnpm package-readmes:check` enforces the agreement and runs as part of
 To promote or demote a surface:
 
 1. Edit the row in the matrix above.
-2. Edit the `**Support level:**` line in each affected `packages/*/README.md`.
+2. Edit the `**Support level:**` line in the affected public README: `README.md`
+   for the root `agent-inspect` package, or `packages/*/README.md` for scoped packages.
 3. Run `pnpm package-readmes:check`.
 
 The check also reports packages whose level is **unenforced** — those the matrix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.18.0",
+  "version": "6.19.1",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
@@ -243,7 +243,8 @@
     "public-truth:check": "node scripts/validate-public-truth.mjs",
     "ai-assets:check": "node scripts/validate-ai-assets.mjs",
     "package-readmes:check": "node scripts/validate-package-readmes.mjs",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run build:cli && pnpm run demo:verify",
+    "actions:check": "node scripts/check-github-actions-pins.mjs",
+    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run actions:check && pnpm run build:cli && pnpm run demo:verify",
     "build:cli": "pnpm exec tsup --config tsup.cli.config.ts",
     "repo:health": "node scripts/validate-repo-health.mjs",
     "demo:generate": "node scripts/demo-generate.mjs",