agent-inspect 6.17.0 → 6.17.2

package/docs/SCREENSHOTS.md

@@ -1,231 +1,62 @@
-# Visual demos
+# Demos and screenshots
 
-Curated terminal recordings and static diagrams for AgentInspect **6.7.x**. They show local capture → inspect → enforce → verify/bundle — without a maintainer-hosted dashboard or vendor upload.
+Curated terminal recordings and diagrams for AgentInspect **6.17.x**. They show **Debug / Prevent / Share** from one local trace — without a maintainer-hosted dashboard or vendor upload.
 
-**Synthetic output only:** demos use committed [fixtures](../fixtures/README.md), [examples](../examples/README.md), and recipes. No external LLM calls or API keys.
+**Synthetic output only:** demos use committed [fixtures](../fixtures/README.md), [examples](../examples/README.md), and the [broken-agent-debugging](../examples/starters/broken-agent-debugging/) showcase. No external LLM calls or API keys.
 
-**npm note:** GIFs live in `docs/assets/demos/` for GitHub documentation. They are **not** shipped in the `agent-inspect` npm tarball. Brand SVGs used by the root README **are** included in the npm package.
+**npm note:** Showcase GIFs live in `docs/assets/showcase/` for GitHub documentation. They are **not** shipped in the `agent-inspect` npm tarball. Brand SVGs used by the root README **are** included in the npm package.
 
-**Re-record guide:** [assets/demos/RECORDING.md](assets/demos/RECORDING.md)
-**Maintainer audit:** [implementation/VISUAL-DEMO-AUDIT.md](implementation/VISUAL-DEMO-AUDIT.md)
-**Live demo script:** [DEMO-SCRIPT.md](DEMO-SCRIPT.md) (uses [broken-agent-debugging](../examples/starters/broken-agent-debugging/) starter)
+**Provenance:** [assets/showcase/provenance.json](assets/showcase/provenance.json)
 
----
-
-## README brand assets (6.7.x)
-
-| Asset | Use |
-| ----- | --- |
-| [agent-inspect-logo.svg](assets/agent-inspect-logo.svg) | Light-mode wordmark |
-| [agent-inspect-logo-dark.svg](assets/agent-inspect-logo-dark.svg) | Dark-mode wordmark |
-| [readme-product-loop.svg](assets/readme-product-loop.svg) | Capture → understand → enforce → verify/bundle → local/Studio |
-
-Root README embeds the logo and product-loop SVG only. Terminal GIFs stay below.
-
----
-
-## Adoption demo (6.7.x)
-
-Deterministic broken-agent flow — recommended for live demos.
-
-**Run:**
-
-```bash
-cd examples/starters/broken-agent-debugging
-pnpm install && pnpm start
-npx agent-inspect report <run-id> --dir .agent-inspect
-npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o safe.jsonl
-npx agent-inspect verify-safe <run-id> --dir .agent-inspect
-```
+**Re-record helper:** `node scripts/render-showcase-tapes.mjs` (requires ffmpeg + Python Pillow)
 
-**GIF status:** re-record optional; use [error-handling.gif](assets/demos/error-handling.gif) as b-roll until a dedicated broken-agent GIF exists.
+**Older recordings:** [assets/demos/RECORDING.md](assets/demos/RECORDING.md)
 
 ---
 
-## Start tracing
-
-Manual `inspectRun` / `step` traces written as local JSONL.
-
-### Quickstart (install → trace → view)
-
-![Quickstart: install, run a traced script, list and view the run](assets/demos/quickstart.gif)
-
-Run: [examples/00-quickstart-demo](../examples/00-quickstart-demo/README.md)  
-Also: [GETTING-STARTED.md](GETTING-STARTED.md)
-
-### Nested execution tree
-
-![Nested steps rendered as an execution tree in the terminal](assets/demos/execution-tree.gif)
-
-Run: [examples/02-nested-steps](../examples/02-nested-steps/README.md)  
-Command: `agent-inspect view <run-id> --dir <trace-dir>`
-
-### Parallel sibling steps
-
-![Parallel tool steps under one parent in the execution tree](assets/demos/parallel-execution.gif)
-
-Run: [examples/03-parallel-steps](../examples/03-parallel-steps/README.md)
+## README showcase (6.17.x)
 
-### Error handling
-
-![Failed step recorded on step_completed with status error](assets/demos/error-handling.gif)
-
-Run: [examples/04-error-handling](../examples/04-error-handling/README.md)
-
-### `observe()` wrapper
-
-![observe() wrapper tracing an agent-like object](assets/demos/observe-wrapper.gif)
-
-Run: [examples/05-observe-wrapper](../examples/05-observe-wrapper/README.md) · API: [API.md](API.md)
-
-### Env-gated tracing (`maybeInspectRun`)
-
-![AGENT_INSPECT=1 toggles tracing; unset leaves no trace files](assets/demos/env-gated-tracing.gif)
+| Asset | Job |
+| ----- | --- |
+| [debug-tree.gif](assets/showcase/gif/debug-tree.gif) | Debug — `list` then inspect a local run |
+| [check-pass-fail.gif](assets/showcase/gif/check-pass-fail.gif) | Prevent — `check --preset trajectory` plus shorthands, pass then fail |
+| [evidence-bundle.gif](assets/showcase/gif/evidence-bundle.gif) | Share — `bundle --profile share` then `bundle verify` (relative `./evidence`) |
+| [value-loop.svg](assets/showcase/diagrams/value-loop.svg) | Capture once → debug, prevent, share |
 
-Docs: [GETTING-STARTED.md](GETTING-STARTED.md) · [API.md](API.md) (`maybeInspectRun`)
+The check tape is named for the `check` command, not `gate`.
 
 ---
 
-## Use existing logs
-
-Turn structured logs you already emit into a **local** grouped timeline or tree.
+## Full six-flow set
 
-### JSON logs → tree
+| Flow | GIF | Video |
+| ---- | --- | ----- |
+| Debug tree / list | [debug-tree.gif](assets/showcase/gif/debug-tree.gif) | [debug-tree.webm](assets/showcase/video/debug-tree.webm) |
+| Check pass/fail | [check-pass-fail.gif](assets/showcase/gif/check-pass-fail.gif) | [check-pass-fail.webm](assets/showcase/video/check-pass-fail.webm) |
+| Evidence bundle | [evidence-bundle.gif](assets/showcase/gif/evidence-bundle.gif) | [evidence-bundle.webm](assets/showcase/video/evidence-bundle.webm) |
+| Explain | [explain.gif](assets/showcase/gif/explain.gif) | [explain.webm](assets/showcase/video/explain.webm) |
+| Redact (derived copy) | [redact.gif](assets/showcase/gif/redact.gif) | [redact.webm](assets/showcase/video/redact.webm) |
 
-**Status:** animated demo pending re-record (staging asset had summary-count mismatch).  
-**Command:**
-
-```bash
-agent-inspect logs ./your.json.log \
-  --format json \
-  --run-id-key runId \
-  --event-key event \
-  --timestamp-key timestamp
-```
-
-Run: [examples/06-log-to-tree](../examples/06-log-to-tree/README.md) · [LOGS.md](LOGS.md) · [LOG-TO-TREE-QUICKSTART.md](LOG-TO-TREE-QUICKSTART.md)
-
-### Live tail
-
-**Status:** animated demo pending re-record.  
-**Command:** `agent-inspect tail <log-file> [mapping flags]` — see [LOGS.md](LOGS.md).
-
-### log4js (best-effort)
-
-**Status:** pending re-record. Documented in [LOGS.md](LOGS.md); recipe: [log4js-json-layout](../examples/recipes/log4js-json-layout/README.md).
+Rejected source tapes (not published): blank one-frame `docs/demo-kit/b77a3f11-….gif` (PNG mislabeled as GIF); kit `06-run-live.mp4` (not re-recorded from the canonical starter). Kit MP4s that printed `/private/tmp` or captioned `check` as `gate` were re-recorded.
 
 ---
 
-## Inspect and compare
-
-Read-only CLI over local JSONL traces.
-
-### Chronological timeline (`--focus slow`)
-
-![Timeline with slow-step focus highlighting longest steps](assets/demos/timeline.gif)
+## Canonical showcase commands
 
 ```bash
-agent-inspect timeline <run-id> --dir fixtures/traces --focus slow
-```
-
-Docs: [CLI.md](CLI.md) § timeline
-
-### Local stats
-
-![Aggregate stats over a trace directory](assets/demos/stats.gif)
-
-```bash
-agent-inspect stats --dir fixtures/traces
-```
-
-Filter by correlation: `agent-inspect stats --correlation-id <id>` or `--group-id <id>`.  
-Docs: [CLI.md](CLI.md) § stats
-
-### Deterministic search
-
-![Search traces by status error](assets/demos/search.gif)
-
-```bash
-agent-inspect search --dir fixtures/traces --status error --limit 5
-```
-
-Docs: [CLI.md](CLI.md) § search
-
-### Diff two runs
-
-![Diff comparing success and error runs](assets/demos/diff-runs.gif)
-
-```bash
-agent-inspect diff minimal-success minimal-error --dir fixtures/traces
-```
-
-Docs: [DIFF.md](DIFF.md)
-
-### Markdown export
-
-![Export a run to Markdown locally](assets/demos/markdown-export.gif)
-
-```bash
-agent-inspect export minimal-success --dir fixtures/traces --format markdown
+cd examples/starters/broken-agent-debugging
+node demo-agent.mjs good
+npx agent-inspect list --dir .agent-inspect
+npx agent-inspect check demo-good --dir .agent-inspect \
+  --preset trajectory --required-tool retrieve_policy --fail-on-observation failed
+npx agent-inspect bundle demo-good --dir .agent-inspect --profile share --out ./evidence
+npx agent-inspect bundle verify ./evidence
 ```
 
-Docs: [EXPORTS.md](EXPORTS.md)
-
-### HTML / OpenInference / OTLP
-
-- **HTML:** rendered-report visual pending re-record; export command in [EXPORTS.md](EXPORTS.md).
-- **OpenInference / OTLP JSON:** compatibility-oriented local formats — see prose and `--validate` in [EXPORTS.md](EXPORTS.md), not dedicated GIFs.
-
----
-
-## Integrations and optional UI
-
-### LangChain persistence
-
-![LangChain callback with persist true writing inspectable JSONL](assets/demos/langchain-persistence.gif)
-
-Run: [examples/08-langchain-adapter](../examples/08-langchain-adapter/README.md) · [ADAPTERS.md](ADAPTERS.md)
-
-Streaming metadata (`stream: true`) demo pending re-record until `chunkCount` / `streamDurationMs` are non-null.
-
-### Optional TUI (`@agent-inspect/tui`)
-
-![Optional Ink TUI viewer for a local trace](assets/demos/tui-viewer.gif)
-
-Requires optional package: `pnpm add @agent-inspect/tui`  
-Command: `agent-inspect view <run-id> --tui`  
-Docs: [ADAPTERS.md](ADAPTERS.md)
+Stable run ids: `demo-good`, `demo-regression`, `demo-pii`.
 
 ---
 
-## Safety and sharing
-
-### Default metadata redaction
-
-![Sensitive metadata keys redacted before disk](assets/demos/redaction.gif)
-
-Profiles (`local` / `share` / `strict`) and export redaction: [SAFE-TRACE-SHARING.md](SAFE-TRACE-SHARING.md)
-
-### Event size bounds
-
-Described in [LIMITATIONS.md](LIMITATIONS.md) — no GIF (static explanation preferred).
-
-### Correlation metadata
-
-Described in [API.md](API.md) — optional `correlationId`, `requestId`, `decisionId`, `groupId` on `run_started`.
-
----
-
-## VS Code (v3.3)
-
-Read-only sidebar trace explorer backed by the `agent-inspect` CLI. Develop with F5 from `packages/vscode`.
-
-Guide: [VSCODE.md](VSCODE.md)
+## Earlier 6.7.x terminal GIFs
 
-- [x] Basic trace tree (`inspectRun` + `step`)
-- [x] Failed step rendering
-- [x] `agent-inspect logs` output (JSON) — **re-record pending**
-- [x] `agent-inspect diff` output
-- [x] Optional TUI (`view --tui`)
-- [x] `timeline`, `stats`, `search` (v1.4.0)
-- [x] VS Code read-only trace explorer (v3.3.0) — see [VSCODE.md](VSCODE.md); Marketplace GIF pending first publish
+The files under [assets/demos/](assets/demos/) remain available as additional command-level recordings (`quickstart.gif`, `execution-tree.gif`, `error-handling.gif`, …). Prefer the 6.17.x showcase above for README and website hero media. Log-to-tree and export HTML visuals still live in that older set.

package/docs/SUPPORT-LEVELS.md

@@ -1,6 +1,6 @@
 # Support levels
 
-Canonical maturity labels for AgentInspect public packages and major surfaces (6.16.x fixed release line).
+Canonical maturity labels for AgentInspect public packages and major surfaces (6.17.x fixed release line).
 
 ## Definitions
 
@@ -19,10 +19,11 @@ Canonical maturity labels for AgentInspect public packages and major surfaces (6
 | `agent-inspect` core schema, readers, writers, inspection CLI | Stable |
 | Redaction engine / `@agent-inspect/redact` | Stable |
 | Deterministic checks (`agent-inspect/checks`) | Stable |
-| Official adapters (ai-sdk, openai-agents, langchain) | Supported |
+| Official adapters (ai-sdk, openai-agents, langchain / LangGraph fidelity classes) | Supported |
 | Vitest / Jest reporters | Supported |
 | `@agent-inspect/harness` | Supported |
-| Workspace / bundles / observed outcomes | Supported |
+| Workspace / bundles / observed outcomes / Evidence v2 | Supported |
+| TraceFacts programmatic API | Beta |
 | TraceContract API | Beta |
 | Suites / cohorts / gates | Beta |
 | `@agent-inspect/index-sqlite` | Beta |
@@ -30,12 +31,22 @@ Canonical maturity labels for AgentInspect public packages and major surfaces (6
 | `@agent-inspect/adapter-sdk` / plugins | Beta |
 | `@agent-inspect/studio` | Beta |
 | Studio HTTP / GitHub ingest | Preview |
-| `@agent-inspect/mcp-server` | Preview |
+| `@agent-inspect/mcp-server` (read-only MCP) | Preview |
 | Standards round-trip / Collector–Phoenix external proof | Preview |
 | Vitest/Jest TraceContract matchers (`toPassTraceContract`, `toHaveRequiredTool`) | Experimental |
 
 Part of the fixed AgentInspect release line — see the npm badge for the current version.
 
+## Public package groups (presentation only)
+
+Physical packages stay the fixed group of 18. Outreach/install kits group them as:
+
+1. **Core kit** — `agent-inspect` (+ CLI)
+2. **Framework kit** — official adapters matching your stack
+3. **CI / Evidence kit** — checks, gates, reporters, Evidence v2 workflows
+
+See [INSTALL-KITS.md](./INSTALL-KITS.md).
+
 ## Compatibility promise
 
 - Persisted schema **1.0**; v0.1 / v0.2 / 1.0 traces remain readable
@@ -44,4 +55,4 @@ Part of the fixed AgentInspect release line — see the npm badge for the curren
 
 ## Promotion criteria
 
-A surface moves up only with tests, docs, packed smoke where relevant, and honest limitation disclosure — not changelog marketing alone.
+A surface moves up only with tests, docs, packed smoke where relevant, real-project or external retained use where required for Supported/Stable, and honest limitation disclosure — not changelog marketing alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.17.0",
+  "version": "6.17.2",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
@@ -240,8 +240,10 @@
     "docs:links": "node scripts/validate-doc-links.mjs",
     "public-truth:check": "node scripts/validate-public-truth.mjs",
     "ai-assets:check": "node scripts/validate-ai-assets.mjs",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run repo:health",
+    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run repo:health && pnpm run demo:verify",
     "repo:health": "node scripts/validate-repo-health.mjs",
+    "demo:generate": "node scripts/demo-generate.mjs",
+    "demo:verify": "node scripts/demo-verify.mjs",
     "compat:smoke": "node scripts/compat-smoke.mjs",
     "fixtures:check": "node scripts/validate-fixtures.mjs",
     "recipes:check": "node scripts/validate-recipes.mjs",

package/packages/cli/dist/{chunk-LFSBMUCD.mjs → chunk-FXGWXSFV.mjs}

@@ -6580,6 +6580,18 @@ function stringAttr(event, keys) {
   }
   return void 0;
 }
+function metadataStringAttr(event, keys) {
+  const metadata = event.attributes?.metadata;
+  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+    return void 0;
+  }
+  const record = metadata;
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return void 0;
+}
 function numericAttr(event, keys) {
   for (const key of keys) {
     const value = event.attributes?.[key];
@@ -6638,13 +6650,16 @@ function semanticEvents(context) {
   return context.logicalEvents ?? context.events;
 }
 function llmModel(event) {
-  return stringAttr(event, ["model", "modelId", "responseModelId", "modelName", "model_name"]) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
+  const keys = ["model", "modelId", "responseModelId", "modelName", "model_name"];
+  return stringAttr(event, keys) ?? metadataStringAttr(event, keys) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
 }
 function llmProvider(event) {
-  return stringAttr(event, ["provider", "providerName", "provider_name"]);
+  const keys = ["provider", "providerName", "provider_name"];
+  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
 }
 function llmFinishReason(event) {
-  return stringAttr(event, ["finishReason", "rawFinishReason", "finish_reason"]);
+  const keys = ["finishReason", "rawFinishReason", "finish_reason"];
+  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
 }
 function retryCount(event) {
   return numericAttr(event, ["retryCount", "retryAttempt", "retry_attempt", "attempt"]);
@@ -11321,5 +11336,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-LFSBMUCD.mjs.map
-//# sourceMappingURL=chunk-LFSBMUCD.mjs.map
+//# sourceMappingURL=chunk-FXGWXSFV.mjs.map
+//# sourceMappingURL=chunk-FXGWXSFV.mjs.map