agent-inspect 6.22.0 → 6.23.0

package/packages/core/dist/checks.d.cts

@@ -223,6 +223,141 @@ declare function resolveTraceContractScope(input: TraceCheckInput, scope: TraceC
     diagnostics: TraceCheckDiagnostic[];
 };
 
+/**
+ * Declared-versus-enforced control checks for TraceContract (6.23).
+ *
+ * A stored declaration is not proof of enforcement.
+ *
+ * @experimental
+ */
+
+type ControlStage = "declared" | "presented" | "validated" | "enforced" | "observed" | "accepted";
+interface TraceContractControlRules {
+    /**
+     * Tools declared/presented to the agent (inline). Distinct from `enforcedTools`.
+     */
+    declaredTools?: string[];
+    /**
+     * Tools the harness claims to enforce (inline allowlist).
+     */
+    enforcedTools?: string[];
+    /**
+     * RUN/event attribute holding a string[] of declared tool names.
+     * Used when `declaredTools` is omitted.
+     */
+    declaredToolsAttribute?: string;
+    /**
+     * RUN/event attribute holding a string[] of enforced tool names.
+     */
+    enforcedToolsAttribute?: string;
+    /**
+     * Fail when both declared and enforced sets resolve and differ.
+     */
+    requireDeclaredMatchesEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the enforced set.
+     */
+    requireObservedWithinEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the declared set.
+     */
+    requireObservedWithinDeclared?: boolean;
+    /**
+     * Require observation names for control stages (default `control.<stage>`).
+     */
+    requiredStages?: Array<{
+        stage: ControlStage;
+        /** Observation name; defaults to `control.<stage>`. */
+        observation?: string;
+    }>;
+}
+
+/**
+ * Retry / side-effect safety checks for TraceContract (6.23).
+ *
+ * Uses explicit attempt identity from session workflow metadata.
+ * AgentInspect evaluates; it does not perform retries.
+ *
+ * @experimental
+ */
+
+interface TraceContractRetryRules {
+    /**
+     * Maximum attempts per `operationId` (or `attemptOf` grouping).
+     * Counts distinct `attemptId` values when present, else finished tool/LLM events.
+     */
+    maxAttempts?: number;
+    /**
+     * When true, every operation with attempts must include a non-running terminal event.
+     */
+    requireTerminalResult?: boolean;
+    /**
+     * Fail when `fallbackOf` is set without a prior error attempt for the referenced operation.
+     */
+    fallbackOnlyAfterFailure?: boolean;
+    /**
+     * Tool names treated as non-idempotent. A later attempt after an `ok` occurrence fails
+     * unless idempotency / no-side-effect evidence is present on the retry.
+     */
+    nonIdempotentTools?: string[];
+    /**
+     * When true, retries require `idempotencyKey` or `attributes.noSideEffect === true`.
+     */
+    requireIdempotencyEvidenceForRetry?: boolean;
+    /**
+     * When true, recovered success paths must still retain at least one error attempt event.
+     */
+    requireRecoveredFailureVisible?: boolean;
+}
+
+/**
+ * Resolve an RFC 6901 JSON Pointer against a JSON-like value.
+ * Returns `{ found: false }` when the path does not exist.
+ */
+declare function resolveJsonPointer(document: unknown, pointer: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+type ToolArgumentOperator = "exists" | "type" | "equals" | "oneOf";
+type ToolArgumentOccurrence = "first" | "last" | "any" | "all";
+interface ToolArgumentCheck {
+    tool: string;
+    path: string;
+    operator: ToolArgumentOperator;
+    occurrence?: ToolArgumentOccurrence;
+    /** Required for `equals`. */
+    expected?: unknown;
+    /** Required for `oneOf`. */
+    oneOf?: readonly unknown[];
+    /** Required for `type` (`string` | `number` | `boolean` | `object` | `array` | `null`). */
+    type?: "string" | "number" | "boolean" | "object" | "array" | "null";
+}
+type ToolArgumentEval = {
+    status: "pass";
+} | {
+    status: "fail";
+    message: string;
+    code: string;
+} | {
+    status: "unavailable";
+    message: string;
+    code: "AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE";
+};
+/**
+ * Extract structured tool-argument evidence from a tool event.
+ * Preview-only strings and digests do not count as structured evidence.
+ */
+declare function extractToolArgumentPayload(event: {
+    attributes?: Record<string, unknown>;
+    inputSummary?: unknown;
+}): {
+    present: boolean;
+    value: unknown;
+};
+declare function evaluateToolArgumentValue(value: unknown, check: ToolArgumentCheck, evidencePresent: boolean): ToolArgumentEval;
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -277,6 +412,32 @@ interface TraceContractToolRules {
      * @beta Available through `agent-inspect/checks`.
      */
     requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Bounded structured tool-argument checks (JSON Pointer + limited operators).
+     *
+     * Missing structured evidence fails closed as unevaluable (not pass).
+     * Findings never embed full actual inputs.
+     *
+     * @experimental Additive in 6.23.
+     */
+    arguments?: ToolArgumentCheck[];
+    /**
+     * Default occurrence mode for `orderRules` when a rule omits `occurrenceMode`.
+     *
+     * @experimental Additive in 6.23.
+     */
+    defaultOccurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Mixed per-pair ordering rules (additive alongside `requiredOrder`).
+     *
+     * @experimental Additive in 6.23.
+     */
+    orderRules?: Array<{
+        before: string;
+        after: string;
+        occurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+        requireEndpoints?: boolean;
+    }>;
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -344,6 +505,18 @@ type TraceContractBody = {
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+    /**
+     * Declared-versus-enforced control invariants.
+     *
+     * @experimental Additive in 6.23.
+     */
+    controls?: TraceContractControlRules;
+    /**
+     * Retry / side-effect safety using explicit attempt identity.
+     *
+     * @experimental Additive in 6.23.
+     */
+    retry?: TraceContractRetryRules;
 };
 interface TraceContractInput extends TraceContractBody {
     /**
@@ -412,4 +585,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };
+export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

package/packages/core/dist/checks.d.ts

@@ -223,6 +223,141 @@ declare function resolveTraceContractScope(input: TraceCheckInput, scope: TraceC
     diagnostics: TraceCheckDiagnostic[];
 };
 
+/**
+ * Declared-versus-enforced control checks for TraceContract (6.23).
+ *
+ * A stored declaration is not proof of enforcement.
+ *
+ * @experimental
+ */
+
+type ControlStage = "declared" | "presented" | "validated" | "enforced" | "observed" | "accepted";
+interface TraceContractControlRules {
+    /**
+     * Tools declared/presented to the agent (inline). Distinct from `enforcedTools`.
+     */
+    declaredTools?: string[];
+    /**
+     * Tools the harness claims to enforce (inline allowlist).
+     */
+    enforcedTools?: string[];
+    /**
+     * RUN/event attribute holding a string[] of declared tool names.
+     * Used when `declaredTools` is omitted.
+     */
+    declaredToolsAttribute?: string;
+    /**
+     * RUN/event attribute holding a string[] of enforced tool names.
+     */
+    enforcedToolsAttribute?: string;
+    /**
+     * Fail when both declared and enforced sets resolve and differ.
+     */
+    requireDeclaredMatchesEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the enforced set.
+     */
+    requireObservedWithinEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the declared set.
+     */
+    requireObservedWithinDeclared?: boolean;
+    /**
+     * Require observation names for control stages (default `control.<stage>`).
+     */
+    requiredStages?: Array<{
+        stage: ControlStage;
+        /** Observation name; defaults to `control.<stage>`. */
+        observation?: string;
+    }>;
+}
+
+/**
+ * Retry / side-effect safety checks for TraceContract (6.23).
+ *
+ * Uses explicit attempt identity from session workflow metadata.
+ * AgentInspect evaluates; it does not perform retries.
+ *
+ * @experimental
+ */
+
+interface TraceContractRetryRules {
+    /**
+     * Maximum attempts per `operationId` (or `attemptOf` grouping).
+     * Counts distinct `attemptId` values when present, else finished tool/LLM events.
+     */
+    maxAttempts?: number;
+    /**
+     * When true, every operation with attempts must include a non-running terminal event.
+     */
+    requireTerminalResult?: boolean;
+    /**
+     * Fail when `fallbackOf` is set without a prior error attempt for the referenced operation.
+     */
+    fallbackOnlyAfterFailure?: boolean;
+    /**
+     * Tool names treated as non-idempotent. A later attempt after an `ok` occurrence fails
+     * unless idempotency / no-side-effect evidence is present on the retry.
+     */
+    nonIdempotentTools?: string[];
+    /**
+     * When true, retries require `idempotencyKey` or `attributes.noSideEffect === true`.
+     */
+    requireIdempotencyEvidenceForRetry?: boolean;
+    /**
+     * When true, recovered success paths must still retain at least one error attempt event.
+     */
+    requireRecoveredFailureVisible?: boolean;
+}
+
+/**
+ * Resolve an RFC 6901 JSON Pointer against a JSON-like value.
+ * Returns `{ found: false }` when the path does not exist.
+ */
+declare function resolveJsonPointer(document: unknown, pointer: string): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};
+type ToolArgumentOperator = "exists" | "type" | "equals" | "oneOf";
+type ToolArgumentOccurrence = "first" | "last" | "any" | "all";
+interface ToolArgumentCheck {
+    tool: string;
+    path: string;
+    operator: ToolArgumentOperator;
+    occurrence?: ToolArgumentOccurrence;
+    /** Required for `equals`. */
+    expected?: unknown;
+    /** Required for `oneOf`. */
+    oneOf?: readonly unknown[];
+    /** Required for `type` (`string` | `number` | `boolean` | `object` | `array` | `null`). */
+    type?: "string" | "number" | "boolean" | "object" | "array" | "null";
+}
+type ToolArgumentEval = {
+    status: "pass";
+} | {
+    status: "fail";
+    message: string;
+    code: string;
+} | {
+    status: "unavailable";
+    message: string;
+    code: "AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE";
+};
+/**
+ * Extract structured tool-argument evidence from a tool event.
+ * Preview-only strings and digests do not count as structured evidence.
+ */
+declare function extractToolArgumentPayload(event: {
+    attributes?: Record<string, unknown>;
+    inputSummary?: unknown;
+}): {
+    present: boolean;
+    value: unknown;
+};
+declare function evaluateToolArgumentValue(value: unknown, check: ToolArgumentCheck, evidencePresent: boolean): ToolArgumentEval;
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -277,6 +412,32 @@ interface TraceContractToolRules {
      * @beta Available through `agent-inspect/checks`.
      */
     requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Bounded structured tool-argument checks (JSON Pointer + limited operators).
+     *
+     * Missing structured evidence fails closed as unevaluable (not pass).
+     * Findings never embed full actual inputs.
+     *
+     * @experimental Additive in 6.23.
+     */
+    arguments?: ToolArgumentCheck[];
+    /**
+     * Default occurrence mode for `orderRules` when a rule omits `occurrenceMode`.
+     *
+     * @experimental Additive in 6.23.
+     */
+    defaultOccurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Mixed per-pair ordering rules (additive alongside `requiredOrder`).
+     *
+     * @experimental Additive in 6.23.
+     */
+    orderRules?: Array<{
+        before: string;
+        after: string;
+        occurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+        requireEndpoints?: boolean;
+    }>;
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -344,6 +505,18 @@ type TraceContractBody = {
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+    /**
+     * Declared-versus-enforced control invariants.
+     *
+     * @experimental Additive in 6.23.
+     */
+    controls?: TraceContractControlRules;
+    /**
+     * Retry / side-effect safety using explicit attempt identity.
+     *
+     * @experimental Additive in 6.23.
+     */
+    retry?: TraceContractRetryRules;
 };
 interface TraceContractInput extends TraceContractBody {
     /**
@@ -412,4 +585,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };
+export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

package/packages/core/dist/checks.mjs

@@ -1,4 +1,4 @@
-export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-OG3GAWCX.mjs';
+export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveJsonPointer, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-VMDCDWBE.mjs';
 import './chunk-R4SSYU6D.mjs';
 import './chunk-U25RHRSU.mjs';
 import './chunk-VU6O5QAH.mjs';