agent-inspect 6.29.6 → 6.31.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 6.31.0
+
+### Minor Changes
+
+- 11a8b90: Add TraceContract `steps.orderRelations` for typed TOOL↔LLM step ordering (additive; TOOL-only `requiredOrder` / `orderRules` unchanged).
+
+## 6.30.0
+
+### Minor Changes
+
+- 094854f: Strict CLI TraceContract JSON for `agent-inspect check --config`:
+
+  - Top-level `contract` evaluates through `defineTraceContract` / `evaluateTraceContract`.
+  - Strict nested validation for run/tools/llm/observations/scope/alternatives/controls/retry (unknown keys fail closed).
+  - Mutually exclusive with an effective top-level `checks` block.
+  - `--evidence-on` binds the resolved contract (`contract.resolved.json` + check-results digests).
+
 ## 6.29.6
 
 ### Patch 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.29.6** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.31.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/CLI.md

@@ -58,9 +58,9 @@ No new CLI commands were added for branching paths.
 | ---- | ------ |
 | One tool must always run | CLI `--required-tool` / contract `tools.required` |
 | Tool must never run | CLI `--forbidden-tool` / contract `tools.forbidden` |
-| Legitimate alternate paths (OR) | TraceContract `alternatives.anyOf` (not CLI flags) |
-| Causal order between tools | TraceContract `requiredOrder` + `requiredOrderMode` |
-| Read recovery vs write fail-closed | TraceContract `retry.operations` + `sideEffectClass` |
+| Legitimate alternate paths (OR) | TraceContract `alternatives.anyOf` via `--config` `contract` (or TS API) |
+| Causal order between tools | TraceContract `requiredOrder` + `requiredOrderMode` via `--config` `contract` |
+| Read recovery vs write fail-closed | TraceContract `retry.operations` + `sideEffectClass` via `--config` `contract` |
 | Sensitive expected literals in Evidence | Contract binding safety (`unavailable` on credential-like expected); never silent complete packaging |
 | Share-safe offline review package | CLI `bundle` / Evidence CI helpers |
 
@@ -351,7 +351,8 @@ Options:
 
 By default, `check` runs `run.status`. Additional built-in rules can be selected with `--rule` or config when their options are available. Prefer `--preset trajectory` in CI, then `verify-safe` before sharing.
 
-Config files use this shape:
+Config files use either `checks` (flat rule options) or top-level `contract`
+(TraceContract vocabulary). Do not combine both in one file.
 
 ```json
 {
@@ -364,6 +365,27 @@ Config files use this shape:
 }
 ```
 
+Rich TraceContract JSON (6.30+):
+
+```json
+{
+  "contract": {
+    "tools": {
+      "required": ["retrieve_policy"],
+      "forbidden": ["send_email"],
+      "requiredOrder": ["retrieve_policy", "generate_answer"],
+      "requiredOrderMode": "first-occurrence"
+    },
+    "observations": { "failOn": ["failed"] },
+    "scope": { "runId": "optional-run-id" }
+  }
+}
+```
+
+Supported `contract` fields: `run`, `tools` (including `arguments`, `orderRules`),
+`llm`, `observations` (including `requireProvenance`), `scope`, `alternatives.anyOf`,
+`controls`, and `retry`. Unknown keys fail closed (exit 2). With `--evidence-on`,
+contract mode writes `contract.resolved.json` and binds digests into check-results.
 YAML is not supported. TypeScript config files (`.ts`, `.mts`, `.cts`) fail clearly unless a future explicit loader strategy is added; use precompiled JavaScript config instead.
 
 Examples:

package/docs/TRACE-CONTRACTS.md

@@ -12,6 +12,7 @@ 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`)
 - additive `tools.orderRules` with per-rule occurrence modes
+- typed cross-kind `steps.orderRelations` (TOOL ↔ LLM endpoints; additive in 6.31)
 - bounded `tools.arguments` JSON Pointer checks (`exists` | `type` | `equals` | `oneOf`)
 - `controls` declared-versus-enforced invariants
 - `retry` / side-effect safety using explicit attempt identity (additive `retry.operations[]` recovery oracles in 6.27)
@@ -61,6 +62,30 @@ For overlapping first calls, omitted / `first-occurrence` warns while `happens-b
 
 Immediate or positional `all-pairs` matching is not implemented.
 
+## `steps.orderRelations` (shipped — experimental, 6.31)
+
+Typed before/after relations with explicit `kind: "TOOL" | "LLM"` endpoints. Use this when a TOOL must precede an LLM (or vice versa). It does **not** change TOOL-only `tools.requiredOrder` / `orderRules` semantics.
+
+```ts
+defineTraceContract({
+  steps: {
+    orderRelations: [
+      {
+        before: { kind: "TOOL", name: "retrieve_policy" },
+        after: { kind: "LLM", name: "generate_answer" },
+        // mode?: "first-occurrence" | "happens-before" | "all-occurrences"
+        // requireEndpoints?: boolean // default true
+      },
+    ],
+  },
+});
+```
+
+- Default `mode` is `first-occurrence` (same three modes as tool order).
+- Default `requireEndpoints: true` — missing kind+name fails; a same display name under the other kind does **not** satisfy the endpoint.
+- LLM names match finished LLM events after stripping common prefixes (`llm:`, `generation:`, …).
+- Low-level `createStepOrderingRule` is compositional when `requireEndpoints` is omitted/false.
+
 ### Experimental Vitest / Jest matchers (shipped)
 
 | Package | Export | Matchers |

package/package.json

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