agent-inspect 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,7 +1,15 @@
 # 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.

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.7.0** (`agent-inspect`, `@agent-inspect/ai-sdk`, `@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.7.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.
@@ -122,9 +238,10 @@ AGENT_INSPECT=1 node eval-runner.mjs
 - **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).
 
@@ -136,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.
 
@@ -201,7 +318,7 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.7.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)
@@ -211,6 +328,8 @@ 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.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**.
 
 **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**.

package/docs/ADAPTERS.md

@@ -4,7 +4,7 @@ AgentInspect is **framework-agnostic** at its core. Optional adapter packages in
 
 ## Vercel AI SDK (`@agent-inspect/ai-sdk`)
 
-**Status:** experimental v1.7 adapter — optional package published in the v1.7.0 linked release.
+**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.
 
@@ -49,6 +49,34 @@ const result = await generateText({
 
 [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.
 
 ---
@@ -181,6 +209,8 @@ LangGraph support is expected to ride through this same `@agent-inspect/langchai
 
 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).
 
 ---
@@ -202,13 +232,13 @@ 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.
+**Status:** experimental workspace package, private/unpublished.
 
 ```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.
+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";
@@ -251,13 +281,13 @@ Full API: [API.md](./API.md) §12.
 
 ## Jest (`@agent-inspect/jest`)
 
-**Status:** experimental v1.8 reporter — optional workspace package, private/unpublished until release readiness.
+**Status:** experimental workspace package, private/unpublished.
 
 ```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.
+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 = {
@@ -294,7 +324,7 @@ 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.
+**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). Install the AgentInspect processor by replacing processors:
 
@@ -312,6 +342,11 @@ setTraceProcessors([
 
 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.

package/docs/API.md

@@ -9,14 +9,42 @@ AgentInspect is a **local-first execution-tree debugger**. It is not a SaaS, not
 - **Stable**: intended to be compatible across v1.x. Breaking changes require v2.0.
 - **Experimental**: available for adoption, but subject to refinement (including naming/shape changes) before a future stability declaration. Experimental APIs may change in v1.x.
 
-**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
+Use the root import for stable beginner APIs. Use subpaths for advanced, experimental, or lower-level workflows.
+
+```ts
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**v1.9 root API direction:** do not add new root exports casually. Existing root imports keep working through v1.x for compatibility, but new advanced examples should use the subpath where the API lives. The intended stable root set for v2 is:
+
+```ts
+import {
+  createInspector,
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
+```
+
+**1.x subpath exports:** Additive subpaths (`/logs`, `/exporters`, `/persisted`, `/diff`, `/advanced`, `/writers`, `/readers`, `/checks`) narrow the import surface for experimental and advanced APIs. Root `"."` imports remain valid through v1.x. Design: [API-BOUNDARY-V1.5.md](./implementation/API-BOUNDARY-V1.5.md).
 
 ```ts
-import { inspectRun, step } from "agent-inspect";
 import { parseLogsToTrees } from "agent-inspect/logs";
 import { exportMarkdown } from "agent-inspect/exporters";
 import { memoryWriter } from "agent-inspect/writers";
 import { openTrace } from "agent-inspect/readers";
+import { runTraceChecks } from "agent-inspect/checks";
+import { diffTraceEvents } from "agent-inspect/diff";
+import { traceEventsToPersistedInspectEvents } from "agent-inspect/persisted";
+import { createInspector } from "agent-inspect/advanced";
 ```
 
 Notes:
@@ -24,6 +52,7 @@ Notes:
 - The core guarantee of v1.x is **stable local debugging**: manual tracing + CLI inspection.
 - Export formats (OpenInference / OTLP JSON) are **local-only** and **compatibility-oriented**. They do **not** upload anywhere.
 - There are **zero production sinks** in v1.x; sink/uploader APIs are not stable.
+- Advanced root exports in v1.x are compatibility aliases. Prefer `agent-inspect/advanced`, `agent-inspect/readers`, `agent-inspect/writers`, `agent-inspect/checks`, `agent-inspect/diff`, `agent-inspect/exporters`, `agent-inspect/logs`, and `agent-inspect/persisted` for new code.
 
 ## 2. Stable core APIs (manual tracing)
 
@@ -32,7 +61,13 @@ These are the recommended entry points for manual instrumentation. They are desi
 Import from `agent-inspect`:
 
 ```ts
-import { inspectRun, maybeInspectRun, step, observe } from "agent-inspect";
+import {
+  observe,
+  inspectRun,
+  maybeInspectRun,
+  step,
+  getCurrentCorrelationMetadata,
+} from "agent-inspect";
 ```
 
 - **`inspectRun(name, fn, options?)`**: wraps a workflow in a local JSONL trace (`run_started` / `run_completed`), prints terminal progress, and swallows instrumentation failures (user errors are re-thrown). **Traces by default** when `enabled` is omitted or `true`. Pass **`enabled: false`** to run `fn` with no trace file, no execution context, and no terminal output.
@@ -90,7 +125,7 @@ These APIs support local workflows like listing traces, extracting metadata/summ
 
 ## 5. Experimental log parsing APIs
 
-These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
+Advanced ingestion: use this when your app already emits structured logs. These are compatibility-oriented utilities for turning structured logs into normalized `InspectEvent` and grouped trees. They remain conservative: **no eval**, **no parsing JS object literals**, JSON logs first-class, log4js best-effort.
 
 - **`parseLogsToTrees`**
 - **`JsonLogParser`**, **`Log4jsParser`**
@@ -152,7 +187,7 @@ Rationale: v1.x includes one official adapter and **zero production sinks**, so
 
 ## 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.
+`@agent-inspect/ai-sdk` is an optional adapter package for Vercel AI SDK v6 telemetry integrations. It is experimental and published as part of the aligned v1.8.0 package set.
 
 Import from `@agent-inspect/ai-sdk`:
 
@@ -188,7 +223,7 @@ Recipe: [examples/recipes/ai-sdk-local-telemetry](../examples/recipes/ai-sdk-loc
 
 ## 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.
+`@agent-inspect/vitest` is an optional experimental workspace package for local Vitest failure artifacts. It remains private/unpublished. 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`:
 
@@ -220,7 +255,7 @@ Artifacts are safe structural summaries. They include bounded test identity, sta
 
 ## 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.
+`@agent-inspect/jest` is an optional experimental workspace package for local Jest failure artifacts. It remains private/unpublished. 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`:
 
@@ -262,7 +297,7 @@ Artifacts are safe structural summaries. They include bounded test identity, sta
 
 ## 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.
+`@agent-inspect/openai-agents` is an optional experimental package for OpenAI Agents JS tracing processor integration. It is public in the aligned v1.8.0 package set and records runtime metadata locally.
 
 Import from `@agent-inspect/openai-agents`:
 
@@ -295,7 +330,7 @@ The processor records local v0.2 persisted events for trace/run, agent, generati
 
 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.
 
-Import from `agent-inspect`:
+Import from `agent-inspect/persisted`:
 
 | API | Role |
 | --- | ---- |
@@ -461,16 +496,67 @@ The checks API is experimental in v1.x. The `agent-inspect check` CLI uses this
 
 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
+## 22. Experimental local explain APIs (v1.9)
+
+`buildLocalExplanation()` creates a deterministic local explanation payload from a reader-selected `InspectRunTree`. It performs no network I/O, does not call model providers, and separates observed facts from deterministic inference labels.
+
+Import from `agent-inspect`:
+
+```ts
+import { buildLocalExplanation } from "agent-inspect";
+```
+
+- **`buildLocalExplanation(run, options?)`**:
+  - **`mode: "dry-run"`**: returns redacted observed facts and no inference labels.
+  - **`mode: "local"`** (default): returns observed facts plus deterministic local inference labels.
+  - **`redactionProfile`**: `local`, `share`, or `strict`; profile keys are redacted before the payload is returned.
+
+CLI wrapper: `agent-inspect explain <trace-path-or-run-id> --dry-run --json`.
+
+Provider design gate:
+
+- No provider payload is submitted in v1.9 implementation chunks; `--provider <provider>` is reserved and rejected with `PROVIDER_NOT_IMPLEMENTED`.
+- The reviewable provider payload contract is the `ExplainResult` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider implementations must require explicit provider selection and documented environment requirements. The current local API reads no provider credentials.
+- Provider prompts must use redacted facts only, label inferred claims, and must not request raw chain-of-thought.
+- Provider packages or SDKs must not become root/core runtime dependencies.
+
+## 23. Experimental `@agent-inspect/harness` APIs
+
+`@agent-inspect/harness` is a private experimental workspace package during the v1.9 release train. It provides a no-framework fixture runner for local targets and recipes; first public package publication remains a manual maintainer gate.
+
+Import from `@agent-inspect/harness` inside the workspace:
+
+```ts
+import { createFixtureRunner, defineTarget } from "@agent-inspect/harness";
+```
+
+- **`defineTarget(definition)`**: returns a typed target definition with `resolve(app, context)` and `invoke(target, input, context)` hooks.
+- **`createFixtureRunner(options)`**: returns a local runner with:
+  - **`listTargets()`**: deterministic target metadata listing.
+  - **`runTarget(name, input, options?)`**: bootstrap, resolve, invoke, and shutdown lifecycle.
+  - **`runFromArgv(argv?, io?)`**: CLI-friendly execution with target listing, JSON fixture files, JSON stdin, JSON stdout, stderr summaries, trace flags, and expected-output comparison.
+  - **`getDiagnostics()`**: deterministic diagnostics for missing targets, bootstrap failures, resolve failures, invocation failures, and shutdown failures.
+- **`trace`** options use existing AgentInspect local APIs only:
+  - **`mode: "run-if-enabled"`** (default): uses `maybeInspectRun()` and writes no trace unless `options.enabled` or `AGENT_INSPECT` enables tracing.
+  - **`mode: "run"`**: explicitly wraps the target invocation in `inspectRun()`.
+  - **`mode: "observe"`**: proxies the resolved target with `observe()` for `run` / `execute` / `invoke` methods when enabled.
+  - **`mode: "off"`**: invokes the target without AgentInspect tracing.
+
+The harness package does not add root/core dependencies, does not upload traces, does not call providers, and does not capture raw prompts or outputs by itself. It writes only local AgentInspect traces when explicitly enabled by runner options or environment-gated tracing.
+
+Recipes: [harness-basic](../examples/recipes/harness-basic/README.md) and [harness-adapter-local](../examples/recipes/harness-adapter-local/README.md).
+
+## 24. Deprecated APIs
 
 No deprecated APIs are declared as of 1.4.0.
 
-## 23. Removal / deprecation policy
+## 25. 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.
 
-## 24. Backward compatibility policy
+## 26. Backward compatibility policy
 
 - Manual trace JSONL (`schemaVersion: "0.1"`) remains readable.
 - Additive schema changes are allowed in minor versions.

package/docs/CLI.md

@@ -36,6 +36,7 @@ Core commands:
 - `search` — deterministic local search over traces
 - `what` — concise summary of a single run (local JSONL)
 - `report` — markdown or HTML inspection report for a single run
+- `explain` — deterministic local facts/inferences for a trace, with dry-run payloads
 
 ## 2. Environment variables
 
@@ -138,7 +139,7 @@ Recommendation: run with `--dry-run` first.
 
 ### 6.4 `logs`
 
-Parse structured logs into local execution trees.
+Advanced ingestion: use this when your app already emits structured logs. Parse those logs into local execution trees.
 
 ```bash
 agent-inspect logs <file> [options]
@@ -554,6 +555,39 @@ Example:
 npx agent-inspect report minimal-success --dir fixtures/traces --format html -o report.html
 ```
 
+### 6.17 `explain`
+
+Explain a local trace using deterministic facts and local inference labels. This command reads through the same local reader pipeline as `open` / `check`; it does not call a model provider, upload traces, replay agents, or mutate input files.
+
+```bash
+agent-inspect explain <trace-path-or-run-id> [options]
+```
+
+Options:
+
+- `--dir <path>` — trace directory for run-id lookup
+- `--format <agent-inspect-jsonl|openinference-json|otlp-json>` — explicit input format
+- `--run <run-id>` — select a run when the trace contains multiple runs
+- `--dry-run` — emit only the redacted facts payload, with no local inference labels
+- `--provider <provider>` — reserved for an explicit future provider mode; currently rejected without network calls
+- `--json` — print deterministic JSON output
+- `--redaction-profile <local|share|strict>` — key-based redaction profile for the explanation payload (default `local`)
+
+Examples:
+
+```bash
+npx agent-inspect explain minimal-success --dir fixtures/traces
+npx agent-inspect explain fixtures/traces/minimal-success.jsonl --dry-run --json --redaction-profile strict
+```
+
+Provider design gate:
+
+- Current behavior is local only. `--provider <provider>` exits with a user-facing `PROVIDER_NOT_IMPLEMENTED` error and performs no provider call.
+- `--dry-run --json` is the payload review surface. The provider payload contract is the returned `explanation` object: `mode`, `runId`, optional `name` / `status`, `redactionProfile`, `facts`, `inferences`, and `notes`.
+- Provider chunks must require explicit provider selection, document required environment variables, and keep credentials out of trace data and dry-run output.
+- Provider prompts must ask for concise explanations from redacted facts only. They must not request, expose, or preserve raw chain-of-thought.
+- Cloud provider behavior is never selected by default and must be reviewed before implementation. Local provider support must still be explicit and opt-in.
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.