agent-inspect 6.31.0 → 6.31.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.31.2
+
+### Patch Changes
+
+- 520c7c3: Clarify README Prevent path (trajectory without leading observation flags), AI SDK inspect/bundle commands, and Jest/Vitest explicit trace association in CI docs.
+
+## 6.31.1
+
+### Patch Changes
+
+- 11a0159: Strict `allowedStatuses` validation (typos like `succes` no longer map to permissive `error`); portable `prepublishOnly` skip runner for Trusted Publish; LangChain `handleChainStart` parentage matches CallbackManager runtime arg order.
+
 ## 6.31.0
 
 ### Minor Changes

package/README.md

@@ -74,10 +74,11 @@ Checks are deterministic and provider-free: the same trace and rules produce the
 ```bash
 npx agent-inspect check <run-id> --dir .agent-inspect \
   --preset trajectory \
-  --required-tool retrieve_policy \
-  --fail-on-observation failed
+  --required-tool retrieve_policy
 ```
 
+Use `--fail-on-observation failed` only when the run records explicit OUTCOME events (for example the [broken-agent-debugging starter](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging)). Trajectory checks do not invent outcomes from tool/LLM/run success.
+
 A passing check exits `0`; a rule failure exits `1`. Invalid configuration and unreadable/unsupported inputs use separate documented exit codes. Use TraceContract, suites, cohorts, Vitest/Jest reporters, or `--evidence-on fail` when the workflow needs more than one CLI check.
 
 ### Share — create reviewable offline evidence
@@ -212,7 +213,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.31.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.31.2** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
 Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 

package/docs/AI-SDK-ADOPTION.md

@@ -97,10 +97,15 @@ sensitive free text; redact before sharing. Full contract:
 
 ```bash
 npx agent-inspect list --dir .agent-inspect
-npx agent-inspect open .agent-inspect/<run>.jsonl
-npx agent-inspect check .agent-inspect/<run>.jsonl
+npx agent-inspect view <run-id> --dir .agent-inspect --summary
+npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
+npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
+npx agent-inspect bundle verify ./evidence
 ```
 
+Use `--fail-on-observation` only when the run records explicit OUTCOME events.
+
 ## Troubleshooting
 
 | Symptom | Fix |

package/docs/CI-ARTIFACTS.md

@@ -56,6 +56,8 @@ npx agent-inspect ci-summary .agent-inspect/jest-artifacts/tests/**/report.json
 
 `ci-summary` writes local files only. It validates reporter artifact paths as relative paths and includes bounded structural metadata: package/framework, test status counts, trace filenames, artifact paths, redaction profile, and diagnostic counts.
 
+**Jest / Vitest association:** reporters do **not** invent run↔test links from timestamps. Wire an explicit association (`withAgentInspectJestTrace`, reporter `associations` / `resolveTrace`, or the Vitest equivalents) or expect a `no-trace-association` diagnostic. See [`@agent-inspect/jest`](https://github.com/rajudandigam/agent-inspect/blob/main/packages/jest/README.md#trace-association) and [`@agent-inspect/vitest`](https://github.com/rajudandigam/agent-inspect/blob/main/packages/vitest/README.md).
+
 ```bash
 npx agent-inspect export <run-id> --dir ./.agent-inspect \
   --format markdown --redaction-profile share -o ./artifacts/trace.md

package/docs/COMPARE.md

@@ -120,7 +120,7 @@ AgentInspect avoids SDK/collector setup for local debugging:
 
 ## v3.5 positioning (local inner loop)
 
-AgentInspect v3.5 is the **adoption release**. The npm map is one core package (`agent-inspect`: APIs + CLI) plus optional packages that stay out of the root dependency graph: framework adapters (`ai-sdk`, `openai-agents`, `langchain`, `mcp`, `adapter-sdk`), CI and quality gates (`vitest`, `jest`, `eval`, `guardrails`, `circuit`, `harness`), and inspection surfaces (`viewer`, `tui`, `mcp-server`, `redact`). See the [package map](../README.md#package-map).
+AgentInspect v3.5 is the **adoption release**. The npm map is one core package (`agent-inspect`: APIs + CLI) plus optional packages that stay out of the root dependency graph: framework adapters (`ai-sdk`, `openai-agents`, `langchain`, `mcp`, `adapter-sdk`), CI and quality gates (`vitest`, `jest`, `eval`, `guardrails`, `circuit`, `harness`), and inspection surfaces (`viewer`, `tui`, `mcp-server`, `redact`). See the [package map](https://github.com/rajudandigam/agent-inspect#package-map).
 
 Use it when:
 

package/docs/FIRST-TRACE-IN-5-MINUTES.md

@@ -1,6 +1,6 @@
 # First trace in 5 minutes
 
-Goal: install → one trace → one check → one share-safe bundle.
+Goal: install → one trace → one trajectory check → one share-safe Evidence bundle.
 
 **Docs site:** [https://agentinspect.vercel.app/docs/getting-started/](https://agentinspect.vercel.app/docs/getting-started/)
 
@@ -14,12 +14,15 @@ npx agent-inspect list --dir .agent-inspect
 Copy a `<run-id>` from `list`, then:
 
 ```bash
-npx agent-inspect report <run-id> --dir .agent-inspect
-npx agent-inspect check <run-id> --dir .agent-inspect
-npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
+npx agent-inspect view <run-id> --dir .agent-inspect --summary
+npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
 npx agent-inspect verify-safe <run-id> --dir .agent-inspect
+npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
+npx agent-inspect bundle verify ./evidence
 ```
 
+`init` scaffolds files into the current directory (`agent-inspect.config.ts`, `.agent-inspect/`, and `examples/agent-inspect-demo.mjs`). It does **not** install dependencies or write a trace by itself. Use `--preset trajectory` for structural CI gates; `--fail-on-observation` belongs only in examples that record explicit OUTCOME events.
+
 ## Minutes 0–1: Install
 
 ```bash
@@ -28,9 +31,6 @@ npm install agent-inspect
 npx agent-inspect init --yes
 ```
 
-Creates `agent-inspect.config.ts`, `.agent-inspect/`, and `examples/agent-inspect-demo.mjs`.  
-`init` scaffolds files; it does **not** write a trace by itself.
-
 Framework users: pick the correct capture path first — [CHOOSE-YOUR-CAPTURE-PATH.md](./CHOOSE-YOUR-CAPTURE-PATH.md).
 
 ## Minutes 1–2: Run
@@ -39,33 +39,36 @@ Framework users: pick the correct capture path first — [CHOOSE-YOUR-CAPTURE-PA
 node examples/agent-inspect-demo.mjs
 ```
 
-No API keys. Deterministic local trace.
+No API keys. Deterministic local trace under `.agent-inspect/`.
 
 ## Minutes 2–3: Inspect
 
 ```bash
 npx agent-inspect list --dir .agent-inspect
-npx agent-inspect view <run-id> --dir .agent-inspect
-npx agent-inspect report <run-id> --dir .agent-inspect
+npx agent-inspect view <run-id> --dir .agent-inspect --summary
 ```
 
+Replace `<run-id>` with the ID printed by `list` (do not guess “latest file”).
+
 ## Minutes 3–4: Check
 
 ```bash
-npx agent-inspect check <run-id> --dir .agent-inspect
+npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
 ```
 
+Expected exit code `0` for the keyless demo. Add `--required-tool <name>` only when that tool is part of the real expected workflow.
+
 ## Minutes 4–5: Share-safe artifact
 
 ```bash
-npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
 npx agent-inspect verify-safe <run-id> --dir .agent-inspect
-npx agent-inspect bundle verify .agent-inspect/bundles/<run-id>
+npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
+npx agent-inspect bundle verify ./evidence
 ```
 
-Attach the share-profile bundle (or a redacted file) to a PR or issue — not raw traces.
+`--out ./evidence` writes the Evidence v2 package to a known path; `bundle verify ./evidence` checks that exact directory. Do not use `--allow-unsafe` to force a share.
 
-Optional file redaction:
+Optional file redaction before bundling:
 
 ```bash
 npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o redacted.jsonl
@@ -75,8 +78,9 @@ npx agent-inspect redact <run-id> --dir .agent-inspect --profile share -o redact
 
 | If you use… | Go to |
 | ----------- | ----- |
-| Broken agent demo (same answer, wrong path) | [broken-agent-debugging starter](../examples/starters/broken-agent-debugging/README.md) (`node prove-same-output-wrong-path.mjs`) |
-| Coding-agent MCP loop | [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md) · [coding-agent-debug-loop](../examples/starters/coding-agent-debug-loop/README.md) |
+| Full install + instrumentation guide | [GETTING-STARTED.md](./GETTING-STARTED.md) (site: [/docs/getting-started/guide](/docs/getting-started/guide)) |
+| Broken agent demo (same answer, wrong path) | [broken-agent-debugging starter](../examples/starters/broken-agent-debugging/README.md) |
+| Coding-agent MCP loop | [CODING-AGENT-LOOP.md](./CODING-AGENT-LOOP.md) |
 | Contracts / CI gates | [TRACE-CONTRACTS.md](./TRACE-CONTRACTS.md) · [SUITES-COHORTS-GATES.md](./SUITES-COHORTS-GATES.md) |
 | AI SDK | [AI SDK adoption](./AI-SDK-ADOPTION.md) |
 | OpenAI Agents | [OpenAI Agents local](./OPENAI-AGENTS-LOCAL.md) |

package/docs/GETTING-STARTED.md

@@ -14,7 +14,7 @@ pnpm add agent-inspect
 
 ### Quick bootstrap (v3.1+)
 
-See also [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md).
+Prefer the five-minute path first: [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md) (site: [/docs/getting-started](/docs/getting-started)). This page is the longer install and instrumentation guide (site: [/docs/getting-started/guide](/docs/getting-started/guide)).
 
 ```bash
 npx agent-inspect init --yes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.31.0",
+  "version": "6.31.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",
@@ -234,7 +234,7 @@
     "test:coverage": "vitest run --coverage",
     "size": "size-limit --config size-limit.config.mjs",
     "test:all": "pnpm run typecheck && pnpm run linked-versions:check && pnpm run build && pnpm run test && 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 linked-versions:check && pnpm run repo:health && pnpm run pack:smoke",
+    "prepublish:checks": "pnpm run typecheck && pnpm run build && pnpm run test && pnpm run test:coverage && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run linked-versions:check && pnpm run repo:health && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
     "pack:smoke": "pnpm run package-licenses:check && pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-openai-agents-e2e.mjs && node scripts/packed-ai-sdk-e2e.mjs && node scripts/packed-mcp-e2e.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs && node scripts/packed-swarm-loop-e2e.mjs && node scripts/evidence-ci-golden-paths.mjs",
     "linked-versions:check": "node scripts/check-linked-versions.mjs",
@@ -262,6 +262,8 @@
     "website:dev": "pnpm --filter @agent-inspect/website dev",
     "website:build": "pnpm --filter @agent-inspect/website build",
     "website:typecheck": "pnpm --filter @agent-inspect/website typecheck",
+    "website:check": "pnpm --filter @agent-inspect/website check",
+    "website:crawl": "pnpm --filter @agent-inspect/website crawl",
     "package-licenses:check": "node scripts/validate-package-licenses.mjs",
     "package-licenses:sync": "node scripts/sync-package-licenses.mjs",
     "demo-version-sync:check": "node scripts/check-demo-version-sync.mjs"

package/packages/cli/dist/{chunk-Y5Z4BXUO.mjs → chunk-SJ6FRNOE.mjs}

@@ -6351,11 +6351,40 @@ function contractFailFinding(ruleId, message, evidence, expected, actual) {
     evidence: [...evidence]
   };
 }
+var ALLOWED_STATUS_ALIASES = {
+  ok: "ok",
+  error: "error",
+  running: "running",
+  success: "ok",
+  failed: "error"
+};
+function parseAllowedStatus(status) {
+  return ALLOWED_STATUS_ALIASES[status];
+}
 function normalizeStatus(status) {
-  if (status === "ok" || status === "error" || status === "running") return status;
-  if (status === "success") return "ok";
-  if (status === "failed") return "error";
-  return "error";
+  const parsed = parseAllowedStatus(status);
+  if (parsed === void 0) {
+    throw new TypeError(
+      `Unknown run status ${JSON.stringify(status)}. Allowed: ok, error, running (aliases: success, failed).`
+    );
+  }
+  return parsed;
+}
+function validateAllowedStatusesShape(allowedStatuses, pathPrefix = "run.allowedStatuses") {
+  if (!allowedStatuses?.length) return [];
+  const out = [];
+  for (let i = 0; i < allowedStatuses.length; i++) {
+    const status = allowedStatuses[i];
+    if (parseAllowedStatus(status) === void 0) {
+      out.push({
+        code: "contract.run.allowedStatuses.unknown",
+        severity: "error",
+        message: `${pathPrefix}[${i}] has unknown status ${JSON.stringify(status)}. Allowed: ok, error, running (aliases: success, failed).`,
+        path: `${pathPrefix}[${i}]`
+      });
+    }
+  }
+  return out;
 }
 function cloneBody(body) {
   return {
@@ -7022,6 +7051,7 @@ function evaluateBody(input, body, options = {}) {
 }
 function defineTraceContract(input) {
   const shapeErrors = [
+    ...validateAllowedStatusesShape(input.run?.allowedStatuses),
     ...validateAlternativesShape(input.alternatives),
     ...validateScopeShape(input.scope),
     ...validateProvenanceShape(input.observations)
@@ -7052,6 +7082,7 @@ function defineTraceContract(input) {
 }
 function evaluateTraceContract(input, contract, options = {}) {
   const shapeErrors = [
+    ...validateAllowedStatusesShape(contract.run?.allowedStatuses),
     ...validateAlternativesShape(contract.alternatives),
     ...validateScopeShape(contract.scope),
     ...validateProvenanceShape(contract.observations)
@@ -14854,5 +14885,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { ATTRIBUTION_CONFIDENCES, 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, defineTraceContract, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, evaluateTraceContract, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isAttributionConfidence, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, projectLogicalEvents, 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-Y5Z4BXUO.mjs.map
-//# sourceMappingURL=chunk-Y5Z4BXUO.mjs.map
+//# sourceMappingURL=chunk-SJ6FRNOE.mjs.map
+//# sourceMappingURL=chunk-SJ6FRNOE.mjs.map