agent-inspect 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,10 +1,30 @@
 # Changelog
 
+## 1.9.0
+
+### Minor Changes
+
+- 309350e: Release v1.9.0 adoption leverage with the private harness workspace, explain dry-run/local analysis, promoted adapter adoption paths, and the v2 root API slimming plan.
+
+## 1.8.0
+
+Released **2026-06-27**.
+
+### 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, adapter conformance coverage, and local-first adapter documentation.
+- 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
 

package/README.md

@@ -1,12 +1,12 @@
 # agent-inspect
 
-**Local execution trees for TypeScript AI agents.**
+**Trace, check, and safely share TypeScript AI agent runs locally.**
 
-agent-inspect helps you understand what happened inside an AI agent run — **locally**. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into **readable execution trees** you can inspect from the terminal.
+agent-inspect helps you understand what happened inside an AI agent run without sending traces to a hosted service. It turns framework events, observed objects/classes, manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into readable local execution trees.
 
 It is built for TypeScript/Node.js developers and teams shipping real agentic products — not just toy demos. Use it for **local TypeScript agent debugging**, **eval iteration**, and **CI trace artifacts**. It **complements** production observability platforms; it does **not** replace them.
 
-The tool starts with **manual traces** and **existing structured logs**, and extends into **optional framework callbacks** and **standards-aligned local export** — without turning the core into a SaaS or a vendor pipeline.
+The default loop is local-first: capture a trace, inspect/report/diff it, run deterministic checks in CI, then export a redacted copy only when you choose to share.
 
 **No account. No cloud upload. No dashboard required.**
 
@@ -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.8.0** (`agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, `@agent-inspect/openai-agents` — all aligned).
 
 ```bash
 npm install agent-inspect
@@ -40,10 +40,110 @@ npx agent-inspect --help
 
 For a clean npm/pnpm install checklist with ESM, CJS, and CLI checks, see [Clean install smoke test](docs/INSTALL-SMOKE-TEST.md).
 
-## 60-second quickstart
+## Three adoption paths
+
+Already using AI SDK, OpenAI Agents JS, LangChain, or LangGraph-through-LangChain? Start with **Path B** for framework-native local traces before adding manual instrumentation.
+
+### Path A — Observe an existing object/class
+
+Use `observe()` when you already have an agent-like object with a `run`, `execute`, or `invoke` method.
 
 Create `demo.mjs`:
 
+```js
+import { observe } from "agent-inspect";
+
+class SupportAgent {
+  async run(input) {
+    return {
+      answer: `Answering: ${input.question}`,
+    };
+  }
+}
+
+const agent = observe(new SupportAgent(), {
+  traceDir: "./.agent-inspect",
+});
+
+await agent.run({
+  question: "How do refunds work?",
+});
+```
+
+Run it, then inspect the trace:
+
+```bash
+node demo.mjs
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+```
+
+### Path B — Use a framework adapter
+
+Optional adapters keep framework dependencies out of the root package and write local traces only when configured.
+
+AI SDK local telemetry:
+
+```ts
+import { generateText } from "ai";
+import { agentInspect } from "@agent-inspect/ai-sdk";
+
+await generateText({
+  model,
+  prompt,
+  experimental_telemetry: {
+    isEnabled: true,
+    recordInputs: false,
+    recordOutputs: false,
+    integrations: [
+      agentInspect({
+        traceDir: "./.agent-inspect",
+        runName: "support-agent",
+        capture: "metadata-only",
+      }),
+    ],
+  },
+});
+```
+
+OpenAI Agents local-only processor:
+
+```ts
+import { setTraceProcessors } from "@openai/agents";
+import { agentInspectProcessor } from "@agent-inspect/openai-agents";
+
+setTraceProcessors([
+  agentInspectProcessor({
+    traceDir: "./.agent-inspect",
+    workflowName: "support-agent",
+    capture: "metadata-only",
+  }),
+]);
+```
+
+LangChain callback adapter:
+
+```ts
+import { AgentInspectCallback } from "@agent-inspect/langchain";
+
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
+  capture: "metadata-only",
+});
+
+await agent.invoke(input, { callbacks: [callback] });
+```
+
+See [docs/ADAPTERS.md](docs/ADAPTERS.md).
+
+No-network recipes: [ai-sdk-local-telemetry](examples/recipes/ai-sdk-local-telemetry/), [openai-agents-local-tracing](examples/recipes/openai-agents-local-tracing/), and [langgraph-callback-local](examples/recipes/langgraph-callback-local/).
+
+### Path C — Manually instrument custom flows
+
+Use `inspectRun` and `step` when you want explicit names, custom nesting, or flows that are not object/class shaped.
+
 ```js
 import { inspectRun, step } from "agent-inspect";
 
@@ -71,15 +171,6 @@ await inspectRun(
 );
 ```
 
-Run it, then inspect the trace:
-
-```bash
-node demo.mjs
-npx agent-inspect list --dir ./.agent-inspect
-npx agent-inspect view <run-id> --dir ./.agent-inspect
-npx agent-inspect view <run-id> --dir ./.agent-inspect --summary
-```
-
 Full flow:
 
 ```bash
@@ -99,6 +190,31 @@ support-agent
 
 A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
+Use the root import for stable beginner APIs:
+
+```ts
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+Use subpaths for advanced, experimental, or lower-level workflows:
+
+```ts
+import { openTrace } from "agent-inspect/readers";
+import { memoryWriter } from "agent-inspect/writers";
+import { runTraceChecks } from "agent-inspect/checks";
+import { diffTraceEvents } from "agent-inspect/diff";
+import { exportMarkdown } from "agent-inspect/exporters";
+import { parseLogsToTrees } from "agent-inspect/logs";
+import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
+import { createInspector } from "agent-inspect/advanced";
+```
+
 **Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
 
 ```ts
@@ -111,7 +227,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.8.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,9 +237,11 @@ 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 OpenAI Agents adapter** — experimental `@agent-inspect/openai-agents` trace processor for local OpenAI Agents JS trace processing.
 - **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.
+- **Experimental subpaths** — `agent-inspect/readers`, `/writers`, `/checks`, `/diff`, `/exporters`, `/logs`, `/persisted`, and `/advanced` for advanced local workflows.
 
 Nothing uploads traces by default. Review exports before sharing — see [safe trace sharing](docs/SAFE-TRACE-SHARING.md).
 
@@ -135,7 +253,7 @@ Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_star
 
 *Synthetic demo — [examples/02-nested-steps](examples/02-nested-steps/README.md). More visuals: [SCREENSHOTS.md](docs/SCREENSHOTS.md).*
 
-## Works with structured logs you already have
+## Advanced ingestion: use this when your app already emits structured logs
 
 Many production systems already emit **line-delimited JSON** or text logs with embedded JSON (e.g. via **pino**, **winston**, **log4js**, **NestJS** loggers, job runners, or custom event streams). agent-inspect can turn those into **local grouped timelines/trees** without wrapping every function.
 
@@ -180,6 +298,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 +318,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.8.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,13 +328,15 @@ 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.8.0:** experimental deterministic checks (`agent-inspect/checks` and `agent-inspect check`), safe-sharing workflows (`scan`, `verify-safe`, safe artifacts), and first public `@agent-inspect/openai-agents` package. Linked release aligns `agent-inspect`, `@agent-inspect/ai-sdk`, `@agent-inspect/langchain`, `@agent-inspect/tui`, and `@agent-inspect/openai-agents` at **1.8.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**.
 
-**In progress for 1.7.0 on main:** 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/). Examples keep `recordInputs: false`, `recordOutputs: false`, metadata-only capture, and no upload behavior.
+**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**.
 
@@ -291,6 +413,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

@@ -12,14 +12,18 @@ The machine-readable matrix lives at [docs/implementation/adapter-conformance-ma
 - 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 | AI SDK telemetry integration | optional package peer dependency |
+| 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` | scaffold only | `setTraceProcessors()` replacement | optional package peer dependency |
-| LangGraph | `@agent-inspect/langchain` | decision only | explicit LangChain callback | existing LangChain adapter first |
+| 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
 

package/docs/ADAPTERS.md

@@ -4,7 +4,9 @@ AgentInspect is **framework-agnostic** at its core. Optional adapter packages in
 
 ## Vercel AI SDK (`@agent-inspect/ai-sdk`)
 
-**Status:** experimental v1.7 train — optional workspace package; publication waits for v1.7 release readiness.
+**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
+
+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
 
@@ -41,11 +43,40 @@ const result = await generateText({
 - **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`.
 
+### Common host shapes
+
+Use the same explicit telemetry block for route handlers, streaming, and tool calls. The adapter does not wrap providers or change host-call settings.
+
+```ts
+const telemetry = {
+  isEnabled: true,
+  recordInputs: false,
+  recordOutputs: false,
+  integrations: [agentInspect({ traceDir: "./.agent-inspect", capture: "metadata-only" })],
+};
+
+// Next.js route or local handler
+await generateText({ model, prompt, experimental_telemetry: telemetry });
+
+// Streaming
+await streamText({ model, prompt, experimental_telemetry: telemetry });
+
+// Tool calls
+await generateText({ model, prompt, tools, experimental_telemetry: telemetry });
+```
+
+Review recipe output with:
+
+```bash
+npx agent-inspect open ./examples/recipes/ai-sdk-local-telemetry/.agent-inspect-runs
+```
+
 Full API: [API.md](./API.md) §11.
 
 ---
@@ -112,6 +143,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 |
@@ -164,10 +205,12 @@ Full API: [API.md](./API.md) §9.
 
 ### LangGraph boundary
 
-LangGraph support is expected to ride through this same `@agent-inspect/langchain` callback boundary first. A dedicated LangGraph package is deferred until no-network fixtures prove that LangGraph exposes important lifecycle data unavailable through LangChain callbacks.
+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.
 
+Runnable local recipe: [langgraph-callback-local](../examples/recipes/langgraph-callback-local).
+
 Decision note: [LANGGRAPH-ADAPTER-BOUNDARY.md](./proposals/LANGGRAPH-ADAPTER-BOUNDARY.md).
 
 ---
@@ -187,11 +230,103 @@ Requires an interactive terminal. See [API.md](./API.md) §10.
 
 ---
 
+## Vitest (`@agent-inspect/vitest`)
+
+**Status:** experimental workspace package, private/unpublished.
+
+```bash
+npm install agent-inspect @agent-inspect/vitest vitest
+```
+
+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 workspace package, private/unpublished.
+
+```bash
+npm install agent-inspect @agent-inspect/jest jest
+```
+
+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:** scaffolded for v1.7 train — optional workspace package; runtime mapping is not implemented yet.
+**Status:** experimental adapter — optional package published in the aligned v1.8.0 package set.
 
-The safe integration boundary is documented in [OPENAI-AGENTS-JS-TRACING.md](./proposals/OPENAI-AGENTS-JS-TRACING.md). Future examples must install the AgentInspect processor by replacing processors:
+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";
@@ -205,7 +340,22 @@ setTraceProcessors([
 ]);
 ```
 
-Do not use `addTraceProcessor()` as the default AgentInspect path; that preserves the OpenAI default exporter in server runtimes. The scaffold does not auto-install a processor, does not upload, and does not add OpenAI Agents dependencies to root/core.
+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.
+
+Integration modes:
+
+- **Local-only replacement:** `setTraceProcessors([agentInspectProcessor(...)])` replaces existing processors for the current process. This is the documented safe default when you want AgentInspect to own local trace output.
+- **Additional processor:** `addTraceProcessor(agentInspectProcessor(...))` is an advanced, user-owned choice. It can preserve existing/default processors and any backend export behavior they already perform.
+
+- **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).
 
 ---