@desplega.ai/agent-swarm 1.84.0 → 1.85.0

package/src/http/tasks.ts

@@ -22,6 +22,7 @@ import {
   updateTaskVcs,
 } from "../be/db";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import { createWorkerTaskFollowUp } from "../tasks/worker-follow-up";
 import { telemetry } from "../telemetry";
 import {
   type AgentTaskSource,
@@ -635,6 +636,22 @@ export async function handleTasks(
         filter: ({}, ctx) => ctx.deps.length > 0,
         conditions: [{ timeout_ms: 3_600_000 }], // 1 hour: task running time
       });
+
+      try {
+        const followUp = createWorkerTaskFollowUp({
+          task: result.task,
+          status: parsed.body.status,
+          output: parsed.body.output,
+          failureReason: parsed.body.failureReason,
+        });
+        if (followUp) {
+          console.log(
+            `[tasks.finish] Created follow-up task ${followUp.id.slice(0, 8)} for ${parsed.body.status} task ${parsed.params.id.slice(0, 8)}`,
+          );
+        }
+      } catch (err) {
+        console.warn(`[tasks.finish] Failed to create follow-up task: ${err}`);
+      }
     }
 
     json(res, {

package/src/http/users.ts

@@ -151,7 +151,11 @@ const resolveUnmapped = route({
   params: z.object({ kind: z.string(), externalId: z.string() }),
   body: z.union([
     z.object({ userId: z.string().min(1) }),
-    z.object({ name: z.string().min(1), email: z.string().email() }),
+    z.object({
+      name: z.string().min(1),
+      email: z.string().email().optional(),
+      notes: z.string().optional(),
+    }),
   ]),
   responses: {
     200: { description: "Identity linked + kv entries cleared" },
@@ -322,7 +326,7 @@ const deleteIdentityRoute = route({
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-const UNMAPPED_KINDS = ["slack", "github", "gitlab", "linear"] as const;
+const UNMAPPED_KINDS = ["slack", "github", "gitlab", "linear", "kapso"] as const;
 
 /**
  * Group the two-key-per-identity kv entries (`<externalId>:meta` json +
@@ -477,7 +481,11 @@ export async function handleUsers(
         }
         targetUserId = existing.id;
       } else {
-        const created = createUser({ name: parsed.body.name, email: parsed.body.email });
+        const created = createUser({
+          name: parsed.body.name,
+          email: parsed.body.email,
+          notes: parsed.body.notes,
+        });
         targetUserId = created.id;
       }
       linkIdentity(targetUserId, kind, externalId, actor);

package/src/http/utils.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { getActiveTaskCount } from "../be/db";
+import { scrubSecrets } from "../utils/secret-scrubber";
 
 export function setCorsHeaders(req: IncomingMessage, res: ServerResponse) {
   // Echo the request Origin (rather than emitting `*`) so credentialed fetches
@@ -46,6 +47,22 @@ export function getPathSegments(url: string): string[] {
   return path.split("/").filter(Boolean);
 }
 
+export function safeRequestUrlForLog(rawUrl: string | undefined): string {
+  if (!rawUrl) return "";
+
+  try {
+    const url = new URL(rawUrl, "http://localhost");
+    const params = Array.from(url.searchParams.keys());
+    if (params.length === 0) return url.pathname;
+
+    const redactedQuery = params.map((key) => `${key}=[REDACTED]`).join("&");
+    return `${url.pathname}?${redactedQuery}`;
+  } catch {
+    const pathOnly = rawUrl.split("?")[0] || rawUrl;
+    return scrubSecrets(pathOnly);
+  }
+}
+
 /** Add capacity info to agent response */
 export function agentWithCapacity<T extends { id: string; maxTasks?: number }>(
   agent: T,

package/src/integrations/kapso/inbound.ts

@@ -2,8 +2,13 @@ import { resolveTemplate } from "@/prompts/resolver";
 import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import { workflowEventBus } from "@/workflows/event-bus";
 import "@/tools/templates";
+import { recordUnmappedIdentity } from "@/be/unmapped-identities";
+import { findUserByExternalId } from "@/be/users";
 import { getKapsoNumberMapping, markKapsoMessageSeen } from "./config";
 
+const KAPSO_IDENTITY_KIND = "kapso";
+const WHATSAPP_IDENTITY_KIND = "whatsapp";
+
 /** Minimal shape of the Kapso v2 inbound webhook payload (see the kapso-whatsapp skill). */
 export interface KapsoWebhookPayload {
   message?: {
@@ -50,6 +55,36 @@ function buildTaskDescription(payload: KapsoWebhookPayload): string {
   }).text;
 }
 
+function normalizeKapsoSender(payload: KapsoWebhookPayload): string | null {
+  const raw = payload.message?.from ?? payload.conversation?.phone_number ?? "";
+  const digits = raw.replace(/\D/g, "");
+  return digits || null;
+}
+
+function resolveKapsoRequestedByUserId(payload: KapsoWebhookPayload): string | undefined {
+  const externalId = normalizeKapsoSender(payload);
+  if (!externalId) return undefined;
+
+  const mapped =
+    findUserByExternalId(KAPSO_IDENTITY_KIND, externalId) ??
+    findUserByExternalId(WHATSAPP_IDENTITY_KIND, externalId);
+  if (mapped) return mapped.id;
+
+  recordUnmappedIdentity(KAPSO_IDENTITY_KIND, externalId, {
+    sampleEventType: "kapso.message.received",
+    sampleContext: [
+      payload.conversation?.contact_name ? `contact=${payload.conversation.contact_name}` : null,
+      payload.conversation?.id ? `conversation=${payload.conversation.id}` : null,
+      payload.message?.id ? `message=${payload.message.id}` : null,
+      payload.phone_number_id ? `phone_number_id=${payload.phone_number_id}` : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+  });
+
+  return undefined;
+}
+
 /**
  * Route one inbound Kapso webhook delivery. Pure of HTTP concerns — the caller
  * handles HMAC verification and the workflow-trigger dispatch (which needs the
@@ -104,6 +139,7 @@ export function routeKapsoInbound(payload: KapsoWebhookPayload): KapsoRouting {
     taskType: "kapso-inbound",
     tags: ["kapso-whatsapp", "inbound"],
     priority: 70,
+    requestedByUserId: resolveKapsoRequestedByUserId(payload),
     contextKey: `kapso:conversation:${payload.conversation?.id ?? messageId}`,
   });
 

package/src/oauth/ensure-token.ts

@@ -1,6 +1,18 @@
-import { getOAuthApp, getOAuthTokens, isTokenExpiringSoon } from "../be/db-queries/oauth";
+import {
+  acquireOAuthRefreshLock,
+  getOAuthApp,
+  getOAuthTokens,
+  isTokenExpiringSoon,
+  releaseOAuthRefreshLock,
+} from "../be/db-queries/oauth";
+import type { OAuthTokens } from "../tracker/types";
 import { type OAuthProviderConfig, refreshAccessToken } from "./wrapper";
 
+const refreshLocks = new Map<string, Promise<void>>();
+const REFRESH_LOCK_TTL_MS = 2 * 60 * 1000;
+const REFRESH_LOCK_WAIT_MS = 30 * 1000;
+const REFRESH_LOCK_POLL_MS = 250;
+
 /**
  * Build an OAuthProviderConfig from the oauth_apps table for any provider.
  */
@@ -22,6 +34,41 @@ function getOAuthConfig(provider: string): OAuthProviderConfig | null {
   };
 }
 
+async function withProviderRefreshLock<T>(provider: string, fn: () => Promise<T>): Promise<T> {
+  const previous = refreshLocks.get(provider) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const next = previous.catch(() => undefined).then(() => current);
+  refreshLocks.set(provider, next);
+
+  await previous.catch(() => undefined);
+
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (refreshLocks.get(provider) === next) {
+      refreshLocks.delete(provider);
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function tokenRowChanged(current: OAuthTokens | null, observed: OAuthTokens | null): boolean {
+  if (!observed) return current !== null;
+  if (!current) return true;
+  return (
+    current.accessToken !== observed.accessToken ||
+    current.refreshToken !== observed.refreshToken ||
+    current.expiresAt !== observed.expiresAt
+  );
+}
+
 /**
  * Ensure a valid OAuth token exists for the given provider.
  * If the token is expiring soon, attempt to refresh it.
@@ -57,16 +104,55 @@ export async function ensureToken(provider: string, bufferMs?: number): Promise<
  */
 export async function ensureTokenOrThrow(provider: string, bufferMs?: number): Promise<void> {
   if (!isTokenExpiringSoon(provider, bufferMs)) return;
+  const observedTokens = getOAuthTokens(provider);
 
-  const config = getOAuthConfig(provider);
-  const tokens = getOAuthTokens(provider);
-  if (!config || !tokens?.refreshToken) {
-    console.warn(
-      `[OAuth] ${provider} token expiring but cannot refresh (missing config or refresh token)`,
-    );
-    return;
-  }
+  await withProviderRefreshLock(provider, async () => {
+    const waitStartedAt = Date.now();
+
+    while (isTokenExpiringSoon(provider, bufferMs)) {
+      const tokens = getOAuthTokens(provider);
+      if (tokenRowChanged(tokens, observedTokens)) return;
+
+      const config = getOAuthConfig(provider);
+      if (!config || !tokens?.refreshToken) {
+        console.warn(
+          `[OAuth] ${provider} token expiring but cannot refresh (missing config or refresh token)`,
+        );
+        return;
+      }
+
+      const lockOwner = acquireOAuthRefreshLock(provider, REFRESH_LOCK_TTL_MS);
+      if (!lockOwner) {
+        if (Date.now() - waitStartedAt > REFRESH_LOCK_WAIT_MS) {
+          throw new Error(`Timed out waiting for ${provider} OAuth token refresh lock`);
+        }
+        await sleep(REFRESH_LOCK_POLL_MS);
+        continue;
+      }
+
+      try {
+        const lockedTokens = getOAuthTokens(provider);
+        if (
+          !isTokenExpiringSoon(provider, bufferMs) ||
+          tokenRowChanged(lockedTokens, observedTokens)
+        ) {
+          return;
+        }
+
+        const lockedConfig = getOAuthConfig(provider);
+        if (!lockedConfig || !lockedTokens?.refreshToken) {
+          console.warn(
+            `[OAuth] ${provider} token expiring but cannot refresh (missing config or refresh token)`,
+          );
+          return;
+        }
 
-  await refreshAccessToken(config, tokens.refreshToken);
-  console.log(`[OAuth] ${provider} token refreshed successfully`);
+        await refreshAccessToken(lockedConfig, lockedTokens.refreshToken);
+        console.log(`[OAuth] ${provider} token refreshed successfully`);
+        return;
+      } finally {
+        releaseOAuthRefreshLock(provider, lockOwner);
+      }
+    }
+  });
 }

package/src/prompts/base-prompt.ts

@@ -23,6 +23,13 @@ const BOOTSTRAP_TOTAL_MAX_CHARS = 150_000;
 const truncationNotice = (file: string) =>
   `\n\n[...truncated, see /workspace/${file} for full content]\n`;
 
+export function areSlackPromptToolsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const slackDisable = env.SLACK_DISABLE;
+  if (slackDisable === "true" || slackDisable === "1") return false;
+
+  return Boolean(env.SLACK_BOT_TOKEN && env.SLACK_APP_TOKEN);
+}
+
 export type BasePromptArgs = {
   role: string;
   agentId: string;
@@ -71,9 +78,15 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
   const compositeResult = await resolveTemplateAsync(compositeEventType, vars);
   let prompt = compositeResult.text;
 
+  const slackPromptToolsEnabled = areSlackPromptToolsEnabled();
+
+  if (hasMcp && slackPromptToolsEnabled) {
+    const slackResult = await resolveTemplateAsync("system.agent.slack", {});
+    prompt += slackResult.text;
+  }
+
   // Conditionally inject Slack instructions for workers with Slack-originated tasks
-  // Skip for providers without MCP — they can't call Slack tools (slack-reply, etc.)
-  if (role !== "lead" && args.slackContext && hasMcp) {
+  if (role !== "lead" && args.slackContext && hasMcp && slackPromptToolsEnabled) {
     const slackResult = await resolveTemplateAsync("system.agent.worker.slack", {
       slackChannelId: args.slackContext.channelId,
       slackThreadTs: args.slackContext.threadTs ?? "",

package/src/prompts/session-templates.ts

@@ -59,16 +59,11 @@ As the lead agent, you coordinate all worker agents in the swarm.
 - \`send-task\`: Assign a task to a specific worker or to the general pool. Slack/AgentMail metadata auto-inherits from parent task.
 - \`store-progress\`: Track coordination notes or update task status
 
-**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
-
-**Slack:**
-- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
-- \`slack-read\`: Read thread/channel history (use taskId or channelId)
-- \`slack-list-channels\`: Discover available Slack channels
+**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the task metadata attached to the task.
 
 **Identity:**
 - \`update-profile\`: Update your own or other agents' profile fields (name, role, capabilities, soulMd, identityMd, heartbeatMd, claudeMd, toolsMd, setupScript)
-- \`manage-user\`: Register or update human users (resolve from Slack/GitHub/GitLab identity)
+- \`manage-user\`: Register or update human users (resolve from GitHub/GitLab identity or other source metadata)
 
 #### Task Routing
 
@@ -85,16 +80,14 @@ When composing task descriptions: include the repo URL (if applicable), specific
 For follow-up tasks that should continue from previous work, pass \`parentTaskId\` with the previous task's ID:
 - Worker resumes the parent's Claude session (full conversation context preserved)
 - Child task is auto-routed to the same worker (session data is local)
-- Slack metadata (channelId, threadTs, userId) auto-inherits
 
 If you explicitly assign to a different worker, session resume gracefully falls back to a fresh session.
 
-#### Follow-Up Tasks & Slack
+#### Follow-Up Tasks
 
 When a worker completes or fails a task, you receive an automatic follow-up task. Handle it by:
 1. Review the output/failure reason
-2. If the task has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread
-3. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
+2. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
 
 #### Heartbeat Checklist
 
@@ -106,7 +99,6 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
 
 **Example standing orders:**
 \`\`\`markdown
-- Check Slack for unaddressed requests older than 1 hour
 - Review active tasks for any that seem stuck or need follow-up
 - If idle workers exist and unassigned tasks are available, investigate why
 \`\`\`
@@ -122,6 +114,28 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.slack",
+  header: "",
+  defaultBody: `
+#### Slack Tools
+
+- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
+- \`slack-read\`: Read thread/channel history (use taskId or channelId)
+- \`slack-list-channels\`: Discover available Slack channels
+
+**Slack User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`) with Slack metadata, use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
+
+**Slack context inheritance:** For follow-up tasks using \`parentTaskId\`, Slack metadata (channelId, threadTs, userId) auto-inherits.
+
+**Slack follow-up tasks:** When a worker completes or fails a task that has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread before completing the follow-up task.
+
+**Slack standing orders:** If you maintain heartbeat standing orders, check Slack for unaddressed requests older than 1 hour when appropriate.
+`,
+  variables: [],
+  category: "system",
+});
+
 registerTemplate({
   eventType: "system.agent.worker",
   header: "",

package/src/providers/pi-mono-adapter.ts

@@ -316,6 +316,26 @@ function cleanupAgentsMdSymlink(cwd: string): void {
   }
 }
 
+function extractTextContent(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (c): c is { type?: string; text?: string } =>
+        typeof c === "object" && c !== null && (c as { type?: string }).type === "text",
+    )
+    .map((c) => c.text || "")
+    .join("")
+    .trim();
+}
+
+export function extractPiAssistantText(message: unknown): string {
+  if (!message || typeof message !== "object") return "";
+  const msg = message as { role?: string; content?: unknown };
+  if (msg.role !== "assistant") return "";
+  return extractTextContent(msg.content);
+}
+
 export class PiMonoSession implements ProviderSession {
   private listeners: Array<(event: ProviderEvent) => void> = [];
   private eventQueue: ProviderEvent[] = [];
@@ -327,6 +347,8 @@ export class PiMonoSession implements ProviderSession {
   private logFileHandle: ReturnType<ReturnType<typeof Bun.file>["writer"]>;
   /** Track last emitted message text to avoid duplicates across turns */
   private lastEmittedMessage = "";
+  /** Last assistant text surfaced by pi-mono; used as runner fallback output. */
+  private lastAssistantText = "";
   /** Phase 7: wallclock start so we can populate `durationMs` on the cost row. */
   private sessionStartedAt: number = Date.now();
   /**
@@ -391,31 +413,27 @@ export class PiMonoSession implements ProviderSession {
   private handleAgentEvent(event: AgentSessionEvent): void {
     switch (event.type) {
       case "message_end": {
-        // Extract text from the final message (skip duplicates across turns)
-        const msg = event.message;
-        if (msg && "content" in msg) {
-          const text = Array.isArray(msg.content)
-            ? msg.content
-                .filter((c: unknown) => (c as { type: string }).type === "text")
-                .map((c: unknown) => (c as { text?: string }).text || "")
-                .join("")
-                .trim()
-            : String(msg.content || "").trim();
-          if (text && text !== this.lastEmittedMessage) {
-            const model = this.reportedModel();
-            this.emit({
-              type: "raw_log",
-              content: JSON.stringify({
-                type: "assistant",
-                message: {
-                  role: "assistant",
-                  content: [{ type: "text", text }],
-                  model,
-                },
-              }),
-            });
-            this.lastEmittedMessage = text;
-          }
+        // Pi emits message_end for user, assistant, and tool-result messages.
+        // Only assistant text should be printed or used as fallback output.
+        const text = extractPiAssistantText(event.message);
+        if (text) {
+          this.lastAssistantText = text;
+        }
+        if (text && text !== this.lastEmittedMessage) {
+          const model = this.reportedModel();
+          this.emit({
+            type: "raw_log",
+            content: JSON.stringify({
+              type: "assistant",
+              message: {
+                role: "assistant",
+                content: [{ type: "text", text }],
+                model,
+              },
+            }),
+          });
+          this.emit({ type: "message", role: "assistant", content: text });
+          this.lastEmittedMessage = text;
         }
         // Emit context_usage for dashboard tracking.
         // Phase 7: derive `outputTokens` from `SessionStats` delta (pi-ai's
@@ -522,6 +540,7 @@ export class PiMonoSession implements ProviderSession {
         exitCode: 0,
         sessionId: this._sessionId,
         cost,
+        output: this.lastAssistantText || undefined,
         isError: false,
       };
     } catch (err) {

package/src/server.ts

@@ -43,6 +43,7 @@ import { registerMemoryGetTool } from "./tools/memory-get";
 import { registerMemoryRateTool } from "./tools/memory-rate";
 import { registerMemorySearchTool } from "./tools/memory-search";
 import { registerMyAgentInfoTool } from "./tools/my-agent-info";
+import { registerGetOauthAccessTokenTool } from "./tools/oauth-access-token";
 import { registerPollTaskTool } from "./tools/poll-task";
 import { registerPostMessageTool } from "./tools/post-message";
 // Prompt template tools
@@ -199,6 +200,7 @@ export function createServer() {
 
   // Debug tools - always registered (self-guards with lead check)
   registerDbQueryTool(server);
+  registerGetOauthAccessTokenTool(server);
 
   // Swarm config tools - always registered (config management is fundamental)
   registerSetConfigTool(server);

package/src/tasks/worker-follow-up.ts

@@ -0,0 +1,82 @@
+import { createTaskExtended, getAgentById, getLeadAgent, getTaskAttachments } from "../be/db";
+import { resolveTemplate } from "../prompts/resolver";
+import type { AgentTask, TaskAttachment } from "../types";
+// Side-effect import: registers task lifecycle templates in the in-memory registry.
+import "../tools/templates";
+
+function attachmentPointer(a: TaskAttachment): string {
+  switch (a.kind) {
+    case "url":
+      return a.url ?? "";
+    case "page":
+      return `page:${a.pageId ?? ""}`;
+    case "agent-fs":
+      return `agent-fs:${a.path ?? ""}`;
+    case "shared-fs":
+      return `shared-fs:${a.path ?? ""}`;
+  }
+}
+
+function formatAttachmentsBlock(attachments: TaskAttachment[]): string {
+  if (attachments.length === 0) return "";
+  const lines = attachments.map((a) => {
+    const tag = a.isPrimary ? "[primary] " : "";
+    const intent = a.intent ? ` (intent: ${a.intent})` : "";
+    return `- ${tag}${a.name} - ${attachmentPointer(a)}${intent}`;
+  });
+  return `\n\nAttachments (${attachments.length}):\n${lines.join("\n")}`;
+}
+
+export function createWorkerTaskFollowUp(args: {
+  task: AgentTask;
+  status: "completed" | "failed";
+  output?: string;
+  failureReason?: string;
+}): AgentTask | null {
+  const { task, status, output, failureReason } = args;
+
+  if (task.workflowRunId) return null;
+
+  const taskAgent = getAgentById(task.agentId ?? "");
+  if (!taskAgent || taskAgent.isLead) return null;
+
+  const leadAgent = getLeadAgent();
+  if (!leadAgent) return null;
+
+  const agentName = taskAgent.name || task.agentId?.slice(0, 8) || "Unknown";
+  const taskDesc = task.task.slice(0, 200);
+
+  let followUpDescription: string;
+  if (status === "completed") {
+    const attachmentsBlock = formatAttachmentsBlock(getTaskAttachments(task.id));
+    const outputSummary = output
+      ? `${output.slice(0, 500)}${output.length > 500 ? "..." : ""}${attachmentsBlock}`
+      : `(no output)${attachmentsBlock}`;
+    const completedResult = resolveTemplate("task.worker.completed", {
+      agent_name: agentName,
+      task_desc: taskDesc,
+      output_summary: outputSummary,
+      task_id: task.id,
+    });
+    followUpDescription = completedResult.text;
+  } else {
+    const reason = failureReason || "(no reason given)";
+    const failedResult = resolveTemplate("task.worker.failed", {
+      agent_name: agentName,
+      task_desc: taskDesc,
+      failure_reason: reason,
+      task_id: task.id,
+    });
+    followUpDescription = failedResult.text;
+  }
+
+  return createTaskExtended(followUpDescription, {
+    agentId: leadAgent.id,
+    source: "system",
+    taskType: "follow-up",
+    parentTaskId: task.id,
+    slackChannelId: task.slackChannelId,
+    slackThreadTs: task.slackThreadTs,
+    slackUserId: task.slackUserId,
+  });
+}

package/src/tests/agentmail-sending-skill.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+
+const skillPath = `${import.meta.dir}/../../templates/skills/agentmail-sending/SKILL.md`;
+const skill = await Bun.file(skillPath).text();
+const curlInboxVariable = "$" + "{INBOX}";
+const scriptApiKeyVariable = "$" + "{apiKey}";
+
+function requireMatch(pattern: RegExp, label: string): RegExpMatchArray {
+  const match = skill.match(pattern);
+  if (!match) {
+    throw new Error(`Missing ${label}`);
+  }
+  return match;
+}
+
+describe("agentmail-sending skill template", () => {
+  test("pins the canonical base URL and rejects the hallucinated host", () => {
+    expect(skill).toContain("```text\nhttps://api.agentmail.to/v0/\n```");
+    expect(skill).toContain("DO NOT use `api.agentmail.ai`");
+    expect(skill).not.toContain("https://api.agentmail.ai");
+  });
+
+  test("pins send-message field names and text-only guidance", () => {
+    expect(skill).toContain("```text\nto\nbcc\nsubject\ntext\n```");
+    expect(skill).toContain("Use `text`, NOT `text_body`, `body`, or `content`.");
+    expect(skill).toContain("Do NOT pass `html`.");
+  });
+
+  test("curl example uses the canonical endpoint, bearer auth, and exact JSON fields", () => {
+    expect(skill).toContain("https://api.agentmail.to/v0/inboxes/{inbox}/messages/send");
+    expect(skill).toContain(
+      [
+        'curl -sS -X POST "https://api.agentmail.to/v0/inboxes/',
+        curlInboxVariable,
+        '/messages/send"',
+      ].join(""),
+    );
+    expect(skill).toContain('-H "Authorization: Bearer $AGENTMAIL_API_KEY"');
+
+    const jsonBlock = requireMatch(
+      /--data-binary @- <<'JSON'\n([\s\S]*?)\nJSON/,
+      "curl JSON body",
+    )[1];
+    const payload = JSON.parse(jsonBlock);
+
+    expect(Object.keys(payload)).toEqual(["to", "bcc", "subject", "text"]);
+    expect(payload).not.toHaveProperty("text_body");
+    expect(payload).not.toHaveProperty("body");
+    expect(payload).not.toHaveProperty("content");
+    expect(payload).not.toHaveProperty("html");
+  });
+
+  test("script_upsert example uses fetch and resolves AGENTMAIL_API_KEY from swarm config", () => {
+    const scriptBlock = requireMatch(/```ts\n([\s\S]*?)\n```/, "script_upsert example")[1];
+
+    expect(scriptBlock).toContain("await script_upsert({");
+    expect(scriptBlock).toContain("ctx.swarm.config.get('AGENTMAIL_API_KEY')");
+    expect(scriptBlock).toContain("ctx.stdlib.fetch(");
+    expect(scriptBlock).toContain("https://api.agentmail.to/v0/inboxes/");
+    expect(scriptBlock).toContain("messages/send");
+    expect(scriptBlock).toContain(
+      ["Authorization: \\`Bearer \\", scriptApiKeyVariable, "\\`"].join(""),
+    );
+    expect(scriptBlock).toContain("text: args.text");
+    expect(scriptBlock).not.toContain("text_body");
+    expect(scriptBlock).not.toContain("html:");
+  });
+
+  test("common error table covers known AgentMail mistakes", () => {
+    expect(skill).toContain("404 on `/v0/inboxes/.../send`");
+    expect(skill).toContain('422 `{"detail":"text Field required"}`');
+    expect(skill).toContain("401");
+    expect(skill).toContain("HTML rendering bug");
+  });
+});