agent-inspect 6.22.0 → 6.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.23.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.22.0",
+  "version": "6.23.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-BVQO5CWA.mjs}

@@ -11804,5 +11804,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-CHBYF4LE.mjs.map
-//# sourceMappingURL=chunk-CHBYF4LE.mjs.map
+//# sourceMappingURL=chunk-BVQO5CWA.mjs.map
+//# sourceMappingURL=chunk-BVQO5CWA.mjs.map