@desplega.ai/agent-swarm 1.83.1 → 1.84.0

package/src/http/poll.ts

@@ -42,11 +42,13 @@ import { json, jsonError } from "./utils";
  * + workflow bus emit. See `src/be/budget-refusal-notify.ts`.
  */
 function buildBudgetRefusedTrigger(refusal: {
-  cause: "agent" | "global";
+  cause: "agent" | "global" | "user";
   agentSpend?: number;
   agentBudget?: number;
   globalSpend?: number;
   globalBudget?: number;
+  userSpend?: number;
+  userBudget?: number;
   resetAt: string;
 }): { type: "budget_refused"; [key: string]: unknown } {
   const trigger: { type: "budget_refused"; [key: string]: unknown } = {
@@ -58,6 +60,8 @@ function buildBudgetRefusedTrigger(refusal: {
   if (refusal.agentBudget !== undefined) trigger.agentBudget = refusal.agentBudget;
   if (refusal.globalSpend !== undefined) trigger.globalSpend = refusal.globalSpend;
   if (refusal.globalBudget !== undefined) trigger.globalBudget = refusal.globalBudget;
+  if (refusal.userSpend !== undefined) trigger.userSpend = refusal.userSpend;
+  if (refusal.userBudget !== undefined) trigger.userBudget = refusal.userBudget;
   return trigger;
 }
 
@@ -180,7 +184,7 @@ export async function handlePoll(
             // the capacity check so capacity AND budget gates share atomicity.
             // Phase 5 also records the dedup row + captures the side-effect
             // context here so the after-commit step can notify the lead.
-            const admission = canClaim(myAgentId, new Date());
+            const admission = canClaim(myAgentId, new Date(), pendingTask.requestedByUserId);
             if (!admission.allowed) {
               const utcDate = new Date().toISOString().slice(0, 10);
               const dedup = recordBudgetRefusalNotification({
@@ -192,6 +196,8 @@ export async function handlePoll(
                 agentBudgetUsd: admission.agentBudget,
                 globalSpendUsd: admission.globalSpend,
                 globalBudgetUsd: admission.globalBudget,
+                userSpendUsd: admission.userSpend,
+                userBudgetUsd: admission.userBudget,
               });
               return {
                 trigger: buildBudgetRefusedTrigger(admission),
@@ -200,6 +206,7 @@ export async function handlePoll(
                     task: {
                       id: pendingTask.id,
                       task: pendingTask.task,
+                      requestedByUserId: pendingTask.requestedByUserId,
                       slackChannelId: pendingTask.slackChannelId,
                       slackThreadTs: pendingTask.slackThreadTs,
                       slackUserId: pendingTask.slackUserId,
@@ -211,6 +218,8 @@ export async function handlePoll(
                     agentBudgetUsd: admission.agentBudget,
                     globalSpendUsd: admission.globalSpend,
                     globalBudgetUsd: admission.globalBudget,
+                    userSpendUsd: admission.userSpend,
+                    userBudgetUsd: admission.userBudget,
                     resetAt: admission.resetAt,
                   },
                   inserted: dedup.inserted,
@@ -303,10 +312,10 @@ export async function handlePoll(
             // refusal, and the dedup is per-(task,date) so subsequent same-day
             // refusals on the same lead-candidate are suppressed.
             if (unassignedIds.length > 0) {
-              const admission = canClaim(myAgentId, new Date());
+              const candidateId = unassignedIds[0]!;
+              const candidateTask = getTaskById(candidateId);
+              const admission = canClaim(myAgentId, new Date(), candidateTask?.requestedByUserId);
               if (!admission.allowed) {
-                const candidateId = unassignedIds[0]!;
-                const candidateTask = getTaskById(candidateId);
                 const utcDate = new Date().toISOString().slice(0, 10);
                 const dedup = recordBudgetRefusalNotification({
                   taskId: candidateId,
@@ -317,6 +326,8 @@ export async function handlePoll(
                   agentBudgetUsd: admission.agentBudget,
                   globalSpendUsd: admission.globalSpend,
                   globalBudgetUsd: admission.globalBudget,
+                  userSpendUsd: admission.userSpend,
+                  userBudgetUsd: admission.userBudget,
                 });
                 return {
                   trigger: buildBudgetRefusedTrigger(admission),
@@ -326,6 +337,7 @@ export async function handlePoll(
                           task: {
                             id: candidateTask.id,
                             task: candidateTask.task,
+                            requestedByUserId: candidateTask.requestedByUserId,
                             slackChannelId: candidateTask.slackChannelId,
                             slackThreadTs: candidateTask.slackThreadTs,
                             slackUserId: candidateTask.slackUserId,
@@ -337,6 +349,8 @@ export async function handlePoll(
                           agentBudgetUsd: admission.agentBudget,
                           globalSpendUsd: admission.globalSpend,
                           globalBudgetUsd: admission.globalBudget,
+                          userSpendUsd: admission.userSpend,
+                          userBudgetUsd: admission.userBudget,
                           resetAt: admission.resetAt,
                         },
                         inserted: dedup.inserted,

package/src/http/schedules.ts

@@ -466,11 +466,11 @@ export async function handleSchedules(
         const mergedTimezone =
           parsed.body.timezone !== undefined ? parsed.body.timezone : existing.timezone;
         if (timing.mergedCron || timing.mergedInterval) {
-          // biome-ignore lint/suspicious/noExplicitAny: need partial ScheduledTask for calculateNextRun
           body.nextRunAt = calculateNextRun({
             cronExpression: timing.mergedCron,
             intervalMs: timing.mergedInterval,
             timezone: mergedTimezone,
+            // biome-ignore lint/suspicious/noExplicitAny: need partial ScheduledTask for calculateNextRun
           } as any);
         }
       }

package/src/http/users.ts

@@ -7,8 +7,7 @@
  * pass it as the `IdentityActor` arg to the helpers in `src/be/users.ts` — so
  * every identity mutation lands an event row tagged `op:<sha256-16>`.
  *
- * Endpoint set (Core Req #6, minus `POST/DELETE /users/:id/mcp-tokens` which
- * are deferred to the MCP plan):
+ * Endpoint set:
  *
  *   GET    /api/users
  *   POST   /api/users
@@ -16,6 +15,8 @@
  *   POST   /api/users/unmapped/:kind/:externalId/resolve
  *   GET    /api/users/:id
  *   PATCH  /api/users/:id
+ *   POST   /api/users/:id/mcp-tokens
+ *   DELETE /api/users/:id/mcp-tokens/:tokenId
  *   POST   /api/users/:id/merge
  *   GET    /api/users/:id/events
  *   POST   /api/users/:id/identities
@@ -26,12 +27,14 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
   createUser,
+  deleteBudget,
   deleteKv,
   deleteUser,
   getAllUsers,
   getUserById,
   listKv,
   updateUser,
+  upsertBudget,
 } from "../be/db";
 import {
   getUserIdentities,
@@ -39,7 +42,9 @@ import {
   linkIdentity,
   listUserEvents,
   listUserTokens,
+  mintToken,
   recordIdentityEvent,
+  revokeToken,
   unlinkIdentity,
 } from "../be/users";
 import { getOperatorActor } from "./operator-actor";
@@ -64,6 +69,15 @@ function composeUser(userId: string, recentEventLimit = 5) {
   };
 }
 
+function syncUserBudgetMirror(userId: string, dailyBudgetUsd: number | null | undefined): void {
+  if (dailyBudgetUsd === undefined) return;
+  if (dailyBudgetUsd === null) {
+    deleteBudget("user", userId);
+    return;
+  }
+  upsertBudget("user", userId, dailyBudgetUsd);
+}
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const listUsers = route({
@@ -203,6 +217,41 @@ const updateUserRoute = route({
   auth: { apiKey: true },
 });
 
+const mintUserMcpTokenRoute = route({
+  method: "post",
+  path: "/api/users/{id}/mcp-tokens",
+  pattern: ["api", "users", null, "mcp-tokens"],
+  summary: "Mint a one-time plaintext MCP token for a user",
+  description:
+    "Returns the plaintext token exactly once. Subsequent reads only expose token summaries.",
+  tags: ["Users"],
+  params: z.object({ id: z.string() }),
+  body: z.object({
+    label: z.string().nullable().optional(),
+  }),
+  responses: {
+    200: { description: "Minted token plaintext, token summary and composed user" },
+    401: { description: "Unauthorized" },
+    404: { description: "User not found" },
+  },
+  auth: { apiKey: true },
+});
+
+const revokeUserMcpTokenRoute = route({
+  method: "delete",
+  path: "/api/users/{id}/mcp-tokens/{tokenId}",
+  pattern: ["api", "users", null, "mcp-tokens", null],
+  summary: "Revoke a user's MCP token",
+  tags: ["Users"],
+  params: z.object({ id: z.string(), tokenId: z.string() }),
+  responses: {
+    200: { description: "Composed user after token revocation" },
+    401: { description: "Unauthorized" },
+    404: { description: "User or token not found" },
+  },
+  auth: { apiKey: true },
+});
+
 const mergeUsersRoute = route({
   method: "post",
   path: "/api/users/{id}/merge",
@@ -370,6 +419,7 @@ export async function handleUsers(
     try {
       const { identities, ...userFields } = parsed.body;
       const user = createUser(userFields);
+      syncUserBudgetMirror(user.id, userFields.dailyBudgetUsd);
       for (const ident of identities ?? []) {
         linkIdentity(user.id, ident.kind, ident.externalId, actor);
       }
@@ -459,6 +509,60 @@ export async function handleUsers(
     return true;
   }
 
+  // ─── POST /api/users/:id/mcp-tokens ───────────────────────────────────────
+  if (mintUserMcpTokenRoute.match(req.method, pathSegments)) {
+    const parsed = await mintUserMcpTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    if (!getUserById(parsed.params.id)) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+
+    try {
+      const { tokenId, plaintext } = mintToken(parsed.params.id, parsed.body.label ?? null, actor);
+      const token = listUserTokens(parsed.params.id).find((t) => t.id === tokenId);
+      json(res, { plaintext, token, user: composeUser(parsed.params.id) });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to mint token", 500);
+    }
+    return true;
+  }
+
+  // ─── DELETE /api/users/:id/mcp-tokens/:tokenId ────────────────────────────
+  if (revokeUserMcpTokenRoute.match(req.method, pathSegments)) {
+    const parsed = await revokeUserMcpTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const actor = getOperatorActor(req, res);
+    if (!actor) return true;
+    if (!getUserById(parsed.params.id)) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+
+    const tokenBelongsToUser = listUserTokens(parsed.params.id).some(
+      (token) => token.id === parsed.params.tokenId,
+    );
+    if (!tokenBelongsToUser) {
+      jsonError(res, "Token not found", 404);
+      return true;
+    }
+
+    try {
+      revokeToken(parsed.params.tokenId, actor);
+      json(res, { user: composeUser(parsed.params.id) });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Failed to revoke token";
+      if (message.includes("Token not found")) {
+        jsonError(res, "Token not found", 404);
+      } else {
+        jsonError(res, message, 500);
+      }
+    }
+    return true;
+  }
+
   // ─── POST /api/users/:id/identities ────────────────────────────────────────
   if (addIdentityRoute.match(req.method, pathSegments)) {
     const parsed = await addIdentityRoute.parse(req, res, pathSegments, queryParams);
@@ -625,6 +729,7 @@ export async function handleUsers(
         jsonError(res, "User not found", 404);
         return true;
       }
+      syncUserBudgetMirror(parsed.params.id, parsed.body.dailyBudgetUsd);
 
       // Budget event
       if (

package/src/http/webhooks.ts

@@ -41,7 +41,11 @@ import {
   isGitLabEnabled,
   verifyGitLabWebhook,
 } from "../gitlab";
+import { getKapsoConfig } from "../integrations/kapso/config";
+import { routeKapsoInbound } from "../integrations/kapso/inbound";
+import { getExecutorRegistry } from "../workflows";
 import { workflowEventBus } from "../workflows/event-bus";
+import { handleWebhookTrigger, verifyHmacSignature, WebhookError } from "../workflows/triggers";
 import { route } from "./route-def";
 
 // ─── Route Definitions (documentation only — webhooks handle their own body parsing) ─
@@ -88,6 +92,20 @@ const agentmailWebhook = route({
   },
 });
 
+const kapsoWebhook = route({
+  method: "post",
+  path: "/api/integrations/kapso/webhook",
+  pattern: ["api", "integrations", "kapso", "webhook"],
+  summary: "Handle native Kapso/WhatsApp webhook events",
+  tags: ["Webhooks"],
+  auth: { apiKey: false },
+  responses: {
+    200: { description: "Event received" },
+    401: { description: "Invalid signature" },
+    503: { description: "Kapso integration not configured" },
+  },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleWebhooks(
@@ -437,5 +455,88 @@ export async function handleWebhooks(
     return true;
   }
 
+  // Native Kapso/WhatsApp webhook — needs raw body for HMAC verification.
+  // Registered numbers route here (register-kapso-number points Kapso's webhook
+  // at this URL); the generic workflow-webhook path (/api/webhooks/{id}) is
+  // untouched and still serves any number not registered in KV.
+  if (kapsoWebhook.match(req.method, pathSegments)) {
+    const config = getKapsoConfig();
+    if (!config.webhookHmacSecret) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Kapso integration not configured" }));
+      return true;
+    }
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk as Buffer);
+    }
+    const rawBody = Buffer.concat(chunks).toString();
+
+    const signature = req.headers["x-webhook-signature"];
+    const signatureValue = Array.isArray(signature) ? signature[0] : signature;
+    if (
+      !signatureValue ||
+      !verifyHmacSignature(config.webhookHmacSecret, rawBody, signatureValue)
+    ) {
+      console.log("[Kapso] Invalid webhook signature");
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid signature" }));
+      return true;
+    }
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      return true;
+    }
+
+    try {
+      const routing = routeKapsoInbound(payload);
+      switch (routing.kind) {
+        case "workflow":
+          // Advanced override — dispatch through the workflow's webhook trigger.
+          await handleWebhookTrigger(
+            routing.workflowId,
+            rawBody,
+            req.headers,
+            getExecutorRegistry(),
+          );
+          break;
+        case "no_mapping":
+          console.warn(
+            `[Kapso] No native mapping for phone_number_id "${routing.phoneNumberId}" — ignoring (register it with register-kapso-number)`,
+          );
+          break;
+        case "task":
+          console.log(`[Kapso] Dispatched kapso-inbound task ${routing.taskId}`);
+          break;
+        case "duplicate":
+          console.log(`[Kapso] Duplicate delivery for message ${routing.messageId}, skipping`);
+          break;
+        case "skip":
+          console.log(`[Kapso] Skipping event: ${routing.reason}`);
+          break;
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true, routing: routing.kind }));
+    } catch (err) {
+      // Never fail the delivery on a downstream dispatch error — we already
+      // verified + deduped. Log and ack so Kapso doesn't hammer retries.
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      if (err instanceof WebhookError) {
+        console.warn(`[Kapso] Workflow dispatch rejected: ${errorMessage}`);
+      } else {
+        console.error(`[Kapso] Error handling inbound event: ${errorMessage}`);
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true, routing: "error" }));
+    }
+    return true;
+  }
+
   return false;
 }

package/src/integrations/kapso/client.ts

@@ -0,0 +1,198 @@
+/**
+ * Thin Kapso REST client for the native integration. Pure `fetch` — no DB access.
+ *
+ * Two Kapso surfaces are used:
+ *  - Meta Cloud API proxy:  `{base}/meta/whatsapp/v24.0/{phoneNumberId}/messages`
+ *  - Kapso platform API:    `{base}/platform/v1/whatsapp/phone_numbers/{id}/webhooks`
+ *
+ * Both authenticate with the `X-API-Key` header.
+ */
+
+/** Result of an outbound text/reply send through the Meta proxy. */
+export interface KapsoSendResult {
+  ok: boolean;
+  status: number;
+  /** Outbound WAMID when the send succeeded. */
+  messageId?: string;
+  raw: unknown;
+  /** True when Kapso/Meta rejected the send for being outside the 24h session window. */
+  sessionWindowExpired: boolean;
+  errorMessage?: string;
+}
+
+/** Meta error codes that mean "outside the 24h customer-service window". */
+const SESSION_WINDOW_ERROR_CODES = new Set([131047, 131051, 470]);
+
+function extractMetaError(raw: unknown): { code?: number; message?: string } {
+  if (raw && typeof raw === "object" && "error" in raw) {
+    const err = (raw as { error?: { code?: number; message?: string } }).error;
+    if (err) return { code: err.code, message: err.message };
+  }
+  return {};
+}
+
+function isSessionWindowError(raw: unknown): boolean {
+  const { code, message } = extractMetaError(raw);
+  if (code !== undefined && SESSION_WINDOW_ERROR_CODES.has(code)) return true;
+  const text = (message ?? "").toLowerCase();
+  return text.includes("24 hours") || text.includes("re-engagement") || text.includes("outside");
+}
+
+async function parseJsonSafe(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Send a free-form WhatsApp text message via the Meta Cloud API proxy. When
+ * `contextMessageId` is set, the message renders as a quote-reply to that WAMID.
+ */
+export async function sendKapsoText(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  to: string;
+  body: string;
+  previewUrl?: boolean;
+  contextMessageId?: string;
+}): Promise<KapsoSendResult> {
+  const url = `${params.apiBaseUrl}/meta/whatsapp/v24.0/${params.phoneNumberId}/messages`;
+  const payload: Record<string, unknown> = {
+    messaging_product: "whatsapp",
+    recipient_type: "individual",
+    to: params.to,
+    type: "text",
+    text: { preview_url: params.previewUrl ?? false, body: params.body },
+  };
+  if (params.contextMessageId) {
+    payload.context = { message_id: params.contextMessageId };
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      sessionWindowExpired: isSessionWindowError(raw),
+      errorMessage: message ?? `Kapso send failed with status ${res.status}`,
+    };
+  }
+
+  const messageId =
+    raw && typeof raw === "object" && "messages" in raw
+      ? (raw as { messages?: Array<{ id?: string }> }).messages?.[0]?.id
+      : undefined;
+  return { ok: true, status: res.status, messageId, raw, sessionWindowExpired: false };
+}
+
+/** Result of configuring a webhook on a phone number. */
+export interface KapsoWebhookResult {
+  ok: boolean;
+  status: number;
+  raw: unknown;
+  errorMessage?: string;
+  /** True when an identical webhook already existed and we skipped re-creating it. */
+  alreadyRegistered?: boolean;
+}
+
+/** Pull a webhook array out of the various shapes Kapso's list endpoint may return. */
+function extractWebhookList(raw: unknown): Array<{ url?: string; kind?: string }> {
+  if (Array.isArray(raw)) return raw as Array<{ url?: string; kind?: string }>;
+  if (raw && typeof raw === "object") {
+    for (const key of ["whatsapp_webhooks", "webhooks", "data"]) {
+      const val = (raw as Record<string, unknown>)[key];
+      if (Array.isArray(val)) return val as Array<{ url?: string; kind?: string }>;
+    }
+  }
+  return [];
+}
+
+/**
+ * Return true when a Kapso webhook already points at `webhookUrl` for this
+ * phone number — used to avoid creating duplicate webhooks on re-registration.
+ * Best-effort: returns false if the list endpoint is unavailable.
+ */
+async function kapsoWebhookExists(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  webhookUrl: string;
+}): Promise<boolean> {
+  const url = `${params.apiBaseUrl}/platform/v1/whatsapp/phone_numbers/${params.phoneNumberId}/webhooks`;
+  try {
+    const res = await fetch(url, { headers: { "X-API-Key": params.apiKey } });
+    if (!res.ok) return false;
+    const raw = await parseJsonSafe(res);
+    return extractWebhookList(raw).some((w) => w?.url === params.webhookUrl);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register (or re-point) the Kapso webhook for a phone number so inbound events
+ * are delivered to `webhookUrl`, signed with `secret` via `X-Webhook-Signature`.
+ *
+ * First checks whether an identical webhook already exists for the number and
+ * skips the create call if so, to avoid piling up duplicate webhooks when a
+ * number is registered more than once.
+ */
+export async function registerKapsoWebhook(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  webhookUrl: string;
+  secret?: string;
+  events?: string[];
+}): Promise<KapsoWebhookResult> {
+  const url = `${params.apiBaseUrl}/platform/v1/whatsapp/phone_numbers/${params.phoneNumberId}/webhooks`;
+
+  if (
+    await kapsoWebhookExists({
+      apiBaseUrl: params.apiBaseUrl,
+      apiKey: params.apiKey,
+      phoneNumberId: params.phoneNumberId,
+      webhookUrl: params.webhookUrl,
+    })
+  ) {
+    return { ok: true, status: 200, raw: null, alreadyRegistered: true };
+  }
+
+  const whatsapp_webhook: Record<string, unknown> = {
+    kind: "kapso",
+    url: params.webhookUrl,
+    events: params.events ?? ["whatsapp.message.received"],
+  };
+  if (params.secret) whatsapp_webhook.secret_key = params.secret;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify({ whatsapp_webhook }),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      errorMessage: message ?? `Kapso webhook registration failed with status ${res.status}`,
+    };
+  }
+  return { ok: true, status: res.status, raw };
+}