@desplega.ai/agent-swarm 2.4.4 → 2.5.0

package/src/workflows/task-step-routing.ts

@@ -17,14 +17,40 @@ import {
 } from "../types";
 import { checkpointStep, checkpointStepFailure } from "./checkpoint";
 import { getSuccessors } from "./definition";
-import { joinForeach, resolveForeachParent } from "./foreach-join";
+import type { ExecutorRegistry } from "./executors/registry";
+import { type ForeachSettleResult, resolveForeachParent, settleForeachChild } from "./foreach-join";
 
-export interface PortStepRoutingResult {
-  /** False when the step was already claimed or its run is terminal. */
+export interface TaskStepRoutingResult {
+  /**
+   * False when another handler already moved the step out of `waiting` — the
+   * caller must not route successors again. The same task terminal event can
+   * reach two resume paths (the DB-emitted bus event and a direct emit, or a
+   * recovery sweep racing a live event); only the first one may route.
+   */
   claimed: boolean;
+  foreachChild: boolean;
+  joined: boolean;
   successors: WorkflowNode[];
+  /** True when this call failed the run: nothing may route or re-park it. */
+  runFailed: boolean;
 }
 
+const UNCLAIMED: TaskStepRoutingResult = {
+  claimed: false,
+  foreachChild: false,
+  joined: false,
+  successors: [],
+  runFailed: false,
+};
+
+/**
+ * Port-routed resume result. `claimed` is false when the step was already
+ * claimed or its run is terminal. A foreach child (`foreachChild`) routes
+ * nothing unless its settlement closed the join (`joined`), in which case
+ * `successors` are the parent's.
+ */
+export type PortStepRoutingResult = TaskStepRoutingResult;
+
 /**
  * True while `taskId` is still the task bound to `stepId`. A retry detaches
  * the failed task and the poller binds a fresh one to the same step, so a
@@ -37,24 +63,41 @@ async function isTaskBoundToStep(taskId: string, stepId: string): Promise<boolea
 }
 
 /**
- * Atomically fail a waiting step and its run. Returns false when another
- * handler already moved the step out of `waiting` — the same task terminal
- * event can reach both the live bus listener and a recovery sweep, and a
- * blind write here would stomp a run another handler is already advancing.
- * With `ownerTaskId`, also returns false when that task is no longer the one
- * bound to the step (a stale snapshot of a step that was since redriven).
+ * Atomically fail a waiting step and its run. Returns `claimed: false` when
+ * another handler already moved the step out of `waiting` — the same task
+ * terminal event can reach both the live bus listener and a recovery sweep,
+ * and a blind write here would stomp a run another handler is already
+ * advancing. With `ownerTaskId`, also unclaimed when that task is no longer
+ * the one bound to the step (a stale snapshot of a step that was since
+ * redriven).
+ *
+ * A synthetic foreach child settles `failed` through `settleForeachChild`
+ * instead: under `onNodeFailure: "fail"` that fails the run as before; under
+ * `"continue"` the item counts as failed and the join may close, so the
+ * caller walks `successors` when `joined`.
  */
 export async function failStepAndRunIfWaiting(
+  def: WorkflowDefinition,
   stepId: string,
   runId: string,
   reason: string,
   ownerTaskId?: string,
-): Promise<boolean> {
+  options: { ctx?: Record<string, unknown>; registry?: ExecutorRegistry } = {},
+): Promise<TaskStepRoutingResult> {
   const now = new Date().toISOString();
-  return await getDbClient().transaction(async () => {
+  return await getDbClient().transaction(async (): Promise<TaskStepRoutingResult> => {
     const current = await getWorkflowRunStep(stepId);
-    if (!current || current.status !== "waiting") return false;
-    if (ownerTaskId && !(await isTaskBoundToStep(ownerTaskId, stepId))) return false;
+    if (!current || current.status !== "waiting") return UNCLAIMED;
+    if (ownerTaskId && !(await isTaskBoundToStep(ownerTaskId, stepId))) return UNCLAIMED;
+    if (resolveForeachParent(def, current.nodeId)) {
+      const ctx =
+        options.ctx ?? (((await getWorkflowRun(runId))?.context ?? {}) as Record<string, unknown>);
+      return toRoutingResult(
+        await settleForeachChild(def, runId, stepId, { status: "failed", error: reason }, ctx, {
+          registry: options.registry,
+        }),
+      );
+    }
     await updateWorkflowRunStep(stepId, {
       status: "failed",
       error: reason,
@@ -65,10 +108,20 @@ export async function failStepAndRunIfWaiting(
       error: reason,
       finishedAt: now,
     });
-    return true;
+    return { claimed: true, foreachChild: false, joined: false, successors: [], runFailed: true };
   });
 }
 
+function toRoutingResult(settle: ForeachSettleResult): TaskStepRoutingResult {
+  return {
+    claimed: settle.claimed,
+    foreachChild: true,
+    joined: settle.joined,
+    successors: settle.successors,
+    runFailed: settle.runFailed,
+  };
+}
+
 /**
  * Checkpoint a waiting step with a port-based result and resolve its
  * successors. Mirrors `completeTaskStepAndResolveSuccessors`: callers check
@@ -84,17 +137,41 @@ export async function checkpointPortStepAndResolveSuccessors(
   output: unknown,
   nextPort: string,
   ctx: Record<string, unknown>,
+  registry?: ExecutorRegistry,
 ): Promise<PortStepRoutingResult> {
   return await getDbClient().transaction(async (): Promise<PortStepRoutingResult> => {
     const current = await getWorkflowRunStep(stepId);
-    if (!current || current.status !== "waiting") return { claimed: false, successors: [] };
+    if (!current || current.status !== "waiting") return UNCLAIMED;
     const run = await getWorkflowRun(runId);
     if (!run || (run.status !== "waiting" && run.status !== "running")) {
-      return { claimed: false, successors: [] };
+      return UNCLAIMED;
+    }
+    // A foreach child's port (approval rejected/timeout, wait event/timeout)
+    // is stored for display and still counts as a completed item: the body's
+    // ports do not route, the item's consumer reads the output.
+    if (resolveForeachParent(def, nodeId)) {
+      return toRoutingResult(
+        await settleForeachChild(
+          def,
+          runId,
+          stepId,
+          { status: "completed", output, nextPort },
+          ctx,
+          {
+            registry,
+          },
+        ),
+      );
     }
     await checkpointStep(runId, stepId, nodeId, { output, nextPort }, ctx);
     await updateWorkflowRun(runId, { status: "running" });
-    return { claimed: true, successors: getSuccessors(def, nodeId, nextPort) };
+    return {
+      claimed: true,
+      foreachChild: false,
+      joined: true,
+      successors: getSuccessors(def, nodeId, nextPort),
+      runFailed: false,
+    };
   });
 }
 
@@ -179,26 +256,6 @@ async function isSupersedeCut(taskId: string, reason: string): Promise<boolean>
   return task?.failureReason === SUPERSEDED_WORKFLOW_TASK_REASON;
 }
 
-export interface TaskStepRoutingResult {
-  /**
-   * False when another handler already moved the step out of `waiting` — the
-   * caller must not route successors again. The same task terminal event can
-   * reach two resume paths (the DB-emitted bus event and a direct emit, or a
-   * recovery sweep racing a live event); only the first one may route.
-   */
-  claimed: boolean;
-  foreachChild: boolean;
-  joined: boolean;
-  successors: WorkflowNode[];
-}
-
-const UNCLAIMED: TaskStepRoutingResult = {
-  claimed: false,
-  foreachChild: false,
-  joined: false,
-  successors: [],
-};
-
 /**
  * Persist an agent-task result and resolve its next nodes. Synthetic foreach
  * children never checkpoint into workflow context; only their parent join does.
@@ -211,6 +268,7 @@ export async function completeTaskStepAndResolveSuccessors(
   ctx: Record<string, unknown>,
   failureReason?: string,
   ownerTaskId?: string,
+  registry?: ExecutorRegistry,
 ): Promise<TaskStepRoutingResult> {
   // The task step, optional foreach join checkpoint, workflow context, and
   // running status must commit together. A crash after this transaction is
@@ -223,25 +281,24 @@ export async function completeTaskStepAndResolveSuccessors(
     // A stale snapshot of a step since redriven to a fresh task must not route it.
     if (ownerTaskId && !(await isTaskBoundToStep(ownerTaskId, step.id))) return UNCLAIMED;
 
-    const foreachParent = resolveForeachParent(def, step.nodeId);
-    if (foreachParent) {
-      await updateWorkflowRunStep(step.id, {
-        status: "completed",
-        output,
-        // onNodeFailure:"continue" completions persist the failure reason as
-        // explicit metadata — the join classifies children on THIS, not on
-        // whether user-controlled output text happens to start with "[FAILED:".
-        ...(failureReason !== undefined ? { error: failureReason } : {}),
-        finishedAt: new Date().toISOString(),
-      });
-      const join = await joinForeach(def, runId, step, ctx);
-      await updateWorkflowRun(runId, { status: "running" });
-      return {
-        claimed: true,
-        foreachChild: true,
-        joined: join.joined,
-        successors: join.successors,
-      };
+    if (resolveForeachParent(def, step.nodeId)) {
+      // onNodeFailure:"continue" completions persist the failure reason as
+      // explicit metadata — the join classifies children on THIS, not on
+      // whether user-controlled output text happens to start with "[FAILED:".
+      return toRoutingResult(
+        await settleForeachChild(
+          def,
+          runId,
+          step.id,
+          {
+            status: "completed",
+            output,
+            ...(failureReason !== undefined ? { error: failureReason } : {}),
+          },
+          ctx,
+          { registry },
+        ),
+      );
     }
 
     await checkpointStep(runId, step.id, step.nodeId, { output }, ctx);
@@ -251,6 +308,7 @@ export async function completeTaskStepAndResolveSuccessors(
       foreachChild: false,
       joined: true,
       successors: getSuccessors(def, step.nodeId),
+      runFailed: false,
     };
   });
 }

package/templates/extensions/slack-reply-gate/README.md

@@ -1,6 +1,6 @@
 # slack-reply-gate
 
-Lead is woken by every human message in a Slack thread the swarm takes part in, including "lol", an emoji, or two people chatting with each other. This extension asks Jev, [TypeSafe](https://typesafe.ai)'s decision model, whether Lead should answer a new thread message, and drops the wake-up when it should not.
+Lead is woken by every human message in a Slack thread the swarm takes part in, including "lol", an emoji, or two people chatting with each other. This extension asks a SystemOne decision model, Jev ([TypeSafe](https://typesafe.ai)) or Clef (Cloudflare Workers AI), whether Lead should answer a new thread message, and drops the wake-up when it should not.
 
 Install config:
 
@@ -15,8 +15,8 @@ Start in `shadow`, read the decisions in KV for a few days, then switch to `enfo
 | `mode` | Effect |
 |---|---|
 | `off` | Never evaluates. |
-| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |
-| `enforce` | Asks Jev, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |
+| `shadow` (default) | Asks the model and records the verdict. Never blocks. |
+| `enforce` | Asks the model, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |
 
 ## What it gates
 
@@ -26,28 +26,30 @@ The header counts only at the start of the description or right after the closin
 
 ## Decision
 
-1. A follow-up with downloaded files (status `draft`) passes without a Jev call.
-2. **@mention pass-through.** A new message that @mentions Lead passes without a Jev call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.
-3. Otherwise one Jev call (one `choice` question, see [Jev transport](#jev-transport)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.
+1. A follow-up with downloaded files (status `draft`) passes without a decision call.
+2. **@mention pass-through.** A new message that @mentions Lead passes without a decision call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.
+3. Otherwise one decision call (one `choice` question, see [Provider](#provider)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.
 4. The answer is no only when the top label is `reaction_only`, `banter_between_others`, or `not_addressed_to_lead`, and the summed probability of those three labels is at least `minConfidence`. A split between two skip labels is still a skip. An unsure verdict replies.
 
 Several buffered messages are judged together. One mention in any of them passes the batch.
 
-## Jev transport
+## Provider
 
-Jev is reachable two ways. Both take the same request and return the same answer, so the decision is identical whichever one runs.
+The decision is made on the API server by the `system-one-decide` tool (`ctx.swarm.systemOne_decide`), the same path a `system-one-decision` workflow node takes. The server reads the provider's credential, sends the request, and validates the answer, so every SystemOne host works and no key enters the hook.
 
-| `provider` | Endpoint | Key | Model |
-|---|---|---|---|
-| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |
-| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |
-| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |
+| `provider` | Model | Credential |
+|---|---|---|
+| `typesafe` | Jev, `model` (default `jev-latest`) | `TYPESAFE_API_KEY` |
+| `openrouter` | Jev, `openrouterModel` (default `typesafe/jev-1.13`) | `OPENROUTER_API_KEY` |
+| `cloudflare` | Clef, `cloudflareModel` (default `clef`, or `clef-flash`) | `CLOUDFLARE_API_TOKEN` (or `CLOUDFLARE_API_KEY`) and `CLOUDFLARE_ACCOUNT_ID` |
+| `laya`, `openai` | The host's default model | See the workflows guide |
+| `auto` (default) | The first of typesafe, openrouter, cloudflare whose credential is set. A provider the server refuses for a deployment setting (openrouter when `OPENROUTER_BASE_URL` points at a gateway) is skipped for the next one | |
 
-Under `auto`, `TYPESAFE_API_KEY` wins when both keys are set. With neither key, every message fails open and the KV row names both secrets. Each decision row records the `provider` that answered.
+With no credential for `auto`, every message fails open and the KV row names the secrets. Each decision row records the `provider` that answered. `minConfidence` was tuned on Jev; check Clef's verdicts in `shadow` before you enforce on it.
 
 ## Fail open
 
-Every error lets the task through: a missing key, a TypeSafe HTTP error, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.
+Every error lets the task through: a missing key, a provider error relayed by the server, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.
 
 ## :mute: on drop (enforce)
 
@@ -63,23 +65,23 @@ The block returns first and the Slack calls run after it. A slow or failing Slac
 | Key | Default | Notes |
 |---|---|---|
 | `mode` | `shadow` | `off`, `shadow`, or `enforce` |
-| `timeoutMs` | `3000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
-| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |
+| `timeoutMs` | `3000` | Decision call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
+| `provider` | `auto` | `auto`, `typesafe`, `openrouter`, `cloudflare`, `laya`, or `openai`. See [Provider](#provider) |
 | `model` | `jev-latest` | Jev model on TypeSafe |
 | `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |
+| `cloudflareModel` | `clef` | Clef model on Cloudflare Workers AI |
 | `minConfidence` | `0.55` | Minimum summed skip probability to skip |
-| `contextMessages` | `6` | Thread messages sent to Jev, 0 to 20 |
+| `contextMessages` | `6` | Thread messages sent to the model, 0 to 20 |
 | `leadAliases` | `["lead"]` | A literal `@alias` in a new message counts as a mention |
-| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for Jev |
-| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |
+| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for the model |
 | `muteReaction` | `mute` | Reaction for a dropped message; `""` only removes the acceptance reaction(s) |
 | `slackTimeoutMs` | `5000` | Timeout per Slack call |
 
 ## Required secrets
 
-All are read from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.
+Set them as global `swarm_config` values. The server reads the provider credential from the global row when it makes the decision. `auto` and the Slack token read the API process environment, which loads global rows at boot and on config reload.
 
-- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every message fails open.
+- One provider credential from the [Provider](#provider) table is required for any evaluation. Without one, every message fails open. The `apiKey` config field of earlier versions is gone: the hook never holds a key, so store it as the global `TYPESAFE_API_KEY` secret.
 - `SLACK_BOT_TOKEN`: the Slack app's bot token. A swarm with Slack connected already has it. Without it, `enforce` still drops the message but cannot touch its reactions, and logs a `mute-error`.
 
 No key is written to config, KV, logs, or a description.