@desplega.ai/agent-swarm 1.83.1 → 1.84.0

package/src/tools/task-tool-ctx.ts

@@ -0,0 +1,43 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AgentTask, User } from "@/types";
+import type { RequestInfo } from "./utils";
+
+export type ToolCtx =
+  | { kind: "owner"; agentId?: string; sourceTaskId?: string; sessionId?: string }
+  | { kind: "user"; userId: string; user: User; sessionId?: string };
+
+export function ownerCtx(info: RequestInfo): ToolCtx {
+  return {
+    kind: "owner",
+    agentId: info.agentId,
+    sourceTaskId: info.sourceTaskId,
+    sessionId: info.sessionId,
+  };
+}
+
+export function userCtx(user: User, sessionId?: string): ToolCtx {
+  return {
+    kind: "user",
+    userId: user.id,
+    user,
+    sessionId,
+  };
+}
+
+export function assertOwnsTask(ctx: ToolCtx, task: AgentTask): CallToolResult | null {
+  if (ctx.kind === "owner" || task.requestedByUserId === ctx.userId) {
+    return null;
+  }
+
+  const message = `Forbidden: this task is not yours (task ${task.id}).`;
+  // RBAC chokepoint — a future admin/role tier widens visibility here, in this one function.
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }],
+    structuredContent: {
+      success: false,
+      code: "forbidden",
+      message,
+    },
+  };
+}

package/src/tools/templates.ts

@@ -7,6 +7,41 @@
 
 import { registerTemplate } from "../prompts/registry";
 
+// ============================================================================
+// Kapso/WhatsApp inbound (native handler creates a kapso-inbound task)
+// ============================================================================
+
+registerTemplate({
+  eventType: "kapso.message.received",
+  header: "",
+  defaultBody: `# WhatsApp inbound (Kapso)
+
+A Kapso webhook fired on the swarm's provisioned WhatsApp number. Load the \`kapso-whatsapp\` skill, then triage this like any other interaction and reply on WhatsApp by quote-replying the inbound WAMID (\`context.message_id\`).
+
+## Source: WhatsApp (Kapso)
+- conversation_id: {{conversation_id}}
+- inbound_wamid: {{inbound_wamid}}
+- sender_phone: {{sender_phone}}
+- contact_name: {{contact_name}}
+- phone_number_id: {{phone_number_id}}{{test_note}}
+
+## Message
+{{message_text}}`,
+  variables: [
+    { name: "conversation_id", description: "Kapso conversation id, or 'unknown'" },
+    { name: "inbound_wamid", description: "Inbound message WAMID, or 'unknown'" },
+    { name: "sender_phone", description: "Sender phone (E.164 no +), or 'unknown'" },
+    { name: "contact_name", description: "Contact display name, or 'unknown'" },
+    { name: "phone_number_id", description: "Provisioned phone-number id, or 'unknown'" },
+    {
+      name: "test_note",
+      description: "Appended note when the payload is a Kapso test delivery (else empty)",
+    },
+    { name: "message_text", description: "Inbound message text or a non-text placeholder" },
+  ],
+  category: "event",
+});
+
 // ============================================================================
 // Worker task follow-ups (created by store-progress for the lead)
 // ============================================================================

package/src/tools/tool-config.ts

@@ -98,6 +98,12 @@ export const DEFERRED_TOOLS = new Set([
   // AgentMail (1)
   "register-agentmail-inbox",
 
+  // Kapso/WhatsApp (4)
+  "register-kapso-number",
+  "unregister-kapso-number",
+  "send-whatsapp-message",
+  "reply-whatsapp-message",
+
   // Tracker (6)
   "tracker-status",
   "tracker-link-task",

package/src/tools/whatsapp-message.ts

@@ -0,0 +1,135 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { sendKapsoText } from "@/integrations/kapso/client";
+import { getKapsoConfig } from "@/integrations/kapso/config";
+import { createToolRegistrar } from "@/tools/utils";
+
+/** Shared structured-error message for the 24h session-window case. */
+const SESSION_WINDOW_HINT =
+  'Outside the 24h WhatsApp session window — free-form text is rejected. Use a pre-approved template message (see the `kapso-whatsapp` skill, "Send a template").';
+
+const outputSchema = z.object({
+  yourAgentId: z.string().uuid().optional(),
+  success: z.boolean(),
+  message: z.string(),
+  messageId: z.string().optional(),
+  sessionWindowExpired: z.boolean().optional(),
+});
+
+export const registerSendWhatsappMessageTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "send-whatsapp-message",
+    {
+      title: "Send WhatsApp Message",
+      annotations: { openWorldHint: true },
+      description:
+        "Send a free-form WhatsApp text via Kapso (within the 24h session window). Thin wrapper over the Kapso Meta-proxy send. For templates/media/reactions use the `kapso-whatsapp` skill. If the recipient is outside the 24h window the call returns a structured error pointing at the template path.",
+      inputSchema: z.object({
+        phoneNumberId: z
+          .string()
+          .min(1)
+          .describe("The swarm's Kapso/Meta phone-number ID to send from (KAPSO_PHONE_NUMBER_ID)."),
+        to: z
+          .string()
+          .min(1)
+          .describe("Recipient phone in E.164 WITHOUT '+' (e.g. '15551234567')."),
+        body: z.string().min(1).describe("Message text."),
+        previewUrl: z
+          .boolean()
+          .optional()
+          .describe("Render a link preview for URLs in the body (default false)."),
+      }),
+      outputSchema,
+    },
+    async ({ phoneNumberId, to, body, previewUrl }, requestInfo) => {
+      return sendAndFormat({ phoneNumberId, to, body, previewUrl }, requestInfo.agentId, undefined);
+    },
+  );
+};
+
+export const registerReplyWhatsappMessageTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "reply-whatsapp-message",
+    {
+      title: "Reply to WhatsApp Message",
+      annotations: { openWorldHint: true },
+      description:
+        "Quote-reply a WhatsApp message via Kapso — same as send-whatsapp-message but threads to a specific inbound WAMID via context.message_id. Recipient is inferred from the conversation; pass the original sender's phone as `to`.",
+      inputSchema: z.object({
+        phoneNumberId: z
+          .string()
+          .min(1)
+          .describe("The swarm's Kapso/Meta phone-number ID to send from (KAPSO_PHONE_NUMBER_ID)."),
+        to: z.string().min(1).describe("Recipient phone in E.164 WITHOUT '+'."),
+        inReplyTo: z
+          .string()
+          .min(1)
+          .describe("The inbound WAMID to quote-reply (set as context.message_id)."),
+        body: z.string().min(1).describe("Reply text."),
+      }),
+      outputSchema,
+    },
+    async ({ phoneNumberId, to, inReplyTo, body }, requestInfo) => {
+      return sendAndFormat({ phoneNumberId, to, body }, requestInfo.agentId, inReplyTo);
+    },
+  );
+};
+
+async function sendAndFormat(
+  params: { phoneNumberId: string; to: string; body: string; previewUrl?: boolean },
+  agentId: string | undefined,
+  contextMessageId: string | undefined,
+) {
+  try {
+    const config = getKapsoConfig();
+    if (!config.apiKey) {
+      const msg = "KAPSO_API_KEY is not configured in swarm config.";
+      return {
+        content: [{ type: "text" as const, text: msg }],
+        structuredContent: { yourAgentId: agentId, success: false, message: msg },
+      };
+    }
+
+    const result = await sendKapsoText({
+      apiBaseUrl: config.apiBaseUrl,
+      apiKey: config.apiKey,
+      phoneNumberId: params.phoneNumberId,
+      to: params.to,
+      body: params.body,
+      previewUrl: params.previewUrl,
+      contextMessageId,
+    });
+
+    if (result.ok) {
+      const text = `Sent WhatsApp message to ${params.to} (wamid ${result.messageId ?? "unknown"})`;
+      return {
+        content: [{ type: "text" as const, text }],
+        structuredContent: {
+          yourAgentId: agentId,
+          success: true,
+          message: text,
+          messageId: result.messageId,
+        },
+      };
+    }
+
+    const text = result.sessionWindowExpired
+      ? `${SESSION_WINDOW_HINT} (Kapso: ${result.errorMessage})`
+      : `Kapso send failed: ${result.errorMessage}`;
+    return {
+      content: [{ type: "text" as const, text }],
+      structuredContent: {
+        yourAgentId: agentId,
+        success: false,
+        message: text,
+        sessionWindowExpired: result.sessionWindowExpired,
+      },
+    };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text" as const, text: `Error: ${errorMessage}` }],
+      structuredContent: { yourAgentId: agentId, success: false, message: errorMessage },
+    };
+  }
+}

package/src/types.ts

@@ -1682,7 +1682,7 @@ export type ContextSnapshot = z.infer<typeof ContextSnapshotSchema>;
 // effective_from <= now" lookup is a pure integer comparison. Matches the
 // SQL columns in migration 046_budgets_and_pricing.sql verbatim.
 
-export const BudgetScopeSchema = z.enum(["global", "agent"]);
+export const BudgetScopeSchema = z.enum(["global", "agent", "user"]);
 export type BudgetScope = z.infer<typeof BudgetScopeSchema>;
 
 export const BudgetSchema = z.object({
@@ -1730,7 +1730,7 @@ export const PricingRowSchema = z.object({
 });
 export type PricingRow = z.infer<typeof PricingRowSchema>;
 
-export const BudgetRefusalCauseSchema = z.enum(["agent", "global"]);
+export const BudgetRefusalCauseSchema = z.enum(["agent", "global", "user"]);
 export type BudgetRefusalCause = z.infer<typeof BudgetRefusalCauseSchema>;
 
 export const BudgetRefusalNotificationSchema = z.object({
@@ -1742,6 +1742,8 @@ export const BudgetRefusalNotificationSchema = z.object({
   agentBudgetUsd: z.number().nullable().optional(),
   globalSpendUsd: z.number().nullable().optional(),
   globalBudgetUsd: z.number().nullable().optional(),
+  userSpendUsd: z.number().nullable().optional(),
+  userBudgetUsd: z.number().nullable().optional(),
   followUpTaskId: z.string().nullable().optional(),
   createdAt: z.number(), // epoch ms
 });
@@ -1761,6 +1763,8 @@ export const BudgetRefusedTriggerSchema = z.object({
   agentBudget: z.number().optional(),
   globalSpend: z.number().optional(),
   globalBudget: z.number().optional(),
+  userSpend: z.number().optional(),
+  userBudget: z.number().optional(),
   resetAt: z.string(), // ISO 8601, next UTC midnight
 });
 export type BudgetRefusedTrigger = z.infer<typeof BudgetRefusedTriggerSchema>;

package/src/utils/error-tracker.ts

@@ -11,13 +11,34 @@ export interface ErrorSignal {
 }
 
 /**
- * Clamps a candidate reset timestamp (ms) to [now+60s, now+6h].
+ * Maximum cooldown horizon for a rate-limit reset. A weekly OAuth limit resets
+ * up to ~7 days out, so the cap must be at least that or a weekly-limited key
+ * gets re-clamped to a short cooldown and re-handed to a worker every few hours
+ * (the fail-every-6h sawtooth). 7d still guards against absurd far-future
+ * (malformed) values.
+ */
+export const MAX_RATE_LIMIT_RESET_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Single source of truth for "does this text look like a rate-limit signal?".
+ * Shared by the runner's cooldown gate and {@link parseStderrForErrors} so the
+ * two matchers can't drift. Tolerates a qualifier between "your" and "limit"
+ * (weekly / 5-hour / daily): matches "hit your weekly limit", "hit your 5-hour
+ * limit", "hit your limit", "Claude usage limit reached", "rate limit exceeded",
+ * "429 Too Many Requests"; does not match "No conversation found with session ID".
+ */
+export function isRateLimitMessage(s: string): boolean {
+  return /rate.?limit|hit your[\w\s-]*limit|usage[ _-]?limit|too many requests|\b429\b/i.test(s);
+}
+
+/**
+ * Clamps a candidate reset timestamp (ms) to [now+60s, now+7d].
  * Protects against past timestamps (clock skew) and absurdly far future values (malformed).
  */
 function clampRateLimitResetMs(candidateMs: number): number {
   const nowMs = Date.now();
   const minMs = nowMs + 60_000;
-  const maxMs = nowMs + 6 * 60 * 60 * 1000;
+  const maxMs = nowMs + MAX_RATE_LIMIT_RESET_MS;
   return Math.min(Math.max(candidateMs, minMs), maxMs);
 }
 
@@ -96,6 +117,26 @@ export class SessionErrorTracker {
     }
   }
 
+  /**
+   * Process a Codex-style usage-limit error message (from a `{type:"error"}`
+   * or `{type:"turn.failed"}` SDK event). Only stashes when the message
+   * contains the usage-limit signature AND carries a parseable wall-clock
+   * reset time. "Try again later." and workspace-credit branches fall through
+   * to the runner's tier-3 fallback instead.
+   * Last call wins — multiple events per session are deduped to the latest.
+   */
+  processCodexUsageLimitMessage(message: string): void {
+    if (!message) return;
+    if (!/usage limit|hit your usage/i.test(message)) return;
+
+    const iso = parseCodexRateLimitResetTime(message);
+    if (!iso) return;
+
+    const candidateMs = new Date(iso).getTime();
+    if (!Number.isFinite(candidateMs)) return;
+    this.rateLimitResetAtMs = clampRateLimitResetMs(candidateMs);
+  }
+
   /**
    * Returns the stashed rate limit reset time as an ISO string, or undefined
    * if no rejected rate_limit_event was seen in this session.
@@ -173,7 +214,14 @@ export class SessionErrorTracker {
 
   /** Check if the failure was due to a missing/stale session ID */
   isSessionNotFound(): boolean {
-    return this.errors.some((e) => e.message.includes("No conversation found with session ID"));
+    return this.errors.some((e) => {
+      const message = e.message.toLowerCase();
+      return (
+        message.includes("no conversation found with session id") ||
+        (message.includes("--resume requires a valid session id") &&
+          message.includes("does not match any session title"))
+      );
+    });
   }
 
   getErrors(): ReadonlyArray<ErrorSignal> {
@@ -250,6 +298,76 @@ const MONTH_NAMES: Record<string, number> = {
   december: 11,
 };
 
+/**
+ * Parse the reset time embedded in a Codex `UsageLimitReached` error message.
+ * Codex emits one of these formats via chrono's `%-I:%M %p` (same day) or
+ * `%b %-d{th/st/nd/rd}, %Y %-I:%M %p` (different day):
+ *   "Try again at 8:35 PM."
+ *   "or try again at 8:35 PM."
+ *   "Try again at May 26th, 2026 8:35 PM."
+ *   "or try again at May 26th, 2026 8:35 PM."
+ * Wall-clock times are UTC because the agent-swarm Docker worker has TZ=Etc/UTC;
+ * chrono::Local resolves to UTC in that container.
+ */
+export function parseCodexRateLimitResetTime(
+  message: string,
+  now: Date = new Date(),
+): string | undefined {
+  if (!message) return undefined;
+
+  // Different-day format (more specific — try first):
+  // "Month Day{st/nd/rd/th}, Year HH:MM AM/PM"
+  const datedMatch = message.match(
+    /\btry again at\s+([A-Za-z]+)\s+(\d{1,2})(?:st|nd|rd|th)?,\s+(\d{4})\s+(\d{1,2}):(\d{2})\s*(AM|PM|am|pm)\b/i,
+  );
+  if (datedMatch) {
+    const monthIdx = MONTH_NAMES[datedMatch[1]!.toLowerCase()];
+    if (monthIdx !== undefined) {
+      const day = Number.parseInt(datedMatch[2]!, 10);
+      const year = Number.parseInt(datedMatch[3]!, 10);
+      const rawHours = Number.parseInt(datedMatch[4]!, 10);
+      const minutes = Number.parseInt(datedMatch[5]!, 10);
+      const ampm = datedMatch[6]!.toLowerCase();
+      if (rawHours < 1 || rawHours > 12 || minutes < 0 || minutes > 59) return undefined;
+      let hours = rawHours;
+      if (ampm === "pm" && hours !== 12) hours += 12;
+      if (ampm === "am" && hours === 12) hours = 0;
+      const d = new Date(Date.UTC(year, monthIdx, day, hours, minutes, 0));
+      // Round-trip guard: Date.UTC silently normalises out-of-range days (e.g. May 32 → June 1).
+      if (d.getUTCFullYear() !== year || d.getUTCMonth() !== monthIdx || d.getUTCDate() !== day) {
+        return undefined;
+      }
+      return d.toISOString();
+    }
+  }
+
+  // Same-day format: "HH:MM AM/PM"
+  // Anchored on "try again at" so we don't match times elsewhere in the message.
+  const timeMatch = message.match(/\btry again at\s+(\d{1,2}):(\d{2})\s*(AM|PM|am|pm)\b/i);
+  if (timeMatch) {
+    const rawHours = Number.parseInt(timeMatch[1]!, 10);
+    const minutes = Number.parseInt(timeMatch[2]!, 10);
+    const ampm = timeMatch[3]!.toLowerCase();
+    if (rawHours < 1 || rawHours > 12 || minutes < 0 || minutes > 59) return undefined;
+    let hours = rawHours;
+    if (ampm === "pm" && hours !== 12) hours += 12;
+    if (ampm === "am" && hours === 12) hours = 0;
+    const candidate = new Date(
+      Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), hours, minutes, 0),
+    );
+    // Rollover: if the parsed wall-clock is more than SKEW_MS before "now", assume tomorrow.
+    // At-or-just-before-now candidates (clock skew, second truncation) stay same-day and
+    // flow to clampRateLimitResetMs which applies the now+60s floor.
+    const SKEW_MS = 2 * 60 * 1000;
+    if (candidate.getTime() < now.getTime() - SKEW_MS) {
+      candidate.setUTCDate(candidate.getUTCDate() + 1);
+    }
+    return candidate.toISOString();
+  }
+
+  return undefined;
+}
+
 /**
  * Parse a rate limit error message to extract a reset time, returning an ISO datetime string.
  * Handles patterns like:
@@ -338,12 +456,7 @@ export function parseStderrForErrors(stderr: string, tracker: SessionErrorTracke
   const lower = stderr.toLowerCase();
   const firstLine = stderr.trim().split("\n")[0] ?? stderr.trim();
 
-  if (
-    lower.includes("rate limit") ||
-    lower.includes("rate_limit") ||
-    lower.includes("429") ||
-    lower.includes("hit your limit")
-  ) {
+  if (isRateLimitMessage(stderr)) {
     tracker.addStderrError(firstLine);
   } else if (
     lower.includes("authentication") ||

package/templates/skills/agentmail-sending/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agentmail-sending
+description: CRITICAL rules for sending emails via AgentMail API. Covers the HTML bug workaround, BCC policy, and best practices. ALL agents MUST follow these rules when using send_message or reply_to_message.
+user-invocable: false
+---
+
+# AgentMail Sending Rules
+
+These rules are MANDATORY for all agents sending email via AgentMail. Violating them will result in blank emails reaching real people.
+
+## Rule 1: TEXT ONLY — Never Pass `html` Parameter
+
+**AgentMail has a critical bug (as of 2026-03-25):** When both `text` and `html` parameters are passed to `send_message` or `reply_to_message`, the HTML body content is silently dropped. The resulting email has an empty `<div dir="ltr"></div>`. Email clients (Gmail, etc.) prefer the HTML version over plain text, so recipients see a completely blank email.
+
+**What to do:**
+- ONLY pass the `text` parameter
+- NEVER pass the `html` parameter
+- This applies to BOTH `send_message` and `reply_to_message`
+
+**Why this matters:** This bug causes outbound emails to arrive completely blank, burning contacts permanently. It is not a cosmetic issue — it is a data loss / reputation issue.
+
+## Rule 2: BCC a Human Oversight Address on Outbound Emails
+
+All outbound emails to external recipients MUST include a human oversight email address as BCC. This gives your team visibility into what the swarm is sending on your behalf.
+
+**Configure a BCC oversight address for your swarm** (e.g. a founder address, ops inbox, or shared team address):
+
+```
+send_message({
+  inboxId: "<your-agentmail-inbox-id>",
+  to: ["recipient@example.com"],
+  bcc: ["oversight@yourcompany.com"],
+  subject: "...",
+  text: "..."
+})
+```
+
+**Exception:** Internal emails between your swarm's own agent inboxes do NOT need BCC.
+
+## Rule 3: Human Approval Before Sending to External Recipients
+
+Never send outreach or cold emails to external recipients without explicit human approval. Draft the emails, present them for review, and only send after receiving "approved" or equivalent confirmation.
+
+## Summary Checklist
+
+Before every `send_message` or `reply_to_message` call:
+- [ ] Only `text` param, NO `html` param
+- [ ] BCC your oversight address if recipient is external
+- [ ] Human-approved if it is outreach/cold email