agent-inspect 6.22.0 → 6.24.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.24.0
+
+### Minor Changes
+
+- 2fa9d46: Production adoption distribution: lifecycle guidance, init/doctor CLI docs, gate compact JSON and GitHub annotations, VS Code Marketplace deferral confirmed.
+
+## 6.23.0
+
+### Minor Changes
+
+- 97b962f: Structured control contracts: JSON Pointer tool-argument checks, mixed orderRules, declared-versus-enforced controls, and retry/side-effect safety.
+
 ## 6.22.0
 
 ### Minor Changes

package/README.md

@@ -212,7 +212,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.22.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.24.0** · 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/ADOPTION.md

@@ -14,6 +14,8 @@ AgentInspect is **local-first**: traces stay on disk, checks run in CI, and shar
 
 See [FIRST-TRACE-IN-5-MINUTES.md](./FIRST-TRACE-IN-5-MINUTES.md) or the [docs site getting started](https://agentinspect.vercel.app/docs/getting-started/).
 
+Lifecycle (flush/close by runtime): [LIFECYCLE.md](./LIFECYCLE.md).
+
 ```bash
 npm install agent-inspect
 npx agent-inspect init --yes

package/docs/CLI.md

@@ -1026,9 +1026,9 @@ Options:
 - `--max-p95-duration <ms>` — maximum allowed p95 run duration
 - `--forbid-tool <name>` — forbidden tool (repeatable or comma-separated)
 - `--require-observation <name>` — required passed observation (repeatable or comma-separated)
-- `--format <format>` — `markdown`, `json`, `html`, `junit`, or `github` (default: `markdown`)
-- `-o, --output <dir>` — write `gate-results.json`, `gate-summary.md`, `gate-report.html`, `junit.xml`, `github-step-summary.md`
-- `--json` — print deterministic JSON result
+- `--format <format>` — `markdown`, `json`, `json-compact`, `html`, `junit`, `github`, or `github-annotations` (default: `markdown`)
+- `-o, --output <dir>` — write `gate-results.json`, `gate-summary.md`, `gate-report.html`, `junit.xml`, `github-step-summary.md`, `github-annotations.txt`
+- `--json` — print deterministic JSON result (pretty); use `--format json-compact` for CI logs
 - `--evidence-on <fail|always|never>` — write local Evidence v2 (no upload); omitted = never
 - `--evidence-dir <path>` — Evidence output directory or base path
 - `--evidence-profile <local|share|strict>` — redaction profile (default `share`)
@@ -1042,6 +1042,8 @@ Example:
 npx agent-inspect gate --suite fixtures/configs/outcome-suite.suite.json --output ./gate-artifacts
 npx agent-inspect gate --dir fixtures/cohorts/before-after --max-error-rate 5 --forbid-tool deleteAccount
 npx agent-inspect gate --suite agent-inspect.suite.ts --evidence-on fail --evidence-profile share
+npx agent-inspect gate --suite agent-inspect.suite.ts --format github-annotations
+npx agent-inspect gate --suite agent-inspect.suite.ts --format json-compact
 ```
 
 Recipe: [github-actions-gate](../examples/recipes/github-actions-gate/README.md).
@@ -1069,6 +1071,36 @@ npx agent-inspect viewer --suite --config fixtures/configs/outcome-suite.suite.j
 npx agent-inspect viewer --workspace
 ```
 
+### 6.29 `init`
+
+Scaffold local AgentInspect config and a metadata-only demo (v3.1+). Does **not** install packages or rewrite application source unless you opt in later.
+
+```bash
+agent-inspect init [--framework <name>] [--ci github] [--dry-run] [--yes] [--json]
+```
+
+`--framework` values (adoption order):
+
+| Value | Meaning |
+| --- | --- |
+| `ai-sdk` | AI SDK kit pointer + demo |
+| `langchain` / `langgraph` | LangChain/LangGraph kit pointer + demo |
+| `openai-agents` | OpenAI Agents kit pointer + demo |
+| `custom` | Manual `inspectRun` / `step` demo |
+| `observe` / `manual` | Aliases of `custom` (`observe(...)` demo) |
+
+Also writes `.agent-inspect/.gitkeep` and optional GitHub Actions workflow when `--ci github` is set. See [ADOPTION.md](./ADOPTION.md), [INSTALL-KITS.md](./INSTALL-KITS.md), and [LIFECYCLE.md](./LIFECYCLE.md).
+
+### 6.30 `doctor`
+
+Diagnose local setup **without network probes or installs** (v3.1+).
+
+```bash
+agent-inspect doctor [--framework <name>] [--trace-dir <path>] [--check-imports] [--json]
+```
+
+Reports version alignment, peer/package resolution, capture posture hints, writer path, redaction profile reminders, and no-default-egress expectations. Failures exit non-zero. Prefer `workspace doctor` when using a managed workspace layout.
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

package/docs/TRACE-CONTRACTS.md

@@ -11,6 +11,10 @@ Contracts compile to deterministic check rules for common cases:
 - run status / completion / max duration
 - tool required / forbidden / allowed / maxCalls / order (`requiredTools` / `forbiddenTools` aliases)
 - selectable `requiredOrderMode` (`first-occurrence` | `happens-before` | `all-occurrences`)
+- additive `tools.orderRules` with per-rule occurrence modes
+- bounded `tools.arguments` JSON Pointer checks (`exists` | `type` | `equals` | `oneOf`)
+- `controls` declared-versus-enforced invariants
+- `retry` / side-effect safety using explicit attempt identity
 - `alternatives.anyOf` for one level of legitimate alternate paths
 - actor `scope` selectors (`runId`, `subAgentId`, `groupId`, `workflowStep`, `rootEventId`)
 - observation `requireProvenance` (structural method / evidence / same-run event references)
@@ -165,6 +169,58 @@ defineTraceContract({
 
 Bounded evidence shapes: string event id, `{ eventId }`, or `{ eventIds }` (max 16). Method must be in the `ObservedOutcomeMethod` vocabulary. Omitting `requireProvenance` leaves prior observation behavior unchanged.
 
+### `tools.arguments` / `tools.orderRules` / `controls` / `retry` (shipped — experimental, 6.23)
+
+See [ADR-0010](./decisions/ADR-0010-structured-control-contracts.md).
+
+```ts
+defineTraceContract({
+  tools: {
+    defaultOccurrenceMode: "first-occurrence",
+    orderRules: [
+      { before: "authorize", after: "charge", occurrenceMode: "all-occurrences" },
+    ],
+    arguments: [
+      {
+        tool: "charge",
+        occurrence: "all",
+        path: "/dryRun",
+        operator: "equals",
+        expected: true,
+      },
+    ],
+  },
+  controls: {
+    declaredTools: ["search", "charge"],
+    enforcedTools: ["search", "charge"],
+    requireDeclaredMatchesEnforced: true,
+    requireObservedWithinEnforced: true,
+    requiredStages: [{ stage: "enforced" }],
+  },
+  retry: {
+    maxAttempts: 2,
+    nonIdempotentTools: ["charge"],
+    requireIdempotencyEvidenceForRetry: true,
+    requireRecoveredFailureVisible: true,
+  },
+});
+```
+
+Missing structured argument evidence fails closed (`AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE`). Findings never include full actual inputs.
+
+### Capture capability matrix (tool-argument evidence)
+
+| Source | Structured input | Preview only | Digest only | Unavailable |
+| --- | :---: | :---: | :---: | :---: |
+| Manual `attributes.arguments` / `attributes.input` (object) | yes | — | — | — |
+| Manual `inputSummary` string | — | yes | — | for pointer checks |
+| AI SDK / LangChain metadata-only default | — | sometimes | — | typical |
+| OpenAI Agents metadata-only | — | sometimes | — | typical |
+| MCP / OTLP / OpenInference import | varies | varies | optional digest | when unmapped |
+| Custom TraceReader | reader-defined | reader-defined | reader-defined | fail closed |
+
+Do not advertise a structured argument rule when the selected capture mode cannot supply object evidence.
+
 ### Lint and explain (shipped)
 
 ```ts

package/docs/VSCODE.md

@@ -4,11 +4,16 @@ Read-only sidebar for local trace directories. The extension shells out to the p
 
 **Support level:** Experimental (unpublished). Ignored by Changesets; not part of the fixed npm release group.
 
-## Product scope decision (6.18.0-H)
+## Product scope decision (6.24.0)
 
-**Disposition: defer (Option A).** Keep the in-repo extension unpublished. Core, official adapters, CLI, and Evidence take precedence over Marketplace packaging. Open PR #295 (sample trace command) and related issues (#66, #65) stay out of the active 6.18 implementation train until a later capacity window revisits VS Code.
+**Disposition: close without Marketplace publish (Option A, confirmed).**
 
-Do not merge #295 merely to clear the contributor queue.
+- Keep the in-repo extension unpublished.
+- Do **not** publish to the VS Code Marketplace in this train (credentials + product priority).
+- Open PR [#295](https://github.com/rajudandigam/agent-inspect/pull/295) (sample trace command) remains **out of the adoption train** — close or park as contributor-optional; do not merge solely to clear the queue while CI is red.
+- Related issues (#66, #65) stay deferred until a later capacity window revisits VS Code.
+
+Core, official adapters, CLI, Evidence, and TraceContract remain the adoption surface.
 
 ## Develop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.22.0",
+  "version": "6.24.0",
   "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",

package/packages/cli/dist/{chunk-CHBYF4LE.mjs → chunk-NHVN5AYW.mjs}

@@ -11794,15 +11794,34 @@ ${cases}
   </testsuite>
 </testsuites>`;
 }
+function renderGateGithubAnnotations(result) {
+  return result.checks.filter((check) => !check.ok).map((check) => {
+    const message = check.message.replace(/\r?\n/g, " ").replace(/%/g, "%25");
+    return `::error title=${check.name}::${message}`;
+  }).join("\n");
+}
 function renderGateReport(result, options = {}) {
   const format = options.format ?? "markdown";
   if (format === "json") return JSON.stringify(result, null, 2);
+  if (format === "json-compact") {
+    return JSON.stringify({
+      ok: result.ok,
+      exitCode: result.exitCode,
+      failed: result.checks.filter((check) => !check.ok).map((check) => check.name),
+      checks: result.checks.map((check) => ({
+        name: check.name,
+        ok: check.ok,
+        message: check.message
+      }))
+    });
+  }
   if (format === "html") return renderGateReportHtml(result);
   if (format === "junit") return renderGateJUnit(result);
   if (format === "github") return renderGateGithubStepSummary(result);
+  if (format === "github-annotations") return renderGateGithubAnnotations(result);
   return renderGateSummaryMarkdown(result);
 }
 
 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-CHBYF4LE.mjs.map
-//# sourceMappingURL=chunk-CHBYF4LE.mjs.map
+//# sourceMappingURL=chunk-NHVN5AYW.mjs.map
+//# sourceMappingURL=chunk-NHVN5AYW.mjs.map