@desplega.ai/agent-swarm 2.5.1 → 2.5.3

package/src/tools/schedules/update-schedule.ts

@@ -15,6 +15,7 @@ import {
 import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { mergeScheduleTiming, validateRecurringTiming } from "@/be/schedules/validate";
 import { getScript } from "@/be/scripts/db";
+import { can } from "@/rbac";
 import { calculateNextRun } from "@/scheduler";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import {
@@ -173,6 +174,23 @@ export const registerUpdateScheduleTool = (server: McpServer) => {
         return toolErr("Agent not found.");
       }
 
+      // A deferral continues its owner's task, in that task's chat thread when
+      // it has one (src/scheduler/schedule-task.ts). Only the owner or a lead
+      // may change it.
+      if (
+        schedule.taskType === "deferred" &&
+        !can({
+          principal: { kind: "agent", agentId: caller.id, isLead: caller.isLead },
+          verb: "schedule.deferral.update.any",
+          resource: { kind: "owned", ownerAgentId: schedule.createdByAgentId },
+          source: "mcp",
+        }).allow
+      ) {
+        return toolErr(
+          `Schedule "${schedule.name}" defers another agent's task. Only that agent or a lead can change it.`,
+        );
+      }
+
       // Reject updates on completed one-time schedules
       if (schedule.scheduleType === "one_time" && !schedule.enabled && schedule.lastRunAt) {
         return toolErr(

package/src/types.ts

@@ -1076,6 +1076,22 @@ export const UserSchema = z
 
 export type User = z.infer<typeof UserSchema>;
 
+export const RbacRoleSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    isBuiltin: z.boolean(),
+    grantsAll: z.boolean(),
+    primary: z.boolean(),
+    verbs: z.array(z.string()),
+  })
+  .openapi("RbacRole");
+
+export const UserRbacRolesSchema = z
+  .object({ userId: z.string(), roles: z.array(RbacRoleSchema) })
+  .openapi("UserRbacRoles");
+
 /**
  * Structured communication preferences read from `users.metadata.comms`.
  * All fields are free-form strings; values render verbatim into the requester
@@ -2942,6 +2958,13 @@ export const WorkflowRunSchema = z
     finishedAt: z.string().optional(),
     /** The `sub-workflow` step that started this run. Unset on a top-level run. */
     parentStepId: z.string().optional(),
+    /**
+     * The parent step's attempt (its `retryCount`) that started this run. A
+     * step has at most one child per attempt, so `(parentStepId,
+     * parentStepAttempt)` identifies the invocation; a node `retry` adds a
+     * child with the next attempt. Unset on a top-level run.
+     */
+    parentStepAttempt: z.number().int().min(0).optional(),
   })
   .openapi("WorkflowRun");
 

package/src/workflows/approval-notifications.ts

@@ -1,16 +1,235 @@
+import { formatConfigResult } from "../be/approval-config-question";
 import {
   type ApprovalRequest,
   claimApprovalCancellationNotification,
   completeApprovalCancellationNotificationClaim,
   createTaskExtended,
+  getApprovalRequestById,
   getTaskById,
   releaseApprovalCancellationNotificationClaim,
+  updateApprovalRequestNotifications,
 } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
 import { getSlackApp } from "../slack/app";
+import { resolveSlackConversationId } from "../slack/dm";
+import {
+  externalChannelToolError,
+  getChannelBlockReason,
+  isBlockExternalEnabled,
+} from "../slack/external-channel";
 import { TERMINAL_TASK_STATUSES } from "../types";
+import { getAppUrl } from "../utils/constants";
 import { scrubSecrets } from "../utils/secret-scrubber";
 
+/** Slack Block Kit caps a section block's text at 3000 characters. */
+const SLACK_SECTION_TEXT_LIMIT = 3000;
+
+function escapeSlackMrkdwn(text: string): string {
+  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+/**
+ * Render the Slack "Questions" section text within Block Kit's 3000-character
+ * section limit. Labels are escaped so upstream text cannot inject mentions or
+ * links. When the list does not fit, the tail is replaced by a count; every
+ * question stays answerable on the dashboard page the card's button opens.
+ */
+export function buildSlackQuestionsSummary(
+  questions: ReadonlyArray<{ label?: string; type?: string }>,
+  timeoutText = "",
+): string {
+  const header = "*Questions:*\n";
+  // A config question is only ever answered on the dashboard, never in Slack.
+  const lines = questions.map(
+    (q) =>
+      `• ${escapeSlackMrkdwn((q.label ?? "").replace(/\s+/g, " ").trim())}${q.type === "config" ? " (set on dashboard)" : ""}`,
+  );
+  const fits = (shown: string[], omitted: number) => {
+    const tail =
+      omitted > 0 ? `\n_…and ${omitted} more. Answer all of them on the dashboard._` : "";
+    const text = `${header}${shown.join("\n")}${tail}${timeoutText}`;
+    return text.length <= SLACK_SECTION_TEXT_LIMIT ? text : null;
+  };
+
+  const full = fits(lines, 0);
+  if (full) return full;
+  for (let count = lines.length - 1; count >= 0; count--) {
+    const text = fits(lines.slice(0, count), lines.length - count);
+    if (text) return text;
+  }
+  return `${header}_${questions.length} questions. Answer them on the dashboard._`;
+}
+
+function formatTimeout(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  const hours = Math.floor(seconds / 3600);
+  const mins = Math.round((seconds % 3600) / 60);
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+}
+
+export interface ApprovalNotificationChannel {
+  channel: "slack" | "email";
+  target: string;
+}
+
+export interface ApprovalNotificationsInput {
+  requestId: string;
+  title: string;
+  questions: ReadonlyArray<{ label?: string; type?: string }>;
+  timeoutSeconds?: number;
+  notifications: ReadonlyArray<ApprovalNotificationChannel>;
+}
+
+/** The DB calls the dispatch makes; the HITL executor injects its own. */
+export interface ApprovalNotificationsDb {
+  updateApprovalRequestNotifications: typeof updateApprovalRequestNotifications;
+  getApprovalRequestById: typeof getApprovalRequestById;
+}
+
+/**
+ * Post the "Approval Required" card for each notification channel and store
+ * the Slack `messageTs` on the request. Used by the workflow HITL executor and
+ * by `POST /api/approval-requests`, which checks the caller may post to Slack.
+ * Callers fire and forget: a Slack failure is logged and never fails the
+ * request. Email is not supported yet and is skipped.
+ */
+export async function dispatchApprovalNotifications(
+  input: ApprovalNotificationsInput,
+  db: ApprovalNotificationsDb = { updateApprovalRequestNotifications, getApprovalRequestById },
+): Promise<void> {
+  const { requestId, title, questions, timeoutSeconds, notifications } = input;
+  if (!notifications.length) return;
+
+  const approvalUrl = `${getAppUrl()}/approval-requests/${requestId}`;
+  const updatedChannels: Array<ApprovalNotificationChannel & { messageTs?: string }> = [
+    ...notifications,
+  ];
+  let updated = false;
+
+  for (let i = 0; i < notifications.length; i++) {
+    const notification = notifications[i]!;
+
+    if (notification.channel === "email") {
+      console.warn(`[HITL] Email notifications not yet supported (target: ${notification.target})`);
+      continue;
+    }
+
+    if (notification.channel === "slack") {
+      try {
+        const slackApp = getSlackApp();
+        if (!slackApp) {
+          console.warn("[HITL] Slack not initialized — cannot send notification");
+          continue;
+        }
+
+        // Same guard as the Slack tools: never post into a channel shared with another org.
+        if (isBlockExternalEnabled()) {
+          const conversationId = await resolveSlackConversationId(
+            slackApp.client,
+            notification.target,
+          );
+          const blockReason = await getChannelBlockReason(slackApp.client, conversationId);
+          if (blockReason) {
+            console.warn(`[HITL] ${externalChannelToolError(conversationId, blockReason)}`);
+            continue;
+          }
+        }
+
+        const questionsText = buildSlackQuestionsSummary(questions);
+
+        // The deadline is a caption under the button, not part of the ask.
+        const timeoutCaption =
+          timeoutSeconds !== undefined
+            ? [
+                {
+                  type: "context",
+                  elements: [
+                    {
+                      type: "mrkdwn",
+                      text: `⏱ Timeout: ${formatTimeout(timeoutSeconds)} — times out if not responded`,
+                    },
+                  ],
+                },
+              ]
+            : [];
+
+        const blocks = [
+          {
+            type: "section",
+            text: {
+              type: "mrkdwn",
+              text: `🔔 *Approval Required: ${escapeSlackMrkdwn(title)}*`,
+            },
+          },
+          {
+            type: "section",
+            text: {
+              type: "mrkdwn",
+              text: questionsText,
+            },
+          },
+          {
+            type: "actions",
+            elements: [
+              {
+                type: "button",
+                text: { type: "plain_text", text: "Review & Respond" },
+                url: approvalUrl,
+                style: "primary",
+              },
+            ],
+          },
+          ...timeoutCaption,
+        ];
+
+        const result = await slackApp.client.chat.postMessage({
+          channel: notification.target,
+          text: `Approval Required: ${escapeSlackMrkdwn(title)} — ${approvalUrl}`,
+          unfurl_links: false,
+          unfurl_media: false,
+          // biome-ignore lint/suspicious/noExplicitAny: Block Kit objects
+          blocks: blocks as any,
+        });
+
+        if (result.ts) {
+          updatedChannels[i] = { ...notification, messageTs: result.ts };
+          updated = true;
+        }
+
+        console.log(
+          `[HITL] Slack notification sent to ${notification.target} for request ${requestId}`,
+        );
+      } catch (err) {
+        console.error(
+          `[HITL] Failed to send Slack notification to ${notification.target}:`,
+          scrubSecrets(err instanceof Error ? err.message : String(err)),
+        );
+      }
+    }
+  }
+
+  // Persist messageTs values back to DB
+  if (updated) {
+    try {
+      await db.updateApprovalRequestNotifications(requestId, updatedChannels);
+      // A cancel that landed while the card was posting found no messageTs to thread under.
+      const latest = await db.getApprovalRequestById(requestId);
+      if (latest?.status === "cancelled") {
+        await postApprovalCancellationUpdates(
+          [latest],
+          latest.resolutionReason ?? "Workflow run cancelled",
+        );
+      }
+    } catch (err) {
+      console.error(
+        "[HITL] Failed to update notification channels in DB:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      );
+    }
+  }
+}
+
 export interface ApprovalSlackClient {
   chat: {
     postMessage(input: {
@@ -141,6 +360,8 @@ function formatResponses(
       let answerText: string;
       if (answer == null) {
         answerText = "(no answer)";
+      } else if (q.type === "config") {
+        answerText = formatConfigResult(answer) ?? "(unreadable config result)";
       } else if (q.type === "approval") {
         const a = answer as { approved?: boolean; comment?: string };
         answerText = a.approved ? "Approved" : "Rejected";

package/src/workflows/checkpoint.ts

@@ -1,8 +1,30 @@
 import { getDbClient, getWorkflowRun, updateWorkflowRun, updateWorkflowRunStep } from "../be/db";
 import type { RetryPolicy } from "../types";
 
+/**
+ * The execution a checkpoint belongs to: the step attempt (`retryCount`) that
+ * claimed the row. A fenced checkpoint writes only while that attempt still
+ * owns the row: the step is `running` with that `retryCount` in a `running` or
+ * `waiting` run. A cancel, a newer attempt or another settle that committed
+ * meanwhile wins, and the stale execution writes nothing.
+ */
+export type StepFence = { retryCount: number };
+
+async function holdsFence(runId: string, stepId: string, fence: StepFence): Promise<boolean> {
+  const row = await getDbClient().get<{ found: number }>(
+    `SELECT 1 AS found
+       FROM workflow_run_steps s
+       JOIN workflow_runs r ON r.id = s.runId
+      WHERE s.id = ? AND s.runId = ? AND s.status = 'running' AND s.retryCount = ?
+        AND r.status IN ('running', 'waiting')`,
+    [stepId, runId, fence.retryCount],
+  );
+  return row != null;
+}
+
 /**
  * Checkpoint a successful step — atomic DB write of step result + run context.
+ * Returns false, writing nothing, when `fence` no longer holds.
  */
 export async function checkpointStep(
   runId: string,
@@ -10,8 +32,10 @@ export async function checkpointStep(
   nodeId: string,
   result: { output?: unknown; nextPort?: string },
   ctx: Record<string, unknown>,
-): Promise<void> {
-  await getDbClient().transaction(async () => {
+  options: { fence?: StepFence } = {},
+): Promise<boolean> {
+  return getDbClient().transaction(async () => {
+    if (options.fence && !(await holdsFence(runId, stepId, options.fence))) return false;
     await updateWorkflowRunStep(stepId, {
       status: "completed",
       output: result.output,
@@ -24,11 +48,14 @@ export async function checkpointStep(
     await updateWorkflowRun(runId, {
       context: ctx,
     });
+    return true;
   });
 }
 
 /**
  * Checkpoint a step failure — marks step failed, calculates retry if applicable.
+ * With `fence`, a stale execution writes nothing and gets `stale: true`.
+ * `output` is kept on the failed step for observability, in the same write.
  */
 export async function checkpointStepFailure(
   runId: string,
@@ -36,49 +63,56 @@ export async function checkpointStepFailure(
   error: string,
   retryCount: number,
   retryPolicy?: RetryPolicy,
-  options?: { markRunFailed?: boolean },
-): Promise<{ shouldRetry: boolean }> {
+  options?: { markRunFailed?: boolean; fence?: StepFence; output?: unknown },
+): Promise<{ shouldRetry: boolean; stale?: true }> {
   const now = new Date().toISOString();
 
-  if (retryPolicy && retryCount < retryPolicy.maxRetries) {
-    const delay = calculateBackoff(retryPolicy, retryCount);
-    const nextRetryAt = new Date(Date.now() + delay).toISOString();
+  return getDbClient().transaction(async () => {
+    if (options?.fence && !(await holdsFence(runId, stepId, options.fence))) {
+      return { shouldRetry: false, stale: true as const };
+    }
+
+    if (retryPolicy && retryCount < retryPolicy.maxRetries) {
+      const delay = calculateBackoff(retryPolicy, retryCount);
+      const nextRetryAt = new Date(Date.now() + delay).toISOString();
+
+      await updateWorkflowRunStep(stepId, {
+        status: "failed",
+        error,
+        output: options?.output,
+        retryCount: retryCount + 1,
+        maxRetries: retryPolicy.maxRetries,
+        nextRetryAt,
+      });
+
+      return { shouldRetry: true };
+    }
 
+    // No retries left — mark step failed, and optionally the run too
+    // Clear nextRetryAt so the poller stops picking this step up
     await updateWorkflowRunStep(stepId, {
       status: "failed",
       error,
-      retryCount: retryCount + 1,
-      maxRetries: retryPolicy.maxRetries,
-      nextRetryAt,
+      output: options?.output,
+      finishedAt: now,
+      nextRetryAt: null,
     });
 
-    return { shouldRetry: true };
-  }
-
-  // No retries left — mark step failed, and optionally the run too
-  // Clear nextRetryAt so the poller stops picking this step up
-  await updateWorkflowRunStep(stepId, {
-    status: "failed",
-    error,
-    finishedAt: now,
-    nextRetryAt: null,
-  });
-
-  const markRunFailed = options?.markRunFailed ?? true;
-  if (markRunFailed) {
-    // A cancel or finalization that committed while the step ran wins.
-    await getDbClient().transaction(async () => {
+    const markRunFailed = options?.markRunFailed ?? true;
+    if (markRunFailed) {
+      // A cancel or finalization that committed while the step ran wins.
       const run = await getWorkflowRun(runId);
-      if (run?.status !== "running" && run?.status !== "waiting") return;
-      await updateWorkflowRun(runId, {
-        status: "failed",
-        error: `Step failed: ${error}`,
-        finishedAt: now,
-      });
-    });
-  }
+      if (run?.status === "running" || run?.status === "waiting") {
+        await updateWorkflowRun(runId, {
+          status: "failed",
+          error: `Step failed: ${error}`,
+          finishedAt: now,
+        });
+      }
+    }
 
-  return { shouldRetry: false };
+    return { shouldRetry: false };
+  });
 }
 
 /**