@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/agentmail/handlers.ts

@@ -0,0 +1,262 @@
+import {
+  createTaskExtended,
+  findTaskByAgentMailThread,
+  getAgentById,
+  getAgentMailInboxMapping,
+  getAllAgents,
+} from "../be/db";
+import { resolveTemplate } from "../prompts/resolver";
+import { workflowEventBus } from "../workflows/event-bus";
+// Side-effect import: registers all AgentMail event templates in the in-memory registry
+import "./templates";
+import type { AgentMailMessage, AgentMailWebhookPayload } from "./types";
+
+/**
+ * Check if an inbox domain is allowed by the filter.
+ * Returns true if no filter is set or the inbox domain matches.
+ */
+export function isInboxAllowed(inboxId: string, filter: string | undefined): boolean {
+  if (!filter) return true;
+  const allowedDomains = filter.split(",").map((d) => d.trim().toLowerCase());
+  const inboxDomain = inboxId.split("@")[1]?.toLowerCase();
+  return !!inboxDomain && allowedDomains.includes(inboxDomain);
+}
+
+/**
+ * Check if a sender domain is allowed by the filter.
+ * Returns true if no filter is set or at least one sender domain matches.
+ */
+export function isSenderAllowed(
+  from: AgentMailMessage["from_"],
+  filter: string | undefined,
+): boolean {
+  if (!filter) return true;
+  const allowedDomains = filter.split(",").map((d) => d.trim().toLowerCase());
+  const fromAddresses = Array.isArray(from) ? from : [from || ""];
+  return fromAddresses.some((addr) => {
+    const emailMatch = addr.match(/<([^>]+)>/);
+    const email = emailMatch?.[1] ?? addr;
+    const domain = email.split("@")[1]?.toLowerCase();
+    return !!domain && allowedDomains.includes(domain);
+  });
+}
+
+// Simple deduplication cache (60 second TTL)
+const processedEvents = new Map<string, number>();
+const EVENT_TTL = 60_000;
+
+function isDuplicate(eventKey: string): boolean {
+  const now = Date.now();
+
+  // Clean old entries
+  for (const [key, timestamp] of processedEvents) {
+    if (now - timestamp > EVENT_TTL) {
+      processedEvents.delete(key);
+    }
+  }
+
+  if (processedEvents.has(eventKey)) {
+    return true;
+  }
+
+  processedEvents.set(eventKey, now);
+  return false;
+}
+
+/**
+ * Find the lead agent to receive AgentMail messages when no inbox mapping exists
+ */
+function findLeadAgent() {
+  const agents = getAllAgents();
+  const onlineLead = agents.find((a) => a.isLead && a.status !== "offline");
+  if (onlineLead) return onlineLead;
+  return agents.find((a) => a.isLead) ?? null;
+}
+
+/**
+ * Handle message.received webhook event
+ */
+export async function handleMessageReceived(
+  payload: AgentMailWebhookPayload,
+): Promise<{ created: boolean; taskId?: string }> {
+  const message = payload.message;
+  if (!message) {
+    console.log("[AgentMail] message.received event missing message payload");
+    return { created: false };
+  }
+
+  // Deduplicate using event_id
+  if (isDuplicate(`agentmail:${payload.event_id}`)) {
+    console.log(`[AgentMail] Duplicate event ${payload.event_id}, skipping`);
+    return { created: false };
+  }
+
+  const { inbox_id, thread_id, message_id } = message;
+  const from =
+    (Array.isArray(message.from_) ? message.from_.join(", ") : message.from_) || "unknown";
+  const subject = message.subject || "(no subject)";
+  const body = message.text || message.html || "";
+  const preview = body.length > 500 ? `${body.substring(0, 500)}...` : body;
+
+  // Emit workflow trigger event
+  workflowEventBus.emit("agentmail.message.received", {
+    inboxId: inbox_id,
+    from,
+    subject,
+    body: preview,
+    threadId: thread_id,
+    messageId: message_id,
+  });
+
+  // Check for thread continuity - find existing task for this thread
+  const existingTask = findTaskByAgentMailThread(thread_id);
+  if (existingTask) {
+    // Create a follow-up task with parentTaskId to continue the session
+    const followupResult = resolveTemplate("agentmail.email.followup", {
+      from,
+      subject,
+      inbox_id,
+      thread_id,
+      preview,
+    });
+
+    if (followupResult.skipped) {
+      return { created: false };
+    }
+
+    const task = createTaskExtended(followupResult.text, {
+      agentId: existingTask.agentId,
+      source: "agentmail",
+      taskType: "agentmail-reply",
+      agentmailInboxId: inbox_id,
+      agentmailMessageId: message_id,
+      agentmailThreadId: thread_id,
+      parentTaskId: existingTask.id,
+    });
+
+    console.log(
+      `[AgentMail] Created follow-up task ${task.id} for thread ${thread_id} (parent: ${existingTask.id})`,
+    );
+    return { created: true, taskId: task.id };
+  }
+
+  // Look up agent from inbox mapping
+  const mapping = getAgentMailInboxMapping(inbox_id);
+
+  if (mapping) {
+    const agent = getAgentById(mapping.agentId);
+    if (agent) {
+      if (agent.isLead) {
+        // Route to lead as task
+        const leadResult = resolveTemplate("agentmail.email.mapped_lead", {
+          from,
+          subject,
+          inbox_id,
+          thread_id,
+          message_id,
+          preview,
+        });
+
+        if (leadResult.skipped) {
+          return { created: false };
+        }
+
+        const task = createTaskExtended(leadResult.text, {
+          agentId: agent.id,
+          source: "agentmail",
+          taskType: "agentmail-message",
+          agentmailInboxId: inbox_id,
+          agentmailMessageId: message_id,
+          agentmailThreadId: thread_id,
+        });
+
+        console.log(
+          `[AgentMail] Created task ${task.id} for lead ${agent.name} (inbox: ${inbox_id})`,
+        );
+        return { created: true, taskId: task.id };
+      }
+
+      // Route to worker as task
+      const workerResult = resolveTemplate("agentmail.email.mapped_worker", {
+        from,
+        subject,
+        inbox_id,
+        thread_id,
+        preview,
+      });
+
+      if (workerResult.skipped) {
+        return { created: false };
+      }
+
+      const task = createTaskExtended(workerResult.text, {
+        agentId: agent.id,
+        source: "agentmail",
+        taskType: "agentmail-message",
+        agentmailInboxId: inbox_id,
+        agentmailMessageId: message_id,
+        agentmailThreadId: thread_id,
+      });
+
+      console.log(
+        `[AgentMail] Created task ${task.id} for worker ${agent.name} (inbox: ${inbox_id})`,
+      );
+      return { created: true, taskId: task.id };
+    }
+  }
+
+  // No mapping found - route to lead as task
+  const lead = findLeadAgent();
+  if (lead) {
+    const unmappedResult = resolveTemplate("agentmail.email.unmapped", {
+      from,
+      subject,
+      inbox_id,
+      thread_id,
+      message_id,
+      preview,
+    });
+
+    if (unmappedResult.skipped) {
+      return { created: false };
+    }
+
+    const task = createTaskExtended(unmappedResult.text, {
+      agentId: lead.id,
+      source: "agentmail",
+      taskType: "agentmail-message",
+      agentmailInboxId: inbox_id,
+      agentmailMessageId: message_id,
+      agentmailThreadId: thread_id,
+    });
+
+    console.log(
+      `[AgentMail] Created task ${task.id} for lead ${lead.name} (unmapped inbox: ${inbox_id})`,
+    );
+    return { created: true, taskId: task.id };
+  }
+
+  // No lead available - create unassigned task
+  const noAgentResult = resolveTemplate("agentmail.email.no_agent", {
+    from,
+    subject,
+    inbox_id,
+    thread_id,
+    preview,
+  });
+
+  if (noAgentResult.skipped) {
+    return { created: false };
+  }
+
+  const task = createTaskExtended(noAgentResult.text, {
+    source: "agentmail",
+    taskType: "agentmail-message",
+    agentmailInboxId: inbox_id,
+    agentmailMessageId: message_id,
+    agentmailThreadId: thread_id,
+  });
+
+  console.log(`[AgentMail] Created unassigned task ${task.id} (no lead or mapping available)`);
+  return { created: true, taskId: task.id };
+}

package/src/agentmail/index.ts

@@ -0,0 +1,9 @@
+// AgentMail Integration
+export { initAgentMail, isAgentMailEnabled, resetAgentMail, verifyAgentMailWebhook } from "./app";
+export { handleMessageReceived, isInboxAllowed, isSenderAllowed } from "./handlers";
+export type {
+  AgentMailAttachment,
+  AgentMailEventType,
+  AgentMailMessage,
+  AgentMailWebhookPayload,
+} from "./types";

package/src/agentmail/templates.ts

@@ -0,0 +1,111 @@
+/**
+ * AgentMail event prompt template definitions.
+ *
+ * Each template is registered at module load time via registerTemplate().
+ * Handlers import this module for the side-effect of registration.
+ */
+
+import { registerTemplate } from "../prompts/registry";
+
+// ============================================================================
+// Email events
+// ============================================================================
+
+registerTemplate({
+  eventType: "agentmail.email.followup",
+  header: "[AgentMail] Follow-up email in thread",
+  defaultBody: `From: {{from}}
+Subject: {{subject}}
+Inbox: {{inbox_id}}
+Thread: {{thread_id}}
+
+{{preview}}`,
+  variables: [
+    { name: "from", description: "Sender address(es)" },
+    { name: "subject", description: "Email subject" },
+    { name: "inbox_id", description: "AgentMail inbox ID" },
+    { name: "thread_id", description: "AgentMail thread ID" },
+    { name: "preview", description: "Email body preview (truncated to 500 chars)" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "agentmail.email.mapped_lead",
+  header: "[AgentMail] New email received",
+  defaultBody: `From: {{from}}
+Subject: {{subject}}
+Inbox: {{inbox_id}}
+Thread: {{thread_id}}
+Message: {{message_id}}
+
+{{preview}}`,
+  variables: [
+    { name: "from", description: "Sender address(es)" },
+    { name: "subject", description: "Email subject" },
+    { name: "inbox_id", description: "AgentMail inbox ID" },
+    { name: "thread_id", description: "AgentMail thread ID" },
+    { name: "message_id", description: "AgentMail message ID" },
+    { name: "preview", description: "Email body preview (truncated to 500 chars)" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "agentmail.email.mapped_worker",
+  header: "[AgentMail] New email received",
+  defaultBody: `From: {{from}}
+Subject: {{subject}}
+Inbox: {{inbox_id}}
+Thread: {{thread_id}}
+
+{{preview}}`,
+  variables: [
+    { name: "from", description: "Sender address(es)" },
+    { name: "subject", description: "Email subject" },
+    { name: "inbox_id", description: "AgentMail inbox ID" },
+    { name: "thread_id", description: "AgentMail thread ID" },
+    { name: "preview", description: "Email body preview (truncated to 500 chars)" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "agentmail.email.unmapped",
+  header: "[AgentMail] New email received (unmapped inbox)",
+  defaultBody: `From: {{from}}
+Subject: {{subject}}
+Inbox: {{inbox_id}}
+Thread: {{thread_id}}
+Message: {{message_id}}
+
+{{preview}}`,
+  variables: [
+    { name: "from", description: "Sender address(es)" },
+    { name: "subject", description: "Email subject" },
+    { name: "inbox_id", description: "AgentMail inbox ID" },
+    { name: "thread_id", description: "AgentMail thread ID" },
+    { name: "message_id", description: "AgentMail message ID" },
+    { name: "preview", description: "Email body preview (truncated to 500 chars)" },
+  ],
+  category: "event",
+});
+
+registerTemplate({
+  eventType: "agentmail.email.no_agent",
+  header: "[AgentMail] New email received (no agent available)",
+  defaultBody: `From: {{from}}
+Subject: {{subject}}
+Inbox: {{inbox_id}}
+Thread: {{thread_id}}
+
+{{preview}}`,
+  variables: [
+    { name: "from", description: "Sender address(es)" },
+    { name: "subject", description: "Email subject" },
+    { name: "inbox_id", description: "AgentMail inbox ID" },
+    { name: "thread_id", description: "AgentMail thread ID" },
+    { name: "preview", description: "Email body preview (truncated to 500 chars)" },
+  ],
+  category: "event",
+});

package/src/agentmail/types.ts

@@ -0,0 +1,51 @@
+/**
+ * AgentMail webhook payload types
+ * Based on Svix delivery format used by AgentMail
+ */
+
+export interface AgentMailAttachment {
+  attachment_id: string;
+  filename: string;
+  content_type: string;
+  size: number;
+  inline: boolean;
+}
+
+export interface AgentMailMessage {
+  message_id: string;
+  thread_id: string;
+  inbox_id: string;
+  organization_id: string;
+  from_: string | string[];
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  reply_to: string[];
+  subject: string;
+  preview: string;
+  text: string | null;
+  html: string | null;
+  labels: string[];
+  attachments: AgentMailAttachment[];
+  in_reply_to: string | null;
+  references: string[];
+  timestamp: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface AgentMailWebhookPayload {
+  type: "event";
+  event_type: AgentMailEventType;
+  event_id: string;
+  message?: AgentMailMessage;
+}
+
+export type AgentMailEventType =
+  | "message.received"
+  | "message.sent"
+  | "message.delivered"
+  | "message.bounced"
+  | "message.complained"
+  | "message.rejected"
+  | "domain.verified";

package/src/artifact-sdk/browser-sdk.ts

@@ -0,0 +1,30 @@
+// This is a string template that gets served as JavaScript to the browser
+export const BROWSER_SDK_JS = `
+class SwarmSDK {
+  constructor() {
+    this._configPromise = fetch('/@swarm/config').then(r => r.json());
+  }
+
+  async createTask(opts) { return this._post('/@swarm/api/tasks', opts); }
+  async getTasks(filters) { return this._get('/@swarm/api/tasks?' + new URLSearchParams(filters)); }
+  async getTaskDetails(id) { return this._get('/@swarm/api/tasks/' + id); }
+  async storeProgress(taskId, data) { return this._post('/@swarm/api/tasks/' + taskId + '/progress', data); }
+  async postMessage(opts) { return this._post('/@swarm/api/messages', opts); }
+  async readMessages(opts) { return this._get('/@swarm/api/messages?' + new URLSearchParams(opts)); }
+  async getSwarm() { return this._get('/@swarm/api/agents'); }
+  async listServices() { return this._get('/@swarm/api/services'); }
+  async listEpics(opts) { return this._get('/@swarm/api/epics?' + new URLSearchParams(opts || {})); }
+  async slackReply(opts) { return this._post('/@swarm/api/slack/reply', opts); }
+
+  async _post(url, body) {
+    const res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+    return res.json();
+  }
+  async _get(url) {
+    const res = await fetch(url);
+    return res.json();
+  }
+}
+
+window.SwarmSDK = SwarmSDK;
+`;

package/src/artifact-sdk/index.ts

@@ -0,0 +1,2 @@
+export type { ArtifactServer, ArtifactServerOptions } from "./server";
+export { createArtifactServer } from "./server";

package/src/artifact-sdk/localtunnel.d.ts

@@ -0,0 +1,20 @@
+declare module "@desplega.ai/localtunnel" {
+  interface TunnelOptions {
+    port: number;
+    subdomain?: string;
+    host?: string;
+    auth?: string;
+    username?: string;
+    local_host?: string;
+  }
+
+  interface Tunnel {
+    url: string;
+    close(): void;
+    on(event: "close", listener: () => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+  }
+
+  function localtunnel(opts: TunnelOptions): Promise<Tunnel>;
+  export default localtunnel;
+}

package/src/artifact-sdk/port.ts

@@ -0,0 +1,12 @@
+import { createServer } from "node:net";
+
+export async function getAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, () => {
+      const { port } = server.address() as { port: number };
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}

package/src/artifact-sdk/server.ts

@@ -0,0 +1,156 @@
+import { Hono } from "hono";
+import { serveStatic } from "hono/bun";
+import { BROWSER_SDK_JS } from "./browser-sdk";
+import { getAvailablePort } from "./port";
+import { createTunnel } from "./tunnel";
+
+export interface ArtifactServerOptions {
+  name: string;
+  static?: string;
+  app?: Hono;
+  port?: number;
+  auth?: boolean;
+  subdomain?: string;
+}
+
+export interface ArtifactServer {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  url: string;
+  port: number;
+  tunnel: ReturnType<typeof createTunnel> extends Promise<infer T> ? T | null : never;
+}
+
+export function createArtifactServer(opts: ArtifactServerOptions): ArtifactServer {
+  const agentId = process.env.AGENT_ID || "unknown";
+  const apiKey = process.env.API_KEY || "";
+  const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+
+  const app = new Hono();
+
+  // Inject swarm middleware
+  app.get("/@swarm/sdk.js", (c) => {
+    c.header("Content-Type", "application/javascript");
+    return c.body(BROWSER_SDK_JS);
+  });
+
+  app.get("/@swarm/config", (c) => {
+    return c.json({ agentId, artifactName: opts.name });
+  });
+
+  // API proxy — forwards /@swarm/api/* to MCP server
+  app.all("/@swarm/api/*", async (c) => {
+    const path = c.req.path.replace("/@swarm/api", "/api");
+    const targetUrl = `${mcpBaseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${apiKey}`,
+      "X-Agent-ID": agentId,
+    };
+    if (c.req.method !== "GET") {
+      headers["Content-Type"] = "application/json";
+    }
+    try {
+      const res = await fetch(targetUrl, {
+        method: c.req.method,
+        headers,
+        body: c.req.method !== "GET" ? await c.req.text() : undefined,
+      });
+      return new Response(res.body, {
+        status: res.status,
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type",
+        },
+      });
+    } catch (e) {
+      return c.json({ error: "Proxy error", message: String(e) }, 502);
+    }
+  });
+
+  // CORS preflight
+  app.options("/@swarm/api/*", (_c) => {
+    return new Response(null, {
+      status: 204,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type",
+      },
+    });
+  });
+
+  // User app or static serving
+  if (opts.app) {
+    app.route("/", opts.app);
+  } else if (opts.static) {
+    app.use("/*", serveStatic({ root: opts.static }));
+  }
+
+  let server: ReturnType<typeof Bun.serve> | null = null;
+  // biome-ignore lint/suspicious/noExplicitAny: localtunnel tunnel type
+  let tunnel: any = null;
+  let actualPort = 0;
+
+  const artifact: ArtifactServer = {
+    url: "",
+    port: 0,
+    tunnel: null,
+
+    async start() {
+      actualPort = opts.port || (await getAvailablePort());
+      server = Bun.serve({ port: actualPort, fetch: app.fetch });
+      artifact.port = actualPort;
+
+      const subdomain = opts.subdomain || `${agentId}-${opts.name}`;
+      const authPassword = opts.auth === false ? undefined : apiKey;
+
+      tunnel = await createTunnel({
+        port: actualPort,
+        subdomain,
+        auth: authPassword,
+      });
+
+      artifact.url = tunnel.url;
+      artifact.tunnel = tunnel;
+
+      // Register in service registry
+      try {
+        await fetch(`${mcpBaseUrl}/api/services`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "X-Agent-ID": agentId,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            script: `artifact-${opts.name}`,
+            metadata: {
+              type: "artifact",
+              artifactName: opts.name,
+              port: actualPort,
+              publicUrl: tunnel.url,
+            },
+          }),
+        });
+      } catch (e) {
+        console.warn("Failed to register artifact in service registry:", e);
+      }
+
+      console.log(`Artifact "${opts.name}" live at ${tunnel.url} (port ${actualPort})`);
+    },
+
+    async stop() {
+      if (tunnel) {
+        tunnel.close();
+        tunnel = null;
+      }
+      if (server) {
+        server.stop();
+        server = null;
+      }
+    },
+  };
+
+  return artifact;
+}

package/src/artifact-sdk/tunnel.ts

@@ -0,0 +1,19 @@
+import localtunnel from "@desplega.ai/localtunnel";
+
+interface TunnelOptions {
+  port: number;
+  subdomain: string;
+  auth?: string;
+  username?: string;
+}
+
+export async function createTunnel(opts: TunnelOptions) {
+  const tunnel = await localtunnel({
+    port: opts.port,
+    subdomain: opts.subdomain,
+    auth: opts.auth,
+    username: opts.username || "hi", // default "hi" for MVP (custom username deferred)
+    // host defaults to lt.desplega.ai in our fork
+  });
+  return tunnel;
+}