agent-inspect 1.5.0 → 1.7.0

package/docs/KNOWN-ISSUES.md

@@ -12,9 +12,19 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - **OpenInference** and **OTLP JSON** exports are **compatibility-oriented** and **experimental**. Validate against your target collector or backend before relying on them.
 - Exports generate **strings/files locally** only—there is **no** automatic upload.
 
+## Readers and `open`
+
+- **OpenInference** and **OTLP JSON** readers are **compatibility-oriented** and **experimental**. They normalize local JSON payloads into AgentInspect inspection trees and may warn on unsupported semantic fields.
+- `agent-inspect open` requires `--run <run-id>` when input contains multiple runs. It does not pick an arbitrary run silently.
+- Format detection is conservative. Use `--format agent-inspect-jsonl`, `--format openinference-json`, or `--format otlp-json` for known local inputs.
+- Standards JSON readers summarize bounded prompt/output-like attributes; they do not make raw prompt/output capture a default AgentInspect behavior.
+
 ## Integrations
 
 - **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()`.
+- **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.
 - **Correlation metadata** (`correlationId`, `requestId`, `decisionId`, `groupId`) is written on `run_started` but **CLI list/view does not filter by correlation fields** yet.
@@ -31,7 +41,7 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 ## Cost / tokens
 
-- **Token counting** and **cost calculation** are **not** core features.
+- **Token counting** and **cost calculation** are **not** core features. Token usage fields (`input`, `output`, `total`, `cached`) are displayed only when supplied by user code, fixtures, or adapters.
 
 ## Confidence labels
 

package/docs/LIMITATIONS.md

@@ -16,8 +16,24 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Persisted event model (v1.2.0 foundation)
 
 - **v0.2 is not the default persisted trace file format.** `inspectRun()` / `step()` still write `schemaVersion: "0.1"` JSONL.
-- **CLI commands** (`list`, `view`, `export`, `diff`, `logs`, `tail`) still primarily operate on current v0.1 trace and log paths.
-- **v0.2 read integration** — inspection CLI reads v0.2 JSONL via dual-format normalization (v1.5.0). Default **write** path remains v0.1; `list` metadata for v0.2-only files may be limited.
+- **Dual-format inspection is a read path, not a write migration.** `list`, `view`, `timeline`, `stats`, `search`, `diff`, `export`, `what`, and `report` read v0.1/v0.2 trace files through normalization where applicable. `logs` and `tail` remain structured-log ingestion commands, not v0.2 writers.
+- **Default write path remains v0.1.** v0.2 fixtures and converters are available for adapters and migration testing, but AgentInspect does not automatically rewrite traces.
+
+## Runtime writers and universal readers (v1.6)
+
+- **Experimental APIs:** `agent-inspect/writers`, `agent-inspect/readers`, and `createInspector()` are available for local adoption, but their experimental contracts may be refined in v1.x.
+- **Explicit writer ownership:** `createInspector()` does not print terminal lifecycle output or implicitly choose a disk writer. Use `fileWriter()` / `bufferedFileWriter()` / custom writers when persistence is desired.
+- **No standards upload:** OpenInference and OTLP JSON support is local read/export compatibility only. There is no OTLP gRPC/HTTP streaming sink, collector client, or hosted ingestion behavior.
+- **Conservative detection:** `agent-inspect open` does not silently accept arbitrary JSON. Unsupported or ambiguous inputs produce errors/warnings rather than guessed traces.
+- **Large inputs:** reader inputs are bounded and read into local memory. This is not a database index or production log warehouse.
+
+## Framework adapters (v1.7)
+
+- **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.
+- **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.
 
 ## LangChain streaming (v1.3.0)
 
@@ -47,6 +63,7 @@ This document states what AgentInspect **does not** provide today. It complement
 ## Economics
 
 - **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
+- **Token usage is supplied metadata only**: AgentInspect may display `input`, `output`, `total`, and `cached` counts when callers/adapters provide them; core does not count tokens or infer provider billing.
 
 ## Local observability commands (v1.4.0)
 

package/docs/SCHEMA.md

@@ -210,8 +210,9 @@ v1.2.0 introduces a **source-agnostic persisted event model** as an experimental
 | ----- | ---- |
 | Default write format | Manual traces still use **`schemaVersion: "0.1"`** (`run_started`, `step_started`, `step_completed`, `run_completed`). |
 | v0.2 role | Unified persisted shape for manual traces, log-derived events, adapter events, and future AI SDK / OTel mappings. |
-| v0.2 file writing | **Not enabled by default** in v1.2.0 — converters and fixtures only. |
-| v0.1 compatibility | v0.2 does **not** replace v0.1 in this release; existing `0.1` files remain canonical for CLI write/read today. |
+| v0.2 file writing | **Not enabled by default** — converters and fixtures only unless a caller writes v0.2 data explicitly. |
+| v0.1 compatibility | v0.2 does **not** replace v0.1 in v1.x; existing `0.1` files remain canonical for manual writing and continue to be readable. |
+| v0.2 read path | Inspection read paths normalize v0.1 and v0.2 JSONL for local CLI/API use. |
 | Failures | Still **no** `step_failed`; use `status: "error"` on the persisted event. |
 
 Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:check`).
@@ -235,13 +236,22 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 | `attributes` | no | Shallow metadata bag (redaction-ready) |
 | `inputSummary` / `outputSummary` | no | Truncated previews when explicitly captured |
 | `error` | no | `{ name?, message, code? }` when `status: "error"` |
-| `tokenUsage` | no | `{ input?, output?, total? }` when known |
+| `tokenUsage` | no | `{ input?, output?, total?, cached? }` when supplied/known |
 | `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
 
-Programmatic helpers: see [API.md](./API.md) §11 (experimental persisted-event foundation).
+Programmatic helpers: see [API.md](./API.md) §13 (experimental persisted-event foundation).
 
-## 15. Migration notes
+## 15. v1.6 local reader/writer compatibility
 
-- Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
-- Migration guides (v0.1 → v0.2 file format) are future work; storage/CLI dual-read is not in the v1.2.0 foundation release.
+v1.6 adds experimental writer and reader surfaces without changing the stable manual trace schema:
+
+- `inspectRun()` / `step()` continue to write `schemaVersion: "0.1"` JSONL by default.
+- `createInspector()` can write explicit v0.2 `PersistedInspectEvent` rows when configured with a writer such as `fileWriter()` or `bufferedFileWriter()`.
+- `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.
 
+## 16. Migration notes
+
+- Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
+- v0.1 → v0.2 write migration guides are future work. v1.x inspection readers are dual-format; the default manual writer remains v0.1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -75,6 +75,26 @@
         "types": "./packages/core/dist/diff.d.cts",
         "default": "./packages/core/dist/diff.cjs"
       }
+    },
+    "./writers": {
+      "import": {
+        "types": "./packages/core/dist/writers.d.ts",
+        "default": "./packages/core/dist/writers.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/writers.d.cts",
+        "default": "./packages/core/dist/writers.cjs"
+      }
+    },
+    "./readers": {
+      "import": {
+        "types": "./packages/core/dist/readers.d.ts",
+        "default": "./packages/core/dist/readers.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/readers.d.cts",
+        "default": "./packages/core/dist/readers.cjs"
+      }
     }
   },
   "bin": {
@@ -99,6 +119,7 @@
     "docs/EXPORTS.md",
     "docs/DIFF.md",
     "docs/ADAPTERS.md",
+    "docs/ADAPTER-CONFORMANCE.md",
     "docs/COMPARE.md",
     "docs/LOG-TO-TREE-QUICKSTART.md",
     "docs/SCREENSHOTS.md"
@@ -137,7 +158,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",
+    "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",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",