agent-inspect 6.13.0 → 6.14.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 6.14.1
+
+### Patch Changes
+
+- 44f80dd: Public positioning and AI discoverability patch: align README/docs/website/package metadata with shipped 6.14 TraceFacts, Evidence, MCP, and experimental matchers; add llms/AI manifests, Agent Skill, and public-truth validators. Docs and presentation only — no schema/runtime change.
+
+## Unreleased
+
+### Patch
+
+- (pending 6.14.1) Public positioning, documentation truth, and AI discoverability refresh.
+
+## 6.14.0
+
+### Minor Changes
+
+- 52a3e23: Evidence-first CI and no-egress launch candidate: optional Evidence `semantics` TraceFacts summary on CI packages, MCP `get_trace_facts`, `init --framework langgraph`, langgraph-gate-evidence recipe, and no-egress/acceptance docs. No schema break; no new packages; no default network.
+
 ## 6.13.0
 
 ### Minor Changes
@@ -12,14 +30,6 @@
 
 - a3c0daa: Logical lifecycle projection for built-in checks and TraceContract: additive experimental `logicalEvents` (raw `events` unchanged), v0.1 start/complete pairing, stepId parent normalization, nested tool identity, and `metadata.tokens.*` safe metrics. Eval/gate/Evidence/MCP inherit via `runTraceChecks`. Includes anonymized pilot-shaped fixture and packed check→gate→bundle→verify E2E. No schema break; no new packages; no default network.
 
-## Unreleased
-
-### Patch (6.12.3) / Minor (6.13.0) candidates
-
-- Cross-surface semantic parity: `summarizeSemanticParity`, MCP adapter diagnostics parity payload, scaffolding-root parent diagnostics, TraceContract `requiredTools`/`forbiddenTools` aliases.
-- Experimental `TraceFacts` (`buildTraceFacts`) with tool/LLM/outcome indexes over logicalEvents.
-- Experimental Vitest/Jest matchers: `toPassTraceContract`, `toHaveRequiredTool`.
-
 ## 6.12.1
 
 ### Patch Changes

package/README.md

@@ -8,11 +8,19 @@
 <h1 align="center">agent-inspect</h1>
 
 <p align="center">
-  <strong>The local evidence debugger for TypeScript agents—faithful execution trees, deterministic regression checks, share-checked evidence, and coding-agent access without a collector or account.</strong>
+  <strong>Debug and regression-test TypeScript AI agents from local evidence.</strong>
 </p>
 
 <p align="center">
-  <sub>No account · no default upload · metadata-only by default · optional customer-owned Studio</sub>
+  AgentInspect captures framework-faithful execution trees, evaluates them with deterministic TraceFacts and TraceContract rules, creates integrity-verifiable Evidence v2, and lets coding assistants inspect the same local facts over read-only MCP—without a collector, account, or default upload.
+</p>
+
+<p align="center">
+  <em>See what your agent did. Prove the fix. Keep the evidence.</em>
+</p>
+
+<p align="center">
+  <sub>No account · no collector · no default upload · metadata-only by default</sub>
 </p>
 
 <p align="center">
@@ -33,7 +41,14 @@
 npm install agent-inspect
 ```
 
-## Hero flow
+## Four pillars
+
+| Pillar | What you get |
+| ------ | ------------ |
+| **Capture faithfully** | Framework-aware execution trees and local JSONL you own |
+| **Test behavior deterministically** | TraceFacts, TraceContract, checks, suites, gates, and experimental Vitest/Jest matchers |
+| **Produce portable evidence** | Offline Evidence v2 with integrity verification and share-policy disclosure |
+| **Debug with coding assistants locally** | Read-only MCP over the same TraceFacts — no collector required |
 
 ```text
 1. Capture one real run
@@ -43,18 +58,6 @@ npm install agent-inspect
 5. Attach the share-checked evidence
 ```
 
-## Three workflows
-
-| Workflow | What you do |
-| -------- | ----------- |
-| **Debug one run** | Capture/import → tree / timeline / report → first causal failure |
-| **Prevent one regression** | TraceContract / `check` → suite / cohort → CI gate |
-| **Share one safe artifact** | Redact → `verify-safe` → offline bundle → optional Studio review |
-
-**Coding-agent loop (optional):** local read-only [`@agent-inspect/mcp-server`](https://www.npmjs.com/package/@agent-inspect/mcp-server) — see [CODING-AGENT-LOOP.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md).
-
-**Review as a team (optional):** workspace + optional SQLite index → customer-owned [Studio Beta](https://github.com/rajudandigam/agent-inspect/tree/main/packages/studio) (no AgentInspect-hosted cloud). Portfolio tiers: [POSITIONING-AND-PORTFOLIO.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/POSITIONING-AND-PORTFOLIO.md).
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture or import → understand → enforce → verify and bundle → review locally or in customer-owned Studio" width="900">
 </p>
@@ -66,6 +69,7 @@ Commands below match the packed quickstart. Replace `<run-id>` with a value from
 ```bash
 npm install agent-inspect
 npx agent-inspect init --yes
+# or: npx agent-inspect init --framework langgraph --yes
 node examples/agent-inspect-demo.mjs
 npx agent-inspect list --dir .agent-inspect
 ```
@@ -81,23 +85,22 @@ npx agent-inspect bundle verify .agent-inspect/bundles/<run-id>
 npx agent-inspect mcp configure --client cursor
 ```
 
-`init` scaffolds config and a demo script; the **demo** writes the trace. Guide: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [repo](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) · [Golden path](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GOLDEN-PATH.md) · [Coding-agent loop](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
+Guides: [First trace in 5 minutes](https://agentinspect.vercel.app/docs/getting-started/) · [Golden path](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GOLDEN-PATH.md) · [Coding-agent loop](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md)
 
 ## Why AgentInspect
 
-**Unique position:** a local **evidence debugger** for TypeScript agents—not a hosted APM, eval host, or prompt registry. Complements LangSmith/Langfuse/Phoenix; owns the laptop → PR loop.
+**Category:** the local evidence debugger and trajectory-test toolkit for TypeScript AI agents — not a hosted APM, eval host, or prompt registry. Complements LangSmith/Langfuse/Phoenix; owns the laptop → PR loop.
 
-**Proven mechanisms (shipped):**
+**Proof (public-safe):** Validated against production-shaped NestJS/LangGraph integrations. Fixture-backed across official adapters and packed consumer workflows.
 
 | Mechanism | What you get |
 | --------- | ------------ |
 | Faithful execution trees | Nested steps, tools, LLMs, status, duration on disk |
-| First causal failure | Conservative ordered engine for what failed first |
+| TraceFacts / logical projection | Canonical tool identity and semantic parity without inventing hierarchy |
 | Deterministic checks / TraceContract (Beta) | Trajectory expectations without an LLM judge |
-| Share-checked Evidence v2 | `bundle` + `bundle verify` offline artifacts |
-| Read-only MCP coding-agent loop (Preview) | `mcp configure` + `@agent-inspect/mcp-server` over local traces |
-
-No fabricated adoption counts. External pilot evidence is still pending—see [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md).
+| Experimental Vitest/Jest matchers | `toPassTraceContract` · `toHaveRequiredTool` |
+| Share-checked Evidence v2 | `bundle` + `bundle verify` with optional TraceFacts semantics |
+| Read-only MCP coding-agent loop (Preview) | `get_trace_facts` and related tools over local traces |
 
 ## Choose your capture path
 
@@ -106,29 +109,27 @@ No fabricated adoption counts. External pilot evidence is still pending—see [P
 | **Manual / observe** | Custom nesting or object methods | [Getting started](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GETTING-STARTED.md) |
 | **AI SDK** | Vercel AI SDK `generateText` / `streamText` | [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) |
 | **OpenAI Agents** | OpenAI Agents JS | [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) |
-| **LangChain** | Callbacks / LangGraph-via-LangChain | [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) |
+| **LangChain / LangGraph** | Callbacks / LangGraph | [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) · `init --framework langgraph` |
 | **Structured logs** | Logs already emitted | [Log-to-tree](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LOG-TO-TREE-QUICKSTART.md) |
 | **Harness** | Fixture runner for real projects | [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) |
-| **CI reporters** | Failed-test artifacts | [`vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) · [`jest`](https://www.npmjs.com/package/@agent-inspect/jest) |
+| **CI reporters + matchers** | Failed-test artifacts and contracts | [`vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) · [`jest`](https://www.npmjs.com/package/@agent-inspect/jest) |
 | **Standards files** | OpenInference / OTLP JSON | [Standards](https://github.com/rajudandigam/agent-inspect/blob/main/docs/STANDARDS.md) |
 
-Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
+Blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters) · LangGraph gate/evidence recipe: [langgraph-gate-evidence](https://github.com/rajudandigam/agent-inspect/tree/main/examples/recipes/langgraph-gate-evidence)
 
 ## What you can do after capture
 
-**Understand** — `what` / `view` / tree · timeline · report · diff · sessions / activity  
+**Understand** — `what` / `view` / tree · timeline · report · diff · `buildTraceFacts`
 
-**Prevent regressions** — deterministic checks · typed TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters (artifact reporters today; TraceContract matchers not shipped)  
+**Prevent regressions** — deterministic checks · TraceContract (Beta) · suites · cohorts · CI gates · Vitest/Jest reporters · experimental matchers (`toPassTraceContract`, `toHaveRequiredTool`)
 
-**Share safely** — redaction profiles · `scan` · `verify-safe` · offline bundles · CI artifacts  
+**Share safely** — redaction profiles · `scan` · `verify-safe` · Evidence v2 bundles · CI artifacts
 
-**Scale locally** — workspace · optional SQLite index (Beta) · observed outcomes · viewer / TUI / VS Code  
+**Debug with coding assistants** — `@agent-inspect/mcp-server` · `get_trace_facts` · first-causal-failure
 
-**Review as a team** — customer-owned Studio Beta · explicit file / GitHub / HTTP ingest (disabled by default) · no maintainer cloud  
+**Scale locally** — workspace · optional SQLite index (Beta) · viewer / TUI / VS Code · customer-owned Studio (Beta)
 
-**Interoperate** — read-only MCP server (Preview) · OpenInference-compatible / OTLP GenAI-aligned mapping with known-loss reporting  
-
-Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) · Network: [NETWORK-BEHAVIOR.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md)
+Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) · Network: [NETWORK-BEHAVIOR.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md) · No-egress: [NO-EGRESS-POLICY.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md)
 
 ## Real-world scenarios
 
@@ -136,13 +137,10 @@ Support labels: [SUPPORT-LEVELS.md](https://github.com/rajudandigam/agent-inspec
 | -------- | ----- |
 | Wrong tool / intentional failure | [broken-agent-debugging](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging) |
 | Coding-agent MCP debug loop | [coding-agent-debug-loop](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/coding-agent-debug-loop) · [CODING-AGENT-LOOP](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) |
-| CI trajectory gate + redact | [ci-eval-redact](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/ci-eval-redact) · [CI artifacts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CI-ARTIFACTS.md) |
+| CI trajectory gate + Evidence | [ci-eval-redact](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/ci-eval-redact) · [langgraph-gate-evidence](https://github.com/rajudandigam/agent-inspect/tree/main/examples/recipes/langgraph-gate-evidence) |
 | Safe incident handoff | [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |
 | Multi-agent / session retry | [Sessions & outcomes](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SESSIONS-AND-OUTCOMES.md) |
 | Customer-owned team review | [Self-hosting](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SELF-HOSTING.md) · Studio (optional) |
-| Design partner trial | [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) |
-
-All blessed starters (no API keys): [examples/starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters)
 
 ## Safety and network behavior
 
@@ -159,9 +157,11 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.13.0** (eighteen linked npm packages). Stable launch candidate; eight-week adoption checkpoint in progress; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
+**Current release:** **6.14.1** · schema **1.0** · Node.js **≥ 20** · **MIT** · **actively maintained** (eighteen linked npm packages).
+
+The 6.14 line is actively maintained for correctness, compatibility, documentation, security, and framework evolution.
 
-[Roadmap](ROADMAP.md) · [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) · [Changelog](CHANGELOG.md)
+[Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [Public product facts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/product/PUBLIC-PRODUCT-FACTS.md)
 
 ## What AgentInspect is not
 
@@ -169,7 +169,8 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 - Production APM replacement
 - Eval dataset platform or LLM-as-judge by default
 - Prompt registry, pricing engine, or replay engine
-- Universal standards exporter or completed external adoption proof
+- Universal standards exporter
+- Compliance certification
 
 See [Compare](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).
 
@@ -194,7 +195,7 @@ Canonical tiers: [POSITIONING-AND-PORTFOLIO.md](https://github.com/rajudandigam/
 | ------- | ------- |
 | [`@agent-inspect/ai-sdk`](https://www.npmjs.com/package/@agent-inspect/ai-sdk) | AI SDK telemetry |
 | [`@agent-inspect/openai-agents`](https://www.npmjs.com/package/@agent-inspect/openai-agents) | OpenAI Agents processor |
-| [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) | LangChain callbacks |
+| [`@agent-inspect/langchain`](https://www.npmjs.com/package/@agent-inspect/langchain) | LangChain / LangGraph callbacks |
 
 ### Tier B — Testing / evaluation
 
@@ -202,8 +203,8 @@ Canonical tiers: [POSITIONING-AND-PORTFOLIO.md](https://github.com/rajudandigam/
 | ------- | ------- |
 | [`@agent-inspect/harness`](https://www.npmjs.com/package/@agent-inspect/harness) | Fixture runner |
 | [`@agent-inspect/eval`](https://www.npmjs.com/package/@agent-inspect/eval) | Local eval heuristics |
-| [`@agent-inspect/vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) | Vitest reporter |
-| [`@agent-inspect/jest`](https://www.npmjs.com/package/@agent-inspect/jest) | Jest reporter |
+| [`@agent-inspect/vitest`](https://www.npmjs.com/package/@agent-inspect/vitest) | Vitest reporter + experimental matchers |
+| [`@agent-inspect/jest`](https://www.npmjs.com/package/@agent-inspect/jest) | Jest reporter + experimental matchers |
 
 ### Tier C — Optional supporting (Safety)
 
@@ -244,7 +245,8 @@ Canonical tiers: [POSITIONING-AND-PORTFOLIO.md](https://github.com/rajudandigam/
 | | Website | Repo |
 | - | ------- | ---- |
 | Getting started | [docs](https://agentinspect.vercel.app/docs/getting-started/) | [FIRST-TRACE](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md) |
-| Contracts / suites / gates | — | [TRACE-CONTRACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md) · [SUITES-COHORTS-GATES](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUITES-COHORTS-GATES.md) |
+| TraceFacts / contracts | — | [TRACE-FACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-FACTS.md) · [TRACE-CONTRACTS](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md) |
+| Evidence / MCP / no-egress | — | [EVIDENCE-FORMAT](https://github.com/rajudandigam/agent-inspect/blob/main/docs/EVIDENCE-FORMAT.md) · [CODING-AGENT-LOOP](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) · [NO-EGRESS-POLICY](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md) |
 | Safe sharing | [safe-sharing](https://agentinspect.vercel.app/docs/safe-sharing/) | [SAFE-TRACE-SHARING](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md) |
 | API / CLI | — | [API](docs/API.md) · [CLI](docs/CLI.md) (packed with npm) |
 | Full index | — | [docs/README.md](https://github.com/rajudandigam/agent-inspect/blob/main/docs/README.md) |

package/docs/DEMO-SCRIPT.md

@@ -1,7 +1,7 @@
 # Live demo script (~4 minutes)
 
 **Audience:** TypeScript developers debugging AI agents.
-**Prereqs:** Node 20+. Consumers: `npm install agent-inspect@6.12.1`. Monorepo: `pnpm build` at repo root.
+**Prereqs:** Node 20+. Consumers: `npm install agent-inspect@6.14.1`. Monorepo: `pnpm build` at repo root.
 **Website:** [https://agentinspect.vercel.app/](https://agentinspect.vercel.app/)
 
 **Blessed demo starters:**
@@ -87,7 +87,7 @@ npx agent-inspect diff .agent-inspect/<broken-run>.jsonl .agent-inspect/<fixed-r
 ## Alternative opener (zero clone)
 
 ```bash
-npm install agent-inspect@6.12.1
+npm install agent-inspect@6.14.1
 npx agent-inspect init --yes
 node examples/agent-inspect-demo.mjs
 npx agent-inspect list --dir .agent-inspect

package/docs/GOLDEN-PATH.md

@@ -1,6 +1,6 @@
-# Golden path (stable launch candidate)
+# Golden path
 
-The **6.12.0** stable launch candidate path. Be precise about what is automated today.
+The recommended local evidence path for the current **6.14** release line.
 
 ## Automated packed path (CI)
 
@@ -10,31 +10,31 @@ From a packed `agent-inspect` install (`scripts/packed-quickstart-e2e.mjs` via `
 init --yes → demo → list → verify-safe <runId> --dir .agent-inspect
 ```
 
-This proves install, scaffold, one local run, and safety verification.
+Semantic loop smoke (`scripts/packed-semantic-loop-e2e.mjs`) exercises check → gate → bundle → verify on a pilot-shaped fixture.
 
-## Recommended developer path (manual)
+## Recommended developer path
 
 ```text
-init → demo → list → view/report → check → bundle --profile share → verify-safe
+init → demo → list → view/report → check → bundle --profile share → verify-safe → bundle verify
 ```
 
-Use required positional targets (`<run-id>` or file path). See the root README five-minute path.
-
-## Technical-but-not-fully-automated
-
-`scripts/golden-path-e2e.mjs` covers a subset (init → inspect → verify-safe → report). It does **not** yet automate the full roadmap chain:
+LangGraph-oriented path:
 
 ```text
-broken → contract fail → suite → CI gate → fix → diff/cohort → Studio review
+init --framework langgraph → capture → TraceContract / gate → Evidence v2 → optional MCP get_trace_facts
 ```
 
-## External pilot step
+Use required positional targets (`<run-id>` or file path). See the root README five-minute path.
+
+## Optional extensions
 
-Three external teams + design-partner Studio trial remain **pending**. Do not mark launch adoption complete without rows in [implementation/PRE-V7-ADOPTION-EVIDENCE.md](./implementation/PRE-V7-ADOPTION-EVIDENCE.md). Pilot kit: [PRE-V7-PILOT-KIT.md](./PRE-V7-PILOT-KIT.md).
+- Suites / cohorts / CI gates — [SUITES-COHORTS-GATES.md](./SUITES-COHORTS-GATES.md)
+- Experimental Vitest/Jest matchers — [TRACE-CONTRACTS.md](./TRACE-CONTRACTS.md)
+- Coding-agent MCP loop — [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md)
+- Customer-owned Studio — [SELF-HOSTING.md](./SELF-HOSTING.md)
 
-## Pending product gaps (honest)
+## Honest boundaries
 
-- TraceContract matchers / full contract depth
-- Studio HTML productization for some pages
-- Cross-platform consumer matrix evidence
-- External Collector/Phoenix verification
+- Full broken→fix→Studio productization is not a single automated script.
+- External partner retention attestation is tracked internally; do not invent adoption rows.
+- Redaction is best-effort, not compliance certification.

package/docs/SUPPORT-LEVELS.md

@@ -1,6 +1,6 @@
 # Support levels
 
-Canonical maturity labels for AgentInspect public packages and major surfaces (6.12.x fixed release line).
+Canonical maturity labels for AgentInspect public packages and major surfaces (6.14.x fixed release line).
 
 ## Definitions
 
@@ -32,7 +32,7 @@ Canonical maturity labels for AgentInspect public packages and major surfaces (6
 | Studio HTTP / GitHub ingest | Preview |
 | `@agent-inspect/mcp-server` | Preview |
 | Standards round-trip / Collector–Phoenix external proof | Preview |
-| Vitest/Jest TraceContract matchers | **Not shipped** |
+| Vitest/Jest TraceContract matchers (`toPassTraceContract`, `toHaveRequiredTool`) | Experimental |
 
 Part of the fixed AgentInspect release line — see the npm badge for the current version.
 

package/docs/TRACE-CONTRACTS.md

@@ -9,17 +9,27 @@ Typed trajectory expectations over local AgentInspect traces via `defineTraceCon
 Contracts compile to deterministic check rules for common cases:
 
 - run status / completion / max duration
-- tool required / forbidden / allowed / maxCalls / order
+- tool required / forbidden / allowed / maxCalls / order (`requiredTools` / `forbiddenTools` aliases)
 - LLM maxCalls / maxTotalTokens / allowedModels
 - evidence-bearing findings on failures
+- evaluation over **logical** TraceFacts (raw events remain available)
 
-See [API.md](./API.md) and `packages/core/src/checks/contract.ts`.
+### Experimental Vitest / Jest matchers (shipped)
+
+| Package | Export | Matchers |
+| ------- | ------ | -------- |
+| `@agent-inspect/vitest` | `agentInspectVitestMatchers` | `toPassTraceContract`, `toHaveRequiredTool` |
+| `@agent-inspect/jest` | `agentInspectJestMatchers` | `toPassTraceContract`, `toHaveRequiredTool` |
+
+These are **Experimental** — API names may evolve. There is no `expectTrace(...).toSatisfyTraceContract` helper.
+
+See [API.md](./API.md), [TRACE-FACTS.md](./TRACE-FACTS.md), and `packages/core/src/checks/contract.ts`.
 
 ## What is not shipped (yet)
 
 Do **not** document these as available:
 
-- Vitest / Jest `expectTrace(...).toSatisfyTraceContract` matchers
+- `expectTrace(...).toSatisfyTraceContract` (different API shape than the shipped matchers)
 - Full workflow handoff / approval / MCP protocol contract rules
 - Per-tool argument schema / regex validators on the contract surface
 - Every structure rule (orphan/cycle/depth) exposed on the contract API (many exist as standalone check rules)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "agent-inspect",
-  "version": "6.13.0",
+  "version": "6.14.1",
   "license": "MIT",
   "type": "module",
-  "description": "Debug, regression-test, and safely share TypeScript AI-agent behavior locally — no account, no default upload, metadata-only by default",
+  "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rajudandigam/agent-inspect.git"
@@ -187,12 +187,20 @@
   "keywords": [
     "ai",
     "agents",
-    "debugging",
     "typescript",
+    "debugging",
+    "trajectory-testing",
+    "langgraph",
+    "langchain",
+    "tracecontract",
+    "tracefacts",
+    "evidence",
+    "mcp",
     "llm",
     "devtools",
     "jsonl",
-    "cli"
+    "cli",
+    "local-first"
   ],
   "publishConfig": {
     "access": "public"
@@ -231,7 +239,8 @@
     "docs:commands": "node scripts/validate-doc-commands.mjs",
     "docs:links": "node scripts/validate-doc-links.mjs",
     "public-truth:check": "node scripts/validate-public-truth.mjs",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check",
+    "ai-assets:check": "node scripts/validate-ai-assets.mjs",
+    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check",
     "compat:smoke": "node scripts/compat-smoke.mjs",
     "fixtures:check": "node scripts/validate-fixtures.mjs",
     "recipes:check": "node scripts/validate-recipes.mjs",

package/packages/cli/dist/{chunk-QOKTMZAY.mjs → chunk-MEO2Z3KE.mjs}

@@ -4004,6 +4004,7 @@ function buildEvidenceManifest(parts) {
       verificationPolicy: parts.verificationPolicy ?? parts.redactionProfile
     },
     assessment,
+    ...parts.semantics !== void 0 ? { semantics: { ...parts.semantics } } : {},
     files: buildEvidenceFileEntries(parts.files)
   };
 }
@@ -5568,7 +5569,8 @@ function buildEvidenceCiPackage(input) {
     sourceStatus: input.sourceStatus,
     files: packaged,
     createdAt,
-    note: EVIDENCE_ASSESSMENT_NOTE
+    note: EVIDENCE_ASSESSMENT_NOTE,
+    ...input.semantics !== void 0 ? { semantics: input.semantics } : {}
   });
   return {
     "evidence.html": evidenceHtml,
@@ -6109,6 +6111,30 @@ function pickString(record, keys) {
   return void 0;
 }
 
+// packages/core/src/checks/trace-facts.ts
+function summarizeSemanticParity(events) {
+  const projection = projectLogicalEvents(events);
+  const logical = projection.logicalEvents;
+  const finishedTools = logical.filter(
+    (event) => event.kind === "TOOL" && event.status !== "running"
+  );
+  const finishedToolNames = Object.freeze(
+    finishedTools.map((event) => resolveCanonicalToolName(event)).sort((a, b) => a.localeCompare(b))
+  );
+  return {
+    rawEventCount: events.length,
+    logicalEventCount: logical.length,
+    runningLogicalCount: logical.filter((event) => event.status === "running").length,
+    finishedToolNames,
+    finishedToolCount: finishedTools.length,
+    pairedCount: logical.filter((event) => event.projection.paired).length,
+    parentRemapCount: projection.diagnostics.filter(
+      (item) => item.code === "AI_LOGICAL_PARENT_REMAPPED"
+    ).length,
+    diagnostics: projection.diagnostics
+  };
+}
+
 // packages/core/src/checks/index.ts
 var SEVERITY_RANK = {
   error: 0,
@@ -11019,6 +11045,6 @@ function renderGateReport(result, options = {}) {
   return renderGateSummaryMarkdown(result);
 }
 
-export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-QOKTMZAY.mjs.map
-//# sourceMappingURL=chunk-QOKTMZAY.mjs.map
+export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
+//# sourceMappingURL=chunk-MEO2Z3KE.mjs.map
+//# sourceMappingURL=chunk-MEO2Z3KE.mjs.map