@decocms/bindings 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",

package/src/well-known/language-model.ts

@@ -230,7 +230,6 @@ export const LanguageModelMessageSchema = z.union([
 export const LanguageModelPromptSchema = z
   .array(LanguageModelMessageSchema)
   .describe("A list of messages forming the prompt");
-
 /**
  * Language Model Call Options Schema
  * Based on LanguageModelV2CallOptions from @ai-sdk/provider

package/src/well-known/workflow.ts

@@ -9,113 +9,137 @@
  */
 
 import { z } from "zod";
-import type { Binder } from "../core/binder";
+import { type Binder, bindingClient, type ToolBinder } from "../core/binder";
 import {
   BaseCollectionEntitySchema,
   createCollectionBindings,
 } from "./collections";
-
 export const ToolCallActionSchema = z.object({
-  connectionId: z.string().describe("Integration connection ID"),
-  toolName: z.string().describe("Name of the tool to call"),
+  toolName: z
+    .string()
+    .describe("Name of the tool to invoke on that connection"),
+  transformCode: z
+    .string()
+    .optional()
+    .describe(`Pure TypeScript function for data transformation of the tool call result. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(input): Output { ... }\`
+    The input will match with the tool call outputSchema. If transformCode is not provided, the tool call result will be used as the step output. 
+    Providing an transformCode is recommended because it both allows you to transform the data and validate it against a JSON Schema - tools are ephemeral and may return unexpected data.`),
 });
 export type ToolCallAction = z.infer<typeof ToolCallActionSchema>;
 
 export const CodeActionSchema = z.object({
-  code: z.string().describe("TypeScript code for pure data transformation"),
+  code: z.string().describe(
+    `Pure TypeScript function for data transformation. Useful to merge data from multiple steps and transform it. Must be a TypeScript file that declares the Output interface and exports a default function: \`interface Output { ... } export default async function(input): Output { ... }\`
+       The input is the resolved value of the references in the input field. Example: 
+       {
+         "input": {
+          "name": "@Step_1.name",
+          "age": "@Step_2.age"
+         },
+         "code": "export default function(input): Output { return { result: \`\${input.name} is \${input.age} years old.\` } }"
+       }
+      `,
+  ),
 });
 export type CodeAction = z.infer<typeof CodeActionSchema>;
-export const SleepActionSchema = z.union([
-  z.object({
-    sleepMs: z.number().describe("Milliseconds to sleep"),
-  }),
-  z.object({
-    sleepUntil: z.string().describe("ISO date string or @ref to sleep until"),
-  }),
-]);
 
 export const WaitForSignalActionSchema = z.object({
   signalName: z
     .string()
-    .describe("Name of the signal to wait for (must be unique per execution)"),
-  timeoutMs: z
-    .number()
-    .optional()
-    .describe("Maximum time to wait in milliseconds (default: no timeout)"),
-  description: z
-    .string()
-    .optional()
-    .describe("Human-readable description of what this signal is waiting for"),
+    .describe(
+      "Signal name to wait for (e.g., 'approval'). Execution pauses until SEND_SIGNAL is called with this name.",
+    ),
 });
 export type WaitForSignalAction = z.infer<typeof WaitForSignalActionSchema>;
 
 export const StepActionSchema = z.union([
-  ToolCallActionSchema.describe(
-    "Call an external tool (non-deterministic, checkpointed)",
-  ),
+  ToolCallActionSchema.describe("Call an external tool via MCP connection. "),
   CodeActionSchema.describe(
-    "Pure TypeScript data transformation (deterministic, replayable)",
+    "Run pure TypeScript code for data transformation. Useful to merge data from multiple steps and transform it.",
   ),
-  SleepActionSchema.describe("Wait for time"),
-  WaitForSignalActionSchema.describe("Wait for external signal"),
+  // WaitForSignalActionSchema.describe(
+  //   "Pause execution until an external signal is received (human-in-the-loop)",
+  // ),
 ]);
 export type StepAction = z.infer<typeof StepActionSchema>;
+
 /**
- * Step Schema - Unified schema for all step types
- *
- * Step types:
- * - tool: Call external service via MCP (non-deterministic, checkpointed)
- * - transform: Pure TypeScript data transformation (deterministic, replayable)
- * - sleep: Wait for time
- * - waitForSignal: Block until external signal (human-in-the-loop)
+ * Step Config Schema - Optional configuration for retry, timeout, and looping
  */
-export const StepSchema = z.object({
-  name: z.string().min(1).describe("Unique step name within workflow"),
-  action: StepActionSchema,
-  input: z
-    .record(z.unknown())
+export const StepConfigSchema = z.object({
+  maxAttempts: z
+    .number()
     .optional()
-    .describe(
-      "Input object with @ref resolution or default values. Example: { 'user_id': '@input.user_id', 'product_id': '@input.product_id' }",
-    ),
-  config: z
-    .object({
-      maxAttempts: z.number().default(3).describe("Maximum retry attempts"),
-      backoffMs: z
-        .number()
-        .default(1000)
-        .describe("Initial backoff in milliseconds"),
-      timeoutMs: z.number().default(10000).describe("Timeout in milliseconds"),
-    })
+    .describe("Max retry attempts on failure (default: 1, no retries)"),
+  backoffMs: z
+    .number()
+    .optional()
+    .describe("Initial delay between retries in ms (doubles each attempt)"),
+  timeoutMs: z
+    .number()
     .optional()
-    .describe("Step configuration (max attempts, backoff, timeout)"),
+    .describe("Max execution time in ms before step fails (default: 30000)"),
 });
-
-export type Step = z.infer<typeof StepSchema>;
+export type StepConfig = z.infer<typeof StepConfigSchema>;
 
 /**
- * Trigger Schema - Fire another workflow when execution completes
+ * Step Schema - A single unit of work in a workflow
+ *
+ * Action types:
+ * - Tool call: Invoke an external tool via MCP connection
+ * - Code: Run pure TypeScript for data transformation
+ * - Wait for signal: Pause until external input (human-in-the-loop)
+ *
+ * Data flow uses @ref syntax:
+ * - @input.field → workflow input
+ * - @stepName.field → output from a previous step
  */
-export const TriggerSchema = z.object({
-  /**
-   * Target workflow ID to execute
-   */
-  workflowId: z.string().describe("Target workflow ID to trigger"),
-
-  /**
-   * Input for the new execution (uses @refs like step inputs)
-   * Maps output data to workflow input fields.
-   *
-   * If any @ref doesn't resolve (property missing), this trigger is SKIPPED.
-   */
+
+type JsonSchema = {
+  type?: string;
+  properties?: Record<string, unknown>;
+  required?: string[];
+  description?: string;
+  additionalProperties?: boolean;
+  additionalItems?: boolean;
+  items?: JsonSchema;
+};
+const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
+  z
+    .object({
+      type: z.string().optional(),
+      properties: z.record(z.unknown()).optional(),
+      required: z.array(z.string()).optional(),
+      description: z.string().optional(),
+      additionalProperties: z.boolean().optional(),
+      additionalItems: z.boolean().optional(),
+      items: JsonSchemaSchema.optional(),
+    })
+    .passthrough(),
+);
+
+export const StepSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe(
+      "Unique identifier for this step. Other steps reference its output as @name.field",
+    ),
+  description: z.string().optional().describe("What this step does"),
+  action: StepActionSchema,
   input: z
     .record(z.unknown())
+    .optional()
     .describe(
-      "Input mapping with @refs from current workflow output. Example: { 'user_id': '@stepName.output.user_id' }",
+      "Data passed to the action. Use @ref for dynamic values: @input.field (workflow input), @stepName.field (previous step output), @item/@index (loop context). Example: { 'userId': '@input.user_id', 'data': '@fetch.result' }",
     ),
+  outputSchema: JsonSchemaSchema.optional().describe(
+    "Optional JSON Schema describing the expected output of the step.",
+  ),
+  config: StepConfigSchema.optional().describe("Retry and timeout settings"),
 });
 
-export type Trigger = z.infer<typeof TriggerSchema>;
+export type Step = z.infer<typeof StepSchema>;
 
 /**
  * Workflow Execution Status
@@ -128,8 +152,8 @@ export type Trigger = z.infer<typeof TriggerSchema>;
  */
 
 const WorkflowExecutionStatusEnum = z
-  .enum(["pending", "running", "completed", "cancelled"])
-  .default("pending");
+  .enum(["enqueued", "running", "success", "error", "failed", "cancelled"])
+  .default("enqueued");
 export type WorkflowExecutionStatus = z.infer<
   typeof WorkflowExecutionStatusEnum
 >;
@@ -140,38 +164,48 @@ export type WorkflowExecutionStatus = z.infer<
  * Includes lock columns and retry tracking.
  */
 export const WorkflowExecutionSchema = BaseCollectionEntitySchema.extend({
-  workflow_id: z.string(),
-  status: WorkflowExecutionStatusEnum,
-  input: z.record(z.unknown()).optional(),
-  output: z.unknown().optional(),
-  parent_execution_id: z.string().nullish(),
-  completed_at_epoch_ms: z.number().nullish(),
-  locked_until_epoch_ms: z.number().nullish(),
-  lock_id: z.string().nullish(),
-  retry_count: z.number().default(0),
-  max_retries: z.number().default(10),
-  error: z.string().nullish(),
+  steps: z
+    .array(StepSchema)
+    .describe("Steps that make up the workflow")
+    .describe("Workflow that was executed"),
+  gateway_id: z
+    .string()
+    .describe("ID of the gateway that will be used to execute the workflow"),
+  status: WorkflowExecutionStatusEnum.describe(
+    "Current status of the workflow execution",
+  ),
+  input: z
+    .record(z.unknown())
+    .optional()
+    .describe("Input data for the workflow execution"),
+  output: z
+    .unknown()
+    .optional()
+    .describe("Output data for the workflow execution"),
+  completed_at_epoch_ms: z
+    .number()
+    .nullish()
+    .describe("Timestamp of when the workflow execution completed"),
+  start_at_epoch_ms: z
+    .number()
+    .nullish()
+    .describe("Timestamp of when the workflow execution started or will start"),
+  timeout_ms: z
+    .number()
+    .nullish()
+    .describe("Timeout in milliseconds for the workflow execution"),
+  deadline_at_epoch_ms: z
+    .number()
+    .nullish()
+    .describe(
+      "Deadline for the workflow execution - when the workflow execution will be cancelled if it is not completed. This is read-only and is set by the workflow engine when an execution is created.",
+    ),
+  error: z
+    .unknown()
+    .describe("Error that occurred during the workflow execution"),
 });
 export type WorkflowExecution = z.infer<typeof WorkflowExecutionSchema>;
 
-/**
- * Execution Step Result Schema
- *
- * Includes attempt tracking and error history.
- */
-export const WorkflowExecutionStepResultSchema =
-  BaseCollectionEntitySchema.extend({
-    execution_id: z.string(),
-    step_id: z.string(),
-
-    input: z.record(z.unknown()).nullish(),
-    output: z.unknown().nullish(), // Can be object or array (forEach steps produce arrays)
-    error: z.string().nullish(),
-    completed_at_epoch_ms: z.number().nullish(),
-  });
-export type WorkflowExecutionStepResult = z.infer<
-  typeof WorkflowExecutionStepResultSchema
->;
 /**
  * Event Type Enum
  *
@@ -216,29 +250,35 @@ export const WorkflowEventSchema = BaseCollectionEntitySchema.extend({
 export type WorkflowEvent = z.infer<typeof WorkflowEventSchema>;
 
 /**
- * Workflow entity schema for workflows
- * Extends BaseCollectionEntitySchema with workflow-specific fields
- * Base schema already includes: id, title, created_at, updated_at, created_by, updated_by
+ * Workflow Schema - A sequence of steps that execute with data flowing between them
+ *
+ * Key concepts:
+ * - Steps run in parallel unless they reference each other via @ref
+ * - Use @ref to wire data: @input.field, @stepName.field, @item (in loops)
+ * - Execution order is auto-determined from @ref dependencies
+ *
+ * Example: 2 parallel fetches + 1 merge step
+ * {
+ *   "title": "Fetch and Merge",
+ *   "steps": [
+ *     { "name": "fetch_users", "action": { "connectionId": "api", "toolName": "getUsers" } },
+ *     { "name": "fetch_orders", "action": { "connectionId": "api", "toolName": "getOrders" } },
+ *     { "name": "merge", "action": { "code": "..." }, "input": { "users": "@fetch_users.data", "orders": "@fetch_orders.data" } }
+ *   ]
+ * }
+ * → fetch_users and fetch_orders run in parallel; merge waits for both
  */
 export const WorkflowSchema = BaseCollectionEntitySchema.extend({
-  description: z.string().optional().describe("Workflow description"),
+  description: z
+    .string()
+    .optional()
+    .describe("Human-readable summary of what this workflow does"),
 
-  /**
-   * Steps organized into phases.
-   * - Phases execute sequentially
-   * - Steps within a phase execute in parallel
-   */
   steps: z
-    .array(z.array(StepSchema))
-    .describe("2D array: phases (sequential) containing steps (parallel)"),
-
-  /**
-   * Triggers to fire when execution completes successfully
-   */
-  triggers: z
-    .array(TriggerSchema)
-    .optional()
-    .describe("Workflows to trigger on completion"),
+    .array(StepSchema)
+    .describe(
+      "Ordered list of steps. Execution order is auto-determined by @ref dependencies: steps with no @ref dependencies run in parallel; steps referencing @stepName wait for that step to complete.",
+    ),
 });
 
 export type Workflow = z.infer<typeof WorkflowSchema>;
@@ -254,29 +294,95 @@ export const WORKFLOWS_COLLECTION_BINDING = createCollectionBindings(
   WorkflowSchema,
 );
 
-export const WORKFLOW_EXECUTIONS_COLLECTION_BINDING = createCollectionBindings(
-  "workflow_execution",
-  WorkflowExecutionSchema,
-  {
-    readOnly: true,
+const DEFAULT_STEP_CONFIG: StepConfig = {
+  maxAttempts: 1,
+  timeoutMs: 30000,
+};
+
+// export const DEFAULT_WAIT_FOR_SIGNAL_STEP: Omit<Step, "name"> = {
+//   action: {
+//     signalName: "approve_output",
+//   },
+//   outputSchema: {
+//     type: "object",
+//     properties: {
+//       approved: {
+//         type: "boolean",
+//         description: "Whether the output was approved",
+//       },
+//     },
+//   },
+// };
+export const DEFAULT_TOOL_STEP: Omit<Step, "name"> = {
+  action: {
+    toolName: "LLM_DO_GENERATE",
+    transformCode: `
+    interface Input { 
+      
+    }
+    export default function(input) { return input.result }`,
+  },
+  input: {
+    modelId: "anthropic/claude-4.5-haiku",
+    prompt: "Write a haiku about the weather.",
   },
-);
 
-export const WORKFLOW_STEP_RESULTS_COLLECTION_BINDING =
-  createCollectionBindings(
-    "workflow_execution_step_results",
-    WorkflowExecutionStepResultSchema,
-    {
-      readOnly: true,
+  config: DEFAULT_STEP_CONFIG,
+  outputSchema: {
+    type: "object",
+    properties: {
+      result: {
+        type: "string",
+        description: "The result of the step",
+      },
     },
-  );
+  },
+};
+export const DEFAULT_CODE_STEP: Step = {
+  name: "Initial Step",
+  action: {
+    code: `
+  interface Input {
+    example: string;
+  }
 
-export const WORKFLOW_EVENTS_COLLECTION_BINDING = createCollectionBindings(
-  "workflow_events",
-  WorkflowEventSchema,
-  {
-    readOnly: true,
+  interface Output {
+    result: unknown;
+  }
+    
+  export default async function(input: Input): Promise<Output> { 
+    return {
+      result: input.example
+    }
+  }`,
   },
+  config: DEFAULT_STEP_CONFIG,
+  outputSchema: {
+    type: "object",
+    properties: {
+      result: {
+        type: "string",
+        description: "The result of the step",
+      },
+    },
+    required: ["result"],
+    description:
+      "The output of the step. This is a JSON Schema describing the expected output of the step.",
+  },
+};
+
+export const createDefaultWorkflow = (id?: string): Workflow => ({
+  id: id || crypto.randomUUID(),
+  title: "Default Workflow",
+  description: "The default workflow for the toolkit",
+  steps: [DEFAULT_CODE_STEP],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+});
+
+export const WORKFLOW_EXECUTIONS_COLLECTION_BINDING = createCollectionBindings(
+  "workflow_execution",
+  WorkflowExecutionSchema,
 );
 
 /**
@@ -289,9 +395,275 @@ export const WORKFLOW_EVENTS_COLLECTION_BINDING = createCollectionBindings(
  * - COLLECTION_WORKFLOW_LIST: List available workflows with their configurations
  * - COLLECTION_WORKFLOW_GET: Get a single workflow by ID (includes steps and triggers)
  */
-export const WORKFLOWS_BINDING = [
+export const WORKFLOW_COLLECTIONS_BINDINGS = [
   ...WORKFLOWS_COLLECTION_BINDING,
   ...WORKFLOW_EXECUTIONS_COLLECTION_BINDING,
-  ...WORKFLOW_STEP_RESULTS_COLLECTION_BINDING,
-  ...WORKFLOW_EVENTS_COLLECTION_BINDING,
 ] as const satisfies Binder;
+
+export const WORKFLOW_BINDING = [
+  ...WORKFLOW_COLLECTIONS_BINDINGS,
+] satisfies ToolBinder[];
+
+export const WorkflowBinding = bindingClient(WORKFLOW_BINDING);
+
+export const WORKFLOW_EXECUTION_BINDING = createCollectionBindings(
+  "workflow_execution",
+  WorkflowExecutionSchema,
+);
+
+/**
+ * DAG (Directed Acyclic Graph) utilities for workflow step execution
+ *
+ * Pure TypeScript functions for analyzing step dependencies and grouping
+ * steps into execution levels for parallel execution.
+ *
+ * Can be used in both frontend (visualization) and backend (execution).
+ */
+
+/**
+ * Minimal step interface for DAG computation.
+ * This allows the DAG utilities to work with any step-like object.
+ */
+export interface DAGStep {
+  name: string;
+  input?: unknown;
+}
+
+/**
+ * Extract all @ref references from a value recursively.
+ * Finds patterns like @stepName or @stepName.field
+ *
+ * @param input - Any value that might contain @ref strings
+ * @returns Array of unique reference names (without @ prefix)
+ */
+export function getAllRefs(input: unknown): string[] {
+  const refs: string[] = [];
+
+  function traverse(value: unknown) {
+    if (typeof value === "string") {
+      const matches = value.match(/@(\w+)/g);
+      if (matches) {
+        refs.push(...matches.map((m) => m.substring(1))); // Remove @ prefix
+      }
+    } else if (Array.isArray(value)) {
+      value.forEach(traverse);
+    } else if (typeof value === "object" && value !== null) {
+      Object.values(value).forEach(traverse);
+    }
+  }
+
+  traverse(input);
+  return [...new Set(refs)].sort(); // Dedupe and sort for consistent results
+}
+
+/**
+ * Get the dependencies of a step (other steps it references).
+ * Only returns dependencies that are actual step names (filters out built-ins like "item", "index", "input").
+ *
+ * @param step - The step to analyze
+ * @param allStepNames - Set of all step names in the workflow
+ * @returns Array of step names this step depends on
+ */
+export function getStepDependencies(
+  step: DAGStep,
+  allStepNames: Set<string>,
+): string[] {
+  const deps: string[] = [];
+
+  function traverse(value: unknown) {
+    if (typeof value === "string") {
+      // Match @stepName or @stepName.something patterns
+      const matches = value.match(/@(\w+)/g);
+      if (matches) {
+        for (const match of matches) {
+          const refName = match.substring(1); // Remove @
+          // Only count as dependency if it references another step
+          // (not "item", "index", "input" from forEach or workflow input)
+          if (allStepNames.has(refName)) {
+            deps.push(refName);
+          }
+        }
+      }
+    } else if (Array.isArray(value)) {
+      value.forEach(traverse);
+    } else if (typeof value === "object" && value !== null) {
+      Object.values(value).forEach(traverse);
+    }
+  }
+
+  traverse(step.input);
+  return [...new Set(deps)];
+}
+
+/**
+ * Build edges for the DAG: [fromStep, toStep][]
+ */
+export function buildDagEdges(steps: Step[]): [string, string][] {
+  const stepNames = new Set(steps.map((s) => s.name));
+  const edges: [string, string][] = [];
+
+  for (const step of steps) {
+    const deps = getStepDependencies(step, stepNames);
+    for (const dep of deps) {
+      edges.push([dep, step.name]);
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Compute topological levels for all steps.
+ * Level 0 = no dependencies on other steps
+ * Level N = depends on at least one step at level N-1
+ *
+ * @param steps - Array of steps to analyze
+ * @returns Map from step name to level number
+ */
+export function computeStepLevels<T extends DAGStep>(
+  steps: T[],
+): Map<string, number> {
+  const stepNames = new Set(steps.map((s) => s.name));
+  const levels = new Map<string, number>();
+
+  // Build dependency map
+  const depsMap = new Map<string, string[]>();
+  for (const step of steps) {
+    depsMap.set(step.name, getStepDependencies(step, stepNames));
+  }
+
+  // Compute level for each step (with memoization)
+  function getLevel(stepName: string, visited: Set<string>): number {
+    if (levels.has(stepName)) return levels.get(stepName)!;
+    if (visited.has(stepName)) return 0; // Cycle detection
+
+    visited.add(stepName);
+    const deps = depsMap.get(stepName) || [];
+
+    if (deps.length === 0) {
+      levels.set(stepName, 0);
+      return 0;
+    }
+
+    const maxDepLevel = Math.max(...deps.map((d) => getLevel(d, visited)));
+    const level = maxDepLevel + 1;
+    levels.set(stepName, level);
+    return level;
+  }
+
+  for (const step of steps) {
+    getLevel(step.name, new Set());
+  }
+
+  return levels;
+}
+
+/**
+ * Group steps by their execution level.
+ * Steps at the same level have no dependencies on each other and can run in parallel.
+ *
+ * @param steps - Array of steps to group
+ * @returns Array of step arrays, where index is the level
+ */
+export function groupStepsByLevel<T extends DAGStep>(steps: T[]): T[][] {
+  const levels = computeStepLevels(steps);
+  const maxLevel = Math.max(...Array.from(levels.values()), -1);
+
+  const grouped: T[][] = [];
+  for (let level = 0; level <= maxLevel; level++) {
+    const stepsAtLevel = steps.filter((s) => levels.get(s.name) === level);
+    if (stepsAtLevel.length > 0) {
+      grouped.push(stepsAtLevel);
+    }
+  }
+
+  return grouped;
+}
+
+/**
+ * Get the dependency signature for a step (for grouping steps with same deps).
+ *
+ * @param step - The step to get signature for
+ * @returns Comma-separated sorted list of dependencies
+ */
+export function getRefSignature(step: DAGStep): string {
+  const inputRefs = getAllRefs(step.input);
+  const allRefs = [...new Set([...inputRefs])].sort();
+  return allRefs.join(",");
+}
+
+/**
+ * Build a dependency graph for visualization.
+ * Returns edges as [fromStep, toStep] pairs.
+ *
+ * @param steps - Array of steps
+ * @returns Array of [source, target] pairs representing edges
+ */
+export function buildDependencyEdges<T extends DAGStep>(
+  steps: T[],
+): [string, string][] {
+  const stepNames = new Set(steps.map((s) => s.name));
+  const edges: [string, string][] = [];
+
+  for (const step of steps) {
+    const deps = getStepDependencies(step, stepNames);
+    for (const dep of deps) {
+      edges.push([dep, step.name]);
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Validate that there are no cycles in the step dependencies.
+ *
+ * @param steps - Array of steps to validate
+ * @returns Object with isValid and optional error message
+ */
+export function validateNoCycles<T extends DAGStep>(
+  steps: T[],
+): { isValid: boolean; error?: string } {
+  const stepNames = new Set(steps.map((s) => s.name));
+  const depsMap = new Map<string, string[]>();
+
+  for (const step of steps) {
+    depsMap.set(step.name, getStepDependencies(step, stepNames));
+  }
+
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function hasCycle(stepName: string, path: string[]): string[] | null {
+    if (recursionStack.has(stepName)) {
+      return [...path, stepName];
+    }
+    if (visited.has(stepName)) {
+      return null;
+    }
+
+    visited.add(stepName);
+    recursionStack.add(stepName);
+
+    const deps = depsMap.get(stepName) || [];
+    for (const dep of deps) {
+      const cycle = hasCycle(dep, [...path, stepName]);
+      if (cycle) return cycle;
+    }
+
+    recursionStack.delete(stepName);
+    return null;
+  }
+
+  for (const step of steps) {
+    const cycle = hasCycle(step.name, []);
+    if (cycle) {
+      return {
+        isValid: false,
+        error: `Circular dependency detected: ${cycle.join(" -> ")}`,
+      };
+    }
+  }
+
+  return { isValid: true };
+}