agent-inspect 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- 21ecc6f: v1.1.0: env-gated tracing, trace safety (redaction + size bounds), LangChain JSONL persistence, logging recipes, CJS/ESM type export compatibility, community docs.
+
+## 1.1.0 — Unreleased
+
+### Added
+
+- Added env-gated tracing with `maybeInspectRun()` using `AGENT_INSPECT`.
+- Added `enabled` option for `inspectRun` passthrough when tracing should be skipped.
+- Added default-on persisted trace safety for manual traces, including metadata redaction and event size bounds.
+- Added optional LangChain JSONL persistence with `persist: true` in `@agent-inspect/langchain`.
+- Added production-shaped logging guidance with pino, log4js, and NestJS JSON logging recipes.
+- Added community contribution scaffold, issue templates, and good-first-issue guidance.
+
+### Fixed
+
+- Fixed conditional type exports for ESM and CommonJS TypeScript consumers.
+- Improved package compatibility for TypeScript Node16/NodeNext consumers using `import` and `require`.
+- Updated public docs to avoid treating `docs-local` as primary contributor/user documentation.
+- Updated stale docs around LangChain persistence, redaction, and package boundaries.
+
+### Security
+
+- Redacts sensitive manual trace metadata before disk by default.
+- Allows explicit opt-out with `redact: false`.
+- Bounds persisted event and metadata size to reduce accidental large trace files.
+- Keeps JSON logs first-class and log4js parsing best-effort without unsafe JavaScript object parsing.
+
+### Documentation
+
+- Added/updated logging playbook for structured JSON logs ([docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md)).
+- Updated public roadmap to separate completed v1.1-prep work from Now/Next/Future.
+- Updated contributor/community docs for package boundaries and optional packages.
+- Added clearer community onboarding and issue-draft guidance.
+
+### Notes
+
+- LangChain adapter APIs remain experimental.
+- `persist: false` remains the default for `@agent-inspect/langchain`; `persist: true` is opt-in.
+- Existing manual trace schema remains `schemaVersion: "0.1"`.
+- Existing event names remain `run_started`, `run_completed`, `step_started`, and `step_completed`.
+- There is still no `step_failed` event; failures are represented as `step_completed` with `status: "error"`.
+- JSON logs remain first-class; log4js text parsing remains best-effort.
+- No vendor upload, network sink, dashboard, replay engine, or cost engine was added.
+- Root `agent-inspect` runtime dependencies remain `chalk`, `commander`, and `nanoid` only.
+
+## 1.0.3
+
+### Patch Changes
+
+- Add `enabled` option and `maybeInspectRun` helper for env-gated tracing (`AGENT_INSPECT`).
+- Fix CJS/ESM conditional type exports for TypeScript consumers.
+- Add community contributor scaffold and issue drafts.
+
 ## 1.0.2
 
 ### Patch Changes
@@ -12,16 +69,6 @@
 
 - 575b093: docs: onboarding polish
 
-## Unreleased
-
-### Documentation
-
-- Improved README onboarding for new users.
-- Added comparison guide.
-- Added log-to-tree quickstart.
-- Added a quickstart demo example.
-- Clarified docs organization between user-facing `docs/` and internal `docs-local/`.
-
 ## 1.0.0
 
 ### Stable local tracing

package/README.md

@@ -93,6 +93,18 @@ support-agent
 
 A runnable copy lives in [examples/00-quickstart-demo](examples/00-quickstart-demo/README.md).
 
+**Env-gated tracing** (eval harnesses, CI): use `maybeInspectRun` and set `AGENT_INSPECT=1` when you want a trace — otherwise no files are written.
+
+```ts
+import { maybeInspectRun } from "agent-inspect";
+
+await maybeInspectRun("eval-case-42", async () => runAgent());
+```
+
+```bash
+AGENT_INSPECT=1 node eval-runner.mjs
+```
+
 ## What the trace shows
 
 Each run produces a **JSONL** trace: `run_started` / `run_completed`, `step_started` / `step_completed`, with **nested steps**, **tool/LLM** types where you use `step.tool` / `step.llm`, and **durations** on completed steps. Failures are recorded on `step_completed` with `status: "error"` (there is no separate `step_failed` event). See [docs/SCHEMA.md](docs/SCHEMA.md).
@@ -121,7 +133,7 @@ npx agent-inspect logs ./agent.log --config agent-inspect.logs.json
 - **Flat timeline by default**; nesting when parent relationships are explicit or configured.
 - **Confidence labels** (`explicit`, `correlated`, `heuristic`, `unknown`) describe how attribution was inferred.
 
-More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md).
+More detail: [docs/LOGS.md](docs/LOGS.md) · [docs/LOG-TO-TREE-QUICKSTART.md](docs/LOG-TO-TREE-QUICKSTART.md) · [docs/LOGGING-PLAYBOOK.md](docs/LOGGING-PLAYBOOK.md) (pino, log4js, NestJS).
 
 ## CLI at a glance
 
@@ -155,7 +167,9 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 - Inspect runs with **`list`** and **`view`**
 - Safely remove old trace files with **`clean`**
 
-**Stable APIs:** `inspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+**Stable APIs:** `inspectRun()`, `maybeInspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.
+
+Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInspectRun` with `AGENT_INSPECT=1` (or `true` / `yes` / `on` / `enabled`) to toggle tracing in eval or CI jobs — see [docs/API.md](docs/API.md).
 
 **Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.
 
@@ -185,12 +199,18 @@ pnpm add agent-inspect @agent-inspect/langchain @langchain/core
 import { AgentInspectCallback } from "@agent-inspect/langchain";
 
 const callback = new AgentInspectCallback({
-  runName: "my-run",
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
   capture: "metadata-only",
 });
 
 await agent.invoke(input, { callbacks: [callback] });
+// In-memory events still available:
 const events = callback.getEvents();
+// Persisted runs are inspectable via CLI:
+// npx agent-inspect list --dir ./.agent-inspect
+// npx agent-inspect view <run-id> --dir ./.agent-inspect
 ```
 
 See [examples/08-langchain-adapter](examples/08-langchain-adapter/README.md) and [docs/ADAPTERS.md](docs/ADAPTERS.md).
@@ -222,6 +242,9 @@ The TUI is available as a separate optional package; its programmatic API is exp
 | [examples/recipes/tool-failure-retry](examples/recipes/tool-failure-retry) | Tool failure + retry |
 | [examples/recipes/multi-agent-handoff](examples/recipes/multi-agent-handoff) | Handoff |
 | [examples/recipes/proactive-agent-logs](examples/recipes/proactive-agent-logs) | Structured logs |
+| [examples/recipes/pino-json-logs](examples/recipes/pino-json-logs) | pino-shaped JSON |
+| [examples/recipes/log4js-json-layout](examples/recipes/log4js-json-layout) | log4js embedded JSON |
+| [examples/recipes/nestjs-json-logging](examples/recipes/nestjs-json-logging) | NestJS JSON logs |
 | [examples/recipes/retry-fallback](examples/recipes/retry-fallback) | Fallback pattern |
 | [examples/recipes/parallel-tools](examples/recipes/parallel-tools) | Parallel tools |
 
@@ -231,7 +254,7 @@ The TUI is available as a separate optional package; its programmatic API is exp
 
 - **Local files by default** — no upload, no vendor sinks in core workflows.
 - **No API keys** required for core tracing and CLI inspection.
-- **Manual metadata** is user-controlled; traces and exports can contain sensitive data if you put it there.
+- **Manual metadata** is user-controlled. By default, common sensitive keys are **redacted before disk**; pass `redact: false` to opt out. Long metadata is truncated and events are capped at 64 KiB per JSONL line. Review traces and exports before sharing.
 - **Review exports** before sharing (especially with richer attribute flags).
 
 See [SECURITY.md](SECURITY.md).
@@ -251,6 +274,7 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 - [Architecture (links to deeper design notes)](docs/ARCHITECTURE.md)
 - [Logs & tail](docs/LOGS.md)
 - [Log-to-tree quickstart](docs/LOG-TO-TREE-QUICKSTART.md)
+- [Logging playbook](docs/LOGGING-PLAYBOOK.md)
 - [Exports](docs/EXPORTS.md)
 - [Diff](docs/DIFF.md)
 - [Adapters](docs/ADAPTERS.md)

package/SECURITY.md

@@ -63,11 +63,14 @@ AgentInspect aims to be safe-by-default for **log-derived attributes** and **exp
 
 Important limitations:
 
-- **Manual trace metadata is user-controlled.** If you attach secrets to `inspectRun({ metadata })` or step metadata, those values may appear in local trace files and could appear in some views/exports depending on your settings and what you choose to include.
+- **Manual trace metadata is user-controlled.** By default, `inspectRun()` and `step()` **redact common sensitive keys** before writing JSONL (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email` — case-insensitive). Pass **`redact: false`** to persist metadata as-is (explicit opt-out).
+- **Non-sensitive metadata and custom keys** are still written locally. Do not attach secrets you are unwilling to store on disk, even with redaction enabled (custom key names may bypass defaults).
+- **Size bounds** truncate long metadata values and cap serialized event size (default 64 KiB per line). Oversized events are truncated further or replaced with a `{ truncated: true, reason: "maxEventBytes" }` marker — instrumentation never throws into your app because of payload size.
+- **`@agent-inspect/langchain` with `persist: true`** writes the same local JSONL format as manual traces. Default **`capture: "metadata-only"`** does not persist full prompts/outputs; use **`capture: "preview"`** only when you accept truncated previews on disk.
 - Always **review exported files** before sharing them externally.
 - Avoid committing trace directories (`.agent-inspect-runs/`) to source control.
 
-For redaction design details, see `docs-local/architecture/REDACTION.md`.
+For schema-level redaction notes, see `docs/SCHEMA.md` (redaction section) and `docs/API.md`.
 
 ## Dependency and security review process
 

package/docs/ADAPTERS.md

@@ -5,11 +5,38 @@ AgentInspect is framework-agnostic at its core, but can optionally integrate wit
 - **LangChain.js adapter** (optional): `@agent-inspect/langchain`
   - Documented as **experimental** in `docs/API.md`
   - Requires `@langchain/core` as a peer dependency
+  - **In-memory by default** (`getEvents()` / `clear()`)
+  - **Optional JSONL persistence** (`persist: true`) maps callback lifecycle to schemaVersion `"0.1"` manual events (`run_started`, `step_started`, `step_completed`, `run_completed`) so `list` / `view` / `export` / `diff` work without a separate schema
+  - **Metadata-only capture by default**; `capture: "preview"` is opt-in with truncation
+  - **No monkey-patching**, **no vendor sinks**, **no network upload**
 - **Interactive TUI** (optional): `@agent-inspect/tui`
   - Documented as **experimental** in `docs/API.md`
   - Intended for CLI integration; programmatic TUI APIs may change
 
+### LangChain persistence model (Strategy A)
+
+When `persist: true`:
+
+1. **Standalone callback session** — one AgentInspect run per `AgentInspectCallback` instance until the root LangChain run completes.
+2. **Inside `inspectRun`** — callback steps append to the active manual run (no extra `run_started` / `run_completed`).
+3. **Parent mapping** — LangChain `parentRunId` maps to AgentInspect `parentId` when the parent step was already persisted; unknown parents stay at run root (no invented hierarchy).
+4. **Step types** — `LLM` → `llm`, `TOOL` → `tool`, `DECISION` → `decision`, other kinds → `logic`.
+
+```ts
+const callback = new AgentInspectCallback({
+  runName: "support-agent",
+  traceDir: "./.agent-inspect",
+  persist: true,
+  capture: "metadata-only",
+});
+```
+
+```bash
+npx agent-inspect list --dir ./.agent-inspect
+npx agent-inspect view <run-id> --dir ./.agent-inspect
+```
+
 See also:
 - `docs/MIGRATION.md` (what changed from early versions)
-- `docs-local/RELEASE-CHECKLIST.md` (maintainer-only release steps)
+- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `traceDir`)
 

package/docs/API.md

@@ -22,11 +22,17 @@ These are the recommended entry points for manual instrumentation. They are desi
 Import from `agent-inspect`:
 
 ```ts
-import { inspectRun, step, observe } from "agent-inspect";
+import { inspectRun, maybeInspectRun, step, observe } 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).
-- **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`).
+- **`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.
+  - **`redact`**: default `true` — redacts sensitive metadata keys before disk (`authorization`, `cookie`, `token`, `apiKey`, `password`, `secret`, `email`). Pass `false` to persist metadata as-is. Pass `{ rules?: RedactionRule[] }` for custom rules (defaults still apply).
+  - **`maxMetadataValueLength`**: max string length for metadata values (default `2000`).
+  - **`maxPreviewLength`**: max string length for preview-like keys containing `preview` (default `500`).
+  - **`maxEventBytes`**: max UTF-8 bytes per serialized JSONL event (default `65536`). Oversized events are truncated; instrumentation never throws into user code.
+- **`maybeInspectRun(name, fn, options?)`**: same as `inspectRun` when tracing is enabled; otherwise passthrough. Enablement: explicit **`options.enabled`** wins; when omitted, reads **`AGENT_INSPECT`** (`1`, `true`, `yes`, `on`, `enabled` — case-insensitive). Unset or other values disable tracing. Use in eval harnesses, CI, or jobs where tracing should be toggled by environment.
+- **`isAgentInspectEnabled(value?)`**: returns whether a string (or `process.env.AGENT_INSPECT`) matches an enable token.
+- **`step(name, fn, options?)`**: traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`). Step `metadata` inherits the parent run's redaction and size-bound settings.
   - **`step.llm(model, fn)`**: convenience wrapper (`type: "llm"`, `metadata.model`).
   - **`step.tool(toolName, fn)`**: convenience wrapper (`type: "tool"`, `metadata.toolName`).
 - **`observe(agent, options?)`**: proxy wrapper that traces top-level `run` / `execute` / `invoke` methods via `inspectRun`.
@@ -109,6 +115,13 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
 `@agent-inspect/langchain` is an optional adapter package.
 
 - **`AgentInspectCallback`** (experimental)
+  - **`persist`**: default `false` — when `true`, maps callback lifecycle to schemaVersion `"0.1"` JSONL (`run_started` / `step_started` / `step_completed` / `run_completed`)
+  - **`runName`**: default `"langchain-agent"` for standalone persisted runs
+  - **`traceDir`**: defaults via `resolveTraceDir` / `AGENT_INSPECT_TRACE_DIR`
+  - **`capture`**: `"none"` | `"metadata-only"` (default) | `"preview"` (truncated previews, opt-in)
+  - **`redact`**: custom `RedactionRule[]` applied before disk (core defaults still apply via shared redactor)
+  - **`runId`**: optional id for standalone persisted runs
+  - In-memory **`getEvents()`** / **`clear()`** unchanged when `persist` is false
 - Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
 
 Rationale: v1.0 includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.

package/docs/ARCHITECTURE.md

@@ -1,13 +1,48 @@
 ## Architecture
 
-This doc is a stable entry point for AgentInspect’s internal architecture and product boundaries.
+AgentInspect is a **local-first execution-tree debugger**: manual traces and log ingest produce inspectable step trees stored as JSONL on disk (default `.agent-inspect-runs/`), with a CLI for list/view/clean/logs/tail/export/diff workflows.
 
-- **Canonical architecture overview**: see `docs-local/architecture/ARCHITECTURE.md`
-- **Event model**: `docs-local/architecture/EVENT-MODEL.md`
-- **Tree building rules**: `docs-local/architecture/TREE-BUILDING-RULES.md`
-- **Schema evolution policy**: `docs-local/architecture/SCHEMA-EVOLUTION.md`
-- **Dependency policy**: `docs-local/architecture/DEPENDENCY-POLICY.md`
-- **Redaction design**: `docs-local/architecture/REDACTION.md`
+### Package layout
 
-If you’re new, start with `docs/GETTING-STARTED.md`, then `docs/API.md`, `docs/CLI.md`, and `docs/SCHEMA.md`.
+| Package | Published? | Role |
+| -------- | ---------- | ---- |
+| `agent-inspect` | Yes | Public tarball: core tracing APIs + CLI (`agent-inspect` binary) |
+| `@agent-inspect/core` | No (private) | Tracing, storage, log parsing, export, diff |
+| `@agent-inspect/cli` | No (private) | Commander CLI implementation |
+| `@agent-inspect/langchain` | Yes (optional) | LangChain.js callback adapter (experimental) |
+| `@agent-inspect/tui` | Yes (optional) | Ink/React terminal viewer (experimental) |
 
+Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consumers (`import.types` / `require.types`). Heavy dependencies (LangChain, Ink/React) stay in optional packages.
+
+### Event model and schema
+
+- Manual traces use **`schemaVersion: "0.1"`** JSONL events (`run_started`, `step_started`, `step_completed`, `run_completed`).
+- Failures use `step_completed` with `status: "error"` — there is no `step_failed` event.
+- Log-derived runs use confidence labels (`explicit`, `correlated`, `heuristic`, `unknown`) and conservative tree-building rules.
+
+See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
+
+### Safety and redaction
+
+- Instrumentation must **not throw into user code**; trace safety failures degrade gracefully.
+- **Manual metadata** is redacted before disk by default; `redact: false` opts out.
+- **Size bounds** cap persisted event and metadata size.
+- Log ingest: JSON first-class; log4js best-effort; no `eval` or JS object-literal parsing.
+
+See [SECURITY.md](../SECURITY.md) and [LIMITATIONS.md](./LIMITATIONS.md).
+
+### Optional adapters
+
+- **`@agent-inspect/langchain`**: in-memory by default; `persist: true` writes local JSONL. Experimental.
+- **`@agent-inspect/tui`**: interactive viewer; isolated from root deps. Experimental.
+
+See [ADAPTERS.md](./ADAPTERS.md).
+
+### Where to read next
+
+- New users: [GETTING-STARTED.md](./GETTING-STARTED.md)
+- CLI: [CLI.md](./CLI.md)
+- Structured logs: [LOGS.md](./LOGS.md), [LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
+- Contributors: [CONTRIBUTING.md](../CONTRIBUTING.md), [docs/community/CONTRIBUTING.md](./community/CONTRIBUTING.md)
+
+Maintainer-only internal docs under `docs-local/` may contain additional historical architecture depth; they are not required for contributors.

package/docs/CLI.md

@@ -31,6 +31,7 @@ Core commands:
 
 - **`AGENT_INSPECT_TRACE_DIR`**: default directory for manual trace files (`.jsonl`) when not passed via `--dir` (or API options).
 - **`AGENT_INSPECT_SILENT`**: when `true`, suppresses live terminal tree output during manual tracing (`inspectRun` / `step`). Trace files are still written.
+- **`AGENT_INSPECT`**: enables manual tracing for **`maybeInspectRun`** when set to `1`, `true`, `yes`, `on`, or `enabled` (case-insensitive). Unset or any other value disables tracing. Does **not** change default **`inspectRun`** behavior (which always traces unless `enabled: false` is passed in code). No network upload — local JSONL only.
 
 ## 3. Exit code policy
 

package/docs/EXPORTS.md

@@ -4,7 +4,7 @@ AgentInspect supports local-only exports from run trees and traces. Exports are
 
 - **CLI usage**: `docs/CLI.md` (`export`)
 - **Schema + compatibility guarantees**: `docs/SCHEMA.md`
-- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs-local/architecture/REDACTION.md`
+- **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
 
 Notes:
 - Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.

package/docs/GETTING-STARTED.md

@@ -38,6 +38,28 @@ This writes a local JSONL trace with stable v1.0 event names:
 - `run_started`, `run_completed`
 - `step_started`, `step_completed`
 
+### Always trace vs env-gated tracing
+
+Use **`inspectRun`** when you always want a local trace (default behavior).
+
+Use **`maybeInspectRun`** in eval harnesses, CI, or production-shaped jobs where tracing should be toggled by environment:
+
+```ts
+import { maybeInspectRun } from "agent-inspect";
+
+await maybeInspectRun("eval-case-42", async () => {
+  return runAgent();
+});
+```
+
+```bash
+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.
+
+To skip tracing in code without env vars: `inspectRun(name, fn, { enabled: false })`.
+
 ## 3. View runs
 
 ```bash
@@ -95,12 +117,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:
@@ -111,18 +135,20 @@ 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/LIMITATIONS.md

@@ -15,6 +15,12 @@ This document states what AgentInspect **does not** provide today. It complement
 - **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 +35,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,11 +188,15 @@ 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. Migration notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",
@@ -12,15 +12,19 @@
     "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",
   "exports": {
     ".": {
-      "types": "./packages/core/dist/index.d.ts",
-      "import": "./packages/core/dist/index.mjs",
-      "require": "./packages/core/dist/index.cjs"
+      "import": {
+        "types": "./packages/core/dist/index.d.ts",
+        "default": "./packages/core/dist/index.mjs"
+      },
+      "require": {
+        "types": "./packages/core/dist/index.d.cts",
+        "default": "./packages/core/dist/index.cjs"
+      }
     }
   },
   "bin": {
@@ -71,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",
@@ -81,8 +95,6 @@
     "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",
     "fixtures:check": "node scripts/validate-fixtures.mjs",
@@ -91,15 +103,5 @@
     "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"
   }
-}
+}