agent-inspect 6.31.9 → 6.31.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.31.11
+
+### Patch Changes
+
+- 7180204: C06–C13 suite/capture trust follow-through: explain logical lifecycle counts; TraceCheckSummary rule-status totals and Execution wording in `what`; mock OpenAI Node chat.completions recipe; suite `expect` for semantic failures; Nest Evidence v2 docs; skip exact `[REDACTED]` key-noise in `@agent-inspect/redact`; additive Evidence `inputs` provenance bindings; bounded consumer smoke (disk reread + evidence verify).
+
+## 6.31.10
+
+### Patch Changes
+
+- 1327356: Return actionable diagnostics for reversed evaluateTraceContract arguments and warn (without throwing) when inspectRun is passed an unsupported writer option, pointing callers at createInspector({ writer }).
+
 ## 6.31.9
 
 ### Patch Changes

package/README.md

@@ -213,7 +213,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.31.9** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.31.11** · 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/docs/NESTJS.md

@@ -1,12 +1,23 @@
-# NestJS + AgentInspect (harness path)
+# NestJS + AgentInspect
 
-AgentInspect does **not** ship a production NestJS interceptor in v3.2. Use **`@agent-inspect/harness`** to bootstrap real Nest apps for local fixture runs.
+AgentInspect does **not** ship a production NestJS interceptor package. Use one of
+the maintained paths below depending on whether you need harness fixture runs,
+LangGraph callbacks, structured log ingestion, or Evidence v2 packaging.
 
-## Recommended path (v3.2)
+## Paths (keep them distinct)
 
-1. `npx agent-inspect init` or use [examples/starters/harness-nestjs](../examples/starters/harness-nestjs/)
-2. Wire `createFixtureRunner()` with your `TestingModule` / app bootstrap
-3. Run targets with JSON fixtures — no real model calls by default
+| Path | When to use | Starter / recipe |
+| --- | --- | --- |
+| Harness fixture runner | Bootstrap a real Nest `TestingModule` for local fixture runs | [examples/starters/harness-nestjs](../examples/starters/harness-nestjs/) |
+| LangGraph callbacks | Nest services that already pass a `callbacks` array | [examples/recipes/nestjs-langgraph-local](../examples/recipes/nestjs-langgraph-local/) |
+| Structured logs | Log ingestion without an agent adapter | [examples/recipes/nestjs-json-logging](../examples/recipes/nestjs-json-logging/) |
+| Direct SDK / Evidence v2 | Explicit `createInspector` / writer + share-checked bundle | this guide + [shareable-bundle-basic](../examples/recipes/shareable-bundle-basic/) |
+
+Manual tracing (`createInspector` / `inspectRun`) and framework adapters
+(`@agent-inspect/langchain`) remain separate: do not mix duplicate manual +
+adapter spans for the same invoke.
+
+## Harness path
 
 ```ts
 import { createFixtureRunner, defineTarget } from "@agent-inspect/harness";
@@ -30,27 +41,54 @@ await createFixtureRunner({
 }).runFromArgv();
 ```
 
-## Out of scope (v3.2)
+## LangGraph callbacks (env-gated)
 
-- `@agent-inspect/nestjs` production package (demand-gated)
-- Redis/SQS mocking in harness
-- Global monkey-patching of Nest providers
+Prefer [nestjs-langgraph-local](../examples/recipes/nestjs-langgraph-local/):
 
-## Structured logs alternative
+- `AGENT_INSPECT` gate + lazy dynamic import (no adapter load when disabled)
+- metadata-only capture and workspace-relative `traceDir`
+- no production-path change when the helper returns `[]`
 
-If you only need log ingestion, see [examples/recipes/nestjs-json-logging](../examples/recipes/nestjs-json-logging/).
+## Native Evidence v2 path
 
-## LangGraph agent callbacks (env-gated)
+Use the same CLI builders Nest consumers already get from AgentInspect — do not
+append unregistered files to a verified directory or use `--unexpected ignore`
+to paper over a broken bundle.
 
-For Nest services that invoke LangGraph/LangChain with a `callbacks` array, prefer the
-blessed recipe [examples/recipes/nestjs-langgraph-local](../examples/recipes/nestjs-langgraph-local/):
+```bash
+# After a local Nest/harness run wrote JSONL under .agent-inspect
+npx agent-inspect check <run-id> --dir .agent-inspect --json
+npx agent-inspect bundle <run-id> --dir .agent-inspect --out ./evidence-out --json
+npx agent-inspect bundle verify ./evidence-out --json
+```
 
-- `AGENT_INSPECT` gate + lazy dynamic import (no adapter load when disabled)
-- metadata-only capture and workspace-relative `traceDir`
-- no production-path change when the helper returns `[]`
+Programmatic packaging uses `buildEvidenceManifest` / `verifyEvidenceDirectory`
+from `agent-inspect/advanced` (see [reproducible-repair-evidence](../examples/recipes/reproducible-repair-evidence/)
+and [shareable-bundle-basic](../examples/recipes/shareable-bundle-basic/)).
+
+Acceptance for a fresh consumer:
+
+1. Documented commands produce a share-checked Evidence v2 directory
+2. `bundle verify` reports checked files with zero issues on an intact package
+3. Tampered or missing file bytes fail verification
+4. Contract binding / custom-rule partiality remain visible when present
+5. Verified hashes do **not** prove the Nest app was correctly instrumented —
+   capture assertions and human review stay separate verdicts
+
+For direct OpenAI Node capture without Nest, see
+[openai-node-chat-completions](../examples/recipes/openai-node-chat-completions/).
+
+## Out of scope
+
+- `@agent-inspect/nestjs` production package (demand-gated)
+- Redis/SQS mocking in harness
+- Global monkey-patching of Nest providers
+- Treating verified Evidence hashes as instrumentation proof
 
 ## Related
 
 - [`@agent-inspect/harness`](../packages/harness/README.md)
 - [examples/starters/harness-nestjs](../examples/starters/harness-nestjs/)
 - [examples/recipes/nestjs-langgraph-local](../examples/recipes/nestjs-langgraph-local/)
+- [docs/case-studies/nestjs-langgraph-local-evidence.md](./case-studies/nestjs-langgraph-local-evidence.md)
+- [docs/SUPPORT-REPRODUCTION.md](./SUPPORT-REPRODUCTION.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.31.9",
+  "version": "6.31.11",
   "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",