@desplega.ai/agent-swarm 1.51.2 → 1.52.1

package/src/tools/store-progress.ts

@@ -1,3 +1,4 @@
+import { ensure } from "@desplega.ai/business-use";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import {
@@ -161,6 +162,21 @@ export const registerStoreProgressTool = (server: McpServer) => {
           const result = completeTask(taskId, output);
           if (result) {
             updatedTask = result;
+
+            ensure({
+              id: "completed",
+              flow: "task",
+              runId: taskId,
+              depIds: ["started"],
+              data: {
+                taskId,
+                agentId: existingTask.agentId,
+                previousStatus: existingTask.status,
+                hasOutput: !!output,
+              },
+              validator: (data) => data.previousStatus === "in_progress",
+            });
+
             if (existingTask.agentId) {
               // Derive status from capacity instead of always setting idle
               updateAgentStatusFromCapacity(existingTask.agentId);
@@ -170,6 +186,21 @@ export const registerStoreProgressTool = (server: McpServer) => {
           const result = failTask(taskId, failureReason ?? "Unknown failure");
           if (result) {
             updatedTask = result;
+
+            ensure({
+              id: "failed",
+              flow: "task",
+              runId: taskId,
+              depIds: ["started"],
+              data: {
+                taskId,
+                agentId: existingTask.agentId,
+                previousStatus: existingTask.status,
+                failureReason: failureReason ?? "Unknown failure",
+              },
+              validator: (data) => data.previousStatus === "in_progress",
+            });
+
             if (existingTask.agentId) {
               // Derive status from capacity instead of always setting idle
               updateAgentStatusFromCapacity(existingTask.agentId);

package/src/tools/templates.ts

@@ -32,6 +32,34 @@ Use \`get-task-details\` with taskId "{{task_id}}" for full details.`,
   category: "task_lifecycle",
 });
 
+// ============================================================================
+// HITL follow-up (created when a standalone approval request is resolved)
+// ============================================================================
+
+registerTemplate({
+  eventType: "hitl.follow_up",
+  header: "",
+  defaultBody: `Human responded to your approval request ({{request_id}}).
+
+Title: {{title}}
+Status: {{status}}
+
+Questions and responses:
+{{responses}}
+
+Continue your work based on the human's input.`,
+  variables: [
+    { name: "request_id", description: "The approval request ID" },
+    { name: "title", description: "Title of the approval request" },
+    { name: "status", description: "Resolution status: approved or rejected" },
+    {
+      name: "responses",
+      description: "Formatted questions and human responses",
+    },
+  ],
+  category: "task_lifecycle",
+});
+
 registerTemplate({
   eventType: "task.worker.failed",
   header: "",

package/src/tools/tool-config.ts

@@ -115,6 +115,22 @@ export const DEFERRED_TOOLS = new Set([
   // Debug (1)
   "db-query",
 
+  // Approval Requests (1)
+  "request-human-input",
+
+  // Skills (11)
+  "skill-create",
+  "skill-update",
+  "skill-delete",
+  "skill-get",
+  "skill-list",
+  "skill-search",
+  "skill-install",
+  "skill-uninstall",
+  "skill-install-remote",
+  "skill-sync-remote",
+  "skill-publish",
+
   // Other (3)
   "cancel-task",
   "inject-learning",

package/src/tools/utils.ts

@@ -101,17 +101,19 @@ export const createToolRegistrar = (server: McpServer) => {
     config: ToolConfig<InputArgs, OutputArgs>,
     cb: ToolCallbackWithInfo<InputArgs>,
   ) => {
-    return server.registerTool(name, config, ((args: InferInput<InputArgs>, meta: Meta) => {
-      const requestInfo = getRequestInfo(meta);
-
-      // Handle zero-argument case
-      if (config.inputSchema === undefined) {
+    // When inputSchema is undefined, the MCP SDK calls handler(extra) with a single arg.
+    // When inputSchema is defined, it calls handler(args, extra) with two args.
+    if (config.inputSchema === undefined) {
+      return server.registerTool(name, config, ((meta: Meta) => {
+        const requestInfo = getRequestInfo(meta);
         return (
           cb as (requestInfo: RequestInfo, meta: Meta) => CallToolResult | Promise<CallToolResult>
         )(requestInfo, meta);
-      }
+      }) as Parameters<typeof server.registerTool>[2]);
+    }
 
-      // Handle with-arguments case
+    return server.registerTool(name, config, ((args: InferInput<InputArgs>, meta: Meta) => {
+      const requestInfo = getRequestInfo(meta);
       return (
         cb as (
           args: InferInput<InputArgs>,

package/src/types.ts

@@ -869,3 +869,57 @@ export const PromptTemplateHistorySchema = z.object({
   changeReason: z.string().nullable(),
 });
 export type PromptTemplateHistory = z.infer<typeof PromptTemplateHistorySchema>;
+
+// ============================================================================
+// Skill Types
+// ============================================================================
+
+export const SkillTypeSchema = z.enum(["remote", "personal"]);
+export type SkillType = z.infer<typeof SkillTypeSchema>;
+
+export const SkillScopeSchema = z.enum(["global", "swarm", "agent"]);
+export type SkillScope = z.infer<typeof SkillScopeSchema>;
+
+export const SkillSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  content: z.string(),
+  type: SkillTypeSchema,
+  scope: SkillScopeSchema,
+  ownerAgentId: z.string().nullable(),
+  sourceUrl: z.string().nullable(),
+  sourceRepo: z.string().nullable(),
+  sourcePath: z.string().nullable(),
+  sourceBranch: z.string(),
+  sourceHash: z.string().nullable(),
+  isComplex: z.boolean(),
+  allowedTools: z.string().nullable(),
+  model: z.string().nullable(),
+  effort: z.string().nullable(),
+  context: z.string().nullable(),
+  agent: z.string().nullable(),
+  disableModelInvocation: z.boolean(),
+  userInvocable: z.boolean(),
+  version: z.number(),
+  isEnabled: z.boolean(),
+  createdAt: z.string(),
+  lastUpdatedAt: z.string(),
+  lastFetchedAt: z.string().nullable(),
+});
+export type Skill = z.infer<typeof SkillSchema>;
+
+export const AgentSkillSchema = z.object({
+  id: z.string(),
+  agentId: z.string(),
+  skillId: z.string(),
+  isActive: z.boolean(),
+  installedAt: z.string(),
+});
+export type AgentSkill = z.infer<typeof AgentSkillSchema>;
+
+export const SkillWithInstallInfoSchema = SkillSchema.extend({
+  isActive: z.boolean(),
+  installedAt: z.string(),
+});
+export type SkillWithInstallInfo = z.infer<typeof SkillWithInstallInfoSchema>;

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

@@ -0,0 +1,273 @@
+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,
+    });
+
+    // 3. Dispatch notifications (fire-and-forget — failures must not block the workflow)
+    if (config.notifications?.length) {
+      this.dispatchNotifications(requestId, config, db).catch((err) => {
+        console.error("[HITL] Unexpected error dispatching notifications:", err);
+      });
+    }
+
+    // 4. Return async result — engine will pause the workflow
+    return {
+      status: "success",
+      async: true,
+      waitFor: "approval.resolved",
+      correlationId: requestId,
+    } as unknown as ExecutorResult<HITLOutput>;
+  }
+
+  /** Dispatch notifications for each configured channel. Updates DB with messageTs on success. */
+  private async dispatchNotifications(
+    requestId: string,
+    config: z.infer<typeof HITLConfigSchema>,
+    db: typeof import("../../be/db"),
+  ): Promise<void> {
+    if (!config.notifications?.length) return;
+
+    const approvalUrl = `https://app.agent-swarm.dev/approval-requests/${requestId}`;
+    const updatedChannels = [...config.notifications] as Array<
+      z.infer<typeof NotificationConfigSchema> & { messageTs?: string }
+    >;
+    let updated = false;
+
+    for (let i = 0; i < config.notifications.length; i++) {
+      const notification = config.notifications[i]!;
+
+      if (notification.channel === "email") {
+        console.warn(
+          `[HITL] Email notifications not yet supported (target: ${notification.target})`,
+        );
+        continue;
+      }
+
+      if (notification.channel === "slack") {
+        try {
+          const { getSlackApp } = await import("../../slack/app");
+          const slackApp = getSlackApp();
+          if (!slackApp) {
+            console.warn("[HITL] Slack not initialized — cannot send notification");
+            continue;
+          }
+
+          const questionsSummary = config.questions.map((q) => `• ${q.label}`).join("\n");
+
+          const timeoutText = config.timeout
+            ? `\n⏱ _Timeout: ${formatTimeout(config.timeout.seconds)} — auto-rejects if not responded_`
+            : "";
+
+          const blocks = [
+            {
+              type: "section",
+              text: {
+                type: "mrkdwn",
+                text: `🔔 *Approval Required: ${config.title}*`,
+              },
+            },
+            {
+              type: "section",
+              text: {
+                type: "mrkdwn",
+                text: `*Questions:*\n${questionsSummary}${timeoutText}`,
+              },
+            },
+            {
+              type: "actions",
+              elements: [
+                {
+                  type: "button",
+                  text: { type: "plain_text", text: "Review & Respond" },
+                  url: approvalUrl,
+                  style: "primary",
+                },
+              ],
+            },
+          ];
+
+          const result = await slackApp.client.chat.postMessage({
+            channel: notification.target,
+            text: `Approval Required: ${config.title} — ${approvalUrl}`,
+            // 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}:`, err);
+        }
+      }
+    }
+
+    // Persist messageTs values back to DB
+    if (updated) {
+      try {
+        db.updateApprovalRequestNotifications(requestId, updatedChannels);
+      } catch (err) {
+        console.error("[HITL] Failed to update notification channels in DB:", err);
+      }
+    }
+  }
+}
+
+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`;
+}

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/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.
  */

package/src/workflows/resume.ts

@@ -21,6 +21,14 @@ interface TaskEvent {
   failureReason?: string;
 }
 
+interface ApprovalEvent {
+  requestId: string;
+  status: "approved" | "rejected" | "timeout";
+  responses: Record<string, unknown> | null;
+  workflowRunId?: string;
+  workflowRunStepId?: string;
+}
+
 /**
  * Wire up event bus listeners for workflow resume on task lifecycle events.
  */
@@ -57,6 +65,16 @@ export function setupWorkflowResumeListener(
       console.error("[workflows] Handle task cancellation error:", err);
     }
   });
+
+  eventBus.on("approval.resolved", async (data: unknown) => {
+    const event = data as ApprovalEvent;
+    if (!event.workflowRunId || !event.workflowRunStepId) return;
+    try {
+      await resumeFromApprovalResolution(event, registry);
+    } catch (err) {
+      console.error("[workflows] Resume from approval resolution failed:", err);
+    }
+  });
 }
 
 /**
@@ -119,7 +137,7 @@ async function resumeFromTaskCompletion(
  * If no nodes are ready and no steps are still waiting, finalize the run.
  * Otherwise set it back to waiting for the next task completion.
  */
-function finalizeOrWait(runId: string): void {
+export function finalizeOrWait(runId: string): void {
   const steps = getWorkflowRunStepsByRunId(runId);
   const hasWaiting = steps.some((s) => s.status === "waiting");
   if (hasWaiting) {
@@ -227,3 +245,49 @@ export async function retryFailedRun(runId: string, registry: ExecutorRegistry):
     : [failedNode, ...readyNodes];
   await walkGraph(workflow.definition, runId, ctx, nodesToRun, registry, workflow.id);
 }
+
+/**
+ * Resume a workflow after a linked approval request is resolved.
+ *
+ * 1. Verify run and step are in "waiting" state
+ * 2. Checkpoint step completion with approval response data
+ * 3. Route to the appropriate port (approved/rejected/timeout)
+ * 4. Continue the graph walk
+ */
+async function resumeFromApprovalResolution(
+  event: ApprovalEvent,
+  registry: ExecutorRegistry,
+): Promise<void> {
+  const run = getWorkflowRun(event.workflowRunId!);
+  if (!run || (run.status !== "waiting" && run.status !== "running")) return;
+
+  const step = getWorkflowRunStep(event.workflowRunStepId!);
+  if (!step || step.status !== "waiting") return;
+
+  const workflow = getWorkflow(run.workflowId);
+  if (!workflow) return;
+
+  const ctx = (run.context ?? {}) as Record<string, unknown>;
+
+  // Determine output port based on approval status
+  const nextPort =
+    event.status === "timeout" ? "timeout" : event.status === "rejected" ? "rejected" : "approved";
+
+  const stepOutput = {
+    requestId: event.requestId,
+    status: event.status,
+    responses: event.responses,
+  };
+
+  checkpointStep(run.id, step.id, step.nodeId, { output: stepOutput, nextPort }, ctx);
+  updateWorkflowRun(run.id, { status: "running" });
+
+  const completedNodeIds = new Set(getCompletedStepNodeIds(run.id));
+  const readyNodes = findReadyNodes(workflow.definition, completedNodeIds);
+
+  if (readyNodes.length > 0) {
+    await walkGraph(workflow.definition, run.id, ctx, readyNodes, registry, workflow.id);
+  } else {
+    finalizeOrWait(run.id);
+  }
+}