agent-inspect 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.8.0
+
+### Minor Changes
+
+- 0bee42c: Release v1.8.0 with OpenAI Agents trace processor support, optional Vitest/Jest reporter packages kept private, deterministic CI release checks, and the validated local-first reporting improvements from the v1.8 release train.
+
+## 1.7.0
+
+Released **2026-06-26**.
+
+### Minor Changes
+
+- 94a7220: Release v1.7.0 framework-native adoption with the experimental AI SDK telemetry adapter, declarative adapter conformance matrix, and local-first adapter documentation.
+
+### Notes
+
+- The v1.8 train carries the remaining adapter correctness work: AI SDK logical lifecycle identity, parallel integration isolation, explicit capture/redaction behavior, executable conformance fixtures, OpenAI Agents runtime mapping, and LangGraph no-network fixtures. v1.7.0 should not be read as claiming those deferred behaviors.
+
 ## 1.6.0
 
 Released **2026-06-25**.

package/README.md

@@ -22,7 +22,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.6.0** (`agent-inspect`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
+Current npm release: **1.7.0** (`agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -111,7 +111,7 @@ await maybeInspectRun("eval-case-42", async () => runAgent());
 AGENT_INSPECT=1 node eval-runner.mjs
 ```
 
-## What you can do today (v1.6.0)
+## What you can do today (v1.7.0)
 
 - **Trace manually** with `inspectRun`, `step`, `step.llm`, `step.tool`, and `observe` — local JSONL under `.agent-inspect/` by default.
 - **Toggle tracing** with `maybeInspectRun` and `AGENT_INSPECT=1` in eval harnesses or CI.
@@ -121,6 +121,7 @@ AGENT_INSPECT=1 node eval-runner.mjs
 - **Export share-safe copies** — `export --redaction-profile share` (or `strict`) writes local Markdown/HTML/OpenInference/OTLP JSON only.
 - **Parse structured logs** you already emit (JSON first-class; log4js best-effort).
 - **Optional LangChain adapter** — metadata-only by default; optional `persist: true` and `stream: true` streaming metadata (no full token capture by default).
+- **Optional AI SDK adapter** — experimental `@agent-inspect/ai-sdk` telemetry integration for AI SDK v6; metadata-only by default with `recordInputs: false` and `recordOutputs: false`.
 - **Optional TUI** — `view --tui` when `@agent-inspect/tui` is installed.
 - **Persisted-event foundation (v1.2.0+)** — in-memory `PersistedInspectEvent` converters; manual writing stays `schemaVersion: "0.1"`.
 - **Experimental v1.6.0 APIs** — `agent-inspect/writers`, `agent-inspect/readers`, `createInspector()`, and `agent-inspect open` for local AgentInspect/OpenInference/OTLP ingestion.
@@ -180,6 +181,8 @@ More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](do
 | `search` | Deterministic search over local traces |
 | `what` | Concise summary of one run |
 | `report` | Markdown/HTML inspection report (what + timeline + tree) |
+| `check` / `scan` / `verify-safe` | Deterministic local trace checks and best-effort safety verification |
+| `artifacts` | Safe local CI artifact bundles and optional step-summary file output |
 
 ![Timeline with slow-step focus for one run](https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/demos/timeline.gif)
 
@@ -198,7 +201,7 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.6.0**) is the **local-first trace workbench** for TypeScript AI agents:
+**agent-inspect 1.x** (current: **1.7.0**) is the **local-first trace workbench** for TypeScript AI agents:
 
 - Instrument runs with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
@@ -208,11 +211,13 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 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).
 
-**Shipped in 1.6.0:** experimental writer subpath (`agent-inspect/writers`), isolated `createInspector()` API via `agent-inspect/advanced`, local trace readers via `agent-inspect/readers`, OpenInference/OTLP JSON readers, universal `agent-inspect open`, and deterministic [runtime-and-ingestion recipe](examples/recipes/runtime-and-ingestion/). These remain local-only and do not add upload behavior. Linked release aligns all three npm packages at **1.6.0**.
+**Shipped in 1.7.0:** experimental `@agent-inspect/ai-sdk` telemetry integration for AI SDK v6 with a local no-network [ai-sdk-local-telemetry recipe](examples/recipes/ai-sdk-local-telemetry/), adapter conformance fixtures, OpenAI Agents/LangGraph support decisions, and local-first adapter docs. Examples keep `recordInputs: false`, `recordOutputs: false`, metadata-only capture, and no upload behavior. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, and `@agent-inspect/tui` at **1.7.0**.
+
+**Shipped in 1.6.0:** experimental writer subpath (`agent-inspect/writers`), isolated `createInspector()` API via `agent-inspect/advanced`, local trace readers via `agent-inspect/readers`, OpenInference/OTLP JSON readers, universal `agent-inspect open`, and deterministic [runtime-and-ingestion recipe](examples/recipes/runtime-and-ingestion/). These remain local-only and do not add upload behavior. Linked release aligns all three then-published npm packages at **1.6.0**.
 
 **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:** future work continues from the local runtime and universal ingestion foundation before broadening framework adapters. See [ROADMAP.md](ROADMAP.md).
+**Roadmap beyond current release work:** future work continues from the local runtime, universal ingestion, and optional adapter foundations. 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**.
 
@@ -289,6 +294,8 @@ The TUI is available as a separate optional package; its programmatic API is exp
 | [examples/recipes/retry-fallback](examples/recipes/retry-fallback) | Fallback pattern |
 | [examples/recipes/parallel-tools](examples/recipes/parallel-tools) | Parallel tools |
 | [examples/recipes/github-actions-artifact](examples/recipes/github-actions-artifact) | CI trace artifacts |
+| [examples/recipes/deterministic-ci-checks](examples/recipes/deterministic-ci-checks) | v1.8 checks, baseline, and safe CI artifacts |
+| [examples/recipes/test-reporter-artifacts](examples/recipes/test-reporter-artifacts) | v1.8 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 |
 

package/docs/ADAPTER-CONFORMANCE.md

@@ -0,0 +1,39 @@
+# Adapter conformance
+
+AgentInspect optional framework adapters must stay local-first, dependency-isolated, and metadata-only by default.
+
+The machine-readable matrix lives at [docs/implementation/adapter-conformance-matrix.json](./implementation/adapter-conformance-matrix.json). It tracks expected coverage for:
+
+- run lifecycle
+- generic steps
+- tools
+- LLM calls
+- errors
+- streaming metadata
+- metadata bounds and privacy controls
+
+The v1.7 matrix is declarative coverage guidance. v1.8 makes conformance executable and requires canonical-reader round trips before adapter output is used by checks.
+
+Executable shared assertions live in `packages/core/test/adapter-executable-conformance.test.ts` and `packages/core/test/adapter-conformance-utils.ts`. Adapter-specific suites may add deeper fixture coverage, but the shared suite owns the cross-adapter defaults: local-only execution, no raw payload persistence, lifecycle identity, parentage, streaming summaries, token usage where exposed, and reader round trips.
+
+## Current matrix
+
+| Adapter | Package | Status | Default install mode | Boundary |
+| --- | --- | --- | --- | --- |
+| AI SDK | `@agent-inspect/ai-sdk` | implemented experimental; v1.8 correctness hardening pending | AI SDK telemetry integration | optional package peer dependency |
+| LangChain | `@agent-inspect/langchain` | implemented experimental | explicit callback | optional package peer dependency |
+| OpenAI Agents JS | `@agent-inspect/openai-agents` | implemented experimental; private until first publication gate | `setTraceProcessors()` replacement | optional package peer dependency |
+| LangGraph | `@agent-inspect/langchain` | fixture-backed through LangChain callback | explicit LangChain callback | existing LangChain adapter first |
+
+## Required defaults
+
+- No network behavior.
+- No default upload behavior.
+- No root/core dependency on framework SDKs.
+- Metadata-only capture by default.
+- Raw prompts, messages, outputs, tool payloads, headers, request bodies, and response bodies must not be persisted by default.
+- Framework-specific fixtures must be no-network and dependency-isolated.
+
+## Before claiming support
+
+An adapter can be documented as supported only after no-network fixtures cover run, step, tool, LLM, error, streaming, and metadata-bound expectations for that framework path.

package/docs/ADAPTERS.md

@@ -2,6 +2,57 @@
 
 AgentInspect is **framework-agnostic** at its core. Optional adapter packages integrate specific frameworks without monkey-patching, vendor sinks, or network upload.
 
+## Vercel AI SDK (`@agent-inspect/ai-sdk`)
+
+**Status:** experimental v1.7 adapter — optional package published in the v1.7.0 linked release.
+
+The v1.8 train has hardened lifecycle identity and parallel integration isolation. The adapter remains metadata-only: `capture: "preview"` and preview-only redaction options emit diagnostics and fall back to metadata-only capture until bounded free-text previews are implemented.
+
+### Install
+
+```bash
+npm install agent-inspect @agent-inspect/ai-sdk ai
+```
+
+### Local telemetry integration
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+const result = await generateText({
+  model,
+  prompt,
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: "./.agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+- **No monkey-patching** — pass the integration explicitly through AI SDK telemetry.
+- **No upload behavior** — the adapter writes only to an explicit local writer or `traceDir`.
+- **Metadata-only by default** — records model, finish reason, token usage, timing, and safe counts/summaries.
+- **Required safe telemetry settings** — set `recordInputs: false` and `recordOutputs: false` on every AI SDK call using this adapter.
+- **No raw payload capture by default** — prompts, messages, generated text, stream chunks, tool inputs/outputs, headers, request bodies, and response bodies are not persisted.
+- **Preview capture is not enabled yet** — `capture: "preview"`, `redactionProfile`, and `maxPreviewChars` are diagnosed through `getDiagnostics()` and do not persist raw previews.
+
+### Local no-network recipe
+
+[examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/) uses AI SDK test utilities only (`MockLanguageModelV3`, `simulateReadableStream`) and writes local v0.2 adapter events for `agent-inspect open`.
+
+Full API: [API.md](./API.md) §11.
+
+---
+
 ## LangChain.js (`@agent-inspect/langchain`)
 
 **Status:** experimental — programmatic API may evolve independently of stable core tracing.
@@ -64,6 +115,16 @@ npx agent-inspect export <run-id> --format markdown --redaction-profile share
 
 Written events use `schemaVersion: "0.1"` manual trace names.
 
+### LangGraph through LangChain callbacks
+
+LangGraph-shaped callback metadata is covered through the existing `@agent-inspect/langchain` callback boundary. No separate `@agent-inspect/langgraph` package is shipped.
+
+- **Explicit callback only** — pass `new AgentInspectCallback(...)` through LangChain/LangGraph callback configuration.
+- **Bounded graph metadata** — known graph, node, subgraph, task, branch, checkpoint, retry, handoff, thread, and session identifiers are copied into `attributes.langGraph` when present.
+- **No full graph state** — checkpoint/task/branch containers are summarized by type/count; raw graph state, prompts, tool payloads, outputs, and stream tokens are not stored in `metadata-only` mode.
+- **Conservative parent mapping** — in-memory events preserve framework `parentRunId`; persisted JSONL maps parents only when the parent callback was seen, and marks unresolved parent mappings in step metadata.
+- **No hosted tracing requirement** — fixtures use structural no-network callback payloads and do not require LangSmith, provider calls, or LangGraph platform services.
+
 ### Capture modes
 
 | `capture` | Behavior |
@@ -114,6 +175,14 @@ Full API: [API.md](./API.md) §9.
 
 [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 
+### LangGraph boundary
+
+LangGraph support is expected to ride through this same `@agent-inspect/langchain` callback boundary first. v1.8 adds executable no-network fixtures before claiming broader LangGraph support. A dedicated LangGraph package remains deferred until fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.
+
+Future LangGraph examples must keep the same safety defaults: explicit callback installation, metadata-only capture, no raw prompt/output/tool payload capture by default, no hosted sink, and local persistence only when `persist: true` is set.
+
+Decision note: [LANGGRAPH-ADAPTER-BOUNDARY.md](./proposals/LANGGRAPH-ADAPTER-BOUNDARY.md).
+
 ---
 
 ## TUI (`@agent-inspect/tui`)
@@ -131,11 +200,134 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ---
 
+## Vitest (`@agent-inspect/vitest`)
+
+**Status:** experimental v1.8 reporter — optional workspace package, private/unpublished until release readiness.
+
+```bash
+npm install agent-inspect @agent-inspect/vitest vitest
+```
+
+After publication, the reporter creates safe, structural artifacts for failed tests that explicitly attach AgentInspect trace metadata. It never guesses trace files by timestamp and does not read trace contents into artifacts.
+
+```ts
+import { createAgentInspectVitestReporter } from "@agent-inspect/vitest";
+
+export default {
+  test: {
+    reporters: [
+      "default",
+      createAgentInspectVitestReporter({
+        artifactDir: ".agent-inspect/vitest-artifacts",
+        retainSuccessful: 5,
+      }),
+    ],
+  },
+};
+```
+
+Attach explicit metadata from the test harness, or provide `resolveTrace(test)`:
+
+```ts
+test("agent workflow", async (ctx) => {
+  ctx.task.meta.agentInspect = {
+    runId: "support-agent",
+    tracePath: ".agent-inspect/support-agent.jsonl",
+    artifactLabel: "support-agent",
+  };
+});
+```
+
+- **Explicit association only** — no timestamp matching or directory guessing.
+- **Failure artifacts by default** — passing-test artifacts are kept only when `retainSuccessful` is configured.
+- **Bounded success retention** — successful artifacts are capped by `maxSuccessfulTraces`.
+- **Failure-preserving** — reporter/artifact errors are surfaced through diagnostics and do not replace original Vitest failures.
+- **Local-only** — no network I/O, no hosted upload, no GitHub API, and no root/core Vitest dependency.
+- **Safe rendering** — artifacts include structural test/run/file references only, not raw trace contents, prompts, outputs, request/response bodies, headers, API keys, secrets, or tool payloads.
+
+Full API: [API.md](./API.md) §12.
+
+---
+
+## Jest (`@agent-inspect/jest`)
+
+**Status:** experimental v1.8 reporter — optional workspace package, private/unpublished until release readiness.
+
+```bash
+npm install agent-inspect @agent-inspect/jest jest
+```
+
+After publication, the reporter creates safe, structural artifacts for failed Jest assertions that explicitly attach AgentInspect trace metadata through a map or resolver. It never guesses trace files by timestamp and does not read trace contents into artifacts.
+
+```js
+module.exports = {
+  reporters: [
+    "default",
+    [
+      "@agent-inspect/jest",
+      {
+        artifactDir: ".agent-inspect/jest-artifacts",
+        retainSuccessful: 5,
+        associations: {
+          "agent.test.cjs::agent suite agent workflow": {
+            runId: "support-agent",
+            tracePath: ".agent-inspect/support-agent.jsonl",
+          },
+        },
+      },
+    ],
+  ],
+};
+```
+
+- **Explicit association only** — use `associations` or `resolveTrace(test)`; no timestamp matching or directory guessing.
+- **Jest lifecycle** — processes assertion results from `onTestResult` and aggregated file results from `onRunComplete`.
+- **Failure artifacts by default** — passing-test artifacts are kept only when `retainSuccessful` is configured.
+- **Bounded success retention** — successful artifacts are capped by `maxSuccessfulTraces`.
+- **Failure-preserving** — reporter/artifact errors are surfaced through diagnostics and do not replace original Jest failures.
+- **Local-only** — no network I/O, no hosted upload, no GitHub API, and no root/core Jest dependency.
+- **Safe rendering** — artifacts include structural test/run/file references only, not raw trace contents, prompts, outputs, request/response bodies, headers, API keys, secrets, or tool payloads.
+
+Full API: [API.md](./API.md) §13.
+
+---
+
+## OpenAI Agents JS (`@agent-inspect/openai-agents`)
+
+**Status:** experimental v1.8 adapter — optional workspace package remains private/unpublished until the manual first-publication gate.
+
+The safe integration boundary is documented in [OPENAI-AGENTS-JS-TRACING.md](./proposals/OPENAI-AGENTS-JS-TRACING.md). Install the AgentInspect processor by replacing processors:
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspectProcessor({
+    traceDir: "./.agent-inspect",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The processor does not auto-install itself, does not upload, and does not add OpenAI Agents dependencies to root/core.
+
+- **No auto-install** — importing or constructing `agentInspectProcessor()` never calls `setTraceProcessors()` or `addTraceProcessor()`.
+- **No upload behavior** — the processor writes only to an explicit local writer or `traceDir`.
+- **Metadata-only by default** — records trace/span IDs, parentage, names, timing, status, errors, safe model/tool names, token counts, and bounded summaries.
+- **No raw payload capture by default** — prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, and hosted tool payloads are not persisted.
+- **Preview capture is not enabled yet** — `capture: "preview"`, `redactionProfile`, and `maxPreviewChars` are diagnosed through `getDiagnostics()` and do not persist raw previews.
+
+Full API: [API.md](./API.md) §14.
+
+Runnable local recipe: [openai-agents-local-tracing](../examples/recipes/openai-agents-local-tracing).
+
+---
+
 ## Future adapters (not shipped)
 
 Direction only — see [ROADMAP.md](../ROADMAP.md):
 
-- **Vercel AI SDK** — optional callback-style adapter (metadata-first, no vendor sink)
 - **NestJS / logging bridges** — deeper recipes or helper patterns beyond [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
 
 No automatic universal instrumentation. Integrations remain explicit and opt-in.
@@ -145,5 +337,6 @@ No automatic universal instrumentation. Integrations remain explicit and opt-in.
 ## Related docs
 
 - [API.md](./API.md) — adapter options and stability policy
+- [ADAPTER-CONFORMANCE.md](./ADAPTER-CONFORMANCE.md) — no-network fixture matrix and shared expectations
 - [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) — review exports before sharing
 - [LIMITATIONS.md](./LIMITATIONS.md) — LangChain streaming and metadata boundaries

package/docs/API.md

@@ -150,7 +150,148 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 - `runTraceViewer`, `loadTraceForTui`, `buildTuiTraceModel`, etc.
 
-## 11. Experimental persisted-event foundation (v1.2.0)
+## 11. Experimental `@agent-inspect/ai-sdk` APIs
+
+`@agent-inspect/ai-sdk` is an optional v1.7 adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental and published as part of the v1.7.0 linked release.
+
+Import from `@agent-inspect/ai-sdk`:
+
+```ts
+import { agentInspect } from "@agent-inspect/ai-sdk";
+```
+
+- **`agentInspect(options?)`**: returns an AI SDK `TelemetryIntegration` bound with `bindTelemetryIntegration()`.
+  - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
+  - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
+  - **`runName`**: optional local run name.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"`; `preview` currently emits a diagnostic and falls back to metadata-only.
+  - **`redactionProfile`** and **`maxPreviewChars`**: preview-only knobs; when preview capture is unsupported or not selected, they emit diagnostics instead of silently doing nothing.
+  - **`getDiagnostics()`**: exposes isolated adapter write, lifecycle/configuration, flush, and close failures without throwing into AI SDK callbacks.
+  - **`getWriterStats()`**, **`flush()`**, and **`close()`**: explicit writer lifecycle helpers. Failures are captured in diagnostics.
+
+Every AI SDK call using the adapter must keep telemetry local and metadata-only:
+
+```ts
+experimental_telemetry: {
+  isEnabled: true,
+  recordInputs: false,
+  recordOutputs: false,
+  integrations: [agentInspect({ traceDir: "./.agent-inspect" })],
+}
+```
+
+The adapter records local v0.2 persisted events for run, LLM step, and tool lifecycle metadata. It does not persist raw prompts, messages, generated text, stream chunks, tool inputs, tool outputs, headers, request bodies, response bodies, or user `experimental_context`. Unsupported preview capture options are explicit diagnostics and keep this metadata-only behavior.
+
+No network writer, OpenTelemetry exporter, provider wrapper, or global monkey-patch is part of this package.
+
+Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-local-telemetry/).
+
+## 12. Experimental `@agent-inspect/vitest` APIs
+
+`@agent-inspect/vitest` is an optional experimental package for local Vitest failure artifacts. In the v1.8 train it remains private/unpublished until release readiness. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+
+Import from `@agent-inspect/vitest`:
+
+```ts
+import { createAgentInspectVitestReporter } from "@agent-inspect/vitest";
+```
+
+- **`createAgentInspectVitestReporter(options?)`**: returns a structural Vitest reporter facade with `onTestCaseResult`, `onTaskUpdate`, and `onFinished` hooks.
+  - **`artifactDir`**: local output directory for safe artifacts; defaults to `.agent-inspect/vitest-artifacts`.
+  - **`githubSummary`**: optional GitHub step-summary file path. The reporter appends bounded structural counts only and does not use the GitHub API.
+  - **`retainSuccessful`**: `false`/undefined keeps no passing-test artifacts; `true` keeps up to `maxSuccessfulTraces`; a number keeps up to that many passing-test artifacts.
+  - **`maxSuccessfulTraces`**: upper bound for passing-test artifacts, capped by the reporter.
+  - **`resolveTrace(test)`**: optional explicit association resolver when task metadata is not convenient.
+  - **`onDiagnostic(diagnostic)`**: observes non-fatal reporter/artifact failures.
+  - **`getDiagnostics()`** and **`getArtifacts()`** expose reporter state for tests and custom harnesses.
+- **`agentInspectVitestReporter`**: alias for `createAgentInspectVitestReporter`.
+
+Trace association must be explicit. The default resolver reads `meta.agentInspect`, `meta["agent-inspect"]`, `meta.trace`, `context.meta.agentInspect`, or result metadata when present:
+
+```ts
+ctx.task.meta.agentInspect = {
+  runId: "support-agent",
+  tracePath: ".agent-inspect/support-agent.jsonl",
+  artifactLabel: "support-agent",
+};
+```
+
+Artifacts are safe structural summaries. They include bounded test identity, status, trace run id, and trace filename, but they do not read or embed raw trace contents, prompts, generated outputs, request/response bodies, headers, API keys, secrets, or tool payloads. Reporter/artifact failures are diagnostics and do not replace original Vitest failures.
+
+## 13. Experimental `@agent-inspect/jest` APIs
+
+`@agent-inspect/jest` is an optional experimental package for local Jest failure artifacts. In the v1.8 train it remains private/unpublished until release readiness. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+
+Import from `@agent-inspect/jest`:
+
+```ts
+import { AgentInspectJestReporter, createAgentInspectJestReporter } from "@agent-inspect/jest";
+```
+
+- **`AgentInspectJestReporter`**: default Jest custom reporter class for `reporters: [["@agent-inspect/jest", options]]`.
+- **`createAgentInspectJestReporter(options?)`**: returns a structural reporter facade with `onTestResult` and `onRunComplete` hooks for tests and custom harnesses.
+  - **`artifactDir`**: local output directory for safe artifacts; defaults to `.agent-inspect/jest-artifacts`.
+  - **`githubSummary`**: optional GitHub step-summary file path. The reporter appends bounded structural counts only and does not use the GitHub API.
+  - **`retainSuccessful`**: `false`/undefined keeps no passing-test artifacts; `true` keeps up to `maxSuccessfulTraces`; a number keeps up to that many passing-test artifacts.
+  - **`maxSuccessfulTraces`**: upper bound for passing-test artifacts, capped by the reporter.
+  - **`associations`**: explicit trace associations keyed by `file::fullName`, `basename::fullName`, or `fullName`.
+  - **`resolveTrace(test)`**: optional explicit association resolver for normalized Jest assertion results.
+  - **`onDiagnostic(diagnostic)`**: observes non-fatal reporter/artifact failures.
+  - **`getDiagnostics()`** and **`getArtifacts()`** expose reporter state for tests and custom harnesses.
+- **`agentInspectJestReporter`**: alias for `createAgentInspectJestReporter`.
+
+Jest association is explicit because Jest assertion results do not expose Vitest-style mutable task metadata:
+
+```js
+reporters: [
+  [
+    "@agent-inspect/jest",
+    {
+      associations: {
+        "agent.test.cjs::agent suite agent workflow": {
+          runId: "support-agent",
+          tracePath: ".agent-inspect/support-agent.jsonl",
+        },
+      },
+    },
+  ],
+],
+```
+
+Artifacts are safe structural summaries. They include bounded test identity, status, trace run id, and trace filename, but they do not read or embed raw trace contents, prompts, generated outputs, request/response bodies, headers, API keys, secrets, or tool payloads. Reporter/artifact failures are diagnostics and do not replace original Jest failures.
+
+## 14. Experimental `@agent-inspect/openai-agents` APIs
+
+`@agent-inspect/openai-agents` is an optional experimental package for OpenAI Agents JS tracing processor integration. In the v1.8 train it remains private/unpublished until the manual first-publication gate, but runtime metadata mapping is implemented locally.
+
+Import from `@agent-inspect/openai-agents`:
+
+```ts
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+```
+
+- **`agentInspectProcessor(options?)`**: returns a local-only OpenAI Agents `TracingProcessor`.
+  - **`installMode`**: always `"setTraceProcessors"` to document the safe replacement install path.
+  - **`localOnly`**: always `true`; the processor performs no network I/O and does not install itself globally.
+  - **`writer`**: optional explicit local `TraceWriter` for tests, recipes, and controlled runtime integration.
+  - **`traceDir`**: optional local directory that creates a file writer inside the adapter package.
+  - **`workflowName`**: optional local run name overriding the SDK trace name.
+  - **`capture`**: `"metadata-only"` (default) or `"preview"`; `preview` currently emits a diagnostic and falls back to metadata-only.
+  - **`redactionProfile`** and **`maxPreviewChars`**: preview-only knobs; when preview capture is unsupported or not selected, they emit diagnostics instead of silently doing nothing.
+  - **`getDiagnostics()`**: exposes isolated processor write, lifecycle/configuration, flush, and shutdown failures without throwing into OpenAI Agents callbacks.
+  - **`getWriterStats()`**, **`forceFlush()`**, and **`shutdown()`**: explicit writer lifecycle helpers. Failures are captured in diagnostics.
+
+Safe future usage must replace processors explicitly:
+
+```ts
+setTraceProcessors([agentInspectProcessor({ traceDir: "./.agent-inspect" })]);
+```
+
+Do not use `addTraceProcessor()` as the default AgentInspect path; that leaves existing/default processors in place and can preserve backend export behavior in server runtimes.
+
+The processor records local v0.2 persisted events for trace/run, agent, generation/response, function/tool, handoff, guardrail, MCP tools, custom, transcription, and speech span metadata where safely representable. It does not persist raw prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, or hosted tool payloads by default.
+
+## 15. Experimental persisted-event foundation (v1.2.0)
 
 These helpers expose the **source-agnostic `PersistedInspectEvent` model** (`schemaVersion: "0.2"`). They are **local-only**, **in-memory**, and **do not change** storage write/read or CLI behavior in v1.2.0.
 
@@ -176,7 +317,7 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 - v0.2 is **not written by default**; use converters and `fixtures/traces-v0.2/` samples for validation.
 - Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. v0.2 remains experimental as a persisted-event foundation and is not the default writer.
 
-## 12. Local observability helpers (v1.4.0+)
+## 16. Local observability helpers (v1.4.0+)
 
 Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1 manual traces remain the default writer; v0.2 persisted-event files are accepted where the shared dual-format read path is used. Local files only.
 
@@ -186,7 +327,7 @@ Read-only helpers for timeline, stats, and search over local JSONL traces. v0.1
 
 CLI wrappers: `agent-inspect timeline`, `stats`, `search` — see [CLI.md](./CLI.md).
 
-## 13. Report and what helpers (v1.5.0+)
+## 17. Report and what helpers (v1.5.0+)
 
 Read-only helpers for concise inspection summaries and local reports:
 
@@ -195,7 +336,7 @@ Read-only helpers for concise inspection summaries and local reports:
 
 Report redaction profiles are key-based safeguards applied to the complete rendered report input, not only to the tree section. Review generated reports before sharing; this is not compliance-grade DLP.
 
-## 14. Experimental trace writers (v1.6)
+## 18. Experimental trace writers (v1.6)
 
 Trace writers are the first slice of the v1.6 runtime foundation. They are experimental during v1.x and intended for tests, adapters, and future `createInspector` work.
 
@@ -227,7 +368,7 @@ import type {
 
 No network writer or vendor sink exists in this package.
 
-## 15. Experimental inspector API/runtime (v1.6)
+## 19. Experimental inspector API/runtime (v1.6)
 
 `createInspector()` is the experimental public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records v0.2 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
 
@@ -269,7 +410,7 @@ Public methods:
 
 These APIs are experimental during v1.x. They do not add a default network writer or vendor sink.
 
-## 16. Experimental trace readers (v1.6)
+## 20. Experimental trace readers (v1.6)
 
 `agent-inspect/readers` exposes the experimental local trace reader contract and detection pipeline. It includes AgentInspect JSONL for v0.1, v0.2, and mixed local trace files, plus local OpenInference JSON and OTLP JSON compatibility readers.
 
@@ -300,23 +441,43 @@ import type { TraceReader } from "agent-inspect/readers";
 
 The reader contract does not silently accept arbitrary JSON and does not add OTel SDK, database, hosted ingestion, or network upload dependencies.
 
-## 17. Deprecated APIs
+## 21. Experimental Checks
+
+`agent-inspect/checks` exposes the experimental deterministic trace-check engine foundation. It consumes normalized reader output, runs supplied pure rules in stable order, and returns aggregate findings/diagnostics. It does not read files, discover config, call providers, perform network I/O, mutate inputs, or create a new persisted schema.
+
+Import from `agent-inspect/checks`:
+
+```ts
+import { runTraceChecks } from "agent-inspect/checks";
+import type { TraceCheckRule, TraceCheckResult } from "agent-inspect/checks";
+```
+
+- **`runTraceChecks({ read }, { rules?, select?, runId? })`**: executes provided rules against a `TraceReadResult` from `agent-inspect/readers`.
+- **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`.
+- **`TraceCheckRule`**: synchronous pure rule contract.
+- **`TraceCheckResult`**: deterministic aggregate result with findings, evidence, summary counts, and execution diagnostics.
+
+The checks API is experimental in v1.x. The `agent-inspect check` CLI uses this API for local reader-backed checks and deterministic JSON output; `agent-inspect artifacts` reuses the same safe findings for local CI artifact bundles and optional step-summary file output. Built-in rules operate on normalized event metadata, tree relationships, bounded summaries, token counts, and normalized baseline facts; safety and baseline findings identify event IDs and field paths rather than emitting raw prompts, outputs, secrets, headers, request/response bodies, or full tool payloads.
+
+Recipes: [deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for check/baseline/artifact workflows, and [test-reporter-artifacts](../examples/recipes/test-reporter-artifacts/README.md) for Vitest/Jest reporter configuration patterns.
+
+## 22. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 18. Removal / deprecation policy
+## 23. Removal / deprecation policy
 
 - Stable APIs are not removed in v1.x.
 - If removal is necessary, the API should be **deprecated** first, documented, and kept for a reasonable window (target: at least one minor line) unless security requires faster action.
 
-## 19. Backward compatibility policy
+## 24. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.
 - Breaking changes require a major version.
 - Unknown fields should be ignored where safe.
 
-## 20. Examples
+## 25. Examples
 
 ### Minimal manual trace