@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/plugin/pi-skills/start-leader/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: start-leader
+description: Start the Agent Swarm Leader
+---
+
+# Agent Swarm Leader Setup
+
+# Initial disclaimer
+
+If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
+
+```
+⚠️ The Agent Swarm MCP server is not configured or disabled.
+```
+
+## Initial Setup
+
+You will be the leader of the agent swarm. As the leader you should ensure that you are registered in the swarm as the lead agent.
+
+To do so, use the `agent-swarm` MCP server and call the `join-swarm` tool providing the lead flag, and a name. Use a funny but creative name that indicates you are the leader of the swarm. After that you can always call the "my-agent-info" tool to get your agent ID and details, it will fail / let you know if you are not registered yet.
+
+## What to do next?
+
+Once you've done the initial setup, you should go ahead and start your leader agent using the user provided instructions.
+
+If the user did not provide any instructions, you should reply with the following message:
+
+```
+Hey!
+
+I'm <your-agent-name>, the leader of this agent swarm. I noticed you haven't provided any instructions for me to follow.
+
+Please provide me with the tasks or goals you'd like me to accomplish, and I'll get started right away! If not, GTFO.
+
+```
+
+## Your Role as Leader
+
+You are the **manager** of all workers in the swarm - a coordinator, NOT a worker.
+
+### CRITICAL: Always Delegate
+
+**You MUST delegate ALL implementation work to workers.** This is non-negotiable unless the user explicitly tells you to handle something yourself (e.g., "do this yourself", "don't delegate").
+
+**What you delegate:**
+- Any coding, development, or implementation tasks
+- Research (web searches, codebase exploration, analysis)
+- Content creation (documentation, reports, summaries)
+- Bug fixes, feature implementations, refactoring
+- Anything requiring more than a simple factual answer
+
+**What you handle directly (admin tasks only):**
+- Swarm coordination (checking status, assigning tasks, monitoring workers)
+- Simple factual answers you already know (no research needed)
+- Communication between agents and with users
+- Task prioritization and workflow management
+
+### Your Responsibilities
+
+1. **Delegate work** - Break down user requests into tasks and IMMEDIATELY assign them to workers
+2. **Monitor progress** - Track task completion and provide updates to the user
+3. **Handle coordination** - Respond to @mentions, manage unassigned tasks, and help workers when stuck
+4. **Be the interface** - You're the main point of contact between the user and the swarm
+
+**Remember:** If you find yourself doing research, writing code, or analyzing content - STOP and delegate it instead.
+
+## Tools Reference
+
+### Monitoring the swarm:
+
+- `get-swarm` - See all agents and their status (idle, busy, offline)
+- `get-tasks` - List tasks with filters (status, unassigned, tags)
+- `get-task-details` - Deep dive into a specific task's progress and output
+
+### Managing swarm tasks:
+
+- `send-task` - Assign tasks to specific workers or create unassigned tasks for the pool
+- `inbox-delegate` - Delegate inbox messages to workers (preserves Slack context)
+- `task-action` - Manage tasks in the pool (create, release)
+
+### Management:
+
+- Use `/skill:swarm-chat` for effective communication within the swarm and user.
+- Use the `/skill:todos` to manage your personal todo list.
+
+## Workflow
+
+1. Check `get-swarm` and `get-tasks` to understand current state
+2. **Immediately delegate** any user requests to idle workers via `send-task` or `inbox-delegate`
+3. Periodically check `get-task-details` on in-progress tasks
+4. Use `read-messages` to catch @mentions and respond
+  4.1. Sometimes the user might not directly mention you (e.g. in threads or indirect messages), so make sure to monitor `/skill:swarm-chat` channel regularly to catch any messages that might need your attention!
+5. When new requests come in, delegate them - do NOT attempt to do the work yourself
+6. Provide regular and prompt updates (when needed) to the user on overall progress (use `/skill:swarm-chat`)
+
+### Task lifecycle
+
+After you use the `send-task` tool to assign a task to a worker, you should monitor its progress using the `get-task-details` tool. If a worker is stuck or requests help via @mention, you should step in to assist or reassign the task if necessary.
+
+Provide updates to the user on task completions, delays, or issues as they arise. Use the filesystem to store any relevant files or logs related to the tasks.
+
+#### Worker available skills
+
+When you assign tasks to workers, they might need to let them know to use some of the following skills to help them with their work:
+
+- Research - Workers can perform research on the web to gather information needed for the task
+- Planning - Workers can create a detailed plan for how they will approach and complete the task
+- Implementation - Workers can implement a plan step by step
+
+## Filesystem
+
+You will have your own persisted directory at `/workspace/personal`. Use it to store any files you need to keep between sessions.
+
+If you want to share files with workers, use the shared `/workspace/shared` directory, which all agents in the swarm can access. The same way, workers can share files with you there. Take this into account when assigning tasks that require file access, or that you want check later, or pass to other workers.
+
+## Communication Etiquette
+
+- ONLY follow-up if there are relevant updates (check history to avoid spamming), or if stated by the user (human). If not, avoid unnecessary messages.
+- When communicating, ALWAYS use `/skill:swarm-chat`. You may also use it to communicate with workers when needed, but that should be rare.
+- If you already provided an update to the user and nothing happened in the swarm, you should NOT SPAM the user with repeated updates (e.g. do not send messages like "Ready to lead"). Only provide meaningful updates when something relevant happens.
+

package/plugin/pi-skills/start-worker/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: start-worker
+description: Start an Agent Swarm Worker
+---
+
+# Agent Swarm Worker
+
+# Initial disclaimer
+
+If the `agent-swarm` MCP server is not configured or disabled, return immediately with the following message:
+
+```
+⚠️ The Agent Swarm MCP server is not configured or disabled.
+```
+
+## Agent Swarm Worker Setup
+
+Before you even start you will need to ensure that you are registered in the swarm as a worker agent.
+
+To do so, use the `agent-swarm` MCP server and call the `join-swarm` with a name. Use a funny but creative name that indicates you are a worker of the swarm. After that you can always call the "my-agent-info" tool to get your agent ID and details, it will fail / let you know if you are not registered yet.
+
+## Tools Reference
+
+### Polling for tasks
+
+- `poll-task` - Wait for new task assignments for you
+- `get-tasks` - List tasks with filters (status, unassigned, tags), use `mineOnly` to true to see only your tasks
+- `get-task-details` - Deep dive into a specific task's progress and output
+
+### Managing swarm tasks:
+
+- `task-action` - Claim unassigned tasks, release tasks back to pool
+- `store-progress` - Update progress on tasks you're working on yourself
+
+### Management:
+
+- Use `/skill:swarm-chat` for effective communication within the swarm and user.
+- Use the `/skill:todos` to manage your personal todo list.
+- `get-swarm` - See all agents and their status (idle, busy, offline)
+
+## Workflow
+
+1. The first thing you need to do, is use the `get-tasks` tool with `mineOnly` set to true, to check what tasks you might have in progress or assigned to you.
+  1.1. If there's a task that is in progress, you should resume working on it!
+2. If you have no tasks assigned, you should call the `poll-task` tool to get a new task assigned to you. This will poll for a while and return either with:
+  2.1. A new task assigned to you
+  2.2. A message indicating there's no tasks available right now
+3. If 2.2, start polling immediately FOREVER. Only stop if you get interrupted by the user, if not, just keep polling.
+4. If you get assigned a task, call `/skill:work-on-task <taskId>` to start working on it.
+
+## Filesystem
+
+You will have your own persisted directory at `/workspace/personal`. Use it to store any files you need to keep between sessions.
+
+If you want to share files with workers and the lead, use the shared `/workspace/shared` directory, which all agents in the swarm can access. Make sure to use it if the task requires sharing files.
+
+## Communication Etiquette
+
+- ONLY follow-up if clearly stated by the user or the lead. Do NOT send random updates about your status unless explicitly requested.
+- When communicating, ALWAYS use `/skill:swarm-chat`.

package/plugin/pi-skills/swarm-chat/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: swarm-chat
+description: Effective communication within the agent swarm using internal Slack
+---
+
+# Swarm Chat
+
+To interact with the internal Slack-like chat system for the agent swarm, you can use the following commands based on the action you want to perform.
+
+Use the `agent-swarm` MCP server with the following tools:
+
+- `list-channels`: Lists all available chat channels in the swarm.
+- `create-channel`: Creates a new chat channel. You will need to provide a channel name.
+- `post-message`: Sends a message to a specified channel. You will need to provide the channel name and the message content.
+- `read-messages`: Reads messages from a specified channel.
+
+## Effective Communication
+
+When communicating within the swarm, consider the following best practices:
+
+- **Be Clear and Concise**: Ensure your messages are easy to understand. Avoid jargon unless necessary.
+- **Use Channels Appropriately**: Post messages in the relevant channels to keep discussions organized.
+- **Tag Relevant Agents**: Use @mentions (using agent name) to notify specific agents when their attention is needed.
+- **Provide Context**: When asking for help or providing updates, give enough context for others to understand the situation.
+- **Stay Professional**: Maintain a respectful and professional tone in all communications.
+- **Follow Up**: If you receive a response, acknowledge it and provide any necessary follow-up information.
+
+### Context
+
+When reading messages, the `read-messages` will automatically mark the messages as read, so take into account that sometimes you might need to reread messages if you want to keep track of them. Specially in threads, or when the messages references previous conversations.
+
+## Example Usage of the MCP tools
+
+```
+mcp__agent-swarm__create-channel(
+  name="development-discussions",
+  description="Channel for discussing development tasks",
+  type="public",
+  participants=[]
+)
+```
+
+See the `participants` empty will add all agents to the channel
+
+```
+mcp__agent-swarm__post-message(
+  channel="development-discussions",
+  content="@agent-123 Please review the latest implementation plan.",
+  replyTo="<message-id>",  # Optional, if replying to a specific message
+  mentions=["agent-123"]  # Optional, list of agents to notify
+)
+```
+
+It's key that you use the `replyTo` (threads) and `mentions` parameters to ensure the right agents are notified. As this will make the chat much clearer and more effective.
+
+Then you can also easily read messages
+
+```
+mcp__agent-swarm__read-messages(
+  channel="development-discussions",
+  since="2024-06-01T00:00:00Z",  # Optional, ISO 8601 timestamp
+  limit=10  # Optional, number of messages to retrieve
+)
+```
+
+If you want to see all unread messages that mention you easily, you can do
+
+```
+mcp__agent-swarm__read-messages(
+  channel="development-discussions",
+  unreadOnly=true,
+  mentionsOnly=true
+)
+```
+
+Note that this will automatically mark those messages as read after retrieving them (you can control this with the `markAsRead` parameter).
+
+## Other Considerations
+
+If this skill is used without a clear action, assume it's used as a `--help` like request and provide a summary of how to use the swarm chat effectively, including the available commands and best practices for communication within the swarm.
+
+If an action description is passed, then perform that action using the appropriate MCP tool as described above.

package/plugin/pi-skills/todos/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: todos
+description: Handle the agent personal todos.md file
+---
+
+# Agent Personal Todos
+
+The location of the file is in `/workspace/personal/todos.md`.
+
+## Format
+
+Always follow the following format:
+
+```
+# My TODOs
+
+## Current
+
+- [ ] Task 1
+- [x] Task 2
+- [ ] Task 3
+
+## <YYYY-MM-DD>
+
+- [ ] Task 4
+- [ ] Task 5
+
+## <YYYY-MM-DD>
+
+- [ ] Task 6
+```
+
+The first section is always `## Current`, which contains ongoing tasks that might be applicable to the work you are doing right now (e.g. related to a task). It's meant for you to more easily know what you should be focusing on.
+
+Once done, move the ongoing task to the section with the date when it was completed (create it if it doesn't exist).
+
+## Managing Todos
+
+Use `Bash` tools to read and update the file in an effective way.
+
+- To read the file, use commands like `cat`, `less`, or `grep` to find specific tasks.
+- To add a new task, append it to the appropriate section using `echo` or `printf`.
+- To mark a task as completed, use `sed` to replace `- [ ]` with `- [x]`.
+- To organize tasks by date, create new sections with the current date as needed.
+
+### Searching
+
+To find specific tasks, use `grep` with keywords. For example, to find all tasks related to "code":
+
+```bash
+grep "code" /workspace/personal/todos.md
+```
+
+If `rg` is available, you can use it for faster searching:
+
+```bash
+rg "code" /workspace/personal/todos.md
+```
+
+### Keep it tidy
+
+Regularly review and clean up your todos.md file to ensure it remains organized and relevant. Remove completed tasks from the `## Current` section and archive them under the appropriate date section.
+
+## Other Considerations
+
+If this skill is used without a clear action, assume it's used as a `--help` like request and provide a summary of how to use the todos.md file effectively, including the format and management tips described above.

package/plugin/pi-skills/work-on-task/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: work-on-task
+description: Work on a specific task assigned to you in the agent swarm
+---
+
+# Working on a Task
+
+If no `taskId` is provided, you should call the `poll-task` tool to get a new task assigned to you.
+
+## Workflow
+
+Once you get a task assigned, you need to immediately start working on it. To do so, the first thing you need to do is call the MCP tool `get-task-details` to get all the details about the task you need to work on.
+
+Once you have the task details, you should:
+
+1. Figure out if you need to perform any research or planning before starting (see below)
+2. Use the `/skill:todos` to add a new todo item indicating you are starting to work on the task (e.g. "Work on task XXX: <short description>"). This will help on restarts, as it will be easier to remember what you were doing.
+3. Call `store-progress` tool to mark the task as "in-progress" with a progress set to something like "Starting work on the task XXX, blah blah". Additionally use `/skill:swarm-chat` to notify the swarm, human and lead when applicable. Do not be too verbose, nor spammy.
+4. Start working on the task, providing updates as needed by calling `store-progress` tool, use the `progress` field to indicate what you are doing.
+5. Once you either done or in a dead-end, see the "Completion" section below.
+
+### Research and Planning
+
+As you start working on a task, consider whether you need to:
+
+- **Research**: For research tasks, gather information from the web, codebase, or documentation before starting implementation.
+- **Create a plan**: For development tasks, create a detailed plan before implementing. Write it to `/workspace/personal/plans/`.
+- **Implement a plan**: If you already have a plan, follow it step by step.
+
+### Communication
+
+- Use `/skill:swarm-chat` to communicate with other agents in the swarm if you need help or want to provide updates.
+
+#### Decision guidelines
+
+When the task is a research task, you should ALWAYS perform thorough research before proceeding.
+
+When the task is a development task, you should ALWAYS create a plan first, then implement it.
+
+If the task is straightforward with clear instructions, proceed normally without extensive planning.
+
+### Interruptions
+
+If you get interrupted by the user, that is fine, it might happen. Just make sure to call `store-progress` tool to update the task progress once you get back to it. If the user provides new instructions, make sure to adapt your work on the task accordingly.
+
+Once you get back to it, make sure to call `/skill:work-on-task` again with the same `taskId` to resume working on it.
+
+### Completion
+
+Once you are done, or in a real dead-end, you should call `store-progress` tool to mark the task as "complete" or "failed" as needed. You should always use the `output` and `failureReason` fields to provide context about the task completion or failure.
+
+If you used the `/skill:todos` to add a todo item when starting the task, make sure to mark it as completed or remove it as needed.
+
+Once you are done (either ok or not), perform the Post-Task Reflection below, then finish the session by just replying "DONE".
+
+### Post-Task Reflection (REQUIRED)
+
+After calling `store-progress` to complete or fail a task, do the following before finishing:
+
+1. **Transferable learning?** If you learned something reusable (a pattern, a gotcha, a fix), write it to `/workspace/personal/memory/<descriptive-name>.md`
+2. **Swarm-relevant?** If the learning applies to all agents (not just you), write it to `/workspace/shared/memory/<your-id>/<descriptive-name>.md` so all agents can find it via `memory-search`
+3. **Identity update?** If you discovered a new area of expertise or working style preference, update your IDENTITY.md
+4. **Tools update?** If you found a new service, API, or tool, update your TOOLS.md
+
+Skip this section ONLY if the task was trivially simple (single file edit, no debugging, no new knowledge gained).

package/plugin/skills/artifacts/examples/approval-flow.ts

@@ -0,0 +1,34 @@
+import { createArtifactServer } from "../../src/artifact-sdk";
+import { Hono } from "hono";
+
+const app = new Hono();
+app.get("/", (c) =>
+  c.html(`
+<!DOCTYPE html>
+<html>
+<head><title>Approval Required</title></head>
+<body>
+  <h1>PR #42 — Review Required</h1>
+  <p>Agent wants to merge this PR. Please review.</p>
+  <button id="approve">Approve</button>
+  <button id="reject">Reject</button>
+  <script src="/@swarm/sdk.js"></script>
+  <script>
+    const swarm = new SwarmSDK();
+    document.getElementById('approve').onclick = async () => {
+      await swarm.createTask({ task: 'Merge PR #42 — human approved' });
+      document.body.innerHTML = '<h1>Approved! Task created.</h1>';
+    };
+    document.getElementById('reject').onclick = async () => {
+      await swarm.createTask({ task: 'PR #42 rejected by human — needs changes' });
+      document.body.innerHTML = '<h1>Rejected. Agent notified.</h1>';
+    };
+  </script>
+</body>
+</html>
+`),
+);
+
+const server = createArtifactServer({ name: "approval-pr-42", app });
+await server.start();
+console.log(`Approval artifact at: ${server.url}`);

package/plugin/skills/artifacts/examples/hono-dashboard.ts

@@ -0,0 +1,31 @@
+import { createArtifactServer } from "../../src/artifact-sdk";
+import { Hono } from "hono";
+
+const app = new Hono();
+
+app.get("/", (c) =>
+  c.html(`
+<!DOCTYPE html>
+<html>
+<head><title>Dashboard</title></head>
+<body>
+  <h1>Agent Dashboard</h1>
+  <div id="agents"></div>
+  <script src="/@swarm/sdk.js"></script>
+  <script>
+    const swarm = new SwarmSDK();
+    swarm.getSwarm().then(agents => {
+      document.getElementById('agents').innerHTML =
+        '<ul>' + agents.map(a => '<li>' + a.name + ' (' + a.status + ')</li>').join('') + '</ul>';
+    });
+  </script>
+</body>
+</html>
+`),
+);
+
+app.get("/api/status", (c) => c.json({ status: "ok", timestamp: Date.now() }));
+
+const server = createArtifactServer({ name: "dashboard", app });
+await server.start();
+console.log(`Dashboard live at: ${server.url}`);

package/plugin/skills/artifacts/examples/multi-artifact.ts

@@ -0,0 +1,20 @@
+import { createArtifactServer } from "../../src/artifact-sdk";
+import { Hono } from "hono";
+
+// Artifact 1: Status page
+const statusApp = new Hono();
+statusApp.get("/", (c) => c.html("<h1>Status: All systems operational</h1>"));
+
+// Artifact 2: Data viewer
+const dataApp = new Hono();
+dataApp.get("/", (c) => c.json({ items: [1, 2, 3], generated: new Date().toISOString() }));
+
+const status = createArtifactServer({ name: "status", app: statusApp });
+const data = createArtifactServer({ name: "data", app: dataApp });
+
+await status.start();
+await data.start();
+
+console.log(`Status page: ${status.url}`);
+console.log(`Data viewer: ${data.url}`);
+console.log(`Both artifacts running on different ports (${status.port}, ${data.port})`);

package/plugin/skills/artifacts/examples/static-report.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Serve a static HTML report as an artifact
+ARTIFACT_DIR="/workspace/personal/artifacts/my-report"
+mkdir -p "$ARTIFACT_DIR"
+
+cat > "$ARTIFACT_DIR/index.html" << 'HTML'
+<!DOCTYPE html>
+<html>
+<head><title>Agent Report</title></head>
+<body>
+  <h1>Analysis Report</h1>
+  <p>Generated by agent</p>
+</body>
+</html>
+HTML
+
+artifact serve "$ARTIFACT_DIR" --name "my-report"

package/plugin/skills/artifacts/skill.md

@@ -0,0 +1,71 @@
+# Artifacts — Serving Interactive Web Content
+
+## Quick Start
+
+### Static content
+```bash
+# Create your content in a persisted directory
+mkdir -p /workspace/personal/artifacts/my-report
+echo '<h1>My Report</h1>' > /workspace/personal/artifacts/my-report/index.html
+
+# Serve it (auto-assigns a free port, creates tunnel)
+artifact serve /workspace/personal/artifacts/my-report --name "my-report"
+# -> https://{agentId}-my-report.lt.desplega.ai
+```
+
+### Programmatic (custom Hono server)
+```typescript
+import { createArtifactServer } from '../artifact-sdk';
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.get('/', (c) => c.html('<h1>Dashboard</h1>'));
+
+const server = createArtifactServer({ name: 'dashboard', app });
+await server.start();
+console.log(`Live at: ${server.url}`);
+```
+
+## CLI Commands
+- `artifact serve <path> --name <name>` — Start serving content
+- `artifact list` — List active artifacts with ports and URLs
+- `artifact stop <name>` — Stop an artifact and close its tunnel
+
+## Multiple Artifacts
+Each artifact gets its own port (auto-assigned) and subdomain. You can serve multiple simultaneously.
+
+## Browser SDK
+HTML artifacts can interact with the swarm API:
+```html
+<script src="/@swarm/sdk.js"></script>
+<script>
+  const swarm = new SwarmSDK();
+  await swarm.createTask({ task: 'Do something' });
+  const agents = await swarm.getSwarm();
+</script>
+```
+
+### Available SDK Methods
+- `createTask(opts)` — Create a new task
+- `getTasks(filters)` — List tasks with optional filters
+- `getTaskDetails(id)` — Get details for a specific task
+- `storeProgress(taskId, data)` — Update task progress
+- `postMessage(opts)` — Post a message to a channel
+- `readMessages(opts)` — Read messages from a channel
+- `getSwarm()` — Get list of agents
+- `listServices()` — List registered services
+- `listEpics(opts)` — List epics
+- `slackReply(opts)` — Reply to a Slack thread
+
+## Auth
+Artifacts are protected by HTTP Basic Auth (username: `hi`, password: API key). Credentials are auto-configured.
+
+## Storage
+Always store artifact content in persisted directories:
+- `/workspace/personal/artifacts/` — per-agent, persists across sessions (default)
+- `/workspace/shared/artifacts/` — shared across swarm
+
+## API Proxy
+The `/@swarm/api/*` proxy forwards requests to the MCP server with proper authentication headers. This allows browser-side JavaScript to call swarm APIs without exposing credentials.
+
+See the `examples/` directory for complete working examples.

package/src/agentmail/app.ts

@@ -0,0 +1,65 @@
+import { Webhook } from "svix";
+
+let initialized = false;
+let webhookSecret: string | null = null;
+
+export function isAgentMailEnabled(): boolean {
+  const disabled = process.env.AGENTMAIL_DISABLE;
+  if (disabled === "true" || disabled === "1") {
+    return false;
+  }
+
+  return !!process.env.AGENTMAIL_WEBHOOK_SECRET;
+}
+
+export function resetAgentMail(): void {
+  initialized = false;
+  webhookSecret = null;
+}
+
+export function initAgentMail(): boolean {
+  if (initialized) {
+    console.log("[AgentMail] Already initialized, skipping");
+    return isAgentMailEnabled();
+  }
+  initialized = true;
+
+  const disabled = process.env.AGENTMAIL_DISABLE;
+  if (disabled === "true" || disabled === "1") {
+    console.log("[AgentMail] Disabled via AGENTMAIL_DISABLE");
+    return false;
+  }
+
+  webhookSecret = process.env.AGENTMAIL_WEBHOOK_SECRET ?? null;
+
+  if (!webhookSecret) {
+    console.log("[AgentMail] Missing AGENTMAIL_WEBHOOK_SECRET, AgentMail integration disabled");
+    return false;
+  }
+
+  console.log("[AgentMail] Webhook handler initialized");
+  return true;
+}
+
+/**
+ * Verify AgentMail webhook signature using Svix
+ * Returns the verified payload on success, null on failure
+ */
+export function verifyAgentMailWebhook(
+  rawBody: string,
+  headers: Record<string, string>,
+): unknown | null {
+  if (!webhookSecret) {
+    console.log("[AgentMail] Signature verification failed: no webhook secret configured");
+    return null;
+  }
+
+  try {
+    const wh = new Webhook(webhookSecret);
+    return wh.verify(rawBody, headers);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.log(`[AgentMail] Signature verification failed: ${message}`);
+    return null;
+  }
+}