agent-inspect 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,12 +1,34 @@
 # Changelog
 
-## 1.2.0
+## 1.3.0
 
 ### Minor Changes
 
-- 5a7f785: v1.2.0: experimental persisted-event foundation (`PersistedInspectEvent` schemaVersion 0.2), validators, TraceEvent/InspectEvent converters, in-memory tree bridge, v0.2 fixtures, and docs. Manual trace writing remains schemaVersion 0.1; no storage or CLI behavior change.
+- 503d240: Correlation metadata, redaction profiles for share-safe exports, and LangChain streaming metadata support.
+
+## 1.3.0 — Unreleased
+
+### Added
+
+- Added correlation metadata on `inspectRun` / `maybeInspectRun` (`correlationId`, `requestId`, `decisionId`, `groupId`) and `getCurrentCorrelationMetadata()`.
+- Added redaction profiles (`local`, `share`, `strict`) for trace safety and share-safe exports.
+- Added `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- Added `--redaction-profile` to `agent-inspect export`.
+- Added LangChain streaming metadata support (`stream: true`) for token chunk counts and duration.
+- Added bounded preview behavior for preview capture mode (`maxStreamPreviewChars`).
+
+### Notes
+
+- LangChain `capture: "metadata-only"` remains default; full stream text is not captured by default.
+- LangChain streaming does not emit per-token JSONL events.
+- Redaction profiles are key-based safeguards, not compliance-grade PII detection.
+- Export redaction does not upload anywhere and does not mutate original traces.
+- No vendor upload, hosted dashboard, or OTLP HTTP sink was added.
+- Manual trace writing remains `schemaVersion: "0.1"`; v0.2 is not written by default.
+
+## 1.2.0
 
-## 1.2.0 — Unreleased
+Released **2026-06-11**. Changeset `5a7f785`.
 
 ### Added
 

package/README.md

@@ -20,7 +20,7 @@ agent-inspect gives those runs **structure**: an **execution tree** you can read
 
 ## Install
 
-Current npm release: **1.1.0**.
+Current npm release: **1.2.0**.
 
 ```bash
 npm install agent-inspect
@@ -159,12 +159,12 @@ Full flags and behavior: [docs/CLI.md](docs/CLI.md).
 - See **which step dominated latency** in a multi-step planner or RAG pipeline.
 - **Diff two runs** after a prompt, model, or routing change (see [diff examples](docs/DIFF.md)).
 - Point **`logs`** / **`tail`** at existing job or service logs to get a **local execution view** without shipping data upstream.
-- **Export** a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.
+- **Export** a run to Markdown for a PR, postmortem, or internal thread — use `--redaction-profile share` for share-safe copies, then review before sharing.
 - Keep traces **on disk** while still using enterprise observability elsewhere.
 
 ## Stable foundation (AgentInspect 1.x)
 
-**agent-inspect 1.x** (current: **1.1.0**) stabilizes the **local debugging foundation**:
+**agent-inspect 1.x** (current: **1.2.0**) stabilizes the **local debugging foundation**:
 
 - Instrument a run with `inspectRun` and `step`
 - Write **local JSONL traces** (`schemaVersion: "0.1"` — compatibility retained)
@@ -186,6 +186,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 - Optional **`@agent-inspect/langchain`** callback adapter
 - Optional **`@agent-inspect/tui`** terminal viewer
 - **Fixtures** and **recipes** for deterministic checks and adoption patterns
+- **v1.2.0** — experimental persisted-event foundation (`PersistedInspectEvent`, converters, in-memory tree bridge) for future source-agnostic local inspection. Manual trace writing remains **`schemaVersion: "0.1"`**; v0.2 is **not written by default**; CLI behavior unchanged; no vendor upload.
 
 **Honest boundaries:** programmatic log parsing, export, and diff APIs; LangChain and TUI programmatic surfaces; and OpenInference/OTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.
 
@@ -193,7 +194,7 @@ Pass `enabled: false` to `inspectRun` for a no-trace passthrough. Use `maybeInsp
 
 ### LangChain callback adapter (`@agent-inspect/langchain`)
 
-Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
+Optional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. Optional **`stream: true`** records chunk counts and stream duration **without storing full token text by default**. The LangChain adapter ships with 1.x; its programmatic API remains experimental and may evolve independently of the stable core tracing API.
 
 ```bash
 pnpm add agent-inspect @agent-inspect/langchain @langchain/core
@@ -286,7 +287,7 @@ For a detailed comparison, see [Compare with other tools](docs/COMPARE.md).
 - [Compare with other tools](docs/COMPARE.md)
 - [Security](SECURITY.md)
 - [Safe trace sharing checklist](docs/SAFE-TRACE-SHARING.md)
-- [Changelog](CHANGELOG.md)
+- [Changelog](CHANGELOG.md) — **upcoming [1.3.0](CHANGELOG.md#130--unreleased)** on `main` (not yet on npm): correlation metadata, share-safe export profiles, LangChain streaming metadata
 - [Known issues](docs/KNOWN-ISSUES.md)
 - [Limitations](docs/LIMITATIONS.md)
 - [Screenshot checklist (planned assets)](docs/SCREENSHOTS.md)

package/docs/ADAPTERS.md

@@ -8,6 +8,7 @@ AgentInspect is framework-agnostic at its core, but can optionally integrate wit
   - **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
+  - **Optional streaming metadata** (`stream: true`) — chunk counts, timing, and bounded previews only; **no full token stream** captured by default
   - **No monkey-patching**, **no vendor sinks**, **no network upload**
 - **Interactive TUI** (optional): `@agent-inspect/tui`
   - Documented as **experimental** in `docs/API.md`
@@ -36,7 +37,27 @@ npx agent-inspect list --dir ./.agent-inspect
 npx agent-inspect view <run-id> --dir ./.agent-inspect
 ```
 
+### LangChain streaming metadata (v1.3.0+)
+
+When `stream: true` on `AgentInspectCallback`:
+
+- `handleLLMNewToken` updates **in-memory streaming stats** only (no per-token JSONL lines).
+- On LLM end/error, metadata such as `chunkCount`, `firstChunkAt`, `lastChunkAt`, `streamDurationMs`, and `streamedCharCount` attach to the LLM completion event.
+- **`capture: "metadata-only"`** (default) does **not** store token text.
+- **`capture: "preview"`** may include a **bounded** `streamPreview` via `maxStreamPreviewChars` (defaults to `maxPreviewChars`).
+- With **`persist: true`**, streaming metadata is written on the LLM `step_started` metadata at completion time (deferred write for streaming LLM steps).
+- Inspect persisted runs locally: `agent-inspect list`, `view`, `export --redaction-profile share`.
+
+```ts
+const callback = new AgentInspectCallback({
+  stream: true,
+  capture: "metadata-only",
+  persist: true,
+});
+```
+
 See also:
 - `docs/MIGRATION.md` (what changed from early versions)
-- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `traceDir`)
+- `docs/API.md` (LangChain adapter options: `persist`, `capture`, `stream`, `traceDir`)
+- `docs/SAFE-TRACE-SHARING.md` (review exports before sharing)
 

package/docs/API.md

@@ -26,16 +26,21 @@ 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). **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).
+  - **`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). **`redact: false` wins** over `redactionProfile` for trace writing.
+  - **`redactionProfile`**: optional preset — `local` (default), `share`, or `strict`. Adds extra key-based redaction and tighter metadata string bounds for trace writing. Key-based only — not compliance-grade DLP.
   - **`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.
+  - **Correlation metadata (v1.3.0+):** optional `correlationId`, `requestId`, `decisionId`, and `groupId` strings. When set, they are written on `run_started.metadata` (not on every step). Top-level correlation options override the same keys in `options.metadata`. Useful for eval cases, CI job IDs, request tracing, and future stats/cohort views. They are **metadata only** — they do not replace `runId`. Treat sensitive IDs as trace data before sharing exports.
 - **`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`.
+- **`getCurrentCorrelationMetadata()`**: returns active run correlation fields (`correlationId`, `requestId`, `decisionId`, `groupId`) inside `inspectRun` / `maybeInspectRun`; `undefined` outside a traced run or when none were set.
+- **`RedactionProfile`**: `"local" | "share" | "strict"` — see `redactionProfile` on `InspectRunOptions` and `ExportOptions`.
+- **`resolveRedactionProfile(profile?)`**: resolves profile extra keys and metadata caps (for advanced integrations).
 
 ## 3. Stable local inspection APIs
 
@@ -95,7 +100,8 @@ The CLI `tail` workflow is supported. The programmatic accumulator is experiment
 
 Exports are **read-only**, **local-only**, and **compatibility-oriented**. They do not upload, stream, or integrate vendor SDKs.
 
-- **`exportRunTree`**
+- **`exportRunTree`**, **`redactRunTreeForExport`**
+- **`ExportOptions.redactionProfile`**: `local` (default), `share`, or `strict` — applies key-based redaction to an exported copy without mutating the source tree.
 - **`exportMarkdown`**, **`exportHtml`**
 - **`exportOpenInference`** (OpenInference-compatible JSON)
 - **`exportOtlpJson`** (OTLP JSON, experimental until verified per backend)
@@ -119,6 +125,8 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
   - **`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)
+  - **`stream`**: default `false` — when `true`, records streaming lifecycle metadata (`chunkCount`, `streamDurationMs`, etc.) on LLM end/error; does **not** capture full token text by default
+  - **`maxStreamPreviewChars`**: bounds `streamPreview` when `capture: "preview"` and `stream: true` (defaults to `maxPreviewChars`)
   - **`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
@@ -160,7 +168,7 @@ Related types: `PersistedInspectEvent`, `PersistedEventSourceType`, `PersistedEv
 
 ## 12. Deprecated APIs
 
-No deprecated APIs are declared as of 1.1.0.
+No deprecated APIs are declared as of 1.2.0.
 
 ## 13. Removal / deprecation policy
 

package/docs/ARCHITECTURE.md

@@ -19,7 +19,7 @@ Root `agent-inspect` uses **conditional exports** for ESM/CJS TypeScript consume
 - 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.
-- **v1.2.0 persisted-event foundation (release-readiness):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are future work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.2.0-RELEASE-READINESS.md](./implementation/V1.2.0-RELEASE-READINESS.md).
+- **v1.2.0 persisted-event foundation (released):** source-agnostic `PersistedInspectEvent` helpers (`schemaVersion: "0.2"`) — types, validators, converters, and in-memory tree bridge. Existing **`TreeBuilder`** remains the canonical tree builder. v0.2 bridge works **in memory only**; storage dual-read and CLI integration are v1.3+ / post-foundation work. See [proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md](./proposals/UNIFIED-PERSISTED-INSPECT-EVENT.md) and [implementation/V1.3.0-RELEASE-TRAIN.md](./implementation/V1.3.0-RELEASE-TRAIN.md).
 
 See [SCHEMA.md](./SCHEMA.md) for field reference and [API.md](./API.md) for public surfaces (stable vs experimental).
 

package/docs/CLI.md

@@ -1,4 +1,4 @@
-# CLI (AgentInspect 1.0)
+# CLI (AgentInspect 1.x)
 
 This document describes the **stable CLI surface** of AgentInspect.
 
@@ -178,6 +178,14 @@ Options:
 - `--include-attributes`: include bounded attributes (review before sharing)
 - `--no-metadata`: omit summary/metadata sections
 - `--no-errors`: omit error sections
+- `--redaction-profile <profile>`: redaction profile for exported copies — `local` (default), `share`, or `strict`. Key-based safety only; review exports before sharing.
+
+Examples:
+
+```bash
+npx agent-inspect export <run-id> --format markdown --redaction-profile share
+npx agent-inspect export <run-id> --format html --redaction-profile strict
+```
 
 ### 6.7 `diff`
 

package/docs/EXPORTS.md

@@ -6,6 +6,20 @@ AgentInspect supports local-only exports from run trees and traces. Exports are
 - **Schema + compatibility guarantees**: `docs/SCHEMA.md`
 - **Safety / redaction notes**: `docs/CLI.md`, `SECURITY.md`, and `docs/SCHEMA.md` (redaction section)
 
+## Share-safe exports (v1.3.0+)
+
+Use `--redaction-profile share` (PRs, issues, internal threads) or `strict` (external sharing) when generating an export copy:
+
+```bash
+agent-inspect export <run-id> --format markdown --redaction-profile share
+```
+
+- Profiles are **key-based** redaction presets — not compliance-grade PII detection.
+- Export redaction operates on a **copy** of the run tree; original JSONL traces on disk are **not mutated**.
+- **Review** every export before posting — especially when `--include-attributes` is set.
+
+See [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
+
 Notes:
 - Export formats (Markdown/HTML/OpenInference/OTLP JSON) are documented as **experimental / compatibility-oriented** in `docs/API.md`.
 - AgentInspect does **not** upload anywhere; exports write local strings/files only.

package/docs/LIMITATIONS.md

@@ -9,12 +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).
@@ -23,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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-first execution-tree debugger for TypeScript AI agents",