agent-inspect 6.19.0 → 6.20.0

package/packages/core/dist/{chunk-NABMW5DX.mjs → chunk-G47KQB42.mjs}

@@ -1,4 +1,4 @@
-import { extractOutcomesFromPersistedEvents, outcomesMatchingStatus } from './chunk-VFO76UH3.mjs';
+import { extractOutcomesFromPersistedEvents, outcomesMatchingStatus } from './chunk-3XS5O4JI.mjs';
 import { formatProgrammaticDiagnostic } from './chunk-FWK3Q3OJ.mjs';
 
 // packages/core/src/checks/logical-events.ts
@@ -1676,6 +1676,7 @@ function createToolUsageRule(options) {
 }
 function createToolOrderingRule(options) {
   const ruleId = options.id ?? "tool.order";
+  const mode = options.mode ?? "first-occurrence";
   return {
     id: ruleId,
     category: "tool",
@@ -1688,7 +1689,7 @@ function createToolOrderingRule(options) {
       if (beforeIndex === void 0 || afterIndex === void 0) {
         return [];
       }
-      if (beforeIndex >= afterIndex) {
+      if (mode === "first-occurrence" && beforeIndex >= afterIndex) {
         return [
           failFinding(
             ruleId,
@@ -1703,6 +1704,130 @@ function createToolOrderingRule(options) {
       const afterEvent = tools[afterIndex];
       const beforeEnd = eventEndMs(beforeEvent);
       const afterStart = eventStartMs(afterEvent);
+      if (mode === "happens-before") {
+        const expected = {
+          before: options.before,
+          after: options.after,
+          mode,
+          relation: "before.end <= after.start"
+        };
+        if (options.before === options.after) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} cannot causally happen before itself.`,
+              [eventEvidence(beforeEvent)],
+              expected,
+              { code: "tool.order.same-tool" }
+            )
+          ];
+        }
+        if (beforeEnd === void 0 || afterStart === void 0) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool order ${options.before} before ${options.after} could not establish causal timing.`,
+              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              expected,
+              {
+                code: "tool.order.interval-unresolved",
+                beforeEndResolved: beforeEnd !== void 0,
+                afterStartResolved: afterStart !== void 0
+              }
+            )
+          ];
+        }
+        if (beforeEnd > afterStart) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} must finish before ${options.after} starts.`,
+              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              expected,
+              {
+                beforeEndedAt: new Date(beforeEnd).toISOString(),
+                afterStartedAt: new Date(afterStart).toISOString()
+              }
+            )
+          ];
+        }
+        return [];
+      }
+      if (mode === "all-occurrences") {
+        const beforeEvents = tools.filter((event) => toolName(event) === options.before);
+        const afterEvents = tools.filter((event) => toolName(event) === options.after);
+        const expected = {
+          before: options.before,
+          after: options.after,
+          mode,
+          relation: "max(before.end) <= min(after.start)"
+        };
+        if (options.before === options.after) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} cannot causally happen before itself.`,
+              [eventEvidence(beforeEvent)],
+              expected,
+              { code: "tool.order.same-tool" }
+            )
+          ];
+        }
+        let latestBefore;
+        let earliestAfter;
+        let missingBeforeEnds = 0;
+        let missingAfterStarts = 0;
+        let firstMissingBefore;
+        let firstMissingAfter;
+        for (const event of beforeEvents) {
+          const end = eventEndMs(event);
+          if (end === void 0) {
+            missingBeforeEnds += 1;
+            firstMissingBefore ??= event;
+          } else if (latestBefore === void 0 || end > latestBefore.end) {
+            latestBefore = { event, end };
+          }
+        }
+        for (const event of afterEvents) {
+          const start = eventStartMs(event);
+          if (start === void 0) {
+            missingAfterStarts += 1;
+            firstMissingAfter ??= event;
+          } else if (earliestAfter === void 0 || start < earliestAfter.start) {
+            earliestAfter = { event, start };
+          }
+        }
+        if (missingBeforeEnds > 0 || missingAfterStarts > 0 || latestBefore === void 0 || earliestAfter === void 0) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool order ${options.before} before ${options.after} could not establish all causal intervals.`,
+              [firstMissingBefore, firstMissingAfter].filter((event) => event !== void 0).map((event) => eventEvidence(event)),
+              expected,
+              {
+                code: "tool.order.interval-unresolved",
+                missingBeforeEnds,
+                missingAfterStarts
+              }
+            )
+          ];
+        }
+        if (latestBefore.end > earliestAfter.start) {
+          return [
+            failFinding(
+              ruleId,
+              `Every ${options.before} tool call must finish before any ${options.after} tool call starts.`,
+              [eventEvidence(latestBefore.event), eventEvidence(earliestAfter.event)],
+              expected,
+              {
+                latestBeforeEndedAt: new Date(latestBefore.end).toISOString(),
+                earliestAfterStartedAt: new Date(earliestAfter.start).toISOString()
+              }
+            )
+          ];
+        }
+        return [];
+      }
       if (beforeEnd !== void 0 && afterStart !== void 0 && beforeEnd > afterStart) {
         return [
           {
@@ -2653,6 +2778,17 @@ function normalizeStatus(status) {
   if (status === "failed") return "error";
   return "error";
 }
+function cloneBody(body) {
+  return {
+    ...body.run ? { run: { ...body.run } } : {},
+    ...body.tools ? { tools: { ...body.tools } } : {},
+    ...body.llm ? { llm: { ...body.llm } } : {},
+    ...body.observations ? { observations: { ...body.observations } } : {}
+  };
+}
+function bodyHasRules(body) {
+  return body.run !== void 0 || body.tools !== void 0 || body.llm !== void 0 || body.observations !== void 0;
+}
 function contractToRules(contract) {
   const rules = [];
   const allowedStatuses = contract.run?.allowedStatuses ?? [];
@@ -2727,6 +2863,7 @@ function contractToRules(contract) {
   }
   if (contract.tools) {
     const order = contract.tools.requiredOrder ?? [];
+    const requiredOrderMode = contract.tools.requiredOrderMode ?? "first-occurrence";
     const required = [
       .../* @__PURE__ */ new Set([
         ...contract.tools.required ?? [],
@@ -2751,7 +2888,8 @@ function contractToRules(contract) {
         createToolOrderingRule({
           before: order[i],
           after: order[i + 1],
-          id: `contract.tool.order.${i}`
+          id: `contract.tool.order.${i}`,
+          mode: requiredOrderMode
         })
       );
     }
@@ -2801,25 +2939,319 @@ function contractToRules(contract) {
   }
   return rules;
 }
-function defineTraceContract(input) {
+function validateAlternativesShape(alternatives) {
+  const diagnostics = [];
+  if (alternatives === void 0) return diagnostics;
+  const branches = alternatives.anyOf ?? [];
+  if (branches.length === 0) {
+    diagnostics.push({
+      code: "contract.alternatives.empty",
+      severity: "error",
+      message: "alternatives.anyOf must contain at least one branch.",
+      path: "alternatives.anyOf"
+    });
+    return diagnostics;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, branch] of branches.entries()) {
+    const path = `alternatives.anyOf[${index}]`;
+    if (!branch?.id || branch.id.trim() === "") {
+      diagnostics.push({
+        code: "contract.alternatives.missing-id",
+        severity: "error",
+        message: "Each alternatives.anyOf branch requires a non-empty id.",
+        path
+      });
+      continue;
+    }
+    if (seen.has(branch.id)) {
+      diagnostics.push({
+        code: "contract.alternatives.duplicate-id",
+        severity: "error",
+        message: `Duplicate alternatives.anyOf branch id: ${branch.id}`,
+        path: `${path}.id`
+      });
+    }
+    seen.add(branch.id);
+    if (!bodyHasRules(branch.contract ?? {})) {
+      diagnostics.push({
+        code: "contract.alternatives.empty-branch",
+        severity: "error",
+        message: `Branch ${branch.id} must declare at least one run/tools/llm/observations rule.`,
+        path: `${path}.contract`
+      });
+    }
+    const nested = branch.contract?.alternatives;
+    if (nested !== void 0) {
+      diagnostics.push({
+        code: "contract.alternatives.nested",
+        severity: "error",
+        message: "Nested alternatives.anyOf is not supported. Keep one alternatives level only.",
+        path: `${path}.contract.alternatives`
+      });
+    }
+  }
+  return diagnostics;
+}
+function emptyPassResult(input, runId) {
   return {
-    ...input.run ? { run: { ...input.run } } : {},
-    ...input.tools ? { tools: { ...input.tools } } : {},
-    ...input.llm ? { llm: { ...input.llm } } : {},
-    ...input.observations ? { observations: { ...input.observations } } : {}
+    ok: true,
+    status: "pass",
+    format: input.read.format,
+    ...runId !== void 0 ? { runId } : {},
+    summary: { passed: 0, failed: 0, warnings: 0, errors: 0, rulesEvaluated: 0 },
+    findings: [],
+    diagnostics: [],
+    ruleExecutions: []
   };
 }
-function evaluateTraceContract(input, contract, options = {}) {
-  const rules = contractToRules(contract);
+function mergeContractResults(input, parts, extraFindings = []) {
+  const findings = [...parts.flatMap((part) => part.findings), ...extraFindings];
+  const diagnostics = parts.flatMap((part) => part.diagnostics);
+  const ruleExecutions = parts.flatMap((part) => part.ruleExecutions);
+  const failed = findings.filter(
+    (finding) => finding.status === "fail" && finding.severity === "error"
+  ).length;
+  const errors = diagnostics.filter((item) => item.severity === "error").length;
+  const status = errors > 0 ? "error" : failed > 0 ? "fail" : "pass";
+  const runId = parts.find((part) => part.runId !== void 0)?.runId;
+  return {
+    ok: status === "pass",
+    status,
+    format: input.read.format,
+    ...runId !== void 0 ? { runId } : {},
+    summary: {
+      passed: findings.filter((finding) => finding.status === "pass").length,
+      failed,
+      warnings: findings.filter(
+        (finding) => finding.status === "warning" || finding.severity === "warning"
+      ).length,
+      errors,
+      rulesEvaluated: ruleExecutions.length
+    },
+    findings,
+    diagnostics,
+    ruleExecutions
+  };
+}
+function evaluateBody(input, body, options = {}) {
+  const rules = contractToRules(body);
+  if (rules.length === 0) {
+    return emptyPassResult(input, options.runId);
+  }
   return runTraceChecks(input, {
     rules,
     ...options.runId !== void 0 ? { runId: options.runId } : {}
   });
 }
+function defineTraceContract(input) {
+  const shapeErrors = validateAlternativesShape(input.alternatives).filter(
+    (item) => item.severity === "error"
+  );
+  if (shapeErrors.length > 0) {
+    throw new TypeError(shapeErrors.map((item) => item.message).join(" "));
+  }
+  const body = cloneBody(input);
+  const alternatives = input.alternatives ? {
+    anyOf: input.alternatives.anyOf.map((branch) => ({
+      id: branch.id,
+      ...branch.description !== void 0 ? { description: branch.description } : {},
+      contract: cloneBody(branch.contract)
+    }))
+  } : void 0;
+  return {
+    ...body,
+    ...alternatives ? { alternatives } : {}
+  };
+}
+function evaluateTraceContract(input, contract, options = {}) {
+  const shapeErrors = validateAlternativesShape(contract.alternatives).filter(
+    (item) => item.severity === "error"
+  );
+  if (shapeErrors.length > 0) {
+    return {
+      ok: false,
+      status: "error",
+      format: input.read.format,
+      ...options.runId !== void 0 ? { runId: options.runId } : {},
+      summary: {
+        passed: 0,
+        failed: 0,
+        warnings: 0,
+        errors: shapeErrors.length,
+        rulesEvaluated: 0
+      },
+      findings: [],
+      diagnostics: shapeErrors.map((item) => ({
+        code: "AI_CHECK_INVALID_CONFIG",
+        message: item.message,
+        severity: "error",
+        ruleId: item.code
+      })),
+      ruleExecutions: []
+    };
+  }
+  const base = evaluateBody(input, contract, options);
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length === 0) {
+    return base;
+  }
+  const branchEvaluations = branches.map((branch) => {
+    const result = evaluateBody(input, branch.contract, options);
+    return { branch, result };
+  });
+  const satisfied = branchEvaluations.filter((item) => item.result.ok && item.result.status === "pass").map((item) => item.branch.id);
+  const failedBranches = branchEvaluations.filter(
+    (item) => !(item.result.ok && item.result.status === "pass")
+  );
+  if (satisfied.length > 0) {
+    const passFinding = {
+      ruleId: "contract.alternatives.anyOf",
+      severity: "info",
+      status: "pass",
+      message: `Satisfied alternative branch(es): ${satisfied.join(", ")}.`,
+      expected: { anyOf: branches.map((branch) => branch.id) },
+      actual: {
+        satisfied,
+        failed: failedBranches.map((item) => item.branch.id)
+      },
+      evidence: []
+    };
+    return mergeContractResults(input, [base], [passFinding]);
+  }
+  const noneFinding = {
+    ruleId: "contract.alternatives.none-satisfied",
+    severity: "error",
+    status: "fail",
+    message: "No alternatives.anyOf branch fully satisfied its contract.",
+    expected: { anyOf: branches.map((branch) => branch.id) },
+    actual: {
+      branchFailures: Object.fromEntries(
+        failedBranches.map((item) => [
+          item.branch.id,
+          item.result.findings.filter((finding) => finding.status === "fail").map((finding) => ({
+            ruleId: finding.ruleId,
+            message: finding.message
+          }))
+        ])
+      )
+    },
+    evidence: []
+  };
+  const prefixedBranchFindings = failedBranches.flatMap(
+    (item) => item.result.findings.filter((finding) => finding.status === "fail").map((finding) => ({
+      ...finding,
+      ruleId: `contract.alternatives.${item.branch.id}.${finding.ruleId}`
+    }))
+  );
+  return mergeContractResults(input, [base], [noneFinding, ...prefixedBranchFindings]);
+}
 function evaluateTraceContractRead(read, contract, options = {}) {
   return evaluateTraceContract({ read }, contract, options);
 }
+function lintTraceContract(contract) {
+  const diagnostics = validateAlternativesShape(contract.alternatives);
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length === 1) {
+    diagnostics.push({
+      code: "contract.alternatives.single-branch",
+      severity: "warning",
+      message: "alternatives.anyOf has a single branch. Prefer base rules unless a second valid path exists.",
+      path: "alternatives.anyOf"
+    });
+  }
+  const required = [
+    ...contract.tools?.required ?? [],
+    ...contract.tools?.requiredTools ?? []
+  ];
+  if (required.length > 0 && branches.length === 0) {
+    diagnostics.push({
+      code: "contract.brittle.unconditional-required",
+      severity: "info",
+      message: "tools.required is unconditional. Use alternatives.anyOf when a legitimate shortcut may skip a tool.",
+      path: "tools.required"
+    });
+  }
+  const order = contract.tools?.requiredOrder ?? [];
+  if (order.length >= 2 && contract.tools?.requiredOrderMode === void 0) {
+    diagnostics.push({
+      code: "contract.brittle.first-occurrence-default",
+      severity: "info",
+      message: "requiredOrder defaults to first-occurrence. Set requiredOrderMode when repeated calls must fail.",
+      path: "tools.requiredOrderMode"
+    });
+  }
+  return diagnostics;
+}
+function explainTraceContract(contract) {
+  const lines = [];
+  if (contract.run?.requireCompleted !== false) {
+    lines.push("Base: run must complete (no running events).");
+  }
+  if (contract.run?.allowedStatuses?.length) {
+    lines.push(`Base: run status in [${contract.run.allowedStatuses.join(", ")}].`);
+  }
+  if (contract.run?.maxDurationMs !== void 0) {
+    lines.push(`Base: run duration <= ${contract.run.maxDurationMs}ms.`);
+  }
+  if (contract.tools) {
+    const required = [
+      .../* @__PURE__ */ new Set([
+        ...contract.tools.required ?? [],
+        ...contract.tools.requiredTools ?? [],
+        ...contract.tools.requiredOrder ?? []
+      ])
+    ];
+    if (required.length > 0) {
+      lines.push(`Base: required tools [${required.join(", ")}].`);
+    }
+    const forbidden = [
+      ...contract.tools.forbidden ?? [],
+      ...contract.tools.forbiddenTools ?? []
+    ];
+    if (forbidden.length > 0) {
+      lines.push(`Base: forbidden tools [${forbidden.join(", ")}].`);
+    }
+    if ((contract.tools.requiredOrder?.length ?? 0) >= 2) {
+      const mode = contract.tools.requiredOrderMode ?? "first-occurrence";
+      lines.push(
+        `Base: requiredOrder [${contract.tools.requiredOrder.join(" \u2192 ")}] mode=${mode}.`
+      );
+    }
+  }
+  if (contract.llm) {
+    if (contract.llm.maxCalls !== void 0) {
+      lines.push(`Base: LLM maxCalls=${contract.llm.maxCalls}.`);
+    }
+    if (contract.llm.maxTotalTokens !== void 0) {
+      lines.push(`Base: LLM maxTotalTokens=${contract.llm.maxTotalTokens}.`);
+    }
+    if (contract.llm.allowedModels?.length) {
+      lines.push(`Base: LLM allowedModels [${contract.llm.allowedModels.join(", ")}].`);
+    }
+  }
+  if (contract.observations?.required?.length) {
+    lines.push(`Base: required observations [${contract.observations.required.join(", ")}].`);
+  }
+  if (contract.observations?.failOn?.length) {
+    lines.push(`Base: fail on observations [${contract.observations.failOn.join(", ")}].`);
+  }
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length > 0) {
+    lines.push(
+      `Alternatives: at least one of [${branches.map((branch) => branch.id).join(", ")}] must fully pass.`
+    );
+    for (const branch of branches) {
+      const detail = branch.description ? ` \u2014 ${branch.description}` : "";
+      lines.push(`  branch ${branch.id}${detail}`);
+    }
+  }
+  if (lines.length === 0) {
+    lines.push("Empty contract: no base rules and no alternatives.");
+  }
+  return lines;
+}
 
-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, evaluateTraceContract, evaluateTraceContractRead, projectLogicalEvents, resolveCanonicalToolName, runTraceChecks, summarizeSemanticParity };
-//# sourceMappingURL=chunk-NABMW5DX.mjs.map
-//# sourceMappingURL=chunk-NABMW5DX.mjs.map
+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, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, runTraceChecks, summarizeSemanticParity };
+//# sourceMappingURL=chunk-G47KQB42.mjs.map
+//# sourceMappingURL=chunk-G47KQB42.mjs.map