agent-contracts 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -196,6 +196,7 @@ declare const DslSchema: z.ZodObject<{
                 wait_for_approval: "wait_for_approval";
             }>;
         }, z.core.$loose>>>;
+        validations: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$loose>>>;
     artifacts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodString;
@@ -250,6 +251,22 @@ declare const DslSchema: z.ZodObject<{
         entry_conditions: z.ZodDefault<z.ZodArray<z.ZodString>>;
         trigger: z.ZodOptional<z.ZodString>;
         steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"delegate">;
+            description: z.ZodOptional<z.ZodString>;
+            task: z.ZodString;
+            from_agent: z.ZodString;
+            group: z.ZodOptional<z.ZodString>;
+            retry: z.ZodOptional<z.ZodObject<{
+                condition: z.ZodString;
+                fix_task: z.ZodString;
+                revalidate_task: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"gate">;
+            description: z.ZodOptional<z.ZodString>;
+            gate_kind: z.ZodString;
+            group: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>, z.ZodObject<{
             type: z.ZodLiteral<"handoff">;
             description: z.ZodOptional<z.ZodString>;
             handoff_kind: z.ZodString;
@@ -427,6 +444,7 @@ declare const TaskSchema: z.ZodObject<{
             wait_for_approval: "wait_for_approval";
         }>;
     }, z.core.$loose>>>;
+    validations: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;
 type Task = z.infer<typeof TaskSchema>;
 
@@ -490,6 +508,22 @@ declare const ExternalParticipantSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ExternalParticipant = z.infer<typeof ExternalParticipantSchema>;
 declare const WorkflowStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"delegate">;
+    description: z.ZodOptional<z.ZodString>;
+    task: z.ZodString;
+    from_agent: z.ZodString;
+    group: z.ZodOptional<z.ZodString>;
+    retry: z.ZodOptional<z.ZodObject<{
+        condition: z.ZodString;
+        fix_task: z.ZodString;
+        revalidate_task: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"gate">;
+    description: z.ZodOptional<z.ZodString>;
+    gate_kind: z.ZodString;
+    group: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
     type: z.ZodLiteral<"handoff">;
     description: z.ZodOptional<z.ZodString>;
     handoff_kind: z.ZodString;
@@ -519,6 +553,22 @@ declare const WorkflowSchema: z.ZodObject<{
     entry_conditions: z.ZodDefault<z.ZodArray<z.ZodString>>;
     trigger: z.ZodOptional<z.ZodString>;
     steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"delegate">;
+        description: z.ZodOptional<z.ZodString>;
+        task: z.ZodString;
+        from_agent: z.ZodString;
+        group: z.ZodOptional<z.ZodString>;
+        retry: z.ZodOptional<z.ZodObject<{
+            condition: z.ZodString;
+            fix_task: z.ZodString;
+            revalidate_task: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"gate">;
+        description: z.ZodOptional<z.ZodString>;
+        gate_kind: z.ZodString;
+        group: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
         type: z.ZodLiteral<"handoff">;
         description: z.ZodOptional<z.ZodString>;
         handoff_kind: z.ZodString;

package/dist/index.js

@@ -58419,7 +58419,8 @@ var TaskSchema = z6.object({
   completion_criteria: z6.array(z6.string()).optional(),
   rules: z6.array(RuleSchema).optional(),
   anti_patterns: z6.array(z6.string()).optional(),
-  escalation_criteria: z6.array(EscalationCriterionSchema).optional()
+  escalation_criteria: z6.array(EscalationCriterionSchema).optional(),
+  validations: z6.array(z6.string()).default([])
 }).passthrough();
 
 // src/schema/tool.ts
@@ -58465,6 +58466,20 @@ var ExternalParticipantSchema = z9.object({
   label: z9.string(),
   description: z9.string().optional()
 });
+var WorkflowDelegateStepSchema = z9.object({
+  type: z9.literal("delegate"),
+  description: z9.string().optional(),
+  task: z9.string(),
+  from_agent: z9.string(),
+  group: z9.string().optional(),
+  retry: RetrySchema.optional()
+}).passthrough();
+var WorkflowGateStepSchema = z9.object({
+  type: z9.literal("gate"),
+  description: z9.string().optional(),
+  gate_kind: z9.string(),
+  group: z9.string().optional()
+}).passthrough();
 var WorkflowHandoffStepSchema = z9.object({
   type: z9.literal("handoff"),
   description: z9.string().optional(),
@@ -58488,6 +58503,8 @@ var WorkflowDecisionStepSchema = z9.object({
   group: z9.string().optional()
 }).passthrough();
 var WorkflowStepSchema = z9.discriminatedUnion("type", [
+  WorkflowDelegateStepSchema,
+  WorkflowGateStepSchema,
   WorkflowHandoffStepSchema,
   WorkflowValidationStepSchema,
   WorkflowDecisionStepSchema
@@ -59264,12 +59281,20 @@ function checkReferences(dsl) {
     for (const ref of task.input_artifacts) {
       checkExists(ref, artifactIds, "artifacts", `tasks.${id}.input_artifacts`);
     }
+    for (const ref of task.validations) {
+      checkExists(ref, validationIds, "validations", `tasks.${id}.validations`);
+    }
   }
   for (const [wfId, wf] of Object.entries(dsl.workflow)) {
     checkExists(wfId, workflowIds, "system.default_workflow_order", `workflow.${wfId}`);
     for (let j2 = 0; j2 < wf.steps.length; j2++) {
       const step = wf.steps[j2];
-      if (step.type === "handoff") {
+      if (step.type === "delegate") {
+        checkExists(step.task, taskIds, "tasks", `workflow.${wfId}.steps[${j2}].task`);
+        checkExists(step.from_agent, agentIds, "agents", `workflow.${wfId}.steps[${j2}].from_agent`);
+      } else if (step.type === "gate") {
+        checkExists(step.gate_kind, handoffKinds, "handoff_types", `workflow.${wfId}.steps[${j2}].gate_kind`);
+      } else if (step.type === "handoff") {
         if (step.task) {
           checkExists(step.task, taskIds, "tasks", `workflow.${wfId}.steps[${j2}].task`);
         }
@@ -59394,21 +59419,26 @@ var validationCoverageRule = {
         });
       }
     }
-    const validationsReferencedInWorkflow = /* @__PURE__ */ new Set();
+    const referencedValidations = /* @__PURE__ */ new Set();
     for (const wf of Object.values(dsl.workflow)) {
       for (const step of wf.steps) {
         if (step.type === "validation") {
-          validationsReferencedInWorkflow.add(step.validation);
+          referencedValidations.add(step.validation);
         }
       }
     }
+    for (const task of Object.values(dsl.tasks)) {
+      for (const valId of task.validations) {
+        referencedValidations.add(valId);
+      }
+    }
     for (const [valId, val] of Object.entries(dsl.validations)) {
-      if (val.blocking && !validationsReferencedInWorkflow.has(valId)) {
+      if (val.blocking && !referencedValidations.has(valId)) {
         diagnostics.push({
           ruleId: "validation-coverage",
           severity: "warning",
           path: `validations.${valId}`,
-          message: `Blocking validation "${valId}" is not referenced in any workflow step`
+          message: `Blocking validation "${valId}" is not referenced in any workflow step or task`
         });
       }
     }
@@ -59884,6 +59914,28 @@ var workflow_handoff_kind_exists_default = (0, import_spectral_core6.createRules
     for (let i3 = 0; i3 < steps.length; i3++) {
       const step = steps[i3];
       const stepPath = [...context.path, "steps", i3];
+      if (step.type === "delegate") {
+        if (step.task && !taskKeys.has(step.task)) {
+          results.push({
+            message: `task "${step.task}" does not exist in tasks`,
+            path: [...stepPath, "task"]
+          });
+        }
+        if (step.from_agent && !agentKeys.has(step.from_agent)) {
+          results.push({
+            message: `from_agent "${step.from_agent}" does not exist in agents`,
+            path: [...stepPath, "from_agent"]
+          });
+        }
+      }
+      if (step.type === "gate") {
+        if (step.gate_kind && !handoffKeys.has(step.gate_kind)) {
+          results.push({
+            message: `gate_kind "${step.gate_kind}" does not exist in handoff_types`,
+            path: [...stepPath, "gate_kind"]
+          });
+        }
+      }
       if (step.type === "handoff") {
         if (step.handoff_kind && !handoffKeys.has(step.handoff_kind)) {
           results.push({
@@ -60097,6 +60149,17 @@ var ruleset = {
         functionOptions: { referenceTo: "artifacts" }
       }
     },
+    "task-validations-ref": {
+      description: "Task validations must reference existing validations",
+      message: "{{error}}",
+      severity: "error",
+      given: "$.tasks.*",
+      then: {
+        field: "validations",
+        function: ref_exists_default,
+        functionOptions: { referenceTo: "validations" }
+      }
+    },
     "validation-target-artifact-ref": {
       description: "Validation target_artifact must reference an existing artifact",
       message: "{{error}}",
@@ -60140,7 +60203,7 @@ var ruleset = {
     },
     // ========== 15.2.5 Handoff integrity ==========
     "workflow-step-refs": {
-      description: "Workflow step references (handoff_kind, task, from_agent, validation) must exist",
+      description: "Workflow step references (task, from_agent, gate_kind, handoff_kind, validation) must exist",
       message: "{{error}}",
       severity: "error",
       given: "$.workflow.*",
@@ -60407,7 +60470,23 @@ function buildHandoffTypeContext(dsl, handoffTypeId) {
 function buildWorkflowContext(dsl, workflowId) {
   const wfDef = dsl.workflow[workflowId];
   const workflow = { ...wfDef, id: workflowId };
-  const relatedTasks = Object.entries(dsl.tasks).filter(([, t3]) => t3.workflow === workflowId).map(([id, t3]) => ({ ...t3, id }));
+  const stepReferencedTaskIds = /* @__PURE__ */ new Set();
+  for (const step of wfDef.steps) {
+    if (step.type === "delegate") {
+      stepReferencedTaskIds.add(step.task);
+      if (step.retry) {
+        stepReferencedTaskIds.add(step.retry.fix_task);
+        if (step.retry.revalidate_task) stepReferencedTaskIds.add(step.retry.revalidate_task);
+      }
+    } else if (step.type === "handoff" && step.task) {
+      stepReferencedTaskIds.add(step.task);
+      if (step.retry) {
+        stepReferencedTaskIds.add(step.retry.fix_task);
+        if (step.retry.revalidate_task) stepReferencedTaskIds.add(step.retry.revalidate_task);
+      }
+    }
+  }
+  const relatedTasks = Object.entries(dsl.tasks).filter(([id, t3]) => t3.workflow === workflowId || stepReferencedTaskIds.has(id)).map(([id, t3]) => ({ ...t3, id }));
   const agentIds = /* @__PURE__ */ new Set();
   for (const task of relatedTasks) {
     agentIds.add(task.target_agent);
@@ -60416,7 +60495,9 @@ function buildWorkflowContext(dsl, workflowId) {
     }
   }
   for (const step of wfDef.steps) {
-    if (step.type === "handoff" && step.from_agent) {
+    if (step.type === "delegate") {
+      agentIds.add(step.from_agent);
+    } else if (step.type === "handoff" && step.from_agent) {
       agentIds.add(step.from_agent);
     }
     if (step.type === "validation") {
@@ -60473,6 +60554,11 @@ function buildWorkflowContext(dsl, workflowId) {
       validationIds.add(step.validation);
     }
   }
+  for (const task of relatedTasks) {
+    for (const valId of task.validations ?? []) {
+      validationIds.add(valId);
+    }
+  }
   const relatedValidations = {};
   for (const id of validationIds) {
     if (dsl.validations[id]) relatedValidations[id] = dsl.validations[id];
@@ -60643,33 +60729,34 @@ function collectReferencedIds(workflow, dsl, relatedTasks) {
   const artifacts = /* @__PURE__ */ new Set();
   const taskMap = /* @__PURE__ */ new Map();
   for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  function collectTaskIds(task) {
+    addAgent(task.target_agent);
+    for (const es of task.execution_steps ?? []) {
+      collectExecutionStepIds(es, tools, artifacts);
+    }
+  }
+  function collectRetryIds(retry) {
+    const fixTask = taskMap.get(retry.fix_task);
+    if (fixTask) collectTaskIds(fixTask);
+    if (retry.revalidate_task) {
+      const revalTask = taskMap.get(retry.revalidate_task);
+      if (revalTask) addAgent(revalTask.target_agent);
+    }
+  }
   for (const step of workflow.steps) {
-    if (step.type === "handoff") {
+    if (step.type === "delegate") {
+      addAgent(step.from_agent);
+      const task = taskMap.get(step.task);
+      if (task) collectTaskIds(task);
+      if (step.retry) collectRetryIds(step.retry);
+    } else if (step.type === "gate") {
+    } else if (step.type === "handoff") {
       if (step.from_agent) addAgent(step.from_agent);
       if (step.task) {
         const task = taskMap.get(step.task);
-        if (task) {
-          addAgent(task.target_agent);
-          for (const es of task.execution_steps ?? []) {
-            collectExecutionStepIds(es, tools, artifacts);
-          }
-        }
-      }
-      if (step.retry) {
-        const fixTask = taskMap.get(step.retry.fix_task);
-        if (fixTask) {
-          addAgent(fixTask.target_agent);
-          for (const es of fixTask.execution_steps ?? []) {
-            collectExecutionStepIds(es, tools, artifacts);
-          }
-        }
-        if (step.retry.revalidate_task) {
-          const revalTask = taskMap.get(step.retry.revalidate_task);
-          if (revalTask) {
-            addAgent(revalTask.target_agent);
-          }
-        }
+        if (task) collectTaskIds(task);
       }
+      if (step.retry) collectRetryIds(step.retry);
     } else if (step.type === "validation") {
       const val = dsl.validations[step.validation];
       if (val) {
@@ -60857,16 +60944,33 @@ function emitDecisionStep(step, participants, lastFromAgent, lines, indent) {
   }
   lines.push(`${indent}end`);
 }
-function emitRetryBlock(step, participants, dsl, relatedTasks, lines, indent) {
-  const retry = step.retry;
-  if (!retry) return;
+function emitDelegateStep(step, participants, dsl, relatedTasks, lines, indent) {
+  const taskMap = /* @__PURE__ */ new Map();
+  for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
+  const task = taskMap.get(step.task);
+  if (!task) return;
+  const fromAlias = participantAlias(participants, step.from_agent);
+  const targetAlias = participantAlias(participants, task.target_agent);
+  lines.push(`${indent}${fromAlias}->>${targetAlias}: delegate ${step.task}`);
+  for (const es of task.execution_steps ?? []) {
+    emitExecutionStep(es, targetAlias, participants, lines, indent);
+  }
+  lines.push(`${indent}${targetAlias}-->>${fromAlias}: ${task.result_handoff}`);
+}
+function emitGateStep(step, participants, lastFromAgent, lines, indent) {
+  if (lastFromAgent) {
+    const agentAl = participantAlias(participants, lastFromAgent);
+    lines.push(`${indent}${agentAl}->>${agentAl}: ${step.gate_kind}`);
+  }
+}
+function emitRetryBlock(fromAgent, retry, participants, relatedTasks, lines, indent) {
   const taskMap = /* @__PURE__ */ new Map();
   for (const t3 of relatedTasks) taskMap.set(t3.id, t3);
   lines.push(`${indent}opt ${retry.condition}`);
   const innerIndent = indent + "    ";
   const fixTask = taskMap.get(retry.fix_task);
   if (fixTask) {
-    const fromAlias = step.from_agent ? participantAlias(participants, step.from_agent) : null;
+    const fromAlias = fromAgent ? participantAlias(participants, fromAgent) : null;
     const targetAlias = participantAlias(participants, fixTask.target_agent);
     if (fromAlias) {
       lines.push(`${innerIndent}${fromAlias}->>${targetAlias}: fix ${retry.fix_task}`);
@@ -60881,7 +60985,7 @@ function emitRetryBlock(step, participants, dsl, relatedTasks, lines, indent) {
   if (retry.revalidate_task) {
     const revalTask = taskMap.get(retry.revalidate_task);
     if (revalTask) {
-      const fromAlias = step.from_agent ? participantAlias(participants, step.from_agent) : null;
+      const fromAlias = fromAgent ? participantAlias(participants, fromAgent) : null;
       const revalAlias = participantAlias(participants, revalTask.target_agent);
       if (fromAlias) {
         lines.push(`${innerIndent}${fromAlias}->>${revalAlias}: revalidate ${retry.revalidate_task}`);
@@ -60968,11 +61072,19 @@ function generateSequenceDiagram(workflow, relatedTasks, dsl) {
   return lines.join("\n");
 }
 function emitStep(step, participants, dsl, relatedTasks, lines, indent, lastFromAgent, setLastFromAgent) {
-  if (step.type === "handoff") {
+  if (step.type === "delegate") {
+    setLastFromAgent(step.from_agent);
+    emitDelegateStep(step, participants, dsl, relatedTasks, lines, indent);
+    if (step.retry) {
+      emitRetryBlock(step.from_agent, step.retry, participants, relatedTasks, lines, indent);
+    }
+  } else if (step.type === "gate") {
+    emitGateStep(step, participants, lastFromAgent, lines, indent);
+  } else if (step.type === "handoff") {
     if (step.from_agent) setLastFromAgent(step.from_agent);
     emitHandoffStep(step, participants, dsl, relatedTasks, lines, indent);
     if (step.retry) {
-      emitRetryBlock(step, participants, dsl, relatedTasks, lines, indent);
+      emitRetryBlock(step.from_agent, step.retry, participants, relatedTasks, lines, indent);
     }
   } else if (step.type === "validation") {
     emitValidationStep(step, participants, dsl, lastFromAgent, lines, indent);
@@ -60993,28 +61105,34 @@ function collectPhaseOps(dsl, wfId) {
     map.get(id).add(op);
   }
   const taskMap = new Map(ctx.relatedTasks.map((t3) => [t3.id, t3]));
+  function collectTaskOps(task) {
+    addOp(agentOps, task.target_agent, "execute");
+    for (const es of task.execution_steps ?? []) {
+      if (es.reads_artifact) addOp(artifactOps, es.reads_artifact, "R");
+      if (es.produces_artifact) addOp(artifactOps, es.produces_artifact, "W");
+      if (es.uses_tool) {
+        const tool = dsl.tools[es.uses_tool];
+        if (tool) {
+          const cats = tool.commands.map((c2) => c2.category).filter((v2, i3, a3) => a3.indexOf(v2) === i3);
+          for (const cat of cats) addOp(toolOps, es.uses_tool, cat);
+          if (cats.length === 0) addOp(toolOps, es.uses_tool, "\u2713");
+        } else {
+          addOp(toolOps, es.uses_tool, "\u2713");
+        }
+      }
+    }
+  }
   for (const step of wf.steps) {
-    if (step.type === "handoff") {
+    if (step.type === "delegate") {
+      addOp(agentOps, step.from_agent, "delegate");
+      const task = taskMap.get(step.task);
+      if (task) collectTaskOps(task);
+    } else if (step.type === "gate") {
+    } else if (step.type === "handoff") {
       if (step.from_agent) addOp(agentOps, step.from_agent, "delegate");
       if (step.task) {
         const task = taskMap.get(step.task);
-        if (task) {
-          addOp(agentOps, task.target_agent, "execute");
-          for (const es of task.execution_steps ?? []) {
-            if (es.reads_artifact) addOp(artifactOps, es.reads_artifact, "R");
-            if (es.produces_artifact) addOp(artifactOps, es.produces_artifact, "W");
-            if (es.uses_tool) {
-              const tool = dsl.tools[es.uses_tool];
-              if (tool) {
-                const cats = tool.commands.map((c2) => c2.category).filter((v2, i3, a3) => a3.indexOf(v2) === i3);
-                for (const cat of cats) addOp(toolOps, es.uses_tool, cat);
-                if (cats.length === 0) addOp(toolOps, es.uses_tool, "\u2713");
-              } else {
-                addOp(toolOps, es.uses_tool, "\u2713");
-              }
-            }
-          }
-        }
+        if (task) collectTaskOps(task);
       }
     } else if (step.type === "validation") {
       const val = dsl.validations[step.validation];