@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/tools/update-profile.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { updateAgentName, updateAgentProfile } from "@/be/db";
+import { getAgentById, updateAgentName, updateAgentProfile } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 import { type Agent, AgentSchema } from "@/types";
 
@@ -10,8 +10,17 @@ export const registerUpdateProfileTool = (server: McpServer) => {
     {
       title: "Update Profile",
       description:
-        "Updates the calling agent's profile information (name, description, role, capabilities).",
+        "Updates an agent's profile information (name, description, role, capabilities). By default updates the calling agent. Lead agents can update any agent's profile by providing the agentId parameter.",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
+        agentId: z
+          .string()
+          .uuid()
+          .optional()
+          .describe(
+            "Target agent ID to update. If omitted, updates the calling agent. Only lead agents can update other agents' profiles.",
+          ),
         name: z.string().min(1).optional().describe("Agent name."),
         description: z.string().optional().describe("Agent description."),
         role: z
@@ -30,6 +39,34 @@ export const registerUpdateProfileTool = (server: McpServer) => {
           .describe(
             "Personal CLAUDE.md content. Loaded on session start and synced back on session end. Use for persistent notes and instructions.",
           ),
+        soulMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Soul content: persona and behavioral directives. Updates both DB and /workspace/SOUL.md.",
+          ),
+        identityMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Identity content: expertise and working style. Updates both DB and /workspace/IDENTITY.md.",
+          ),
+        setupScript: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Setup script content (bash). Runs at container start to install tools, configure environment. Persists across sessions. Also written to /workspace/start-up.sh.",
+          ),
+        toolsMd: z
+          .string()
+          .max(65536)
+          .optional()
+          .describe(
+            "Environment-specific operational knowledge. Repos, services, SSH hosts, APIs, device names — anything specific to your setup. Synced to /workspace/TOOLS.md.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -38,7 +75,22 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         agent: AgentSchema.optional(),
       }),
     },
-    async ({ name, description, role, capabilities, claudeMd }, requestInfo, _meta) => {
+    async (
+      {
+        agentId,
+        name,
+        description,
+        role,
+        capabilities,
+        claudeMd,
+        soulMd,
+        identityMd,
+        setupScript,
+        toolsMd,
+      },
+      requestInfo,
+      _meta,
+    ) => {
       if (!requestInfo.agentId) {
         return {
           content: [{ type: "text", text: 'Agent ID not found. Set the "X-Agent-ID" header.' }],
@@ -49,26 +101,78 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         };
       }
 
+      // Determine target agent: if agentId is provided, check lead permissions
+      const isUpdatingSelf = !agentId || agentId === requestInfo.agentId;
+      const targetAgentId = isUpdatingSelf ? requestInfo.agentId : agentId;
+
+      if (!isUpdatingSelf) {
+        // Only lead agents can update other agents' profiles
+        const callingAgent = getAgentById(requestInfo.agentId);
+        if (!callingAgent) {
+          return {
+            content: [{ type: "text", text: "Calling agent not found." }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: "Calling agent not found.",
+            },
+          };
+        }
+        if (!callingAgent.isLead) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Only lead agents can update other agents' profiles. Provide no agentId to update your own profile.",
+              },
+            ],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message:
+                "Only lead agents can update other agents' profiles. Provide no agentId to update your own profile.",
+            },
+          };
+        }
+
+        // Validate target agent exists before proceeding
+        const targetAgent = getAgentById(targetAgentId);
+        if (!targetAgent) {
+          return {
+            content: [{ type: "text", text: `Target agent ${targetAgentId} not found.` }],
+            structuredContent: {
+              yourAgentId: requestInfo.agentId,
+              success: false,
+              message: `Target agent ${targetAgentId} not found.`,
+            },
+          };
+        }
+      }
+
       // At least one field must be provided
       if (
         name === undefined &&
         description === undefined &&
         role === undefined &&
         capabilities === undefined &&
-        claudeMd === undefined
+        claudeMd === undefined &&
+        soulMd === undefined &&
+        identityMd === undefined &&
+        setupScript === undefined &&
+        toolsMd === undefined
       ) {
         return {
           content: [
             {
               type: "text",
-              text: "At least one field (name, description, role, capabilities, or claudeMd) must be provided.",
+              text: "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
             },
           ],
           structuredContent: {
             yourAgentId: requestInfo.agentId,
             success: false,
             message:
-              "At least one field (name, description, role, capabilities, or claudeMd) must be provided.",
+              "At least one field (name, description, role, capabilities, claudeMd, soulMd, identityMd, setupScript, or toolsMd) must be provided.",
           },
         };
       }
@@ -78,26 +182,70 @@ export const registerUpdateProfileTool = (server: McpServer) => {
 
         // Update name if provided
         if (name !== undefined) {
-          agent = updateAgentName(requestInfo.agentId, name);
+          agent = updateAgentName(targetAgentId, name);
           if (!agent) {
             return {
-              content: [{ type: "text", text: "Agent not found." }],
+              content: [{ type: "text", text: "Target agent not found." }],
               structuredContent: {
                 yourAgentId: requestInfo.agentId,
                 success: false,
-                message: "Agent not found.",
+                message: "Target agent not found.",
               },
             };
           }
         }
 
         // Update profile fields if provided
-        agent = updateAgentProfile(requestInfo.agentId, {
-          description,
-          role,
-          capabilities,
-          claudeMd,
-        });
+        agent = updateAgentProfile(
+          targetAgentId,
+          {
+            description,
+            role,
+            capabilities,
+            claudeMd,
+            soulMd,
+            identityMd,
+            setupScript,
+            toolsMd,
+          },
+          {
+            changeSource: isUpdatingSelf ? "self_edit" : "lead_coaching",
+            changedByAgentId: requestInfo.agentId,
+          },
+        );
+
+        // Write updated files to workspace only when updating self
+        // (remote agent files live on their own container)
+        if (isUpdatingSelf) {
+          if (soulMd !== undefined) {
+            try {
+              await Bun.write("/workspace/SOUL.md", soulMd);
+            } catch {
+              /* ignore */
+            }
+          }
+          if (identityMd !== undefined) {
+            try {
+              await Bun.write("/workspace/IDENTITY.md", identityMd);
+            } catch {
+              /* ignore */
+            }
+          }
+          if (setupScript !== undefined) {
+            try {
+              await Bun.write("/workspace/start-up.sh", `#!/bin/bash\n${setupScript}\n`);
+            } catch {
+              /* ignore */
+            }
+          }
+          if (toolsMd !== undefined) {
+            try {
+              await Bun.write("/workspace/TOOLS.md", toolsMd);
+            } catch {
+              /* ignore */
+            }
+          }
+        }
 
         if (!agent) {
           return {
@@ -116,13 +264,20 @@ export const registerUpdateProfileTool = (server: McpServer) => {
         if (role !== undefined) updatedFields.push("role");
         if (capabilities !== undefined) updatedFields.push("capabilities");
         if (claudeMd !== undefined) updatedFields.push("claudeMd");
+        if (soulMd !== undefined) updatedFields.push("soulMd");
+        if (identityMd !== undefined) updatedFields.push("identityMd");
+        if (setupScript !== undefined) updatedFields.push("setupScript");
+        if (toolsMd !== undefined) updatedFields.push("toolsMd");
 
+        const targetLabel = isUpdatingSelf ? "own" : `agent ${targetAgentId}`;
         return {
-          content: [{ type: "text", text: `Updated profile: ${updatedFields.join(", ")}.` }],
+          content: [
+            { type: "text", text: `Updated ${targetLabel} profile: ${updatedFields.join(", ")}.` },
+          ],
           structuredContent: {
             yourAgentId: requestInfo.agentId,
             success: true,
-            message: `Updated profile: ${updatedFields.join(", ")}.`,
+            message: `Updated ${targetLabel} profile: ${updatedFields.join(", ")}.`,
             agent,
           },
         };

package/src/tools/update-service-status.ts

@@ -11,6 +11,8 @@ export const registerUpdateServiceStatusTool = (server: McpServer) => {
       title: "Update Service Status",
       description:
         "Update the health status of a registered service. Use this after a service becomes healthy or needs to be marked as stopped/unhealthy.",
+      annotations: { idempotentHint: true },
+
       inputSchema: z.object({
         serviceId: z.uuid().optional().describe("Service ID to update."),
         name: z.string().optional().describe("Service name to update (alternative to serviceId)."),

package/src/tools/utils.ts

@@ -18,22 +18,31 @@ type Meta = RequestHandlerExtra<ServerRequest, ServerNotification>;
 export type RequestInfo = {
   sessionId: string | undefined;
   agentId: string | undefined;
+  sourceTaskId: string | undefined;
 };
 
 export const getRequestInfo = (req: Meta): RequestInfo => {
   const agentIdHeader = req.requestInfo?.headers?.["x-agent-id"];
+  const sourceTaskIdHeader = req.requestInfo?.headers?.["x-source-task-id"];
 
   let agentId: string | undefined;
-
   if (Array.isArray(agentIdHeader)) {
     agentId = agentIdHeader?.[0];
   } else if (typeof agentIdHeader === "string") {
     agentId = agentIdHeader;
   }
 
+  let sourceTaskId: string | undefined;
+  if (Array.isArray(sourceTaskIdHeader)) {
+    sourceTaskId = sourceTaskIdHeader?.[0];
+  } else if (typeof sourceTaskIdHeader === "string") {
+    sourceTaskId = sourceTaskIdHeader;
+  }
+
   return {
     sessionId: req.sessionId || undefined,
     agentId,
+    sourceTaskId,
   };
 };
 

package/src/tools/workflows/create-workflow.ts

@@ -0,0 +1,129 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createWorkflow } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import {
+  CooldownConfigSchema,
+  InputValueSchema,
+  TriggerConfigSchema,
+  WorkflowDefinitionSchema,
+} from "@/types";
+import { validateDefinition } from "@/workflows/definition";
+
+export const registerCreateWorkflowTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "create-workflow",
+    {
+      title: "Create Workflow",
+      annotations: { destructiveHint: false },
+      description:
+        "Create a new automation workflow. Key concepts:\n" +
+        "- Nodes are linked via 'next' (string or port-based record).\n" +
+        "- CROSS-NODE DATA: To use output from an upstream node, you MUST declare an 'inputs' mapping on the downstream node. " +
+        'Example: inputs: { "cityData": "generate-city" } → then use {{cityData.taskOutput.field}} in config templates. ' +
+        "Without 'inputs', only 'trigger' and workflow-level 'input' are available for interpolation.\n" +
+        "- STRUCTURED OUTPUT: For agent-task nodes, put outputSchema inside 'config' to validate the agent's raw JSON output. " +
+        "Node-level outputSchema validates the executor's return ({taskId, taskOutput}), which is different.\n" +
+        "- Agent-task config: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }.",
+      inputSchema: z.object({
+        name: z.string().describe("Unique name for the workflow"),
+        description: z.string().optional().describe("Description of what this workflow does"),
+        definition: WorkflowDefinitionSchema.describe(
+          "The workflow definition with nodes (each node has id, type, config, and optional next/retry/validation)",
+        ),
+        triggers: z
+          .array(TriggerConfigSchema)
+          .optional()
+          .describe("Optional trigger configurations (webhook, schedule)"),
+        cooldown: CooldownConfigSchema.optional().describe(
+          "Optional cooldown configuration to prevent re-triggering too frequently",
+        ),
+        input: z
+          .record(z.string(), InputValueSchema)
+          .optional()
+          .describe(
+            "Optional input values resolved at execution time (env vars like VAR_NAME, secrets secret.NAME, or literals)",
+          ),
+        dir: z
+          .string()
+          .min(1)
+          .startsWith("/")
+          .optional()
+          .describe(
+            "Default working directory for all agent-task nodes (absolute path, e.g. /tmp/workspace)",
+          ),
+        vcsRepo: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Default VCS repo for all agent-task nodes (e.g. org/repo)"),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        workflow: z.unknown().optional(),
+      }),
+    },
+    async (
+      { name, description, definition, triggers, cooldown, input, dir, vcsRepo },
+      requestInfo,
+    ) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text" as const, text: "Agent ID required." }],
+          structuredContent: { success: false, message: "Agent ID required." },
+        };
+      }
+      try {
+        // Validate definition structure
+        const validation = validateDefinition(definition);
+        if (!validation.valid) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Invalid definition: ${validation.errors.join("; ")}`,
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message: `Invalid definition: ${validation.errors.join("; ")}`,
+            },
+          };
+        }
+
+        const workflow = createWorkflow({
+          name,
+          description,
+          definition,
+          triggers,
+          cooldown,
+          input,
+          dir,
+          vcsRepo,
+          createdByAgentId: requestInfo.agentId,
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Created workflow "${workflow.name}" (${workflow.id}).`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: `Created workflow "${workflow.name}".`,
+            workflow,
+          },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Failed: ${err}` }],
+          structuredContent: { success: false, message: String(err) },
+        };
+      }
+    },
+  );
+};

package/src/tools/workflows/delete-workflow.ts

@@ -0,0 +1,42 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { deleteWorkflow } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerDeleteWorkflowTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "delete-workflow",
+    {
+      title: "Delete Workflow",
+      annotations: { destructiveHint: true },
+      description: "Delete a workflow by ID. This also removes all associated runs and steps.",
+      inputSchema: z.object({
+        id: z.string().uuid().describe("Workflow ID to delete"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ id }) => {
+      try {
+        const deleted = deleteWorkflow(id);
+        if (!deleted) {
+          return {
+            content: [{ type: "text" as const, text: `Workflow not found: ${id}` }],
+            structuredContent: { success: false, message: `Workflow not found: ${id}` },
+          };
+        }
+        return {
+          content: [{ type: "text" as const, text: `Deleted workflow ${id}.` }],
+          structuredContent: { success: true, message: `Deleted workflow ${id}.` },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Failed: ${err}` }],
+          structuredContent: { success: false, message: String(err) },
+        };
+      }
+    },
+  );
+};

package/src/tools/workflows/get-workflow-run.ts

@@ -0,0 +1,59 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getWorkflowRun, getWorkflowRunStepsByRunId } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerGetWorkflowRunTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-workflow-run",
+    {
+      title: "Get Workflow Run",
+      annotations: { destructiveHint: false },
+      description: "Get details of a workflow run by ID, including all steps and their statuses.",
+      inputSchema: z.object({
+        id: z.string().uuid().describe("Workflow run ID"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        run: z.unknown().optional(),
+        steps: z.array(z.unknown()),
+      }),
+    },
+    async ({ id }) => {
+      try {
+        const run = getWorkflowRun(id);
+        if (!run) {
+          return {
+            content: [{ type: "text" as const, text: `Workflow run not found: ${id}` }],
+            structuredContent: {
+              success: false,
+              message: `Workflow run not found: ${id}`,
+              steps: [],
+            },
+          };
+        }
+        const steps = getWorkflowRunStepsByRunId(id);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Run ${id} — status: ${run.status}, steps: ${steps.length}.`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message: `Run ${id} status: ${run.status}.`,
+            run,
+            steps,
+          },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Failed: ${err}` }],
+          structuredContent: { success: false, message: String(err), steps: [] },
+        };
+      }
+    },
+  );
+};

package/src/tools/workflows/get-workflow.ts

@@ -0,0 +1,53 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getWorkflow } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { generateEdges } from "@/workflows/definition";
+
+export const registerGetWorkflowTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-workflow",
+    {
+      title: "Get Workflow",
+      annotations: { destructiveHint: false },
+      description:
+        "Get a workflow by ID, including its definition, triggers, cooldown, input, and auto-generated edges for UI rendering.",
+      inputSchema: z.object({
+        id: z.string().uuid().describe("Workflow ID"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        workflow: z.unknown().optional(),
+        edges: z.array(z.unknown()).optional(),
+      }),
+    },
+    async ({ id }) => {
+      try {
+        const workflow = getWorkflow(id);
+        if (!workflow) {
+          return {
+            content: [{ type: "text" as const, text: `Workflow not found: ${id}` }],
+            structuredContent: { success: false, message: `Workflow not found: ${id}` },
+          };
+        }
+        // Auto-generate edges for UI rendering
+        const edges = generateEdges(workflow.definition);
+        return {
+          content: [{ type: "text" as const, text: `Workflow "${workflow.name}" (${id}).` }],
+          structuredContent: {
+            success: true,
+            message: `Workflow "${workflow.name}".`,
+            workflow,
+            edges,
+          },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Failed: ${err}` }],
+          structuredContent: { success: false, message: String(err) },
+        };
+      }
+    },
+  );
+};

package/src/tools/workflows/index.ts

@@ -0,0 +1,9 @@
+export { registerCreateWorkflowTool } from "./create-workflow";
+export { registerDeleteWorkflowTool } from "./delete-workflow";
+export { registerGetWorkflowTool } from "./get-workflow";
+export { registerGetWorkflowRunTool } from "./get-workflow-run";
+export { registerListWorkflowRunsTool } from "./list-workflow-runs";
+export { registerListWorkflowsTool } from "./list-workflows";
+export { registerRetryWorkflowRunTool } from "./retry-workflow-run";
+export { registerTriggerWorkflowTool } from "./trigger-workflow";
+export { registerUpdateWorkflowTool } from "./update-workflow";

package/src/tools/workflows/list-workflow-runs.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { listWorkflowRuns } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { WorkflowRunStatusSchema } from "@/types";
+
+export const registerListWorkflowRunsTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-workflow-runs",
+    {
+      title: "List Workflow Runs",
+      annotations: { destructiveHint: false },
+      description: "List all execution runs for a given workflow, optionally filtered by status.",
+      inputSchema: z.object({
+        workflowId: z.string().uuid().describe("Workflow ID to list runs for"),
+        status: WorkflowRunStatusSchema.optional().describe(
+          "Filter by run status (running, waiting, completed, failed, skipped)",
+        ),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        runs: z.array(z.unknown()),
+      }),
+    },
+    async ({ workflowId, status }) => {
+      try {
+        let runs = listWorkflowRuns(workflowId);
+        if (status) {
+          runs = runs.filter((r) => r.status === status);
+        }
+        return {
+          content: [{ type: "text" as const, text: `Found ${runs.length} run(s).` }],
+          structuredContent: {
+            success: true,
+            message: `Found ${runs.length} run(s).`,
+            runs,
+          },
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Failed: ${err}` }],
+          structuredContent: { success: false, message: String(err), runs: [] },
+        };
+      }
+    },
+  );
+};