@desplega.ai/agent-swarm 1.83.1 → 1.84.0

package/src/integrations/kapso/config.ts

@@ -0,0 +1,104 @@
+import { deleteKv, getKv, getSwarmConfigs, upsertKv } from "@/be/db";
+
+/**
+ * Native Kapso/WhatsApp integration — shared server-side config + mapping store.
+ *
+ * The mapping (phone-number-id → routing target) is backed by the swarm KV store
+ * under a pinned namespace, NOT a dedicated table. The inbound webhook handler and
+ * the `register-kapso-number` MCP tool are the only readers/writers.
+ */
+
+/** Pinned KV namespace for phone-number → routing mappings. No TTL. */
+export const KAPSO_NUMBERS_NAMESPACE = "integrations:kapso:numbers";
+
+/** Pinned KV namespace for inbound message-id dedupe markers (24h TTL). */
+export const KAPSO_DEDUPE_NAMESPACE = "integrations:kapso:dedupe";
+
+/** How long a dedupe marker lives — long enough to cover Kapso's webhook retries. */
+export const KAPSO_DEDUPE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Default Kapso API host when `KAPSO_API_BASE_URL` is unset (host only, no path). */
+export const DEFAULT_KAPSO_API_BASE_URL = "https://api.kapso.ai";
+
+/** A registered phone number and where its inbound messages should route. */
+export interface KapsoNumberMapping {
+  phoneNumberId: string;
+  /** Route inbound to this agent as a task. */
+  agentId?: string;
+  /** Advanced override: dispatch via this workflow's webhook trigger instead of a task. */
+  workflowId?: string;
+  /** Human-friendly display name for the number. */
+  name?: string;
+  createdAt: string;
+}
+
+export interface KapsoConfig {
+  apiKey: string | undefined;
+  apiBaseUrl: string;
+  webhookHmacSecret: string | undefined;
+  phoneNumberId: string | undefined;
+}
+
+/**
+ * Read a swarm-config value (global scope) by key, falling back to the process
+ * env. Decryption happens inside `getSwarmConfigs`.
+ */
+function readConfigValue(key: string): string | undefined {
+  const found = getSwarmConfigs({ scope: "global", key }).find(
+    (c) => typeof c.value === "string" && c.value.length > 0,
+  );
+  if (found) return found.value;
+  const env = process.env[key];
+  return env && env.length > 0 ? env : undefined;
+}
+
+/** Resolve the Kapso integration config from swarm config (env fallback). */
+export function getKapsoConfig(): KapsoConfig {
+  const base = readConfigValue("KAPSO_API_BASE_URL") ?? DEFAULT_KAPSO_API_BASE_URL;
+  return {
+    apiKey: readConfigValue("KAPSO_API_KEY"),
+    apiBaseUrl: base.replace(/\/+$/, ""),
+    webhookHmacSecret: readConfigValue("KAPSO_WEBHOOK_HMAC_SECRET"),
+    phoneNumberId: readConfigValue("KAPSO_PHONE_NUMBER_ID"),
+  };
+}
+
+/** Look up the routing mapping for a phone-number-id, or null if unregistered. */
+export function getKapsoNumberMapping(phoneNumberId: string): KapsoNumberMapping | null {
+  const row = getKv(KAPSO_NUMBERS_NAMESPACE, phoneNumberId);
+  return row ? (row.value as KapsoNumberMapping) : null;
+}
+
+/** Upsert a routing mapping (no TTL). */
+export function putKapsoNumberMapping(mapping: KapsoNumberMapping): KapsoNumberMapping {
+  upsertKv({
+    namespace: KAPSO_NUMBERS_NAMESPACE,
+    key: mapping.phoneNumberId,
+    value: mapping,
+    valueType: "json",
+    expiresAt: null,
+  });
+  return mapping;
+}
+
+/** Delete a routing mapping. Returns true if a row was removed. */
+export function deleteKapsoNumberMapping(phoneNumberId: string): boolean {
+  return deleteKv(KAPSO_NUMBERS_NAMESPACE, phoneNumberId);
+}
+
+/**
+ * Record a message-id as processed. Returns true the FIRST time a given id is
+ * seen and false on every subsequent delivery within the TTL window — so the
+ * caller drops duplicates (Kapso retries deliveries).
+ */
+export function markKapsoMessageSeen(messageId: string): boolean {
+  if (getKv(KAPSO_DEDUPE_NAMESPACE, messageId)) return false;
+  upsertKv({
+    namespace: KAPSO_DEDUPE_NAMESPACE,
+    key: messageId,
+    value: 1,
+    valueType: "integer",
+    expiresAt: Date.now() + KAPSO_DEDUPE_TTL_MS,
+  });
+  return true;
+}

package/src/integrations/kapso/inbound.ts

@@ -0,0 +1,111 @@
+import { resolveTemplate } from "@/prompts/resolver";
+import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
+import { workflowEventBus } from "@/workflows/event-bus";
+import "@/tools/templates";
+import { getKapsoNumberMapping, markKapsoMessageSeen } from "./config";
+
+/** Minimal shape of the Kapso v2 inbound webhook payload (see the kapso-whatsapp skill). */
+export interface KapsoWebhookPayload {
+  message?: {
+    id?: string;
+    from?: string;
+    type?: string;
+    text?: { body?: string };
+    kapso?: { direction?: string; content?: string; has_media?: boolean };
+  };
+  conversation?: {
+    id?: string;
+    phone_number?: string;
+    contact_name?: string;
+  };
+  phone_number_id?: string;
+  test?: boolean;
+}
+
+/** Outcome of routing one inbound webhook delivery. */
+export type KapsoRouting =
+  | { kind: "skip"; reason: string }
+  | { kind: "duplicate"; messageId: string }
+  | { kind: "workflow"; workflowId: string }
+  | { kind: "task"; taskId: string }
+  | { kind: "no_mapping"; phoneNumberId: string };
+
+function extractText(message: NonNullable<KapsoWebhookPayload["message"]>): string {
+  if (message.text?.body) return message.text.body;
+  if (message.kapso?.content) return message.kapso.content;
+  return `(non-text message — type: ${message.type ?? "unknown"})`;
+}
+
+function buildTaskDescription(payload: KapsoWebhookPayload): string {
+  const message = payload.message ?? {};
+  const conversation = payload.conversation ?? {};
+  return resolveTemplate("kapso.message.received", {
+    conversation_id: conversation.id ?? "unknown",
+    inbound_wamid: message.id ?? "unknown",
+    sender_phone: message.from ?? conversation.phone_number ?? "unknown",
+    contact_name: conversation.contact_name ?? "unknown",
+    phone_number_id: payload.phone_number_id ?? "unknown",
+    test_note: payload.test ? "\n- test: true (do NOT send a real WhatsApp reply)" : "",
+    message_text: extractText(message),
+  }).text;
+}
+
+/**
+ * Route one inbound Kapso webhook delivery. Pure of HTTP concerns — the caller
+ * handles HMAC verification and the workflow-trigger dispatch (which needs the
+ * raw body + executor registry). This:
+ *   1. drops non-inbound events and deliveries missing a message id,
+ *   2. dedupes by message id (KV, 24h TTL),
+ *   3. emits the `kapso.message.received` workflow event (additive),
+ *   4. looks up the phone-number mapping and either signals a workflow dispatch
+ *      or creates a native `kapso-inbound` task,
+ *   5. returns `no_mapping` when the number isn't registered (caller logs a warning).
+ */
+export function routeKapsoInbound(payload: KapsoWebhookPayload): KapsoRouting {
+  const message = payload.message;
+  const direction = message?.kapso?.direction;
+  if (direction !== "inbound") {
+    return { kind: "skip", reason: `non_inbound (direction=${direction ?? "none"})` };
+  }
+
+  const messageId = message?.id;
+  if (!messageId) {
+    return { kind: "skip", reason: "missing_message_id" };
+  }
+
+  if (!markKapsoMessageSeen(messageId)) {
+    return { kind: "duplicate", messageId };
+  }
+
+  const phoneNumberId = payload.phone_number_id ?? "";
+
+  // Additive: let event-subscribed workflows observe inbound regardless of mapping.
+  workflowEventBus.emit("kapso.message.received", {
+    phoneNumberId,
+    conversationId: payload.conversation?.id,
+    messageId,
+    from: message?.from,
+    type: message?.type,
+    text: extractText(message ?? {}),
+  });
+
+  const mapping = phoneNumberId ? getKapsoNumberMapping(phoneNumberId) : null;
+  if (!mapping) {
+    return { kind: "no_mapping", phoneNumberId };
+  }
+
+  if (mapping.workflowId) {
+    return { kind: "workflow", workflowId: mapping.workflowId };
+  }
+
+  const task = createTaskWithSiblingAwareness(buildTaskDescription(payload), {
+    agentId: mapping.agentId ?? null,
+    source: "system",
+    taskType: "kapso-inbound",
+    tags: ["kapso-whatsapp", "inbound"],
+    priority: 70,
+    contextKey: `kapso:conversation:${payload.conversation?.id ?? messageId}`,
+  });
+
+  return { kind: "task", taskId: task.id };
+}

package/src/jira/client.ts

@@ -1,5 +1,5 @@
 import { getOAuthTokens } from "../be/db-queries/oauth";
-import { ensureToken } from "../oauth/ensure-token";
+import { ensureToken, ensureTokenOrThrow } from "../oauth/ensure-token";
 import { getJiraMetadata } from "./metadata";
 
 /**
@@ -36,8 +36,7 @@ export function getJiraCloudId(): string {
  * - Prepends `https://api.atlassian.com/ex/jira/{cloudId}` to `path`.
  * - Sets `Authorization: Bearer <token>` and `Accept: application/json`.
  * - Sets `Content-Type: application/json` when a body is provided.
- * - On 401: refreshes the token (forced via `ensureToken("jira", 0)`) and
- *   retries once.
+ * - On 401: forces a token refresh and retries once.
  * - On 429: respects `Retry-After` (in seconds) with a single retry.
  *
  * Returns the raw `Response` — callers handle `response.json()`/`response.text()`
@@ -64,8 +63,7 @@ export async function jiraFetch(path: string, init?: RequestInit): Promise<Respo
   let response = await send(token);
 
   if (response.status === 401) {
-    // Force refresh — bufferMs=0 means "always refresh if any expiry is set"
-    await ensureToken("jira", 0);
+    await ensureTokenOrThrow("jira", Number.MAX_SAFE_INTEGER);
     token = await getJiraAccessToken();
     response = await send(token);
   }

package/src/jira/oauth.ts

@@ -29,6 +29,7 @@ export function getJiraOAuthConfig(): OAuthProviderConfig | null {
     scopes: app.scopes.split(","),
     scopeSeparator: " ",
     extraParams: { audience: "api.atlassian.com" },
+    requiresRefreshTokenRotation: true,
   };
 }
 

package/src/jira/sync.ts

@@ -21,7 +21,7 @@ import {
   getTrackerSyncByExternalId,
   updateTrackerSyncSwarmId,
 } from "../be/db-queries/tracker";
-import { ensureToken } from "../oauth/ensure-token";
+import { ensureToken, ensureTokenOrThrow } from "../oauth/ensure-token";
 import { resolveTemplate } from "../prompts/resolver";
 import { buildJiraContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
@@ -91,7 +91,7 @@ export async function resolveBotAccountId(): Promise<string | null> {
     // Mirror jiraFetch's 401-retry pattern: a token may go stale between the
     // proactive ensureToken call and the request reaching Atlassian.
     if (res.status === 401) {
-      await ensureToken("jira", 0);
+      await ensureTokenOrThrow("jira", Number.MAX_SAFE_INTEGER);
       tokens = getOAuthTokens("jira");
       if (!tokens?.accessToken) {
         console.warn("[Jira Sync] /me returned 401 and refresh produced no token");

package/src/oauth/ensure-token.ts

@@ -18,6 +18,7 @@ function getOAuthConfig(provider: string): OAuthProviderConfig | null {
     redirectUri: app.redirectUri,
     scopes: app.scopes.split(","),
     extraParams: metadata.extraParams ?? (metadata.actor ? { actor: metadata.actor } : undefined),
+    requiresRefreshTokenRotation: provider === "jira",
   };
 }
 

package/src/oauth/wrapper.ts

@@ -1,5 +1,5 @@
 import * as oauth from "oauth4webapi";
-import { storeOAuthTokens } from "../be/db-queries/oauth";
+import { storeOAuthTokens, updateOAuthTokensAfterRefresh } from "../be/db-queries/oauth";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -13,6 +13,12 @@ export interface OAuthProviderConfig {
   scopes: string[];
   /** Extra query params appended to the authorization URL (e.g. { actor: "app" } for Linear) */
   extraParams?: Record<string, string>;
+  /**
+   * Provider rotates refresh tokens on every refresh. When true, a refresh
+   * response without a new refresh token is unusable because the old one may
+   * already be invalidated server-side.
+   */
+  requiresRefreshTokenRotation?: boolean;
   /**
    * How to join `scopes` in the authorization URL.
    *
@@ -160,7 +166,7 @@ export async function exchangeCode(
 export async function refreshAccessToken(
   config: OAuthProviderConfig,
   refreshToken: string,
-): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number }> {
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
   const body = new URLSearchParams({
     grant_type: "refresh_token",
     client_id: config.clientId,
@@ -183,23 +189,48 @@ export async function refreshAccessToken(
     access_token: string;
     token_type: string;
     expires_in?: number;
+    scope?: string;
     refresh_token?: string;
   };
 
+  if (typeof data.access_token !== "string" || data.access_token.length === 0) {
+    throw new Error(`Token refresh failed: ${config.provider} response missing access_token`);
+  }
+
+  if (
+    config.requiresRefreshTokenRotation &&
+    (typeof data.refresh_token !== "string" || data.refresh_token.length === 0)
+  ) {
+    throw new Error(
+      `Token refresh failed: ${config.provider} response did not include a rotated refresh_token`,
+    );
+  }
+
   const expiresAt = data.expires_in
     ? new Date(Date.now() + data.expires_in * 1000).toISOString()
     : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
 
-  storeOAuthTokens(config.provider, {
-    accessToken: data.access_token,
-    refreshToken: data.refresh_token ?? null,
-    expiresAt,
-  });
+  const nextRefreshToken = data.refresh_token ?? refreshToken;
+  try {
+    updateOAuthTokensAfterRefresh(config.provider, refreshToken, {
+      accessToken: data.access_token,
+      refreshToken: nextRefreshToken,
+      expiresAt,
+      scope: data.scope ?? null,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[OAuth] Refusing to use refreshed ${config.provider} access token because persistence failed: ${message}`,
+    );
+    throw err;
+  }
 
   return {
     accessToken: data.access_token,
     refreshToken: data.refresh_token,
     expiresIn: data.expires_in,
+    scope: data.scope,
   };
 }
 

package/src/providers/claude-adapter.ts

@@ -395,6 +395,10 @@ class ClaudeSession implements ProviderSession {
       this.config.prompt,
     ];
 
+    if (this.config.resumeSessionId) {
+      cmd.push("--resume", this.config.resumeSessionId);
+    }
+
     if (this.config.additionalArgs?.length) {
       cmd.push(...this.config.additionalArgs);
     }
@@ -688,10 +692,11 @@ class ClaudeSession implements ProviderSession {
     // Stale session retry: if process failed because session not found and we used --resume,
     // strip --resume and retry with a fresh session
     if (result.exitCode !== 0 && this.errorTracker.isSessionNotFound()) {
-      const hasResume = (this.config.additionalArgs || []).includes("--resume");
+      const hasResume =
+        !!this.config.resumeSessionId || (this.config.additionalArgs || []).includes("--resume");
       if (hasResume) {
         console.log(
-          `\x1b[33m[${this.config.role}] Session not found for task ${this.config.taskId.slice(0, 8)} — retrying without --resume\x1b[0m`,
+          `\x1b[33m[${this.config.role}] Session resume failed for task ${this.config.taskId.slice(0, 8)} — retrying without --resume\x1b[0m`,
         );
 
         const freshArgs = (this.config.additionalArgs || []).filter((arg, idx, arr) => {

package/src/providers/claude-managed-adapter.ts

@@ -642,7 +642,7 @@ class ClaudeManagedSession implements ProviderSession {
       this.emit({
         type: "session_init",
         sessionId: this._sessionId,
-        provider: "claude" as const,
+        provider: "claude-managed",
         providerMeta: { managed: true },
       });
 

package/src/providers/codex-adapter.ts

@@ -71,6 +71,7 @@ import {
   clampContextPercent,
   computeContextUsedUnified,
 } from "../utils/context-window";
+import { SessionErrorTracker } from "../utils/error-tracker";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { type CodexAgentsMdHandle, writeCodexAgentsMd } from "./codex-agents-md";
@@ -413,6 +414,7 @@ class CodexSession implements ProviderSession {
   private lastUsage: Usage | null = null;
   private aborted = false;
   private settled = false;
+  private readonly errorTracker = new SessionErrorTracker();
   /**
    * Result captured by `settle` but held back from `resolveCompletion` until
    * `runSession`'s `finally` block has fully cleaned up (log writer flush,
@@ -951,9 +953,11 @@ class CodexSession implements ProviderSession {
           }
           if (event.type === "turn.failed" && !terminalError) {
             terminalError = this.formatTerminalError(event.error.message);
+            this.errorTracker.processCodexUsageLimitMessage(event.error.message);
           }
           if (event.type === "error" && !terminalError) {
             terminalError = this.formatTerminalError(event.message);
+            this.errorTracker.processCodexUsageLimitMessage(event.message);
           }
         }
       } catch (err) {
@@ -970,6 +974,30 @@ class CodexSession implements ProviderSession {
           });
           return;
         }
+        // The Codex CLI exits with code 1 after emitting a UsageLimitReached or
+        // other terminal error event. The SDK then throws "Codex Exec exited with
+        // code 1: Reading prompt from stdin" AFTER the event loop ends, which
+        // would overwrite the structured terminalError we already captured above.
+        // Preserve the structured error so the [usage-limit] prefix survives to
+        // the runner's rate-limit resolver.
+        if (terminalError) {
+          const cost = this.buildCostData(this.lastUsage, true);
+          this.emit({
+            type: "result",
+            cost,
+            isError: true,
+            errorCategory: terminalError.category ?? "turn_failed",
+          });
+          this.settle({
+            exitCode: 1,
+            sessionId: this._sessionId,
+            cost,
+            isError: true,
+            failureReason: terminalError.message,
+            rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
+          });
+          return;
+        }
         throw err;
       }
 
@@ -987,6 +1015,7 @@ class CodexSession implements ProviderSession {
         cost,
         isError,
         failureReason: terminalError?.message,
+        rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -1000,6 +1029,7 @@ class CodexSession implements ProviderSession {
         cost,
         isError: true,
         failureReason: message,
+        rateLimitResetAt: this.errorTracker.getRateLimitResetAt(),
       });
     } finally {
       // Session-end summarization. Pure addition for codex — no behavior to