agent-inspect 6.8.0 → 6.10.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.10.0
+
+### Minor Changes
+
+- 3d21e87: Portable Evidence v2: versioned evidence.json manifest (independent of trace schema), self-contained evidence.html with tree/timeline/causal/contract/diff/safety views, directory/html/zip bundle formats, bundle verify, CI artifacts/reporter evidence kind, XSS/a11y corpus, and packed E2E. No schema break; no new root/core dependencies; no default network upload; redaction defaults not weakened.
+
+## 6.9.0
+
+### Minor Changes
+
+- 627f5f4: Safety precision and share policy: additive finding taxonomy, path-aware raw-content and detector precision, framework metadata sensitivity, source-vs-artifact verify-safe/bundle/MCP gating, --explain, and local override docs. No schema break; no new root/core dependencies; no default network upload; defaults not weakened.
+
 ## 6.8.0
 
 ### Minor Changes

package/README.md

@@ -131,7 +131,7 @@ Details: [Safe sharing](https://github.com/rajudandigam/agent-inspect/blob/main/
 
 ## Project status
 
-**Current release:** **6.8.0** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
+**Current release:** **6.10.0** (eighteen linked npm packages). Technical launch candidate; external pilot evidence pending. Persisted schema **1.0**. Node.js **≥ 20**. **v7 not scheduled.**
 
 [Roadmap](ROADMAP.md) · [Pilot kit](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PRE-V7-PILOT-KIT.md) · [Changelog](CHANGELOG.md)
 

package/docs/BUNDLES.md

@@ -2,6 +2,8 @@
 
 AgentInspect **bundles** are local, offline folders you can attach to PRs, incident threads, or internal reviews. They combine redacted trace copies, HTML reports, safety check results, and a human summary — without mutating source traces or calling the network.
 
+Evidence v2 (6.10+) adds `evidence.html` + `evidence.json` (hashed integrity) on top of the existing layout. See [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md).
+
 ## Quick start
 
 ```bash
@@ -12,8 +14,16 @@ npx agent-inspect bundle <runId> --dir ./.agent-inspect
 npx agent-inspect bundle --session <sessionId> --dir ./.agent-inspect
 npx agent-inspect bundle --since 24h --profile strict --dir ./.agent-inspect
 
-# Explicit output folder (.zip suffix is stripped — folder-first MVP)
+# Explicit output folder (directory mode strips a bare .zip suffix)
 npx agent-inspect bundle <runId> --out ./my-bundle --json
+
+# Formats
+npx agent-inspect bundle <runId> --format directory --out ./my-bundle
+npx agent-inspect bundle <runId> --format html --out ./evidence-html
+npx agent-inspect bundle <runId> --format zip --out ./my-bundle.zip
+
+# Integrity check (Evidence v2 directory)
+npx agent-inspect bundle verify ./my-bundle
 ```
 
 When a workspace exists, default output goes under `.agent-inspect/bundles/`.
@@ -21,15 +31,17 @@ When a workspace exists, default output goes under `.agent-inspect/bundles/`.
 ## Bundle layout
 
 ```text
+evidence.html              # offline Evidence v2 report (primary review surface)
+evidence.json              # Evidence v2 manifest + SHA-256 file hashes
 trace.html                 # offline HTML (index for multi-run)
 trace.jsonl                # redacted JSONL copy
 summary.md                 # human overview
-metadata.json              # manifest (version, profile, safe status)
+metadata.json              # legacy manifest (version, profile, safe status)
 check-results.json         # verify-safe results per run
 redaction-report.json      # detector summary (no secret values)
 eval-results.json          # placeholder unless eval artifacts are added later
 performance-summary.json   # placeholder unless perf artifacts are added later
-assets/runs/<runId>.*      # per-run HTML + JSONL mirrors
+assets/runs/<safeRunId>.*  # per-run HTML + JSONL mirrors (safe filenames)
 ```
 
 ## Safety defaults
@@ -37,8 +49,8 @@ assets/runs/<runId>.*      # per-run HTML + JSONL mirrors
 | Setting | Default |
 | ------- | ------- |
 | Redaction profile | `share` |
-| verify-safe | Runs automatically before write |
-| UNSAFE traces | Command fails unless `--allow-unsafe` |
+| verify-safe | Runs automatically on the **redacted artifact** before write |
+| UNSAFE / UNKNOWN artifact | Command fails unless `--allow-unsafe` |
 | Source traces | Read-only; never modified |
 
 Profiles:
@@ -52,16 +64,26 @@ Profiles:
 | Need | Command |
 | ---- | ------- |
 | One redacted file | `redact` |
-| Safety scan only | `verify-safe` |
-| CI artifact set | `artifacts` |
+| Safety scan only | `verify-safe` / `scan` |
+| CI artifact set (+ evidence on failure) | `artifacts` |
 | PR-ready evidence folder | **`bundle`** |
+| Integrity check | **`bundle verify`** |
 
 ## Review before sharing
 
-Bundles are **derived copies**, not compliance certification. Always review `summary.md`, `check-results.json`, and `trace.html` before attaching to tickets or PRs.
+Bundles are **derived copies**, not compliance certification. Always review `evidence.html` / `summary.md`, `check-results.json`, and run `bundle verify` before attaching to tickets or PRs.
 
 See also [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) and [CLI.md §6.24](./CLI.md#624-bundle).
 
+## Review workflow
+
+```text
+capture → check → redact → verify-safe → bundle → bundle verify → attach to PR/incident
+```
+
+Broken vs fixed demo fixtures: [`fixtures/evidence/demo/`](../fixtures/evidence/demo/).
+
 ## RFC
 
-Design details: [proposals/SHAREABLE-BUNDLES-V4.3.md](./proposals/SHAREABLE-BUNDLES-V4.3.md).
+- Shareable bundles (v4.3): [proposals/SHAREABLE-BUNDLES-V4.3.md](./proposals/SHAREABLE-BUNDLES-V4.3.md)
+- Portable Evidence v2: [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md)

package/docs/CI-ARTIFACTS.md

@@ -28,13 +28,22 @@ AgentInspect helps you **write and export traces locally** in CI. Uploading arti
 
 Prefer **`--redaction-profile share`** for internal PR/issue attachments; use **`strict`** for wider sharing.
 
-For a deterministic CI bundle with structural JSON, safe Markdown/HTML summaries, safety check output, optional baseline diff output, and optional GitHub step-summary output:
+For a deterministic CI bundle with structural JSON, safe Markdown/HTML summaries, safety check output, optional baseline diff output, optional Evidence v2 package on failure, and optional GitHub step-summary output:
 
 ```bash
 npx agent-inspect artifacts <run-id> --dir ./.agent-inspect \
   --output-dir ./artifacts --github-summary "$GITHUB_STEP_SUMMARY"
 ```
 
+On check failure (default), this also writes Evidence v2 files matching `bundle`:
+
+- `evidence.html`
+- `evidence.json`
+- `check-results.json`
+- `trace.jsonl` (redacted)
+
+Success stays quiet for evidence unless you pass `--always-evidence`. Disable with `--no-evidence`.
+
 This command writes local files only. It does not call GitHub APIs or upload artifacts.
 
 For Vitest/Jest reporter artifacts, summarize shared `schemaVersion: "0.1"` reporter manifests without reading trace contents:

package/docs/CLI.md

@@ -457,16 +457,19 @@ agent-inspect verify-safe <trace-path-or-run-id> [options]
 Statuses:
 
 - `SAFE`: no safety findings and no reader warnings.
-- `SAFE WITH WARNINGS`: no safety findings, but the reader reported warnings or unsupported fields.
-- `UNSAFE`: safety findings were detected.
+- `SAFE WITH WARNINGS`: no blocking safety findings, but warnings (reader or findings) remain.
+- `UNSAFE`: blocking safety findings were detected.
 - `UNKNOWN`: the input could not be read, normalized, or selected conservatively.
 
+`verify-safe` assesses the **source** trace and a **share-redacted artifact**. The printed/exit `status` follows the **artifact** assessment when a single-file (or stdin) artifact can be derived. `scan` remains source-oriented.
+
 Options:
 
 - `--dir <path>`: trace directory for run-id lookup
 - `--format <agent-inspect-jsonl|openinference-json|otlp-json>`: explicit reader format override
 - `--run <run-id>`: select a run when input contains multiple runs
 - `--json`: print deterministic JSON safety result
+- `--explain`: explain each finding (detector/path/category/confidence/redaction/override/bundle gate) without printing matched secret values
 - `--max-string-length <number>`: unsafe threshold for string values
 - `--max-array-length <number>`: unsafe threshold for array values
 - `--max-object-keys <number>`: unsafe threshold for object key counts
@@ -474,11 +477,15 @@ Options:
 
 The scan looks for raw prompt/output-like capture paths, unredacted sensitive-looking keys, secret-like string patterns, and oversized values. It reports evidence paths rather than raw prompt, output, request/response, header, API key, secret, or full tool payload values. Secret detection is best-effort and should not be treated as exhaustive.
 
+Policy and overrides: [SAFETY-POLICY.md](SAFETY-POLICY.md).
+
 Examples:
 
 ```bash
 npx agent-inspect scan fixtures/traces-v0.2/manual-basic.jsonl --json
+npx agent-inspect scan trace.jsonl --explain
 npx agent-inspect verify-safe minimal-success --dir fixtures/traces
+npx agent-inspect verify-safe trace.jsonl --explain --json
 npx agent-inspect verify-safe trace.jsonl --max-string-length 8192 --json
 ```
 
@@ -866,7 +873,7 @@ If `@agent-inspect/index-sqlite` is not installed, these subcommands print a sho
 
 ### 6.24 `bundle`
 
-Create a **share-safe offline trace bundle** as a local folder (v4.3+). Bundles are derived copies: original traces are read-only and never mutated. Automatic `verify-safe` runs before write; the command fails on `UNSAFE` unless `--allow-unsafe`. See [BUNDLES.md](BUNDLES.md).
+Create a **share-safe offline trace bundle** (v4.3+ / Evidence v2). Bundles are derived copies: original traces are read-only and never mutated. Automatic safety assessment runs on the **redacted artifact** before write; the command fails when the artifact is `UNSAFE`/`UNKNOWN` unless `--allow-unsafe`. Source-only findings that redaction removes do not refuse the bundle. See [BUNDLES.md](BUNDLES.md), [EVIDENCE-FORMAT.md](EVIDENCE-FORMAT.md), and [SAFETY-POLICY.md](SAFETY-POLICY.md).
 
 ```bash
 agent-inspect bundle <run-id> [options]
@@ -880,10 +887,19 @@ Options:
 - `--session <session-id>` — bundle all runs in a session
 - `--since <duration>` — bundle runs with activity since a window (e.g. `24h`, `7d`)
 - `--profile <profile>` — `local`, `share` (default), or `strict` redaction for exported copies (`--redaction-profile` is the canonical alias)
-- `--out <path>` — output directory; `.zip` suffix is stripped (folder-first; `--output` is the canonical alias)
+- `--format <format>` — `directory` (default), `html` (evidence.html + evidence.json sidecar), or `zip` (local archive)
+- `--out <path>` — output directory, `.html` path, or `.zip` path; directory mode still strips a bare `.zip` suffix to a folder (`--output` is the canonical alias)
 - `--allow-unsafe` — write bundle even when verify-safe reports UNSAFE
 - `--json` — print deterministic JSON manifest
 
+Verify an Evidence v2 directory:
+
+```bash
+agent-inspect bundle verify <path> [--unexpected fail|warn|ignore] [--json]
+```
+
+Checks manifest schema, listed-file presence, SHA-256 hashes, unexpected files (default fail), assessment, and generator provenance. Unpack ZIP archives before verify.
+
 Output includes `trace.html`, `trace.jsonl`, `summary.md`, `metadata.json`, `check-results.json`, `redaction-report.json`, and `assets/runs/` mirrors for multi-run bundles.
 
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "license": "MIT",
   "type": "module",
   "description": "Debug, regression-test, and safely share TypeScript AI-agent behavior locally — no account, no default upload, metadata-only by default",