agent-inspect 6.26.0 → 6.28.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 6.28.0
+
+### Minor Changes
+
+- 228b4df: Package resolved TraceContract / check-preset snapshots into Evidence v2 (`contract.resolved.json`) with digest binding to check results, honest partial/unavailable status for custom rules, and verify support — no signing or trusted-time claims (schema stays 1.0).
+
+## 6.27.0
+
+### Minor Changes
+
+- 0f7c2e1: Bounded safe recovery contracts: additive TraceContract `retry.operations[]` oracles (read-first `retrieve_policy`), ADR-0011, and flagship recipe. Schema remains 1.0; AgentInspect still does not execute retries.
+
 ## 6.26.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.26.0** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.28.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/BUNDLES.md

@@ -37,7 +37,8 @@ trace.html                 # offline HTML (index for multi-run)
 trace.jsonl                # redacted JSONL copy
 summary.md                 # human overview
 metadata.json              # legacy manifest (version, profile, safe status)
-check-results.json         # verify-safe results per run
+check-results.json         # verify-safe / check results per run (may include contract digest binding)
+contract.resolved.json     # optional resolved TraceContract / preset snapshot (6.28+)
 redaction-report.json      # detector summary (no secret values)
 eval-results.json          # placeholder unless eval artifacts are added later
 performance-summary.json   # placeholder unless perf artifacts are added later
@@ -73,6 +74,8 @@ Profiles:
 
 Bundles are **derived copies**, not compliance certification. Always review `evidence.html` / `summary.md`, `check-results.json`, and run `bundle verify` before attaching to tickets or PRs.
 
+When `contract.resolved.json` is present (6.28+), reviewers can inspect the resolved TraceContract or check preset that was evaluated and confirm digests via `bundle verify`. Custom/programmatic rules are marked `partial` and are not fully replayable from JSON. Contract binding is **not** a signature or trusted-time claim — see [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md#contract-binding-628).
+
 See also [SAFE-TRACE-SHARING.md](./SAFE-TRACE-SHARING.md) and [CLI.md §6.24](./CLI.md#624-bundle).
 
 ## Review workflow

package/docs/LIMITATIONS.md

@@ -8,7 +8,7 @@ This document states what AgentInspect **does not** provide today. It complement
 - **No production APM replacement**: no sampling agents, no fleet-wide aggregation, no uptime SLAs.
 - **No vendor upload pipeline**: no built-in Langfuse/Braintrust/New Relic/Datadog direct exporters as live sinks.
 - **No automatic universal instrumentation** of every framework: integration is explicit (manual traces, log ingest, optional adapters).
-- **No retry execution engine:** TraceContract `retry` rules evaluate attempt identity and evidence only. AgentInspect does not retry tools, remediates nothing, and does not treat a client `idempotencyKey` as proof of exactly-once writes.
+- **No retry execution engine:** TraceContract `retry` rules (including additive `retry.operations[]` recovery oracles in 6.27) evaluate attempt identity and evidence only. AgentInspect does not retry tools, remediates nothing, and does not treat a client `idempotencyKey` as proof of exactly-once writes. Write-tool timeout/unknown completion is unevaluable without authoritative idempotency evidence; write-retry is not safe by default.
 - **Omitted-payload digests** (`createOmittedPayloadCommitment`) are bounded (1 MiB preflight). Digests prove omitted bytes existed; they are not redaction or authorization.
 
 ## Correlation metadata (v1.3.0)

package/docs/SAFE-TRACE-SHARING.md

@@ -34,6 +34,8 @@ Manual traces redact common sensitive keys **before disk** by default. Pass `red
 
 When a maintainer or support responder needs reproducible evidence, follow the [safe support reproduction workflow](./SUPPORT-REPRODUCTION.md) to create and review a minimized Evidence bundle. Do not attach a raw trace directory.
 
+For reviewer-reproducible trajectory checks (6.28+), prefer Evidence that includes `contract.resolved.json` and a matching `contract` digest in `evidence.json` / `check-results.json`. That lets a reviewer see the resolved TraceContract or check preset that was evaluated. Custom/programmatic rules remain `partial` — JSON cannot replay executable rule functions. Contract binding verifies packaged digests only; it does **not** prove producer identity, trusted time, or that the artifact is safe to publish. See [EVIDENCE-FORMAT.md](./EVIDENCE-FORMAT.md#contract-binding-628).
+
 - Use **`--redaction-profile share`** for PR/issue attachments; use **`strict`** when sharing outside your team.
 - **Review** the exported file — profiles do not detect all sensitive data.
 - Treat traces written with `redact: false` as sensitive. Review every event before sharing them outside your team.

package/docs/TRACE-CONTRACTS.md

@@ -14,7 +14,7 @@ Contracts compile to deterministic check rules for common cases:
 - 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
+- `retry` / side-effect safety using explicit attempt identity (additive `retry.operations[]` recovery oracles in 6.27)
 - `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)
@@ -169,9 +169,9 @@ 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; retry chronology corrected in 6.25.1)
+### `tools.arguments` / `tools.orderRules` / `controls` / `retry` (shipped — experimental, 6.23; retry chronology corrected in 6.25.1; `retry.operations` in 6.27)
 
-See [ADR-0010](./decisions/ADR-0010-structured-control-contracts.md).
+See [ADR-0010](./decisions/ADR-0010-structured-control-contracts.md) and [ADR-0011](./decisions/ADR-0011-bounded-safe-recovery.md).
 
 ```ts
 defineTraceContract({
@@ -203,12 +203,30 @@ defineTraceContract({
     requireIdempotencyEvidenceForRetry: true,
     requireRecoveredFailureVisible: true,
     fallbackOnlyAfterFailure: true,
+    operations: [
+      {
+        tool: "retrieve_policy",
+        sideEffectClass: "read",
+        maxAttempts: 2,
+        retryableErrors: { codes: ["TRANSIENT"] },
+        requireFailureBeforeRetry: true,
+        requireSameArguments: "structured-or-digest",
+        requireTerminalSuccess: true,
+        requireRecoveredFailureVisible: true,
+        successfulResultDependency: {
+          consumerKind: "LLM",
+          requireExplicitReference: true,
+        },
+      },
+    ],
   },
 });
 ```
 
 **Retry classification (6.25.1):** a genuine retry is detected from explicit identity preference — `attemptNumber > 1`, valid `retryOf` (target exists and precedes), distinct later `attemptId` under the same `operationId`, or a later finished attempt in an explicitly grouped operation — **not** only from a prior `ok`. `error → success` without `idempotencyKey` / `noSideEffect` evidence fails when `requireIdempotencyEvidenceForRetry` is set. `fallbackOnlyAfterFailure` and `requireRecoveredFailureVisible` require chronological earlier failure in the related chain. A client `idempotencyKey` is evidence of intent, not proof of exactly-once mutation. AgentInspect evaluates traces; it does not execute retries.
 
+**Bounded recovery operations (6.27):** `retry.operations[]` adds per-tool oracles for safe **read** recovery first (`retrieve_policy` recipe). Same-arguments checks accept structured payloads or matching digests and fail closed when both are missing. Write `sideEffectClass` treats timeout/`unknown`/`running` completion as unevaluable unless authoritative idempotency evidence is present. Write-retry is not safe by default.
+
 Missing structured argument evidence fails closed (`AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE`). Findings never include full actual inputs.
 
 ### Capture capability matrix (tool-argument evidence)

package/package.json

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