@desplega.ai/agent-swarm 2.4.5 → 2.5.0

package/src/workflows/executors/foreach.ts

@@ -1,19 +1,22 @@
 import { z } from "zod";
+import { createForeachChildSteps } from "../../be/db/workflow-runs";
 import type { ExecutorMeta } from "../../types";
-import { deepInterpolate } from "../../utils/template";
+import { FOREACH_ITEMS_WAIT_FOR } from "../constants";
 import { getSuccessors } from "../definition";
+import { foreachBodyTypeError } from "../foreach-body";
 import {
   buildForeachAggregate,
   FOREACH_TERMINAL_STEP_STATUSES,
   parseSyntheticNodeId,
 } from "../foreach-join";
 import { getMaxWorkflowStepsPerRun } from "../limits";
-import { AgentTaskExecutor } from "./agent-task";
 import type { AsyncExecutorResult, ExecutorResult } from "./base";
 import { BaseExecutor } from "./base";
 
+// Any registered executor except `foreach` (see foreach-body.ts); the guard in
+// execute() and definition validation enforce the policy.
 const ForeachBodySchema = z.object({
-  type: z.literal("agent-task"),
+  type: z.string().min(1),
   config: z.record(z.string(), z.unknown()),
 });
 
@@ -21,7 +24,12 @@ export const ForeachConfigSchema = z.object({
   over: z.array(z.record(z.string(), z.unknown())),
   itemKey: z.string().min(1),
   body: ForeachBodySchema,
-  concurrency: z.never().optional(),
+  /** Items in flight at once (`running` or `waiting` children). Unbounded when absent. */
+  concurrency: z.number().int().min(1).optional(),
+  /** Defaults from the workflow `onNodeFailure` (see effectiveFailurePolicy). */
+  // Literal, not FOREACH_FAILURE_POLICIES: foreach-body.ts sits in an import
+  // cycle with this module and would be read before it initializes.
+  failurePolicy: z.enum(["fail-fast", "collect-outcomes"]).optional(),
 });
 
 const ForeachResultSchema = z.object({
@@ -34,6 +42,8 @@ export const ForeachOutputSchema = z.object({
   results: z.array(ForeachResultSchema),
   okCount: z.number().int().nonnegative(),
   failedCount: z.number().int().nonnegative(),
+  /** Items cancelled before they finished (fail-fast queued items, cancelled bodies). Counted in failedCount too. */
+  cancelledCount: z.number().int().nonnegative().optional(),
 });
 
 export type ForeachOutput = z.infer<typeof ForeachOutputSchema>;
@@ -49,7 +59,7 @@ export class ForeachExecutor extends BaseExecutor<
 
   protected async execute(
     config: z.infer<typeof ForeachConfigSchema>,
-    context: Readonly<Record<string, unknown>>,
+    _context: Readonly<Record<string, unknown>>,
     meta: ExecutorMeta,
   ): Promise<ExecutorResult<ForeachOutput>> {
     if (config.over.length === 0) {
@@ -77,16 +87,19 @@ export class ForeachExecutor extends BaseExecutor<
       seenItemKeys.add(itemKey);
     }
 
-    const agentTaskExecutor = new AgentTaskExecutor(this.deps);
+    const bodyTypeError = foreachBodyTypeError(meta.nodeId, config.body.type);
+    if (bodyTypeError) return { status: "failed", error: bodyTypeError };
+
     const runSteps = await this.deps.db.getWorkflowRunStepsByRunId(meta.runId);
-    const childStepsByNodeId = new Map(
+    const existingChildNodeIds = new Set(
       runSteps
         .filter((step) => parseSyntheticNodeId(step.nodeId)?.parentNodeId === meta.nodeId)
-        .map((step) => [step.nodeId, step]),
+        .map((step) => step.nodeId),
+    );
+    const missingItems = items.filter(
+      ({ itemKey }) => !existingChildNodeIds.has(`${meta.nodeId}#${itemKey}`),
     );
-    const childCountToCreate = items.filter(
-      ({ itemKey }) => !childStepsByNodeId.has(`${meta.nodeId}#${itemKey}`),
-    ).length;
+    const childCountToCreate = missingItems.length;
     const maxSteps = getMaxWorkflowStepsPerRun();
     // walkGraph's circuit breaker rejects any post-join walk once allSteps.length
     // >= maxSteps, so a fan-out with a successor that lands exactly on the cap would
@@ -107,79 +120,26 @@ export class ForeachExecutor extends BaseExecutor<
       };
     }
 
-    // Materialize EVERY child step row before dispatching ANY child task. A task
-    // dispatched for an early child can complete (and trigger joinForeach) while
-    // later children are still being set up — the join must always see the full
-    // child set, with not-yet-dispatched children in a non-terminal state.
-    for (const { index, itemKey } of items) {
-      const childNodeId = `${meta.nodeId}#${itemKey}`;
-      if (childStepsByNodeId.has(childNodeId)) continue;
-      const childStepId = crypto.randomUUID();
-      const childStep = await this.deps.db.createWorkflowRunStep({
-        id: childStepId,
-        runId: meta.runId,
-        nodeId: childNodeId,
-        nodeType: "agent-task",
-        input: { itemKey, index },
-      });
-      await this.deps.db.updateWorkflowRunStep(childStepId, {
-        idempotencyKey: `${meta.runId}:${childNodeId}:0`,
-      });
-      childStepsByNodeId.set(childNodeId, childStep);
-    }
-
-    for (const { item, index, itemKey } of items) {
-      const childNodeId = `${meta.nodeId}#${itemKey}`;
-      const childStep = childStepsByNodeId.get(childNodeId)!;
-
-      // Re-walks must not regress terminal children or disturb their aggregate
-      // inputs. Retry resets only the failed child to pending before arriving here.
-      if (FOREACH_TERMINAL_STEP_STATUSES.has(childStep.status)) continue;
-
-      // The deferred per-item pass interpolates against the node's declared-inputs
-      // context (meta.inputCtx) plus item/index — NOT the full run context — so
-      // body.config obeys the same explicit-dataflow boundary as normal node
-      // config instead of silently reading undeclared upstream outputs.
-      const bodyCtx = { ...(meta.inputCtx ?? context), item, index };
-      const childInterpolation = deepInterpolate(config.body.config, bodyCtx);
-      if (childInterpolation.unresolved.length > 0) {
-        console.warn(
-          `[workflow] Step ${childNodeId}: unresolved interpolation tokens: ${childInterpolation.unresolved.join(", ")}`,
-        );
-        await this.deps.db.updateWorkflowRunStep(childStep.id, {
-          diagnostics: JSON.stringify({ unresolvedTokens: childInterpolation.unresolved }),
-        });
-      }
-
-      const linkedTask = await this.deps.db.getTaskByWorkflowRunStepId(childStep.id);
-      if (linkedTask?.status === "failed" || linkedTask?.status === "cancelled") {
-        // A retry needs a fresh task. Detaching the stale terminal task keeps the
-        // executor's one-task-per-step de-duplication deterministic and scoped.
-        await this.deps.db.detachTaskFromWorkflowRunStep(linkedTask.id);
-      }
-
-      const childResult = await agentTaskExecutor.run({
-        config: childInterpolation.value as Record<string, unknown>,
-        context,
-        meta: {
-          ...meta,
-          stepId: childStep.id,
+    // Materialize EVERY child row, queued (`pending`), in one transaction and
+    // before any child starts. An early child can complete (and trigger the
+    // join) while later children are still being set up, so the join must
+    // always see the full child set. The item value is not persisted: the
+    // driver looks it up by key in the re-interpolated `over`, which keeps
+    // resolved secrets out of step rows.
+    await createForeachChildSteps(
+      meta.runId,
+      meta.nodeId,
+      missingItems.map(({ index, itemKey }) => {
+        const childNodeId = `${meta.nodeId}#${itemKey}`;
+        return {
+          id: crypto.randomUUID(),
           nodeId: childNodeId,
-        },
-      });
-      if (childResult.status !== "success") {
-        throw new Error(childResult.error ?? `foreach child "${itemKey}" failed to start`);
-      }
-      if ("async" in childResult) {
-        await this.deps.db.updateWorkflowRunStep(childStep.id, { status: "waiting" });
-      } else {
-        await this.deps.db.updateWorkflowRunStep(childStep.id, {
-          status: "completed",
-          output: normalizeExistingTaskOutput(childResult.output),
-          finishedAt: new Date().toISOString(),
-        });
-      }
-    }
+          nodeType: config.body.type,
+          input: { itemKey, index, attempt: 0 },
+          idempotencyKey: `${meta.runId}:${childNodeId}:0`,
+        };
+      }),
+    );
 
     const childSteps = (await this.deps.db.getWorkflowRunStepsByRunId(meta.runId)).filter(
       (step) => parseSyntheticNodeId(step.nodeId)?.parentNodeId === meta.nodeId,
@@ -188,26 +148,12 @@ export class ForeachExecutor extends BaseExecutor<
       return { status: "success", output: buildForeachAggregate(childSteps) };
     }
 
+    // The engine parks the parent and the foreach driver starts the children.
     return {
       status: "success",
       async: true,
-      waitFor: "task.completed",
+      waitFor: FOREACH_ITEMS_WAIT_FOR,
       correlationId: meta.stepId,
     } as AsyncExecutorResult<ForeachOutput>;
   }
 }
-
-function normalizeExistingTaskOutput(output: unknown): unknown {
-  if (typeof output !== "object" || output === null) return output;
-  const record = output as Record<string, unknown>;
-  if (typeof record.taskOutput !== "string") return output;
-  try {
-    const parsed = JSON.parse(record.taskOutput);
-    if (typeof parsed === "object" && parsed !== null) {
-      return { ...record, taskOutput: parsed };
-    }
-  } catch {
-    // Non-structured task output remains a string.
-  }
-  return output;
-}

package/src/workflows/foreach-body.ts

@@ -0,0 +1,146 @@
+import type { WorkflowDefinition, WorkflowNode } from "../types";
+import type { ExecutorRegistry } from "./executors/registry";
+import { resolveForeachParent } from "./foreach-join";
+
+/**
+ * Executor types a `foreach` body must not use, with the reason. Every other
+ * registered executor is a valid body.
+ */
+export const FOREACH_BODY_REJECTED: Readonly<Record<string, string>> = {
+  foreach: "nested fan-out is not supported: synthetic ids and the join resolve one level only",
+};
+
+/**
+ * Built-in executors accepted as a `foreach` body, by how one item completes:
+ * `inline` items are run and settled by the foreach driver; `parks` items wait
+ * on their own resume path (task, child run, approval, wait), which settles
+ * the item through `settleForeachChild`. A `system-one-decision` without
+ * `humanReview` returns inline.
+ *
+ * Every built-in executor must appear here or in FOREACH_BODY_REJECTED; the
+ * registry exhaustiveness test enforces that a new executor gets a decision.
+ */
+export const FOREACH_BODY_ACCEPTED: Readonly<Record<string, "inline" | "parks">> = {
+  script: "inline",
+  "swarm-script": "inline",
+  "raw-llm": "inline",
+  notify: "inline",
+  "property-match": "inline",
+  "code-match": "inline",
+  validate: "inline",
+  vcs: "inline",
+  "system-one-extraction": "inline",
+  "agent-task": "parks",
+  "sub-workflow": "parks",
+  "human-in-the-loop": "parks",
+  wait: "parks",
+  "system-one-decision": "parks",
+};
+
+/**
+ * True when `type` may be a foreach body: not rejected, and registered (or a
+ * known built-in when no registry is passed).
+ */
+export function isForeachBodyType(type: string, registry?: ExecutorRegistry): boolean {
+  if (Object.hasOwn(FOREACH_BODY_REJECTED, type)) return false;
+  return registry ? registry.has(type) : Object.hasOwn(FOREACH_BODY_ACCEPTED, type);
+}
+
+/**
+ * The validation error for a foreach body type, or null when it is allowed.
+ * Without a registry only the rejection list applies, so a custom executor
+ * registered at run time is not refused by a registry-less validation pass.
+ */
+export function foreachBodyTypeError(
+  nodeId: string,
+  type: string,
+  registry?: ExecutorRegistry,
+): string | null {
+  const reason = FOREACH_BODY_REJECTED[type];
+  if (reason !== undefined) {
+    return `Node "${nodeId}" foreach config.body.type "${type}" is not supported: ${reason} (a ${type} body inside foreach "${nodeId}" is rejected)`;
+  }
+  if (registry && !registry.has(type)) {
+    return `Node "${nodeId}" foreach config.body.type "${type}" is not a registered executor`;
+  }
+  return null;
+}
+
+/**
+ * The definition node a step row executes. A real node wins. A synthetic
+ * foreach child id (`<foreachId>#<itemKey>`) resolves to a node synthesized
+ * from the parent's body: the child's id, the body's type and config, and the
+ * parent's declared `inputs` (the body sees the parent's input context, and the
+ * script-body allowlist classifies those aliases by their source).
+ */
+export function resolveStepNode(
+  def: Pick<WorkflowDefinition, "nodes">,
+  nodeId: string,
+): WorkflowNode | null {
+  const node = def.nodes.find((candidate) => candidate.id === nodeId);
+  if (node) return node;
+  const parent = resolveForeachParent(def, nodeId);
+  if (!parent) return null;
+  const body = parent.config.body;
+  if (!isRecord(body) || typeof body.type !== "string") return null;
+  // `item` and `index` are bound per item, so a parent alias with either name
+  // is dropped: it would otherwise classify item data by the alias's source
+  // and let it past the script-body allowlist.
+  const inputs = parent.inputs
+    ? Object.fromEntries(
+        Object.entries(parent.inputs).filter(([alias]) => !FOREACH_ITEM_BINDINGS.has(alias)),
+      )
+    : undefined;
+  return {
+    id: nodeId,
+    type: body.type,
+    config: isRecord(body.config) ? body.config : {},
+    ...(inputs ? { inputs } : {}),
+  };
+}
+
+const FOREACH_ITEM_BINDINGS = new Set(["item", "index"]);
+
+export const FOREACH_FAILURE_POLICIES = ["fail-fast", "collect-outcomes"] as const;
+export type ForeachFailurePolicy = (typeof FOREACH_FAILURE_POLICIES)[number];
+
+/**
+ * How a failed or cancelled item affects its fan-out. `config.failurePolicy`
+ * wins; otherwise it follows the workflow's `onNodeFailure`, so a definition
+ * without the field behaves as before: `"continue"` collects outcomes, the
+ * default `"fail"` is fail-fast.
+ */
+export function effectiveFailurePolicy(
+  node: WorkflowNode,
+  def: Pick<WorkflowDefinition, "onNodeFailure">,
+): ForeachFailurePolicy {
+  const configured = node.config.failurePolicy;
+  if (configured === "fail-fast" || configured === "collect-outcomes") return configured;
+  return def.onNodeFailure === "continue" ? "collect-outcomes" : "fail-fast";
+}
+
+/** How many items of a fan-out may be in flight at once. Unbounded by default. */
+export function foreachConcurrencyCap(node: WorkflowNode): number {
+  const cap = node.config.concurrency;
+  return typeof cap === "number" && Number.isInteger(cap) && cap >= 1
+    ? cap
+    : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * The failure mode a foreach child's task failure takes: the fan-out's
+ * effective policy for a synthetic child, the workflow's `onNodeFailure`
+ * otherwise.
+ */
+export function stepFailureMode(
+  def: Pick<WorkflowDefinition, "nodes" | "onNodeFailure">,
+  nodeId: string,
+): "fail" | "continue" {
+  const parent = resolveForeachParent(def, nodeId);
+  if (parent) return effectiveFailurePolicy(parent, def) === "fail-fast" ? "fail" : "continue";
+  return def.onNodeFailure ?? "fail";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}