agent-inspect 1.1.0 → 1.3.0

package/docs/KNOWN-ISSUES.md

@@ -32,3 +32,56 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 - Log-derived trees carry **confidence** (`explicit`, `correlated`, `heuristic`, `unknown`). Labels explain **how** relationships were inferred—they are not semantic proof.
 
 When in doubt, treat AgentInspect as a **debugging aid**, not a compliance or billing system of record.
+
+## Common install/runtime compatibility checks
+
+Use these before filing a packaging bug. AgentInspect targets **Node.js ≥ 20**.
+
+### Quick self-check (clean temp project)
+
+```bash
+mkdir /tmp/agent-inspect-check && cd /tmp/agent-inspect-check
+npm init -y
+npm install agent-inspect@latest
+node -e "import('agent-inspect').then(m => console.log('esm', typeof m.inspectRun))"
+node -e "const m=require('agent-inspect'); console.log('cjs', typeof m.inspectRun, typeof m.maybeInspectRun)"
+npx agent-inspect --help
+```
+
+From a **repo clone** (maintainers / contributors):
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm compat:smoke
+```
+
+### ESM import
+
+- Consumer `package.json` should use `"type": "module"` (or `.mjs` entry files).
+- Import: `import { inspectRun, step, maybeInspectRun } from "agent-inspect"`.
+- TypeScript: `module` / `moduleResolution` `NodeNext` or `Node16` with matching `type` field.
+
+### CJS require
+
+- Consumer `package.json` should use `"type": "commonjs"` (or `.cjs` entry files).
+- Require: `const { inspectRun, step, maybeInspectRun } = require("agent-inspect")`.
+- TypeScript: compile `.cts` with `module` / `moduleResolution` `Node16`.
+
+**Note:** `chalk@5` and `nanoid@5` are ESM-only upstream. Published `agent-inspect` bundles them into CJS output so Jest 29 / `require()` consumers do not resolve ESM-only deps at runtime. If you still see `ERR_REQUIRE_ESM`, report Node version, bundler, and full stack trace.
+
+### Jest / ts-jest (CJS)
+
+- Prefer `require("agent-inspect")` in CJS test files, or ensure your Jest config supports the package's export conditions.
+- For tracing off in unit tests: `maybeInspectRun(name, fn, { enabled: false })` or unset `AGENT_INSPECT`.
+- 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.
+
+### What to include in a bug report
+
+- Node.js version (`node -v`)
+- Package manager and lockfile type (npm / pnpm / yarn)
+- ESM vs CJS vs TypeScript + ts-jest
+- Minimal repro repo or snippet
+- Full error stack (not only the top line)
+- Whether `AGENT_INSPECT` is set in the environment

package/docs/LIMITATIONS.md

@@ -9,6 +9,22 @@ This document states what AgentInspect **does not** provide today. It complement
 - **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
 - **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
 
+## Correlation metadata (v1.3.0 chunk 1)
+
+- **No CLI filter/query** by `correlationId`, `requestId`, `decisionId`, or `groupId` yet — fields are written to `run_started.metadata` and available via persisted converters; list/view/export filtering is future work.
+
+## 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/write integration** (dual-format storage, CLI consumption) is future work — v1.2.0 ships in-memory converters and canonical fixtures only.
+
+## LangChain streaming (v1.3.0)
+
+- **Metadata-focused only** — `stream: true` records chunk counts, timing, and optional bounded previews; it is **not** a replay/cassette system.
+- **No full token stream storage by default** — even with `stream: true`, `capture: "metadata-only"` does not persist raw streamed text.
+- **No per-token JSONL events** — streaming does not emit one trace line per token.
+
 ## Data fidelity
 
 - **No full prompt/output capture by default** for manual traces (by design: safety and PII risk).
@@ -17,6 +33,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 ## Trace safety bounds
 
+- **Redaction profiles** (`local`, `share`, `strict`) are key-based presets — not compliance-grade PII detection. Review exports before sharing even with `--redaction-profile strict`.
 - **Default metadata redaction** covers common sensitive keys only (exact key match, case-insensitive). Custom secret field names are not redacted unless you add rules via `redact: { rules: [...] }`.
 - **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.

package/docs/SCHEMA.md

@@ -129,6 +129,7 @@ Unknown status must **not** be treated as success.
 ## 6. Metadata policy
 
 - Runs may include `metadata` on `run_started`.
+- **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` on `run_started.metadata` when passed via `inspectRun` / `maybeInspectRun` options. Event names remain unchanged (`run_started`, `step_started`, `step_completed`, `run_completed`). CLI list/view does not filter by correlation fields yet.
 - Steps may include `metadata` on `step_started`.
 - Manual traces intentionally avoid full prompt/output capture by default.
 - **Redaction (default on):** before disk, `inspectRun` / `step` redact sensitive keys using the shared `Redactor` defaults (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Opt out with `redact: false`.
@@ -198,8 +199,46 @@ Always review any exported content (Markdown/HTML/OpenInference/OTLP JSON) befor
 
 See: `SECURITY.md` and `docs/API.md` (`InspectRunOptions.redact`, size bound options).
 
-## 14. Migration notes
+## 14. Persisted InspectEvent schemaVersion "0.2" — experimental foundation
+
+v1.2.0 introduces a **source-agnostic persisted event model** as an experimental foundation. It is **not** the default on-disk format.
+
+| Topic | Rule |
+| ----- | ---- |
+| 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. |
+| Failures | Still **no** `step_failed`; use `status: "error"` on the persisted event. |
+
+Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:check`).
+
+### 14.1 Field reference (compact)
+
+| Field | Required | Notes |
+| ----- | -------- | ----- |
+| `schemaVersion` | yes | `"0.2"` |
+| `eventId` | yes | Stable per-event identifier |
+| `runId` | yes | Run grouping key |
+| `parentId` | no | Explicit nesting only when present |
+| `kind` | yes | `InspectKind` (`RUN`, `LLM`, `TOOL`, `LOGIC`, …) |
+| `name` | yes | Human-readable step label |
+| `status` | no | `running` \| `ok` \| `error` \| `unknown` |
+| `timestamp` | yes | ISO-8601 string (event time) |
+| `startedAt` / `endedAt` | no | ISO-8601 bounds when known |
+| `durationMs` | no | Non-negative milliseconds when known |
+| `confidence` | yes | `explicit` \| `correlated` \| `heuristic` \| `unknown` |
+| `source` | yes | `{ type, name?, version? }` — `manual`, `json-log`, `log4js`, `adapter`, `ai-sdk`, `otel` |
+| `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 |
+| `trace` | no | Optional `{ traceId?, spanId?, parentSpanId? }` for future OTel alignment |
+
+Programmatic helpers: see [API.md](./API.md) §15 (experimental persisted-event foundation).
+
+## 15. Migration notes
 
 - Minor releases may add optional fields/events, but must keep existing v0.1 traces readable.
-- Migration guides (v0.1 → v1.0) are out of scope for this pass, but this document is the canonical schema reference for that future guide.
+- Migration guides (v0.1 → v0.2 file format) are future work; storage/CLI dual-read is not in the v1.2.0 foundation release.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -97,6 +97,7 @@
     "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
     "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs",
+    "compat:smoke": "node scripts/compat-smoke.mjs",
     "fixtures:check": "node scripts/validate-fixtures.mjs",
     "recipes:check": "node scripts/validate-recipes.mjs",
     "perf:baseline": "node scripts/performance-baseline.mjs",