agent-inspect 1.7.0 → 1.9.0

package/docs/GETTING-STARTED.md

@@ -25,7 +25,36 @@ pnpm build
 node packages/cli/dist/index.cjs --help
 ```
 
-## 2. Basic manual trace
+## 2. Observe an existing object/class first
+
+```ts
+import { observe } from "agent-inspect";
+
+class SupportAgent {
+  async run(input: { question: string }) {
+    return {
+      answer: `Answering: ${input.question}`,
+    };
+  }
+}
+
+const agent = observe(new SupportAgent(), {
+  traceDir: "./.agent-inspect",
+});
+
+await agent.run({
+  question: "How do refunds work?",
+});
+```
+
+This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`) when the observed `run` method is called:
+
+- `run_started`, `run_completed`
+- `step_started`, `step_completed`
+
+## 3. Manually instrument custom flows
+
+Use `inspectRun` and `step` when you want explicit step names, custom nesting, or a flow that is not shaped like an object/class method.
 
 ```ts
 import { inspectRun, step } from "agent-inspect";
@@ -37,10 +66,30 @@ await inspectRun("demo-agent", async () => {
 });
 ```
 
-This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`):
+Use the root import for stable beginner APIs:
 
-- `run_started`, `run_completed`
-- `step_started`, `step_completed`
+```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";
+```
 
 ### Always trace vs env-gated tracing
 
@@ -90,14 +139,14 @@ If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common in
 
 To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
 
-## 3. View runs
+## 4. View runs
 
 ```bash
 agent-inspect list
 agent-inspect view <runId>
 ```
 
-## 4. Clean old runs (safely)
+## 5. Clean old runs (safely)
 
 Always start with `--dry-run`:
 
@@ -106,7 +155,7 @@ agent-inspect clean --older-than 7d --dry-run
 agent-inspect clean --older-than 7d --yes
 ```
 
-## 5. Parse existing logs
+## 6. Advanced ingestion: parse existing structured logs
 
 ```bash
 agent-inspect logs fixtures/logs/proactive-json.log \
@@ -114,7 +163,7 @@ agent-inspect logs fixtures/logs/proactive-json.log \
   --config fixtures/configs/proactive-agent-inspect.logs.json
 ```
 
-## 6. Tail logs
+## 7. Tail logs
 
 For scripting/CI-style usage, `--once` reads and exits:
 
@@ -126,7 +175,7 @@ agent-inspect tail \
   --once
 ```
 
-## 7. Export a run
+## 8. Export a run
 
 ```bash
 agent-inspect export minimal-success --dir fixtures/traces --format markdown
@@ -142,7 +191,7 @@ agent-inspect export minimal-success --dir fixtures/traces \
 
 Exports are **local-only** and do not upload anywhere. Review output before sharing — see [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
-## 8. Local observability (v1.4.0+)
+## 9. Local observability (v1.4.0+)
 
 After traces exist under a directory:
 
@@ -154,17 +203,21 @@ agent-inspect search --dir ./.agent-inspect --status error --limit 10
 
 For CI artifact workflows, see [CI-ARTIFACTS.md](./CI-ARTIFACTS.md) and [github-actions-artifact recipe](../examples/recipes/github-actions-artifact/).
 
-## 9. Diff two runs
+## 10. Diff two runs
 
 ```bash
 agent-inspect diff minimal-success minimal-error --dir fixtures/traces
 ```
 
-## 9. Try recipes
+## 11. Try recipes
 
 See `examples/recipes/README.md`.
 
-## 10. Optional LangChain adapter
+## 12. Optional framework adapters
+
+See [ADAPTERS.md](./ADAPTERS.md) for AI SDK local telemetry, OpenAI Agents local-only processing, and LangChain callbacks.
+
+### LangChain
 
 `@agent-inspect/langchain` is optional and **experimental**. Events are **in-memory by default**; pass `persist: true` to write local JSONL traces inspectable by the CLI.
 
@@ -174,7 +227,7 @@ pnpm add @agent-inspect/langchain
 
 See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](./ADAPTERS.md).
 
-## 11. Optional TUI
+## 13. Optional TUI
 
 `@agent-inspect/tui` is optional and **experimental**. The CLI can invoke it with:
 
@@ -182,14 +235,16 @@ See [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md)
 agent-inspect view <runId> --tui
 ```
 
-## 12. Safety notes
+## 14. Safety notes
 
+- Nothing uploads by default; core tracing, readers, checks, and exports are local-first.
 - Redaction is on by default for log-derived attributes, **manual trace metadata (before disk)**, and exports. Pass `redact: false` to opt out of manual metadata redaction.
+- Export redaction shapes a local copy and does not mutate the source trace; review exported files before sharing.
 - Persisted events are size-bounded by default (see `docs/API.md`).
 - Confidence labels are required to keep attribution honest.
 - AgentInspect is for local debugging, not production monitoring.
 
-## 13. Next docs
+## 15. Next docs
 
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)

package/docs/KNOWN-ISSUES.md

@@ -23,7 +23,7 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
 - **AI SDK adapter** (`@agent-inspect/ai-sdk`) is experimental and metadata-first. It depends on explicit AI SDK telemetry configuration and requires `recordInputs: false` / `recordOutputs: false` for the documented safe path.
-- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is scaffold-only in the v1.7 train. Runtime span mapping is not implemented, and the safe future path is `setTraceProcessors()` rather than `addTraceProcessor()`.
+- **OpenAI Agents JS adapter** (`@agent-inspect/openai-agents`) is experimental and remains private/unpublished until the v1.8 first-publication gate. Runtime metadata mapping is local-only; the safe install path is `setTraceProcessors()` rather than `addTraceProcessor()`.
 - **LangGraph support** is currently a documented boundary through `@agent-inspect/langchain`, not a dedicated package.
 - **LangChain adapter** captures **metadata-oriented** signals by default; it does not replace full framework observability.
 - **LangChain `stream: true`** records chunk counts and timing only — not a full token replay. Per-token JSONL events are not emitted.
@@ -93,6 +93,12 @@ pnpm compat:smoke
 - Fixture pattern: [test/consumer-fixtures/jest-cjs/](../../test/consumer-fixtures/jest-cjs/).
 - Full Jest runner smoke in CI is a documented follow-up — root package does not ship Jest as a devDependency.
 
+## v1.8 pre-release adoption notes
+
+- `@agent-inspect/vitest` and `@agent-inspect/jest` are private/unpublished until the v1.8 release-readiness gate completes. The [test reporter artifact recipe](../examples/recipes/test-reporter-artifacts/README.md) documents the intended config shape without requiring those packages.
+- `agent-inspect artifacts --github-summary` writes a local step-summary file only. It does not call GitHub APIs, open PR comments, upload artifacts, or mutate repository state.
+- Baseline checks compare normalized structural facts from explicit candidate and baseline inputs. They are useful for CI regression evidence, not replay or semantic eval scoring.
+
 ### What to include in a bug report
 
 - Node.js version (`node -v`)

package/docs/LIMITATIONS.md

@@ -31,7 +31,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **AI SDK integration is explicit telemetry wiring.** Use `@agent-inspect/ai-sdk` through AI SDK `experimental_telemetry.integrations`; AgentInspect does not wrap providers, patch fetch, or enable telemetry globally.
 - **AI SDK privacy settings are caller-owned.** Examples set `recordInputs: false` and `recordOutputs: false`; leaving those enabled in user code can cause the AI SDK telemetry layer to include richer data before AgentInspect receives events.
-- **OpenAI Agents JS support is scaffold-only.** `@agent-inspect/openai-agents` documents the safe `setTraceProcessors()` boundary but does not map runtime spans yet and is not part of the v1.7 published package set.
+- **OpenAI Agents JS support is experimental and not published yet.** `@agent-inspect/openai-agents` maps metadata-only runtime spans through the safe `setTraceProcessors()` boundary, remains private until the v1.8 first-publication gate, and does not capture raw payloads by default.
 - **LangGraph support is a boundary decision, not a separate package.** Initial support is expected through `@agent-inspect/langchain` callbacks unless no-network fixtures prove a separate package is needed.
 - **No root/core adapter dependencies.** AI SDK, OpenAI Agents, LangGraph, OpenTelemetry, and LangChain remain outside the root/core runtime dependency graph.
 
@@ -54,6 +54,12 @@ This document states what AgentInspect **does not** provide today. It complement
 - **Metadata truncation** applies to string values and nested structures; very large metadata may be replaced with a truncation marker when `maxEventBytes` is exceeded (default 64 KiB per JSONL line).
 - **Redaction is not encryption.** Local trace files remain readable on disk; treat `.agent-inspect-runs/` like any developer artifact that may contain operational data.
 
+## Checks, artifacts, and test reporters
+
+- **Checks are deterministic local rules, not compliance certification.** `check`, `scan`, and `verify-safe` surface bounded findings and diagnostics over supported local inputs; they do not prove a trace is safe for every sharing context.
+- **Safe CI artifacts are structural summaries.** They avoid raw prompt/output/request/response/header/tool payload content by default, but teams should still review generated files before sharing.
+- **Vitest/Jest reporters are optional and unpublished until release readiness in the v1.8 train.** The recipes document config patterns and explicit associations; consumers should install the packages only after publication.
+
 ## Execution semantics
 
 - **No replay / fork** of past runs from traces alone.

package/docs/LOG-TO-TREE-QUICKSTART.md

@@ -1,6 +1,6 @@
 ## Log-to-tree quickstart
 
-AgentInspect can inspect **structured logs** and render a local execution tree without requiring you to wrap every function in manual tracing.
+Advanced ingestion: use this when your app already emits structured logs. AgentInspect can inspect those logs and render a local execution tree without requiring you to wrap every function in manual tracing.
 
 ## Example JSON log lines
 
@@ -53,4 +53,3 @@ See also:
 - `docs/LOGGING-PLAYBOOK.md` (pino / log4js / NestJS examples + fixtures)
 - `docs/SCHEMA.md` (log ingest config types + confidence)
 - `examples/recipes/pino-json-logs/`, `log4js-json-layout/`, `nestjs-json-logging/`
-

package/docs/MIGRATION.md

@@ -0,0 +1,67 @@
+# Migration
+
+AgentInspect 1.x keeps existing global APIs and published imports working. Manual trace writing remains `schemaVersion: "0.1"`, and v0.1/v0.2 traces remain readable.
+
+## From older 1.x docs
+
+Prefer the current adoption order:
+
+1. Use `observe()` for an existing object/class.
+2. Use framework adapters when you already run AI SDK, OpenAI Agents, or LangChain.
+3. Use `inspectRun` and `step` when you need explicit custom spans.
+4. Use structured log parsing as advanced ingestion when your app already emits structured logs.
+
+## Imports
+
+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";
+```
+
+## v2 import preparation
+
+No import changes are required for v1.x. To prepare for v2, keep beginner workflow APIs at the root and move advanced usage to subpaths now.
+
+| 1.x root compatibility import | Preferred 1.x import for new code | v2 direction |
+| --- | --- | --- |
+| `inspectRun`, `maybeInspectRun`, `step`, `observe`, `getCurrentCorrelationMetadata` | `agent-inspect` | stays root |
+| `createInspector` | `agent-inspect/advanced` | likely root and `/advanced` |
+| `createInspectorRuntime` | `agent-inspect/advanced` | `/advanced` |
+| `openTrace`, `readTrace`, `detectTraceFormat` | `agent-inspect/readers` | `/readers` |
+| `memoryWriter`, `fileWriter`, `bufferedFileWriter`, `compositeWriter`, `nullWriter` | `agent-inspect/writers` | `/writers` |
+| `runTraceChecks` and check types | `agent-inspect/checks` | `/checks` |
+| `diffTraceEvents`, `diffRuns`, `renderRunDiff` | `agent-inspect/diff` | `/diff` |
+| `exportMarkdown`, `exportHtml`, `exportOpenInference`, `exportOtlpJson` | `agent-inspect/exporters` | `/exporters` |
+| `parseLogsToTrees`, log parsers, tree builders | `agent-inspect/logs` | `/logs` |
+| persisted conversion helpers | `agent-inspect/persisted` | `/persisted` |
+
+## Safety
+
+Nothing uploads by default. Manual metadata is redacted before disk by default, and export redaction applies to a local copy before you share it. Review traces and exports before posting them in issues, PRs, chats, or public docs.
+
+## Compatibility notes
+
+- Existing `inspectRun`, `maybeInspectRun`, `step`, `step.llm`, `step.tool`, `observe`, and `getCurrentCorrelationMetadata` imports remain valid.
+- Root/core does not require optional adapter dependencies.
+- Optional adapter APIs are experimental and package-scoped.
+- No destructive migration is required for existing trace directories.

package/docs/SCHEMA.md

@@ -250,6 +250,7 @@ v1.6 adds experimental writer and reader surfaces without changing the stable ma
 - `agent-inspect/readers` and `agent-inspect open` read local AgentInspect JSONL, OpenInference JSON, and OTLP JSON inputs through compatibility adapters.
 - OpenInference and OTLP JSON inputs are **not** a third AgentInspect persisted schema. They are local read formats normalized into inspection trees with warnings and unsupported-field reporting.
 - Reader and writer APIs perform no network upload and do not mutate source files.
+- v1.8 checks, safety verification, baseline comparison, safe CI artifacts, and reporter artifacts are report layers over existing trace inputs. They do not change manual trace writing, introduce a third persisted trace model, or embed raw prompt/output/request/response/header/tool payload content in their default structural outputs.
 
 ## 16. Migration notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -95,6 +95,16 @@
         "types": "./packages/core/dist/readers.d.cts",
         "default": "./packages/core/dist/readers.cjs"
       }
+    },
+    "./checks": {
+      "import": {
+        "types": "./packages/core/dist/checks.d.ts",
+        "default": "./packages/core/dist/checks.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/checks.d.cts",
+        "default": "./packages/core/dist/checks.cjs"
+      }
     }
   },
   "bin": {
@@ -158,7 +168,7 @@
   },
   "scripts": {
     "clean": "pnpm -r exec -- rm -rf dist",
-    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts",
+    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.vitest.config.ts && pnpm exec tsup --config tsup.jest.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts && pnpm exec tsup --config tsup.harness.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",