agent-contracts 0.11.5 → 0.11.7

package/dist/index.d.ts

@@ -1204,6 +1204,22 @@ declare class ConfigLoadError extends Error {
 declare function loadConfig(configPath?: string): Promise<ResolvedConfig | null>;
 declare function resolveDslPath(dirArg: string | undefined, dirArgDefault: string, config: ResolvedConfig | null): string;
 
+interface DimensionResult {
+    id: string;
+    label: string;
+    score: number;
+    total: number;
+    percent: number;
+    weight: number;
+    recommendations: string[];
+}
+interface ScoreResult {
+    overall: number;
+    dimensions: DimensionResult[];
+}
+
+declare function score(dsl: Dsl): ScoreResult;
+
 interface ResolvedCheck {
     guardrail_id: string;
     guardrail: Guardrail;
@@ -1259,4 +1275,4 @@ interface PathResolveResult {
 }
 declare function resolveBindingTargetPath(target: string, paths: Record<string, string>, bindingSoftware: string): PathResolveResult;
 
-export { type Agent, type AgentContractsConfig, AgentContractsConfigSchema, AgentSchema, type AppendOperator, AppendOperatorSchema, type Artifact, ArtifactSchema, BaseResolveError, type BindingOutput, BindingOutputSchema, CONTEXT_TYPES, type Check, CheckSchema, type Command, CommandSchema, type Components, ComponentsSchema, ConfigLoadError, type ContextType, ContextTypeSchema, type DelegatableTaskView, type DiagnosticMessage, type Dsl, DslLoadError, DslSchema, type EscalationCriterion, EscalationCriterionSchema, type ExecutionStep, ExecutionStepSchema, type Extends, ExtendsSchema, type ExternalParticipant, type GenerateDiagnostic, type GenerateGuardrailsOptions, type GenerateResult, type GlobalContext, type Guardrail, type GuardrailGenerationContext, type GuardrailPolicy, type GuardrailPolicyRule, type GuardrailPolicyRuleEscalation, GuardrailPolicyRuleEscalationSchema, GuardrailPolicyRuleSchema, GuardrailPolicySchema, GuardrailSchema, type GuardrailScope, GuardrailScopeSchema, type HandoffType, HandoffTypeSchema, type InsertAfterOperator, InsertAfterOperatorSchema, type LintDiagnostic, type LintRule, type LoadResult, type LoadedBinding, type Matcher, MatcherSchema, MergeError, type MergeableRecord, type MergedBehavioralSpec, type PathResolveResult, type PerAgentContext, type PerArtifactContext, type PerGuardrailContext, type PerGuardrailPolicyContext, type PerHandoffTypeContext, type PerPolicyContext, type PerTaskContext, type PerToolContext, type PerValidationContext, type PerWorkflowContext, type Policy, PolicySchema, type PolicyWhen, PolicyWhenSchema, type PrependOperator, PrependOperatorSchema, type Prerequisite, PrerequisiteSchema, type ReferenceDiagnostic, type RemoveOperator, RemoveOperatorSchema, type RenderTarget, RenderTargetSchema, type ReplaceOperator, ReplaceOperatorSchema, type Reporting, ReportingSchema, type ResolveChecksResult, type ResolveResult, type ResolvedCheck, type ResolvedConfig, type ResolvedRenderTarget, type Retry, type Rule, RuleSchema, type SchemaValidationResult, type Severity, type SoftwareBinding, SoftwareBindingSchema, type System, type SystemContext, SystemSchema, type Task, TaskSchema, type Tool, ToolSchema, type Validation, ValidationSchema, type VersionLiteral, VersionLiteralSchema, type Workflow, WorkflowSchema, type WorkflowStep, WorkflowStepSchema, type XExtensionDecl, XExtensionDeclSchema, buildArtifactContext, buildGlobalContext, buildGuardrailContext, buildGuardrailPolicyContext, buildHandoffTypeContext, buildPerAgentContext, buildPolicyContext, buildSystemContext, buildTaskContext, buildToolContext, buildValidationContext, buildWorkflowContext, builtinRules, checkDriftFromConfig, checkReferences, expandDefaults, generateGuardrails, lint, loadBindings, loadConfig, loadDsl, mergeDsl, renderFromConfig, resolve, resolveAllOf, resolveBase, resolveBindingTargetPath, resolveChecks, resolveDslPath, spectralLint, validateHandoffSchemas, validateSchema, yamlReservedKeySafetyRule };
+export { type Agent, type AgentContractsConfig, AgentContractsConfigSchema, AgentSchema, type AppendOperator, AppendOperatorSchema, type Artifact, ArtifactSchema, BaseResolveError, type BindingOutput, BindingOutputSchema, CONTEXT_TYPES, type Check, CheckSchema, type Command, CommandSchema, type Components, ComponentsSchema, ConfigLoadError, type ContextType, ContextTypeSchema, type DelegatableTaskView, type DiagnosticMessage, type DimensionResult, type Dsl, DslLoadError, DslSchema, type EscalationCriterion, EscalationCriterionSchema, type ExecutionStep, ExecutionStepSchema, type Extends, ExtendsSchema, type ExternalParticipant, type GenerateDiagnostic, type GenerateGuardrailsOptions, type GenerateResult, type GlobalContext, type Guardrail, type GuardrailGenerationContext, type GuardrailPolicy, type GuardrailPolicyRule, type GuardrailPolicyRuleEscalation, GuardrailPolicyRuleEscalationSchema, GuardrailPolicyRuleSchema, GuardrailPolicySchema, GuardrailSchema, type GuardrailScope, GuardrailScopeSchema, type HandoffType, HandoffTypeSchema, type InsertAfterOperator, InsertAfterOperatorSchema, type LintDiagnostic, type LintRule, type LoadResult, type LoadedBinding, type Matcher, MatcherSchema, MergeError, type MergeableRecord, type MergedBehavioralSpec, type PathResolveResult, type PerAgentContext, type PerArtifactContext, type PerGuardrailContext, type PerGuardrailPolicyContext, type PerHandoffTypeContext, type PerPolicyContext, type PerTaskContext, type PerToolContext, type PerValidationContext, type PerWorkflowContext, type Policy, PolicySchema, type PolicyWhen, PolicyWhenSchema, type PrependOperator, PrependOperatorSchema, type Prerequisite, PrerequisiteSchema, type ReferenceDiagnostic, type RemoveOperator, RemoveOperatorSchema, type RenderTarget, RenderTargetSchema, type ReplaceOperator, ReplaceOperatorSchema, type Reporting, ReportingSchema, type ResolveChecksResult, type ResolveResult, type ResolvedCheck, type ResolvedConfig, type ResolvedRenderTarget, type Retry, type Rule, RuleSchema, type SchemaValidationResult, type ScoreResult, type Severity, type SoftwareBinding, SoftwareBindingSchema, type System, type SystemContext, SystemSchema, type Task, TaskSchema, type Tool, ToolSchema, type Validation, ValidationSchema, type VersionLiteral, VersionLiteralSchema, type Workflow, WorkflowSchema, type WorkflowStep, WorkflowStepSchema, type XExtensionDecl, XExtensionDeclSchema, buildArtifactContext, buildGlobalContext, buildGuardrailContext, buildGuardrailPolicyContext, buildHandoffTypeContext, buildPerAgentContext, buildPolicyContext, buildSystemContext, buildTaskContext, buildToolContext, buildValidationContext, buildWorkflowContext, builtinRules, checkDriftFromConfig, checkReferences, expandDefaults, generateGuardrails, lint, loadBindings, loadConfig, loadDsl, mergeDsl, renderFromConfig, resolve, resolveAllOf, resolveBase, resolveBindingTargetPath, resolveChecks, resolveDslPath, score, spectralLint, validateHandoffSchemas, validateSchema, yamlReservedKeySafetyRule };

package/dist/index.js

@@ -51876,6 +51876,7 @@ var validationCoverageRule = {
       }
       validationsByArtifact.get(val.target_artifact).add(val.kind);
     }
+    const strictArtifactTypes = ["code", "config", "schema"];
     for (const [artId, art] of Object.entries(dsl.artifacts)) {
       const kinds = validationsByArtifact.get(artId);
       if (!kinds || kinds.size === 0) {
@@ -51887,8 +51888,7 @@ var validationCoverageRule = {
         });
         continue;
       }
-      const mechanicalTypes = ["code", "config", "schema"];
-      if (mechanicalTypes.includes(art.type) && !kinds.has("mechanical") && !kinds.has("schema")) {
+      if (strictArtifactTypes.includes(art.type) && !kinds.has("mechanical") && !kinds.has("schema")) {
         diagnostics.push({
           ruleId: "validation-coverage",
           severity: "warning",
@@ -51897,6 +51897,16 @@ var validationCoverageRule = {
         });
       }
     }
+    for (const [artId, art] of Object.entries(dsl.artifacts)) {
+      if (art.required_validations.length === 0) {
+        diagnostics.push({
+          ruleId: "validation-coverage",
+          severity: "warning",
+          path: `artifacts.${artId}`,
+          message: `Artifact "${artId}" has empty required_validations`
+        });
+      }
+    }
     const referencedValidations = /* @__PURE__ */ new Set();
     for (const wf of Object.values(dsl.workflow)) {
       for (const step of wf.steps) {
@@ -52283,6 +52293,101 @@ var yamlReservedKeySafetyRule = {
   }
 };
 
+// src/linter/rules/artifact-required-validation-wiring.ts
+var artifactRequiredValidationWiringRule = {
+  id: "artifact-required-validation-wiring",
+  description: "Every validation listed in artifact.required_validations must exist, target the artifact, and be referenced in a workflow step or task.",
+  run(dsl) {
+    const diagnostics = [];
+    const referencedValidations = /* @__PURE__ */ new Set();
+    for (const wf of Object.values(dsl.workflow)) {
+      for (const step of wf.steps) {
+        if (step.type === "validation") {
+          referencedValidations.add(step.validation);
+        }
+      }
+    }
+    for (const task of Object.values(dsl.tasks)) {
+      for (const valId of task.validations) {
+        referencedValidations.add(valId);
+      }
+    }
+    for (const [artId, art] of Object.entries(dsl.artifacts)) {
+      for (const reqValId of art.required_validations) {
+        const val = dsl.validations[reqValId];
+        if (!val) {
+          diagnostics.push({
+            ruleId: "artifact-required-validation-wiring",
+            severity: "error",
+            path: `artifacts.${artId}`,
+            message: `required_validation "${reqValId}" does not exist in validations`
+          });
+          continue;
+        }
+        if (val.target_artifact !== artId) {
+          diagnostics.push({
+            ruleId: "artifact-required-validation-wiring",
+            severity: "error",
+            path: `artifacts.${artId}`,
+            message: `required_validation "${reqValId}" has target_artifact "${val.target_artifact}" instead of "${artId}"`
+          });
+        }
+        if (!referencedValidations.has(reqValId)) {
+          diagnostics.push({
+            ruleId: "artifact-required-validation-wiring",
+            severity: "warning",
+            path: `artifacts.${artId}`,
+            message: `required_validation "${reqValId}" is defined but not referenced in any workflow step or task`
+          });
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/linter/rules/task-output-validation-completeness.ts
+var taskOutputValidationCompletenessRule = {
+  id: "task-output-validation-completeness",
+  description: "Tasks producing artifacts should cover those artifacts' required_validations in their validations list.",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [taskId, task] of Object.entries(dsl.tasks)) {
+      const producedArtifacts = /* @__PURE__ */ new Set();
+      if (task.execution_steps) {
+        for (const step of task.execution_steps) {
+          if (step.produces_artifact) {
+            producedArtifacts.add(step.produces_artifact);
+          }
+        }
+      }
+      const agent = dsl.agents[task.target_agent];
+      if (agent) {
+        for (const artId of agent.can_write_artifacts) {
+          producedArtifacts.add(artId);
+        }
+      }
+      const taskValidations = new Set(task.validations);
+      for (const artId of producedArtifacts) {
+        const art = dsl.artifacts[artId];
+        if (!art || art.required_validations.length === 0) continue;
+        const missing = art.required_validations.filter(
+          (v2) => !taskValidations.has(v2)
+        );
+        if (missing.length > 0) {
+          diagnostics.push({
+            ruleId: "task-output-validation-completeness",
+            severity: "warning",
+            path: `tasks.${taskId}`,
+            message: `Task produces artifact "${artId}" which requires validations [${missing.join(", ")}] but task.validations does not include them`
+          });
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
 // src/linter/linter.ts
 var builtinRules = [
   validationCoverageRule,
@@ -52292,7 +52397,9 @@ var builtinRules = [
   artifactOwnershipRule,
   toolCommandsRule,
   guardrailPolicyCoverageRule,
-  yamlReservedKeySafetyRule
+  yamlReservedKeySafetyRule,
+  artifactRequiredValidationWiringRule,
+  taskOutputValidationCompletenessRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -54437,6 +54544,271 @@ ${issues}`,
   return results;
 }
 
+// src/scorer/scorer.ts
+function pct(n3, d2) {
+  return d2 === 0 ? 100 : Math.round(n3 / d2 * 100);
+}
+function artifactValidationCoverage(dsl) {
+  const entries = Object.entries(dsl.artifacts);
+  const total = entries.length;
+  const covered = entries.filter(
+    ([, a3]) => a3.required_validations.length > 0
+  ).length;
+  const missing = entries.filter(([, a3]) => a3.required_validations.length === 0).map(([id]) => id);
+  return {
+    id: "artifact-validation-coverage",
+    label: "Artifact validation coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} artifacts missing required_validations: ${missing.join(", ")}`] : []
+  };
+}
+function taskValidationCoverage(dsl) {
+  const entries = Object.entries(dsl.tasks);
+  const total = entries.length;
+  const covered = entries.filter(([, t3]) => t3.validations.length > 0).length;
+  const missing = entries.filter(([, t3]) => t3.validations.length === 0).map(([id]) => id);
+  return {
+    id: "task-validation-coverage",
+    label: "Task validation coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} tasks missing validations: ${missing.join(", ")}`] : []
+  };
+}
+function guardrailPolicyCoverage(dsl) {
+  const guardrailIds = Object.keys(dsl.guardrails);
+  const total = guardrailIds.length;
+  const referenced = /* @__PURE__ */ new Set();
+  for (const policy of Object.values(dsl.guardrail_policies)) {
+    for (const rule of policy.rules) {
+      referenced.add(rule.guardrail);
+    }
+  }
+  const covered = guardrailIds.filter((id) => referenced.has(id)).length;
+  const missing = guardrailIds.filter((id) => !referenced.has(id));
+  return {
+    id: "guardrail-policy-coverage",
+    label: "Guardrail policy coverage",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 2,
+    recommendations: missing.length > 0 ? [`${missing.length} guardrails not in any policy: ${missing.join(", ")}`] : []
+  };
+}
+function workflowValidationIntegration(dsl) {
+  const blockingValidations = Object.entries(dsl.validations).filter(
+    ([, v2]) => v2.blocking
+  );
+  const total = blockingValidations.length;
+  const referenced = /* @__PURE__ */ new Set();
+  for (const wf of Object.values(dsl.workflow)) {
+    for (const step of wf.steps) {
+      if (step.type === "validation") {
+        referenced.add(step.validation);
+      }
+    }
+  }
+  for (const task of Object.values(dsl.tasks)) {
+    for (const valId of task.validations) {
+      referenced.add(valId);
+    }
+  }
+  const covered = blockingValidations.filter(
+    ([id]) => referenced.has(id)
+  ).length;
+  const missing = blockingValidations.filter(([id]) => !referenced.has(id)).map(([id]) => id);
+  return {
+    id: "workflow-validation-integration",
+    label: "Workflow validation integration",
+    score: covered,
+    total,
+    percent: pct(covered, total),
+    weight: 3,
+    recommendations: missing.length > 0 ? [`${missing.length} blocking validations not wired: ${missing.join(", ")}`] : []
+  };
+}
+var OPTIONAL_ENTITY_FIELDS = {
+  agents: {
+    section: "agents",
+    fields: ["responsibilities", "constraints", "rules"]
+  },
+  tasks: {
+    section: "tasks",
+    fields: ["description", "responsibilities", "execution_steps", "completion_criteria"]
+  },
+  artifacts: {
+    section: "artifacts",
+    fields: ["description", "visibility"]
+  },
+  tools: {
+    section: "tools",
+    fields: ["description", "commands"]
+  },
+  workflow: {
+    section: "workflow",
+    fields: ["description", "trigger", "entry_conditions"]
+  },
+  guardrails: {
+    section: "guardrails",
+    fields: ["rationale", "tags"]
+  }
+};
+function hasNonEmpty(obj, field) {
+  const val = obj[field];
+  if (val === void 0 || val === null) return false;
+  if (typeof val === "string") return val.length > 0;
+  if (Array.isArray(val)) return val.length > 0;
+  return true;
+}
+function schemaCompleteness(dsl) {
+  let totalSlots = 0;
+  let filledSlots = 0;
+  const lowSections = [];
+  for (const [sectionKey, meta] of Object.entries(OPTIONAL_ENTITY_FIELDS)) {
+    const entities = dsl[meta.section];
+    if (!entities) continue;
+    let sectionTotal = 0;
+    let sectionFilled = 0;
+    for (const entity of Object.values(entities)) {
+      for (const field of meta.fields) {
+        sectionTotal++;
+        totalSlots++;
+        if (hasNonEmpty(entity, field)) {
+          sectionFilled++;
+          filledSlots++;
+        }
+      }
+    }
+    if (sectionTotal > 0 && pct(sectionFilled, sectionTotal) < 50) {
+      lowSections.push(sectionKey);
+    }
+  }
+  return {
+    id: "schema-completeness",
+    label: "Schema completeness",
+    score: filledSlots,
+    total: totalSlots,
+    percent: pct(filledSlots, totalSlots),
+    weight: 1,
+    recommendations: lowSections.length > 0 ? [`Low optional field coverage in: ${lowSections.join(", ")}`] : []
+  };
+}
+function crossReferenceBidirectionality(dsl) {
+  let totalChecks = 0;
+  let passedChecks = 0;
+  const issues = [];
+  for (const [agentId, agent] of Object.entries(dsl.agents)) {
+    for (const toolId of agent.can_execute_tools) {
+      totalChecks++;
+      const tool = dsl.tools[toolId];
+      if (tool && tool.invokable_by.includes(agentId)) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 tool ${toolId}`);
+      }
+    }
+    for (const artId of agent.can_write_artifacts) {
+      totalChecks++;
+      const art = dsl.artifacts[artId];
+      if (art && (art.producers.includes(agentId) || art.editors.includes(agentId))) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 artifact ${artId} (write)`);
+      }
+    }
+    for (const artId of agent.can_read_artifacts) {
+      totalChecks++;
+      const art = dsl.artifacts[artId];
+      if (art && (art.consumers.includes(agentId) || art.producers.includes(agentId) || art.editors.includes(agentId))) {
+        passedChecks++;
+      } else {
+        issues.push(`agent ${agentId} \u2192 artifact ${artId} (read)`);
+      }
+    }
+  }
+  for (const [toolId, tool] of Object.entries(dsl.tools)) {
+    for (const agentId of tool.invokable_by) {
+      totalChecks++;
+      const agent = dsl.agents[agentId];
+      if (agent && agent.can_execute_tools.includes(toolId)) {
+        passedChecks++;
+      } else {
+        issues.push(`tool ${toolId} \u2192 agent ${agentId}`);
+      }
+    }
+  }
+  return {
+    id: "cross-reference-bidirectionality",
+    label: "Cross-reference bidirectionality",
+    score: passedChecks,
+    total: totalChecks,
+    percent: pct(passedChecks, totalChecks),
+    weight: 2,
+    recommendations: issues.length > 0 ? [`${issues.length} unreciprocated cross-references: ${issues.slice(0, 5).join(", ")}${issues.length > 5 ? `, ... (${issues.length - 5} more)` : ""}`] : []
+  };
+}
+function guardrailScopeResolution(dsl) {
+  let totalRefs = 0;
+  let resolvedRefs = 0;
+  const unresolved = [];
+  const sectionMap = {
+    agents: dsl.agents,
+    tasks: dsl.tasks,
+    tools: dsl.tools,
+    artifacts: dsl.artifacts,
+    workflows: dsl.workflow
+  };
+  for (const [guardrailId, guardrail] of Object.entries(dsl.guardrails)) {
+    const scope = guardrail.scope;
+    for (const [scopeKey, entityIds] of Object.entries(scope)) {
+      if (!Array.isArray(entityIds)) continue;
+      const section = sectionMap[scopeKey];
+      if (!section) continue;
+      for (const entityId of entityIds) {
+        totalRefs++;
+        if (section[entityId]) {
+          resolvedRefs++;
+        } else {
+          unresolved.push(`${guardrailId}.scope.${scopeKey}: ${entityId}`);
+        }
+      }
+    }
+  }
+  return {
+    id: "guardrail-scope-resolution",
+    label: "Guardrail scope resolution",
+    score: resolvedRefs,
+    total: totalRefs,
+    percent: pct(resolvedRefs, totalRefs),
+    weight: 2,
+    recommendations: unresolved.length > 0 ? [`${unresolved.length} unresolved scope refs: ${unresolved.join(", ")}`] : []
+  };
+}
+function score(dsl) {
+  const dimensions = [
+    artifactValidationCoverage(dsl),
+    taskValidationCoverage(dsl),
+    guardrailPolicyCoverage(dsl),
+    workflowValidationIntegration(dsl),
+    schemaCompleteness(dsl),
+    crossReferenceBidirectionality(dsl),
+    guardrailScopeResolution(dsl)
+  ];
+  const totalWeight = dimensions.reduce((s2, d2) => s2 + d2.weight, 0);
+  const weightedSum = dimensions.reduce(
+    (s2, d2) => s2 + d2.percent * d2.weight,
+    0
+  );
+  const overall = totalWeight === 0 ? 100 : Math.round(weightedSum / totalWeight);
+  return { overall, dimensions };
+}
+
 // src/guardrail-generator/generator.ts
 import { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, chmod, unlink as unlink2 } from "fs/promises";
 import { resolve as resolve6, dirname as dirname6 } from "path";
@@ -54749,6 +55121,7 @@ export {
   resolveBindingTargetPath,
   resolveChecks,
   resolveDslPath,
+  score,
   spectralLint,
   validateHandoffSchemas,
   validateSchema,