agent-inspect 1.0.3 → 1.2.0

package/docs/GETTING-STARTED.md

@@ -14,6 +14,8 @@ The `agent-inspect` package includes the CLI binary via its `bin` field:
 npx agent-inspect --help
 ```
 
+For a clean install verification path covering npm, pnpm, ESM import, CJS require, and CLI help, see [Clean install smoke test](./INSTALL-SMOKE-TEST.md).
+
 For local repo development (this monorepo), build and run the CLI from `packages/cli`:
 
 ```bash
@@ -33,7 +35,7 @@ await inspectRun("demo-agent", async () => {
 });
 ```
 
-This writes a local JSONL trace with stable v1.0 event names:
+This writes a local JSONL trace with stable event names (`schemaVersion: "0.1"`):
 
 - `run_started`, `run_completed`
 - `step_started`, `step_completed`
@@ -58,6 +60,10 @@ AGENT_INSPECT=1 node eval-runner.mjs
 
 Enable tokens: `1`, `true`, `yes`, `on`, `enabled` (case-insensitive). Explicit `enabled: true | false` in options overrides the env var.
 
+### Install compatibility
+
+If `import` or `require` fails after install, see [KNOWN-ISSUES.md — Common install/runtime compatibility checks](./KNOWN-ISSUES.md#common-installruntime-compatibility-checks).
+
 To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
 
 ## 3. View runs
@@ -117,12 +123,14 @@ See `examples/recipes/README.md`.
 
 ## 10. Optional LangChain adapter
 
-`@agent-inspect/langchain` is optional and **experimental**:
+`@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.
 
 ```bash
 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
 
 `@agent-inspect/tui` is optional and **experimental**. The CLI can invoke it with:
@@ -133,18 +141,19 @@ agent-inspect view <runId> --tui
 
 ## 12. Safety notes
 
-- Redaction is on by default for log-derived attributes and exports.
+- 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.
+- 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
 
-- `docs/API.md`
-- `docs/CLI.md`
-- `docs/SCHEMA.md`
-- `docs/COMPARE.md`
-- `docs/LOG-TO-TREE-QUICKSTART.md`
-- `docs/KNOWN-ISSUES.md`
-- `docs/LIMITATIONS.md`
-- `docs-local/V1-READINESS-CHECKLIST.md`
-
+- [docs/API.md](./API.md)
+- [docs/CLI.md](./CLI.md)
+- [docs/SCHEMA.md](./SCHEMA.md)
+- [docs/LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+- [docs/COMPARE.md](./COMPARE.md)
+- [docs/LOG-TO-TREE-QUICKSTART.md](./LOG-TO-TREE-QUICKSTART.md)
+- [docs/KNOWN-ISSUES.md](./KNOWN-ISSUES.md)
+- [docs/LIMITATIONS.md](./LIMITATIONS.md)
+- [ROADMAP.md](../ROADMAP.md)

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,12 +9,24 @@ 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).
 
+## 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.
+
 ## Data fidelity
 
 - **No full prompt/output capture by default** for manual traces (by design: safety and PII risk).
 - **Log-derived runs** and **manual JSONL traces** may differ in fidelity (timestamps, nesting, confidence).
 - **Confidence labels** qualify inferred relationships; they do not guarantee correctness.
 
+## Trace safety bounds
+
+- **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.
+
 ## Execution semantics
 
 - **No replay / fork** of past runs from traces alone.
@@ -29,4 +41,4 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.
 
-For roadmap intent, see `docs-local/roadmap/VERSION-ROADMAP.md` and `docs-local/prd/v1.0-STABLE-LOCAL-INSPECTOR-PRD.md` (planning docs; not a promise of future features).
+For roadmap intent, see [ROADMAP.md](../ROADMAP.md) (direction only — not a delivery guarantee).

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

@@ -50,5 +50,7 @@ Run req_123
 See also:
 - `docs/CLI.md` (`logs`, `tail`)
 - `docs/LOGS.md`
+- `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/LOGS.md

@@ -4,8 +4,9 @@ AgentInspect can parse **existing logs** (line-delimited JSON, and best-effort l
 
 - **CLI usage**: `docs/CLI.md` (`logs`, `tail`)
 - **Quickstart**: `docs/LOG-TO-TREE-QUICKSTART.md`
-- **Log ingest config (field mapping + redaction)**: `docs-local/architecture/LOG-INGEST-CONFIG.md`
-- **Safety constraints** (no eval, no JS object parsing): `docs-local/architecture/ARCHITECTURE.md`
+- **Production-shaped playbook**: `docs/LOGGING-PLAYBOOK.md` (pino, log4js, NestJS recipes)
+- **Field mapping and redaction**: `docs/API.md` (log ingest APIs) and `docs/SCHEMA.md`
+- **Safety constraints**: JSON logs first-class; log4js best-effort; no `eval`; no JavaScript object-literal parsing as a log interchange format (see `SECURITY.md`)
 
 Notes:
 - Log parsing APIs are documented as **experimental** in `docs/API.md`.

package/docs/SCHEMA.md

@@ -131,6 +131,8 @@ Unknown status must **not** be treated as success.
 - Runs may include `metadata` on `run_started`.
 - 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`.
+- **Size bounds:** long string values are truncated (`maxMetadataValueLength`, default 2000; preview-like keys use `maxPreviewLength`, default 500). Serialized events are capped at `maxEventBytes` (default 65536 UTF-8 bytes). If still too large, `metadata` may be replaced with `{ truncated: true, reason: "maxEventBytes", originalApproxBytes: number }`. Required event fields are never removed.
 
 ## 7. Additive fields and unknown fields
 
@@ -186,14 +188,56 @@ Log-derived trees must remain honest:
 
 ## 13. Redaction considerations
 
-Redaction is applied to log-derived attributes and to exports by default. **Manual trace metadata is user-controlled** and should be treated as potentially sensitive.
+Redaction is applied to **log-derived attributes**, **manual trace metadata (before disk, by default)**, and **exports by default**.
+
+- Manual metadata redaction uses exact key matching (case-insensitive), not substring matching.
+- `redact: false` is an explicit opt-out; use only when you accept local persistence of metadata as provided.
+- Local trace files can still contain sensitive data if you use non-default key names or opt out of redaction.
 
 Always review any exported content (Markdown/HTML/OpenInference/OTLP JSON) before sharing, especially if you enable richer attribute inclusion.
 
-See: `docs-local/architecture/REDACTION.md`.
+See: `SECURITY.md` and `docs/API.md` (`InspectRunOptions.redact`, size bound options).
+
+## 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).
 
-## 14. Migration notes
+## 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.0.3",
+  "version": "1.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -12,7 +12,6 @@
     "url": "https://github.com/rajudandigam/agent-inspect/issues"
   },
   "homepage": "https://github.com/rajudandigam/agent-inspect#readme",
-  "packageManager": "pnpm@9.15.0",
   "main": "./packages/core/dist/index.cjs",
   "module": "./packages/core/dist/index.mjs",
   "types": "./packages/core/dist/index.d.ts",
@@ -76,6 +75,16 @@
     "nanoid": "^5.0.9",
     "commander": "^12.1.0"
   },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.10",
+    "@size-limit/preset-small-lib": "^11.1.6",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "size-limit": "^11.1.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
   "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",
@@ -86,25 +95,14 @@
     "size": "size-limit --config size-limit.config.mjs",
     "test:all": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run size",
     "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",
-    "prepublishOnly": "pnpm run prepublish:checks",
-    "prepack": "pnpm run clean && pnpm run build",
     "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",
     "examples:check": "pnpm install && pnpm --filter agent-inspect-example-01-basic run start",
     "changeset": "changeset",
     "release": "changeset publish"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.10",
-    "@size-limit/preset-small-lib": "^11.1.6",
-    "@types/node": "^22.10.2",
-    "@vitest/coverage-v8": "^2.1.8",
-    "size-limit": "^11.1.6",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
   }
-}
+}