agent-contracts 0.11.4 → 0.11.6

package/dist/index.d.ts

@@ -198,6 +198,17 @@ declare const ComponentsSchema: z.ZodObject<{
     schemas: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>>>;
 }, z.core.$loose>;
 type Components = z.infer<typeof ComponentsSchema>;
+/**
+ * Declaration of project-specific `x-*` extension fields.
+ * Each key must start with `x-` and describes the expected type/shape
+ * so that tooling can validate custom extensions in the future.
+ */
+declare const XExtensionDeclSchema: z.ZodObject<{
+    type: z.ZodString;
+    items: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type XExtensionDecl = z.infer<typeof XExtensionDeclSchema>;
 declare const DslSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     extends: z.ZodOptional<z.ZodString>;
@@ -390,7 +401,8 @@ declare const DslSchema: z.ZodObject<{
         }, z.core.$loose>, z.ZodObject<{
             type: z.ZodLiteral<"decision">;
             description: z.ZodOptional<z.ZodString>;
-            on: z.ZodString;
+            on: z.ZodOptional<z.ZodString>;
+            routing_key: z.ZodOptional<z.ZodString>;
             branches: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
             group: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>], "type">>;
@@ -452,6 +464,11 @@ declare const DslSchema: z.ZodObject<{
     components: z.ZodDefault<z.ZodObject<{
         schemas: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>>>;
     }, z.core.$loose>>;
+    "x-extensions": z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        items: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$loose>;
 type Dsl = z.infer<typeof DslSchema>;
 
@@ -777,7 +794,8 @@ declare const WorkflowStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$loose>, z.ZodObject<{
     type: z.ZodLiteral<"decision">;
     description: z.ZodOptional<z.ZodString>;
-    on: z.ZodString;
+    on: z.ZodOptional<z.ZodString>;
+    routing_key: z.ZodOptional<z.ZodString>;
     branches: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
     group: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>], "type">;
@@ -822,7 +840,8 @@ declare const WorkflowSchema: z.ZodObject<{
     }, z.core.$loose>, z.ZodObject<{
         type: z.ZodLiteral<"decision">;
         description: z.ZodOptional<z.ZodString>;
-        on: z.ZodString;
+        on: z.ZodOptional<z.ZodString>;
+        routing_key: z.ZodOptional<z.ZodString>;
         branches: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
         group: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>], "type">>;
@@ -866,6 +885,15 @@ interface ResolveResult {
 }
 declare function resolve(projectDirOrFile: string): Promise<ResolveResult>;
 
+/**
+ * Parse the resolved DSL through Zod to fill all schema-defined default
+ * values, then return the fully-expanded plain object.
+ *
+ * If parsing fails (e.g. the DSL has validation errors), the original
+ * data is returned unchanged so that `resolve` remains non-destructive.
+ */
+declare function expandDefaults(data: Record<string, unknown>): Record<string, unknown>;
+
 interface DiagnosticMessage {
     path: string;
     message: string;
@@ -916,6 +944,8 @@ declare function lint(dsl: Dsl, rules?: LintRule[]): LintDiagnostic[];
  */
 declare function spectralLint(dslObject: Record<string, unknown>): Promise<LintDiagnostic[]>;
 
+declare const yamlReservedKeySafetyRule: LintRule;
+
 declare const CONTEXT_TYPES: readonly ["agent", "task", "artifact", "tool", "validation", "handoff_type", "workflow", "policy", "guardrail", "guardrail_policy", "system"];
 declare const ContextTypeSchema: z.ZodEnum<{
     guardrail: "guardrail";
@@ -1229,4 +1259,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, buildArtifactContext, buildGlobalContext, buildGuardrailContext, buildGuardrailPolicyContext, buildHandoffTypeContext, buildPerAgentContext, buildPolicyContext, buildSystemContext, buildTaskContext, buildToolContext, buildValidationContext, buildWorkflowContext, builtinRules, checkDriftFromConfig, checkReferences, generateGuardrails, lint, loadBindings, loadConfig, loadDsl, mergeDsl, renderFromConfig, resolve, resolveAllOf, resolveBase, resolveBindingTargetPath, resolveChecks, resolveDslPath, spectralLint, validateHandoffSchemas, validateSchema };
+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 };

package/dist/index.js

@@ -50712,7 +50712,9 @@ var WorkflowValidationStepSchema = z11.object({
 var WorkflowDecisionStepSchema = z11.object({
   type: z11.literal("decision"),
   description: z11.string().optional(),
-  on: z11.string(),
+  /** @deprecated Use `routing_key` instead. `on` is kept for backward compatibility. */
+  on: z11.string().optional(),
+  routing_key: z11.string().optional(),
   branches: z11.record(z11.string(), z11.array(z11.string())),
   group: z11.string().optional()
 }).passthrough();
@@ -50735,6 +50737,11 @@ var WorkflowSchema = z11.object({
 var ComponentsSchema = z12.object({
   schemas: z12.record(z12.string(), z12.record(z12.string(), z12.any())).default({})
 }).passthrough();
+var XExtensionDeclSchema = z12.object({
+  type: z12.string(),
+  items: z12.string().optional(),
+  description: z12.string().optional()
+});
 var DslSchema = z12.object({
   version: z12.literal(1),
   extends: z12.string().optional(),
@@ -50749,7 +50756,8 @@ var DslSchema = z12.object({
   policies: z12.record(z12.string(), PolicySchema).default({}),
   guardrails: z12.record(z12.string(), GuardrailSchema).default({}),
   guardrail_policies: z12.record(z12.string(), GuardrailPolicySchema).default({}),
-  components: ComponentsSchema.default({ schemas: {} })
+  components: ComponentsSchema.default({ schemas: {} }),
+  "x-extensions": z12.record(z12.string(), XExtensionDeclSchema).optional()
 }).passthrough();
 
 // src/schema/json-schema-utils.ts
@@ -51422,6 +51430,13 @@ async function resolve3(projectDirOrFile) {
   };
 }
 
+// src/resolver/expand-defaults.ts
+function expandDefaults(data) {
+  const result = DslSchema.safeParse(data);
+  if (!result.success) return data;
+  return JSON.parse(JSON.stringify(result.data));
+}
+
 // src/validator/schema-validator.ts
 import { z as z14 } from "zod";
 function unwrap(schema) {
@@ -51484,6 +51499,47 @@ function checkCustomPropsRecursive(data, schema, path) {
   }
   return [];
 }
+function checkXExtensionsKeys(data) {
+  const extensions = data["x-extensions"];
+  if (typeof extensions !== "object" || extensions === null) return [];
+  const diagnostics = [];
+  for (const key of Object.keys(extensions)) {
+    if (!key.startsWith("x-")) {
+      diagnostics.push({
+        path: `x-extensions.${key}`,
+        message: `Extension key "${key}" must start with "x-" prefix.`,
+        code: "x-extension-key-prefix"
+      });
+    }
+  }
+  return diagnostics;
+}
+function checkDecisionStepRoutingKey(data) {
+  const workflow = data["workflow"];
+  if (typeof workflow !== "object" || workflow === null) return [];
+  const diagnostics = [];
+  for (const [wfKey, wf] of Object.entries(
+    workflow
+  )) {
+    if (typeof wf !== "object" || wf === null) continue;
+    const steps = wf["steps"];
+    if (!Array.isArray(steps)) continue;
+    for (let i3 = 0; i3 < steps.length; i3++) {
+      const step = steps[i3];
+      if (typeof step !== "object" || step === null) continue;
+      const s2 = step;
+      if (s2["type"] !== "decision") continue;
+      if (s2["routing_key"] === void 0 && s2["on"] === void 0) {
+        diagnostics.push({
+          path: `workflow.${wfKey}.steps[${i3}]`,
+          message: 'Decision step requires "routing_key" (or deprecated "on"). Prefer "routing_key".',
+          code: "decision-missing-routing-key"
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
 function validateSchema(data) {
   const result = DslSchema.safeParse(data);
   if (!result.success) {
@@ -51498,6 +51554,14 @@ function validateSchema(data) {
   if (customPropDiagnostics.length > 0) {
     return { success: false, diagnostics: customPropDiagnostics };
   }
+  const decisionDiagnostics = checkDecisionStepRoutingKey(data);
+  if (decisionDiagnostics.length > 0) {
+    return { success: false, diagnostics: decisionDiagnostics };
+  }
+  const xExtDiagnostics = checkXExtensionsKeys(data);
+  if (xExtDiagnostics.length > 0) {
+    return { success: false, diagnostics: xExtDiagnostics };
+  }
   return { success: true, data: result.data, diagnostics: [] };
 }
 
@@ -51812,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) {
@@ -51823,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",
@@ -51833,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) {
@@ -52174,6 +52248,146 @@ var guardrailPolicyCoverageRule = {
   }
 };
 
+// src/linter/rules/yaml-reserved-key-safety.ts
+var YAML_11_RESERVED_KEYS = /* @__PURE__ */ new Set([
+  "on",
+  "off",
+  "yes",
+  "no",
+  "true",
+  "false",
+  "y",
+  "n"
+]);
+var yamlReservedKeySafetyRule = {
+  id: "yaml-reserved-key-safety",
+  description: "Warns when YAML 1.1 reserved words are used as field values in positions where they may be misinterpreted by non-1.2 parsers",
+  run(dsl) {
+    const diagnostics = [];
+    for (const [wfKey, wf] of Object.entries(dsl.workflow)) {
+      for (let i3 = 0; i3 < wf.steps.length; i3++) {
+        const step = wf.steps[i3];
+        if (step.type !== "decision") continue;
+        if (step.on !== void 0 && step.routing_key === void 0) {
+          diagnostics.push({
+            ruleId: "yaml-reserved-key-safety",
+            severity: "warning",
+            path: `workflow.${wfKey}.steps[${i3}].on`,
+            message: 'Field name "on" is a YAML 1.1 reserved word and may be interpreted as boolean true by some parsers. Use "routing_key" instead.'
+          });
+        }
+        const branchKeys = Object.keys(step.branches);
+        for (const key of branchKeys) {
+          if (YAML_11_RESERVED_KEYS.has(key.toLowerCase())) {
+            diagnostics.push({
+              ruleId: "yaml-reserved-key-safety",
+              severity: "warning",
+              path: `workflow.${wfKey}.steps[${i3}].branches.${key}`,
+              message: `Branch key "${key}" is a YAML 1.1 reserved word and may be interpreted as a boolean by some parsers. Consider quoting or renaming.`
+            });
+          }
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// 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,
@@ -52182,7 +52396,10 @@ var builtinRules = [
   mergeIntegrityRule,
   artifactOwnershipRule,
   toolCommandsRule,
-  guardrailPolicyCoverageRule
+  guardrailPolicyCoverageRule,
+  yamlReservedKeySafetyRule,
+  artifactRequiredValidationWiringRule,
+  taskOutputValidationCompletenessRule
 ];
 function lint(dsl, rules = builtinRules) {
   const diagnostics = [];
@@ -54609,6 +54826,7 @@ export {
   VersionLiteralSchema,
   WorkflowSchema,
   WorkflowStepSchema,
+  XExtensionDeclSchema,
   buildArtifactContext,
   buildGlobalContext,
   buildGuardrailContext,
@@ -54624,6 +54842,7 @@ export {
   builtinRules,
   checkDriftFromConfig,
   checkReferences,
+  expandDefaults,
   generateGuardrails,
   lint,
   loadBindings,
@@ -54639,7 +54858,8 @@ export {
   resolveDslPath,
   spectralLint,
   validateHandoffSchemas,
-  validateSchema
+  validateSchema,
+  yamlReservedKeySafetyRule
 };
 /*! Bundled license information: