agent-inspect 1.2.0 → 1.4.0

package/docs/GETTING-STARTED.md

@@ -60,6 +60,24 @@ 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.
 
+### Correlation metadata (v1.3.0+)
+
+Attach optional correlation fields to `run_started` metadata — useful for eval cases, CI job IDs, and future stats views. They are **metadata only**, not run IDs. Review before sharing exports.
+
+```ts
+await inspectRun(
+  "support-agent",
+  async () => runAgent(),
+  {
+    correlationId: "eval-suite-2026-06",
+    requestId: "req-abc123",
+    groupId: "ci-job-42",
+  }
+);
+```
+
+Inside a traced run, adapters can read active fields via `getCurrentCorrelationMetadata()`.
+
 ### 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).
@@ -109,7 +127,14 @@ agent-inspect export minimal-success --dir fixtures/traces --format markdown
 agent-inspect export minimal-success --dir fixtures/traces --format openinference --validate
 ```
 
-Exports are **local-only** and do not upload anywhere.
+Share-safe copy for a PR or issue (v1.3.0+):
+
+```bash
+agent-inspect export minimal-success --dir fixtures/traces \
+  --format markdown --redaction-profile share
+```
+
+Exports are **local-only** and do not upload anywhere. Review output before sharing — see [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md).
 
 ## 8. Diff two runs
 
@@ -151,6 +176,9 @@ agent-inspect view <runId> --tui
 - [docs/API.md](./API.md)
 - [docs/CLI.md](./CLI.md)
 - [docs/SCHEMA.md](./SCHEMA.md)
+- [docs/EXPORTS.md](./EXPORTS.md)
+- [docs/SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md)
+- [docs/ADAPTERS.md](./ADAPTERS.md)
 - [docs/LOGGING-PLAYBOOK.md](./LOGGING-PLAYBOOK.md)
 - [docs/COMPARE.md](./COMPARE.md)
 - [docs/LOG-TO-TREE-QUICKSTART.md](./LOG-TO-TREE-QUICKSTART.md)

package/docs/KNOWN-ISSUES.md

@@ -16,6 +16,12 @@ AgentInspect is **local-first** and **CLI-first**. These behaviors are intention
 
 - **Vendor sinks** (hosted dashboards, Langfuse/Braintrust/New Relic/Datadog native uploads, OTLP gRPC streaming, etc.) are **not implemented** in the core packages described here.
 - **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.
+
+## Structured log parsing
+
+- Ingest requires **line-delimited JSON** or a **recoverable JSON payload** in the log line (log4js-style is best-effort). Arbitrary printf-style text without JSON is not supported.
 
 ## UI / replay
 

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)
+
+- **`list` / `view` / `export`** do not filter by correlation fields yet — `stats --correlation-id` / `--group-id` and `search` provide targeted read paths; full CLI filtering remains incremental.
+
 ## 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.
@@ -37,6 +48,12 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **No cost engine**: no pricing tables, invoice-grade usage, or provider billing reconciliation.
 
+## Local observability commands (v1.4.0)
+
+- **`timeline`**, **`stats`**, and **`search`** scan local JSONL files — no database index; large directories may be slow.
+- **`search`** is deterministic exact/contains matching only — no semantic or fuzzy search.
+- **`stats`** is local file aggregation — not production fleet analytics.
+
 ## Scale
 
 - Designed for **developer machines** and **inner-loop debugging**, not petabyte log warehouses.

package/docs/SCHEMA.md

@@ -1,4 +1,4 @@
-# Schema (AgentInspect 1.0)
+# Schema (AgentInspect 1.x)
 
 This document describes the **persisted manual trace JSONL schema** and the **log-derived normalized model** used by AgentInspect.
 
@@ -25,7 +25,7 @@ Manual trace events use:
 
 - **`schemaVersion: "0.1"`**
 
-Existing `0.1` traces remain readable in v1.0.
+Existing `0.1` traces remain readable across AgentInspect 1.x.
 
 ### 2.3 TraceEvent union
 
@@ -129,9 +129,11 @@ 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`.
+- **Redaction profiles (v1.3.0+):** optional `redactionProfile` (`local`, `share`, `strict`) adds preset extra keys and tighter metadata bounds for trace writing. Key-based only — not compliance-grade DLP. `export --redaction-profile` applies profiles to export copies without mutating source JSONL.
 - **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
@@ -149,7 +151,7 @@ Manual trace reading:
 
 ## 9. Backward compatibility
 
-- v0.1 JSONL traces remain readable in v1.0.
+- v0.1 JSONL traces remain readable across AgentInspect 1.x.
 - No automatic migrations or rewriting of old files.
 
 ## 10. Breaking change policy
@@ -234,7 +236,7 @@ Canonical samples: `fixtures/traces-v0.2/*.jsonl` (validated by `pnpm fixtures:c
 | `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).
+Programmatic helpers: see [API.md](./API.md) §11 (experimental persisted-event foundation).
 
 ## 15. Migration notes
 

package/package.json

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