@desplega.ai/agent-swarm 1.49.0 → 1.52.0

package/src/workflows/definition.ts

@@ -1,6 +1,13 @@
 import type { WorkflowDefinition, WorkflowEdge, WorkflowNode } from "../types";
 import type { ExecutorRegistry } from "./executors/registry";
 
+/** Extract all target node IDs from a node's `next` field */
+export function getNextTargets(next: string | string[] | Record<string, string>): string[] {
+  if (typeof next === "string") return [next];
+  if (Array.isArray(next)) return next;
+  return Object.values(next);
+}
+
 /**
  * Auto-generate edges from `next` references — for UI graph rendering.
  */
@@ -15,6 +22,15 @@ export function generateEdges(def: WorkflowDefinition): WorkflowEdge[] {
         target: node.next,
         sourcePort: "default",
       });
+    } else if (Array.isArray(node.next)) {
+      for (const targetId of node.next) {
+        edges.push({
+          id: `${node.id}→${targetId}`,
+          source: node.id,
+          target: targetId,
+          sourcePort: "default",
+        });
+      }
     } else {
       for (const [port, targetId] of Object.entries(node.next)) {
         edges.push({
@@ -36,12 +52,8 @@ export function findEntryNodes(def: WorkflowDefinition): WorkflowNode[] {
   const targets = new Set<string>();
   for (const node of def.nodes) {
     if (!node.next) continue;
-    if (typeof node.next === "string") {
-      targets.add(node.next);
-    } else {
-      for (const targetId of Object.values(node.next)) {
-        targets.add(targetId);
-      }
+    for (const targetId of getNextTargets(node.next)) {
+      targets.add(targetId);
     }
   }
   return def.nodes.filter((n) => !targets.has(n.id));
@@ -62,6 +74,9 @@ export function getSuccessors(
   if (typeof node.next === "string") {
     // Single next — any port matches
     targetIds.push(node.next);
+  } else if (Array.isArray(node.next)) {
+    // Fan-out — all targets are parallel successors (port is ignored)
+    targetIds.push(...node.next);
   } else {
     if (port) {
       // Port-based — look up the specific port
@@ -87,8 +102,7 @@ export function isUpstream(def: WorkflowDefinition, sourceId: string, targetId:
   const reverseDeps = new Map<string, string[]>();
   for (const node of def.nodes) {
     if (!node.next) continue;
-    const targets = typeof node.next === "string" ? [node.next] : Object.values(node.next);
-    for (const target of targets) {
+    for (const target of getNextTargets(node.next)) {
       if (!reverseDeps.has(target)) reverseDeps.set(target, []);
       reverseDeps.get(target)!.push(node.id);
     }
@@ -134,6 +148,12 @@ export function validateDefinition(
       if (!nodeIds.has(node.next)) {
         errors.push(`Node "${node.id}" references non-existent next target "${node.next}"`);
       }
+    } else if (Array.isArray(node.next)) {
+      for (const targetId of node.next) {
+        if (!nodeIds.has(targetId)) {
+          errors.push(`Node "${node.id}" fan-out references non-existent target "${targetId}"`);
+        }
+      }
     } else {
       for (const [port, targetId] of Object.entries(node.next)) {
         if (!nodeIds.has(targetId)) {
@@ -164,10 +184,8 @@ export function validateDefinition(
       reachable.add(current);
       const node = def.nodes.find((n) => n.id === current);
       if (!node?.next) continue;
-      if (typeof node.next === "string") {
-        queue.push(node.next);
-      } else {
-        queue.push(...Object.values(node.next));
+      for (const targetId of getNextTargets(node.next)) {
+        queue.push(targetId);
       }
     }
     for (const node of def.nodes) {

package/src/workflows/engine.ts

@@ -11,7 +11,7 @@ import {
 import type { Workflow, WorkflowDefinition, WorkflowNode } from "../types";
 import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./checkpoint";
 import { shouldSkipCooldown } from "./cooldown";
-import { findEntryNodes, getSuccessors } from "./definition";
+import { findEntryNodes, getNextTargets, getSuccessors } from "./definition";
 import type { AsyncExecutorResult } from "./executors/base";
 import type { ExecutorRegistry } from "./executors/registry";
 import { resolveInputs } from "./input";
@@ -73,6 +73,12 @@ export async function startWorkflowExecution(
 
   // Resolve inputs and merge into initial context
   const ctx: Record<string, unknown> = { trigger: triggerData };
+
+  // Inject workflow-level metadata for interpolation ({{workflow.dir}}, {{workflow.vcsRepo}})
+  if (workflow.dir || workflow.vcsRepo) {
+    ctx.workflow = { dir: workflow.dir, vcsRepo: workflow.vcsRepo };
+  }
+
   if (workflow.input) {
     try {
       const resolved = resolveInputs(workflow.input);
@@ -157,8 +163,20 @@ export async function walkGraph(
     }
   }
 
-  // Seed with start nodes that haven't been completed yet
-  let pendingNodes = startNodes.filter((n) => !completedNodeIds.has(n.id));
+  // Seed with start nodes that haven't been completed yet AND whose
+  // predecessors are all completed (convergence gate). This prevents callers
+  // like resumeFromTaskCompletion() and retryFailedRun() from executing a
+  // convergence node before all its fan-out predecessors are done.
+  let pendingNodes = startNodes.filter((n) => {
+    if (completedNodeIds.has(n.id)) return false;
+    const preds = getAllPredecessors(def, n.id);
+    if (preds.length === 0) return true; // Entry node — always ready
+    // Check all predecessors with active edges are completed
+    const activePreds = preds.filter((predId) => activeEdges.has(`${predId}→${n.id}`));
+    // If no active edges yet (first walk), check ALL structural predecessors
+    const predsToCheck = activePreds.length > 0 ? activePreds : preds;
+    return predsToCheck.every((p) => completedNodeIds.has(p));
+  });
 
   while (pendingNodes.length > 0) {
     nodeExecutionCount += pendingNodes.length;
@@ -256,8 +274,7 @@ function getAllPredecessors(def: WorkflowDefinition, nodeId: string): string[] {
   const preds: string[] = [];
   for (const node of def.nodes) {
     if (!node.next) continue;
-    const targets = typeof node.next === "string" ? [node.next] : Object.values(node.next);
-    if (targets.includes(nodeId)) {
+    if (getNextTargets(node.next).includes(nodeId)) {
       preds.push(node.id);
     }
   }
@@ -286,14 +303,22 @@ async function executeStep(
 ): Promise<StepResult> {
   const idempotencyKey = `${runId}:${node.id}`;
 
-  // 1. Memoization check
+  // 1. Memoization / deduplication check
   const existingStep = getStepByIdempotencyKey(idempotencyKey);
-  if (existingStep && existingStep.status === "completed") {
-    // Inject stored output into context
-    ctx[node.id] = existingStep.output;
-    // For memoized steps, return all successors (no port — use default)
-    const successors = getSuccessors(def, node.id);
-    return { outcome: "completed", successors };
+  if (existingStep) {
+    if (existingStep.status === "completed") {
+      // Inject stored output into context
+      ctx[node.id] = existingStep.output;
+      // For memoized steps, return all successors (no port — use default)
+      const successors = getSuccessors(def, node.id);
+      return { outcome: "completed", successors };
+    }
+    if (existingStep.status === "waiting") {
+      // Step already exists and is waiting for async completion (e.g., agent-task).
+      // Don't create a duplicate — just report as waiting.
+      return { outcome: "waiting", successors: [] };
+    }
+    // For "pending" or "failed" steps, fall through to re-execute
   }
 
   // 2. Create step
@@ -319,6 +344,7 @@ async function executeStep(
     // Always include built-in sources
     if (ctx.trigger !== undefined) interpolationCtx.trigger = ctx.trigger;
     if (ctx.input !== undefined) interpolationCtx.input = ctx.input;
+    if (ctx.workflow !== undefined) interpolationCtx.workflow = ctx.workflow;
     // Resolve declared inputs
     for (const [localName, sourcePath] of Object.entries(node.inputs)) {
       const keys = sourcePath.split(".");
@@ -337,6 +363,7 @@ async function executeStep(
     interpolationCtx = {};
     if (ctx.trigger !== undefined) interpolationCtx.trigger = ctx.trigger;
     if (ctx.input !== undefined) interpolationCtx.input = ctx.input;
+    if (ctx.workflow !== undefined) interpolationCtx.workflow = ctx.workflow;
   }
 
   // 3c. Validate resolved inputs against inputSchema if defined
@@ -512,8 +539,7 @@ export function findReadyNodes(
 
   for (const node of def.nodes) {
     if (!node.next) continue;
-    const targets = typeof node.next === "string" ? [node.next] : Object.values(node.next);
-    for (const target of targets) {
+    for (const target of getNextTargets(node.next)) {
       if (!predecessors.has(target)) {
         predecessors.set(target, new Set());
       }

package/src/workflows/executors/agent-task.ts

@@ -65,7 +65,18 @@ export class AgentTaskExecutor extends BaseExecutor<
       } as unknown as ExecutorResult<AgentTaskOutput>;
     }
 
-    // 2. Create the task (config is already deep-interpolated by the engine)
+    // 2. Inherit workflow-level dir/vcsRepo when node config doesn't specify them
+    let effectiveDir = config.dir;
+    let effectiveVcsRepo = config.vcsRepo;
+    if ((!effectiveDir || !effectiveVcsRepo) && meta.workflowId) {
+      const workflow = db.getWorkflow(meta.workflowId);
+      if (workflow) {
+        if (!effectiveDir && workflow.dir) effectiveDir = workflow.dir;
+        if (!effectiveVcsRepo && workflow.vcsRepo) effectiveVcsRepo = workflow.vcsRepo;
+      }
+    }
+
+    // 3. Create the task (config is already deep-interpolated by the engine)
     const task = db.createTaskExtended(config.template, {
       agentId: config.agentId ?? null,
       source: "workflow",
@@ -74,8 +85,8 @@ export class AgentTaskExecutor extends BaseExecutor<
       offeredTo: config.offerMode ? config.agentId : undefined,
       workflowRunId: meta.runId,
       workflowRunStepId: meta.stepId,
-      dir: config.dir,
-      vcsRepo: config.vcsRepo,
+      dir: effectiveDir,
+      vcsRepo: effectiveVcsRepo,
       model: config.model,
       parentTaskId: config.parentTaskId,
       outputSchema: config.outputSchema,

package/src/workflows/executors/human-in-the-loop.ts

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import type { ExecutorMeta } from "../../types";
+import type { ExecutorResult } from "./base";
+import { BaseExecutor } from "./base";
+
+// ─── Config / Output Schemas ────────────────────────────────
+
+const SelectOptionSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+const QuestionSchema = z.discriminatedUnion("type", [
+  z.object({
+    id: z.string(),
+    type: z.literal("approval"),
+    label: z.string(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+  }),
+  z.object({
+    id: z.string(),
+    type: z.literal("text"),
+    label: z.string(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    placeholder: z.string().optional(),
+    multiline: z.boolean().optional(),
+  }),
+  z.object({
+    id: z.string(),
+    type: z.literal("single-select"),
+    label: z.string(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    options: z.array(SelectOptionSchema),
+  }),
+  z.object({
+    id: z.string(),
+    type: z.literal("multi-select"),
+    label: z.string(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    options: z.array(SelectOptionSchema),
+    minSelections: z.number().int().min(0).optional(),
+    maxSelections: z.number().int().min(1).optional(),
+  }),
+  z.object({
+    id: z.string(),
+    type: z.literal("boolean"),
+    label: z.string(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    defaultValue: z.boolean().optional(),
+  }),
+]);
+
+const ApproverConfigSchema = z.object({
+  users: z.array(z.string()).optional(),
+  roles: z.array(z.string()).optional(),
+  policy: z.union([z.literal("any"), z.literal("all"), z.object({ min: z.number().int().min(1) })]),
+});
+
+const NotificationConfigSchema = z.object({
+  channel: z.enum(["slack", "email"]),
+  target: z.string(),
+});
+
+const HITLConfigSchema = z.object({
+  title: z.string(),
+  questions: z.array(QuestionSchema).min(1),
+  approvers: ApproverConfigSchema,
+  timeout: z
+    .object({
+      seconds: z.number().int().min(1),
+      action: z.literal("reject"),
+    })
+    .optional(),
+  notifications: z.array(NotificationConfigSchema).optional(),
+});
+
+const HITLOutputSchema = z.object({
+  requestId: z.string().uuid(),
+  status: z.string(),
+  responses: z.record(z.string(), z.unknown()).nullable(),
+});
+
+type HITLOutput = z.infer<typeof HITLOutputSchema>;
+
+// ─── Executor ───────────────────────────────────────────────
+
+export class HumanInTheLoopExecutor extends BaseExecutor<
+  typeof HITLConfigSchema,
+  typeof HITLOutputSchema
+> {
+  readonly type = "human-in-the-loop";
+  readonly mode = "async" as const;
+  readonly configSchema = HITLConfigSchema;
+  readonly outputSchema = HITLOutputSchema;
+
+  protected async execute(
+    config: z.infer<typeof HITLConfigSchema>,
+    _context: Readonly<Record<string, unknown>>,
+    meta: ExecutorMeta,
+  ): Promise<ExecutorResult<HITLOutput>> {
+    const { db } = this.deps;
+
+    // 1. Idempotency: check if an approval request was already created for this step
+    const existing = db.getApprovalRequestByStepId(meta.stepId);
+    if (existing) {
+      if (existing.status !== "pending") {
+        // Already resolved — return result
+        const nextPort =
+          existing.status === "timeout"
+            ? "timeout"
+            : existing.status === "rejected"
+              ? "rejected"
+              : "approved";
+        return {
+          status: "success",
+          output: {
+            requestId: existing.id,
+            status: existing.status,
+            responses: existing.responses as Record<string, unknown> | null,
+          },
+          nextPort,
+        };
+      }
+      // Still pending — return async marker
+      return {
+        status: "success",
+        async: true,
+        waitFor: "approval.resolved",
+        correlationId: existing.id,
+      } as unknown as ExecutorResult<HITLOutput>;
+    }
+
+    // 2. Create the approval request
+    const requestId = crypto.randomUUID();
+    db.createApprovalRequest({
+      id: requestId,
+      title: config.title,
+      questions: config.questions,
+      approvers: config.approvers,
+      workflowRunId: meta.runId,
+      workflowRunStepId: meta.stepId,
+      timeoutSeconds: config.timeout?.seconds,
+      notificationChannels: config.notifications, // TODO: Notifications are stored but not dispatched yet (Phase 2)
+    });
+
+    // 3. Return async result — engine will pause the workflow
+    return {
+      status: "success",
+      async: true,
+      waitFor: "approval.resolved",
+      correlationId: requestId,
+    } as unknown as ExecutorResult<HITLOutput>;
+  }
+}

package/src/workflows/executors/registry.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { AgentTaskExecutor } from "./agent-task";
 import type { BaseExecutor, ExecutorDependencies } from "./base";
 import { CodeMatchExecutor } from "./code-match";
+import { HumanInTheLoopExecutor } from "./human-in-the-loop";
 import { NotifyExecutor } from "./notify";
 import { PropertyMatchExecutor } from "./property-match";
 import { RawLlmExecutor } from "./raw-llm";
@@ -71,6 +72,7 @@ export function createExecutorRegistry(deps: ExecutorDependencies): ExecutorRegi
 
   // Async executors (Phase 4)
   registry.register(new AgentTaskExecutor(deps));
+  registry.register(new HumanInTheLoopExecutor(deps));
 
   return registry;
 }

package/src/workflows/index.ts

@@ -6,7 +6,7 @@ export { retryFailedRun, setupWorkflowResumeListener } from "./resume";
 export { startRetryPoller, stopRetryPoller } from "./retry-poller";
 export { interpolate } from "./template";
 export { instantiateTemplate, validateTemplateVariables } from "./templates";
-export { handleWebhookTrigger } from "./triggers";
+export { handleScheduleTrigger, handleWebhookTrigger } from "./triggers";
 export { snapshotWorkflow } from "./version";
 
 import * as db from "../be/db";

package/src/workflows/recovery.ts

@@ -1,9 +1,11 @@
 import {
   getCompletedStepNodeIds,
   getDb,
+  getStuckApprovalRuns,
   getStuckWorkflowRuns,
   getWorkflow,
   getWorkflowRun,
+  resolveApprovalRequest,
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
@@ -11,6 +13,7 @@ import { checkpointStep } from "./checkpoint";
 import { getSuccessors } from "./definition";
 import { findReadyNodes, walkGraph } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
+import { finalizeOrWait } from "./resume";
 
 /**
  * Recover incomplete workflow runs on server startup.
@@ -30,6 +33,9 @@ export async function recoverIncompleteRuns(registry: ExecutorRegistry): Promise
   // --- Case 2: Waiting runs whose tasks may have finished ---
   recovered += await recoverWaitingRuns(registry);
 
+  // --- Case 3: Waiting runs whose approval requests may have resolved ---
+  recovered += await recoverApprovalWaitingRuns(registry);
+
   if (recovered > 0) {
     console.log(`[workflows] Recovered ${recovered} incomplete run(s) on startup`);
   }
@@ -128,6 +134,72 @@ async function recoverWaitingRuns(registry: ExecutorRegistry): Promise<number> {
   return recovered;
 }
 
+/**
+ * Recover waiting runs whose linked approval requests have resolved or expired
+ * while the server was down.
+ */
+async function recoverApprovalWaitingRuns(registry: ExecutorRegistry): Promise<number> {
+  const stuckRuns = getStuckApprovalRuns();
+  let recovered = 0;
+
+  for (const stuck of stuckRuns) {
+    try {
+      const run = getWorkflowRun(stuck.runId);
+      const workflow = getWorkflow(stuck.workflowId);
+      if (!run || !workflow) continue;
+
+      let approvalStatus = stuck.approvalStatus;
+      let responses: unknown = stuck.approvalResponses ? JSON.parse(stuck.approvalResponses) : null;
+
+      // If still pending but expired, auto-reject
+      if (approvalStatus === "pending" && stuck.expiresAt) {
+        resolveApprovalRequest(stuck.approvalId, {
+          status: "timeout",
+        });
+        approvalStatus = "timeout";
+        responses = null;
+      }
+
+      const nextPort =
+        approvalStatus === "timeout"
+          ? "timeout"
+          : approvalStatus === "rejected"
+            ? "rejected"
+            : "approved";
+
+      const ctx = (run.context ?? {}) as Record<string, unknown>;
+      const stepOutput = {
+        requestId: stuck.approvalId,
+        status: approvalStatus,
+        responses,
+      };
+
+      checkpointStep(
+        stuck.runId,
+        stuck.stepId,
+        stuck.nodeId,
+        { output: stepOutput, nextPort },
+        ctx,
+      );
+      updateWorkflowRun(stuck.runId, { status: "running" });
+
+      const completedNodeIds = new Set(getCompletedStepNodeIds(stuck.runId));
+      const readyNodes = findReadyNodes(workflow.definition, completedNodeIds);
+
+      if (readyNodes.length > 0) {
+        await walkGraph(workflow.definition, stuck.runId, ctx, readyNodes, registry, workflow.id);
+      } else {
+        finalizeOrWait(stuck.runId);
+      }
+      recovered++;
+    } catch (err) {
+      console.error(`[workflows] Failed to recover approval-waiting run ${stuck.runId}:`, err);
+    }
+  }
+
+  return recovered;
+}
+
 /**
  * Get run IDs by status. Simple query since there's no dedicated function for this.
  */