agent-inspect 6.20.0 → 6.21.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 6.21.0
+
+### Minor Changes
+
+- 9d6a24f: Actor-scoped TraceContracts (`scope` selectors) and structural observation provenance (`observations.requireProvenance`) for multi-agent precision (#320/#321). Includes planner/verifier recipe.
+
 ## 6.20.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.20.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.21.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

@@ -12,6 +12,8 @@ Contracts compile to deterministic check rules for common cases:
 - tool required / forbidden / allowed / maxCalls / order (`requiredTools` / `forbiddenTools` aliases)
 - selectable `requiredOrderMode` (`first-occurrence` | `happens-before` | `all-occurrences`)
 - `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)
 - `lintTraceContract` / `explainTraceContract` for brittle-contract diagnostics
 - LLM maxCalls / maxTotalTokens / allowedModels
 - evidence-bearing findings on failures
@@ -126,6 +128,43 @@ Constraints:
 
 Requires externally observed or effect evidence (for example HTTP status, file write, cache key) rather than a specific tool call. Prefer this when the invariant is about **outcome** rather than **which tool ran**.
 
+### `scope` (shipped — experimental)
+
+Select one actor before evaluation using **explicit** metadata only:
+
+```ts
+defineTraceContract({
+  scope: { subAgentId: "verifier-agent" },
+  tools: { required: ["run_tests"] },
+});
+```
+
+Supported selectors: `runId`, `subAgentId`, `groupId`, `workflowStep`, `rootEventId` (subtree projection).
+
+- zero matches → error (no whole-session fallback)
+- singular selector matching multiple runs → error
+- no timestamp, prose, or display-name inference
+- successful selection reports the actor and evidence event count
+
+### `observations.requireProvenance` (shipped — experimental)
+
+Structural provenance for named outcomes. These checks prove method/evidence linkage was recorded; they do **not** prove the claim is semantically true, authorized, complete, or externally trusted.
+
+```ts
+defineTraceContract({
+  observations: {
+    required: ["refund-confirmed"],
+    requireProvenance: {
+      method: true,
+      evidence: true,
+      sameRunEventReference: true,
+    },
+  },
+});
+```
+
+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.
+
 ### Lint and explain (shipped)
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.20.0",
+  "version": "6.21.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-QPRJUVLH.mjs → chunk-CRUHIL5J.mjs}

@@ -2579,6 +2579,17 @@ var OBSERVED_OUTCOME_STATUSES = [
   "unknown",
   "skipped"
 ];
+var OBSERVED_OUTCOME_METHODS = [
+  "dom",
+  "accessibility",
+  "snapshot",
+  "network",
+  "storage",
+  "filesystem",
+  "database",
+  "queue",
+  "custom"
+];
 var OUTCOME_ATTRIBUTE_STATUS_KEY = "outcomeStatus";
 var OUTCOME_ATTRIBUTE_EXPECTATION_KEY = "expectation";
 var OUTCOME_ATTRIBUTE_METHOD_KEY = "method";
@@ -6681,6 +6692,9 @@ function isCredentialSensitiveKey(key, sensitiveKeys = DEFAULT_CREDENTIAL_SENSIT
   return false;
 }
 
+// packages/core/src/checks/contract.ts
+new Set(OBSERVED_OUTCOME_METHODS);
+
 // packages/core/src/checks/index.ts
 var SEVERITY_RANK = {
   error: 0,
@@ -11781,5 +11795,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-QPRJUVLH.mjs.map
-//# sourceMappingURL=chunk-QPRJUVLH.mjs.map
+//# sourceMappingURL=chunk-CRUHIL5J.mjs.map
+//# sourceMappingURL=chunk-CRUHIL5J.mjs.map