@desplega.ai/agent-swarm 1.167.0 → 1.169.0

package/src/workflows/executors/sub-workflow.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { getChildWorkflowRunId, getWorkflowRunLineage } from "../../be/db/workflow-runs";
+import type { ExecutorMeta, WorkflowRun } from "../../types";
+import { startWorkflowExecution } from "../engine";
+import type { ExecutorDependencies, ExecutorResult } from "./base";
+import { BaseExecutor } from "./base";
+import type { ExecutorRegistry } from "./registry";
+
+// ─── Config / Output Schemas ────────────────────────────────
+
+const SubWorkflowConfigSchema = z.object({
+  workflowId: z.string().min(1).describe("Workflow to run as a child"),
+  inputs: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe("Trigger data for the child run, validated against its triggerSchema"),
+});
+
+const SubWorkflowOutputSchema = z.object({
+  runId: z.string(),
+  /** The child's per-node outputs, keyed by node id. */
+  outputs: z.record(z.string(), z.unknown()),
+  /** Set when the child completed with a partial failure. */
+  error: z.string().optional(),
+});
+
+type SubWorkflowOutput = z.infer<typeof SubWorkflowOutputSchema>;
+
+/** Deepest child run a root run may start, counting the root as depth 0. */
+export const MAX_SUB_WORKFLOW_DEPTH = 16;
+
+/** Run-context keys that are not node outputs. `input` can hold resolved secrets. */
+const NON_NODE_CONTEXT_KEYS = new Set(["trigger", "input", "swarm", "workflow"]);
+
+/**
+ * The parent step's outcome for a child run: its result once the child
+ * completed, an error once it failed, was cancelled or was skipped, and null
+ * while it is still running or waiting.
+ */
+export function childRunOutcome(
+  child: WorkflowRun,
+): { output: SubWorkflowOutput } | { error: string } | null {
+  if (child.status === "running" || child.status === "waiting") return null;
+  if (child.status !== "completed") {
+    const reason = child.error ? `: ${child.error}` : "";
+    return { error: `Child workflow run ${child.id} ${child.status}${reason}` };
+  }
+  const outputs: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(child.context ?? {})) {
+    if (!NON_NODE_CONTEXT_KEYS.has(key)) outputs[key] = value;
+  }
+  return { output: { runId: child.id, outputs, error: child.error } };
+}
+
+// ─── Executor ───────────────────────────────────────────────
+
+/**
+ * Runs another workflow as a child run and waits for it. The child run records
+ * this step as its parent, so a re-executed step reconnects to it instead of
+ * starting a second child. The resume path is `resumeFromChildRun`.
+ */
+export class SubWorkflowExecutor extends BaseExecutor<
+  typeof SubWorkflowConfigSchema,
+  typeof SubWorkflowOutputSchema
+> {
+  readonly type = "sub-workflow";
+  readonly mode = "async" as const;
+  readonly configSchema = SubWorkflowConfigSchema;
+  readonly outputSchema = SubWorkflowOutputSchema;
+
+  constructor(
+    deps: ExecutorDependencies,
+    private readonly registry: ExecutorRegistry,
+  ) {
+    super(deps);
+  }
+
+  protected async execute(
+    config: z.infer<typeof SubWorkflowConfigSchema>,
+    _context: Readonly<Record<string, unknown>>,
+    meta: ExecutorMeta,
+  ): Promise<ExecutorResult<SubWorkflowOutput>> {
+    const { db } = this.deps;
+
+    const existingId = await getChildWorkflowRunId(meta.stepId);
+    const existing = existingId ? await db.getWorkflowRun(existingId) : null;
+    if (existing) return this.settle(existing);
+
+    // Capped at the max depth, so a long chain fails closed instead of
+    // hiding a cycle past the end of the scan.
+    const lineage = await getWorkflowRunLineage(meta.runId, MAX_SUB_WORKFLOW_DEPTH);
+    if (lineage.length > MAX_SUB_WORKFLOW_DEPTH) {
+      return {
+        status: "failed",
+        error: `Sub-workflow nesting exceeds ${MAX_SUB_WORKFLOW_DEPTH} levels`,
+      };
+    }
+    if (config.workflowId === meta.workflowId || lineage.includes(config.workflowId)) {
+      return {
+        status: "failed",
+        error: `Sub-workflow recursion: workflow ${config.workflowId} is already running in this run's ancestry`,
+      };
+    }
+
+    const workflow = await db.getWorkflow(config.workflowId);
+    if (!workflow) return { status: "failed", error: `Workflow ${config.workflowId} not found` };
+    if (!workflow.enabled) {
+      return { status: "failed", error: `Workflow ${config.workflowId} is disabled` };
+    }
+
+    // Returns once the child run exists; the child walks on its own. A child
+    // that already ended (cooldown, readiness, input failure) settles here.
+    const childRunId = await startWorkflowExecution(workflow, config.inputs ?? {}, this.registry, {
+      requestedByUserId: meta.requestedByUserId,
+      parentStepId: meta.stepId,
+    });
+    const child = await db.getWorkflowRun(childRunId);
+    if (!child) return { status: "failed", error: `Child workflow run ${childRunId} not found` };
+    return this.settle(child);
+  }
+
+  private settle(child: WorkflowRun): ExecutorResult<SubWorkflowOutput> {
+    const outcome = childRunOutcome(child);
+    if (!outcome) {
+      return {
+        status: "success",
+        async: true,
+        waitFor: "workflow.child.finished",
+        correlationId: child.id,
+      } as ExecutorResult<SubWorkflowOutput>;
+    }
+    if ("error" in outcome) return { status: "failed", error: outcome.error };
+    return { status: "success", output: outcome.output, nextPort: "success" };
+  }
+}

package/src/workflows/executors/wait.ts

@@ -93,7 +93,7 @@ export class WaitExecutor extends BaseExecutor<typeof WaitConfigSchema, typeof W
         async: true,
         waitFor: "wait.fired",
         correlationId: existing.id,
-      } as unknown as ExecutorResult<WaitOutput>;
+      } as ExecutorResult<WaitOutput>;
     }
 
     // 2. Mode-specific creation.
@@ -113,7 +113,7 @@ export class WaitExecutor extends BaseExecutor<typeof WaitConfigSchema, typeof W
         async: true,
         waitFor: "wait.fired",
         correlationId: waitId,
-      } as unknown as ExecutorResult<WaitOutput>;
+      } as ExecutorResult<WaitOutput>;
     }
 
     // Event mode: validate the filter at executor-init time (so a bad workflow
@@ -149,7 +149,7 @@ export class WaitExecutor extends BaseExecutor<typeof WaitConfigSchema, typeof W
       async: true,
       waitFor: "wait.fired",
       correlationId: waitId,
-    } as unknown as ExecutorResult<WaitOutput>;
+    } as ExecutorResult<WaitOutput>;
   }
 }
 

package/src/workflows/recovery.ts

@@ -12,6 +12,7 @@ import {
   resolveApprovalRequest,
   updateWorkflowRun,
 } from "../be/db";
+import { getSettledChildRunParentSteps } from "../be/db/workflow-runs";
 import type { WorkflowRunStep } from "../types";
 import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
@@ -24,7 +25,7 @@ import {
 } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
 import { getSecretInputKeys } from "./input";
-import { finalizeOrWait, resumeWaitState } from "./resume";
+import { finalizeOrWait, resumeFromChildRun, resumeWaitState } from "./resume";
 import {
   checkpointPortStepAndResolveSuccessors,
   completeTaskStepAndResolveSuccessors,
@@ -56,6 +57,15 @@ export async function recoverIncompleteRuns(registry: ExecutorRegistry): Promise
   // --- Case 4: Waiting runs whose wait_states are overdue or already resolved ---
   recovered += await recoverWaitStates(registry);
 
+  // --- Case 5: Waiting sub-workflow steps whose child run already finished ---
+  for (const parentStepId of await getSettledChildRunParentSteps()) {
+    try {
+      if (await resumeFromChildRun(parentStepId, registry)) recovered++;
+    } catch (err) {
+      console.error(`[workflows] Failed to resume sub-workflow step ${parentStepId}:`, err);
+    }
+  }
+
   if (recovered > 0) {
     console.log(`[workflows] Recovered ${recovered} incomplete run(s)`);
   }

package/src/workflows/resume.ts

@@ -17,6 +17,7 @@ import {
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
+import { getChildWorkflowRunId } from "../be/db/workflow-runs";
 import type { WaitStateRow } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import {
@@ -31,6 +32,7 @@ import { failRunOnUnreadableReplay, findReadyNodes, hasRunningStep, walkGraph }
 import type { WorkflowEventBus } from "./event-bus";
 import { workflowEventBus } from "./event-bus";
 import type { ExecutorRegistry } from "./executors/registry";
+import { childRunOutcome } from "./executors/sub-workflow";
 import { computeNextPort } from "./executors/wait";
 import { resolveForeachParent } from "./foreach-join";
 import { getSecretInputKeys } from "./input";
@@ -120,11 +122,23 @@ export function setupWorkflowResumeListener(
   };
   eventBus.on("approval.resolved", onApprovalResolved);
 
+  const onChildRunFinished = async (data: unknown) => {
+    try {
+      const { parentStepId } = data as { parentStepId?: string };
+      if (!parentStepId) return;
+      await resumeFromChildRun(parentStepId, registry);
+    } catch (err) {
+      console.error("[workflows] Resume from child workflow run failed:", err);
+    }
+  };
+  eventBus.on("workflow.child.finished", onChildRunFinished);
+
   return () => {
     eventBus.off("task.completed", onTaskCompleted);
     eventBus.off("task.failed", onTaskFailed);
     eventBus.off("task.cancelled", onTaskCancelled);
     eventBus.off("approval.resolved", onApprovalResolved);
+    eventBus.off("workflow.child.finished", onChildRunFinished);
   };
 }
 
@@ -765,6 +779,69 @@ async function resumeClaimedWait(
   }
 }
 
+/**
+ * Resume a waiting `sub-workflow` step once its child run is terminal: a
+ * completed child completes the step, any other end (or a deleted child) fails
+ * the step and its run. Returns true when this call claimed the step. Safe to call repeatedly:
+ * the live event and the recovery sweep both route here.
+ */
+export async function resumeFromChildRun(
+  parentStepId: string,
+  registry: ExecutorRegistry,
+): Promise<boolean> {
+  const step = await getWorkflowRunStep(parentStepId);
+  if (!step || step.status !== "waiting" || step.nodeType !== "sub-workflow") return false;
+  const childId = await getChildWorkflowRunId(parentStepId);
+  const child = childId ? await getWorkflowRun(childId) : null;
+  // The child row exists before the step parks, so a missing one was deleted.
+  const outcome = child
+    ? childRunOutcome(child)
+    : { error: `Child workflow run of step ${parentStepId} was deleted` };
+  if (!outcome) return false;
+
+  let claimed = false;
+  await failClosedOnUnreadableReplay(step.runId, step.id, async () => {
+    const run = await getWorkflowRun(step.runId);
+    if (!run || (run.status !== "waiting" && run.status !== "running")) return;
+    const workflow = await getWorkflow(run.workflowId);
+    if (!workflow) return;
+
+    if ("error" in outcome) {
+      claimed = await failStepAndRunIfWaiting(step.id, run.id, outcome.error);
+      return;
+    }
+
+    const ctx = (run.context ?? {}) as Record<string, unknown>;
+    const routing = await checkpointPortStepAndResolveSuccessors(
+      workflow.definition,
+      run.id,
+      step.id,
+      step.nodeId,
+      outcome.output,
+      "success",
+      ctx,
+    );
+    if (!routing.claimed) return;
+    claimed = true;
+
+    if (routing.successors.length > 0) {
+      const secretKeys = getSecretInputKeys(workflow.input);
+      await walkGraph(
+        workflow.definition,
+        run.id,
+        ctx,
+        routing.successors,
+        registry,
+        workflow.id,
+        secretKeys,
+      );
+    } else {
+      await finalizeOrWait(run.id);
+    }
+  });
+  return claimed;
+}
+
 // ─── 64KB firedPayload cap ──────────────────────────────────────────────────
 
 const FIRED_PAYLOAD_BYTE_CAP = 64 * 1024; // 64KB

package/src/workflows/wait-filter.ts

@@ -151,15 +151,13 @@ async function runWithTimeout<T>(fn: () => T): Promise<T | null> {
         // the user fn doesn't crash the runtime) and resolve to a sentinel
         // that the caller treats as "no-match". We wrap in a marker object
         // so the outer `await` can't unwrap a Thenable for us.
-        if (
-          v !== null &&
-          typeof v === "object" &&
-          typeof (v as { then?: unknown }).then === "function"
-        ) {
-          (v as unknown as Promise<unknown>).catch(() => {});
+        const then =
+          v !== null && typeof v === "object" ? (v as { then?: unknown }).then : undefined;
+        if (typeof then === "function") {
+          then.call(v, undefined, () => {});
           settled = true;
           clearTimeout(timer);
-          resolve({ __asyncRejected: true } as unknown as T);
+          resolve({ __asyncRejected: true } as T);
           return;
         }
         if (settled) return;

package/templates/extensions/README.md

@@ -13,6 +13,7 @@ Each folder holds exactly one `manifest.yaml`, `manifest.yml`, or `manifest.json
 | `require-ticket-ref` | `pre.task.create` | Blocks REST, MCP, and Slack tasks that do not name a ticket |
 | `notify-on-complete` | `post.task.completed`, `post.task.failed` | Posts a summary to a Slack channel |
 | `deploy-awareness` | `pre.task.create` | Appends a one-line note to new tasks while a Dokploy deploy is in progress |
+| `slack-reply-gate` | `pre.task.create` | Asks Jev (TypeSafe or OpenRouter) whether Lead should answer a Slack thread follow-up; in `enforce` drops the wake-up and marks the message :mute: |
 | `require-verification-note` | `pre.tool.call` | Refuses completion without a `Verified:` line in the output |
 | `task-digest` | `post.task.completed`, `post.task.failed` | Ships the `task-digest-collect` script, the `task-digest-daily` schedule (09:00 UTC), the `task-digest-report` workflow, and the `task-digest-guide` skill |
 

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

@@ -0,0 +1,98 @@
+# 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.
+
+Install config:
+
+```json
+{ "mode": "shadow" }
+```
+
+Start in `shadow`, read the decisions in KV for a few days, then switch to `enforce`.
+
+## Modes
+
+| `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. |
+
+## What it gates
+
+Hook: `pre.task.create`, for tasks with origin `slack` whose description carries the thread buffer's header `[Thread follow-up — N message(s) buffered]`. Those are the non-mention thread replies that `src/slack/thread-buffer.ts` batches into a Lead task. A direct @mention of the bot creates a task without that header and is never gated.
+
+The header counts only at the start of the description or right after the closing `</thread_context>`. Thread context quotes old messages verbatim, and an older Lead reply can quote the header itself, so a header inside the context is ignored. Only the text after the real header is treated as new.
+
+## 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`.
+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
+
+Jev is reachable two ways. Both take the same request and return the same answer, so the decision is identical whichever one runs.
+
+| `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 | | |
+
+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.
+
+## 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.
+
+## :mute: on drop (enforce)
+
+No swarm tool or extension `ctx` method adds a Slack reaction, so the hook calls the Slack Web API with the bot token. It needs the `reactions:write` scope, which the Slack app already uses for its acceptance reactions.
+
+1. `reactions.remove` for each acceptance reaction the engine may have put on the triggering message: `eyes`, `heavy_plus_sign`, `zap`, `speech_balloon`, or their `SLACK_REACTION_ACCEPTED`, `SLACK_REACTION_BUFFERED`, `SLACK_REACTION_NOW`, and `SLACK_REACTION_STEERED` overrides. Slack only removes the bot's own reaction, so a human's :eyes: stays.
+2. `reactions.add` with `muteReaction` (default `mute`). `already_reacted` counts as success. Skipped when `muteReaction` is `""`.
+
+The block returns first and the Slack calls run after it. A slow or failing Slack call never delays the drop or turns it back into a task. Set `muteReaction` to `""` for a true no-op: step 1 still clears the bot's acceptance reaction(s), and nothing is added.
+
+## Config
+
+| 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) |
+| `model` | `jev-latest` | Jev model on TypeSafe |
+| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |
+| `minConfidence` | `0.55` | Minimum summed skip probability to skip |
+| `contextMessages` | `6` | Thread messages sent to Jev, 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 |
+| `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.
+
+- `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.
+- `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.
+
+## KV namespace `ext:slack-reply-gate`
+
+- `d:<epochMs>:<channel>_<threadTs>`: one row per decision, with `action` (`pass`, `shadow-skip`, `skipped`, `fail-open`), `provider`, `reason`, `confidence`, `skipP`, `latencyMs`, `sender`, and a 300-character `preview`.
+- `m:<epochMs>:<channel>_<threadTs>`: one row per mute attempt, with `action` (`muted`, `unreacted` when `muteReaction` is `""`, `mute-error`), `removed`, `added`, and `errors`.
+- `last`: the latest decision. Mute rows never overwrite it.
+- Counters: `total`, `mention`, `files`, `reply`, `shadow-skip`, `skipped`, `error`, `muted`, `unreacted`, `mute-error`, and `reason:<label>`.
+
+## Known limits
+
+- When Lead already has an active task in the thread, the buffer steers that task instead of creating one, so `pre.task.create` does not fire and the gate does not run.
+- A blocked flush makes the thread buffer log a `TaskCreationBlockedError`. Nothing is lost: the next follow-up's `<thread_context>` carries the earlier messages.
+- A flush of several messages mutes only the triggering (last) message. The others keep their acceptance reaction.