@desplega.ai/agent-swarm 1.83.1 → 1.84.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.83.1",
+    "version": "1.84.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -1440,7 +1440,8 @@
                             "type": "string",
                             "enum": [
                               "global",
-                              "agent"
+                              "agent",
+                              "user"
                             ]
                           },
                           "scopeId": {
@@ -1526,7 +1527,8 @@
                             "type": "string",
                             "enum": [
                               "agent",
-                              "global"
+                              "global",
+                              "user"
                             ]
                           },
                           "agentSpendUsd": {
@@ -1553,6 +1555,18 @@
                               "null"
                             ]
                           },
+                          "userSpendUsd": {
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          },
+                          "userBudgetUsd": {
+                            "type": [
+                              "number",
+                              "null"
+                            ]
+                          },
                           "followUpTaskId": {
                             "type": [
                               "string",
@@ -1600,7 +1614,8 @@
               "type": "string",
               "enum": [
                 "global",
-                "agent"
+                "agent",
+                "user"
               ]
             },
             "required": true,
@@ -1631,7 +1646,8 @@
                       "type": "string",
                       "enum": [
                         "global",
-                        "agent"
+                        "agent",
+                        "user"
                       ]
                     },
                     "scopeId": {
@@ -1680,7 +1696,8 @@
               "type": "string",
               "enum": [
                 "global",
-                "agent"
+                "agent",
+                "user"
               ]
             },
             "required": true,
@@ -1729,7 +1746,8 @@
                       "type": "string",
                       "enum": [
                         "global",
-                        "agent"
+                        "agent",
+                        "user"
                       ]
                     },
                     "scopeId": {
@@ -1778,7 +1796,8 @@
               "type": "string",
               "enum": [
                 "global",
-                "agent"
+                "agent",
+                "user"
               ]
             },
             "required": true,
@@ -3362,6 +3381,24 @@
         }
       }
     },
+    "/api/integrations/mcp-user/config": {
+      "get": {
+        "summary": "Get server-derived config for end-user MCP clients.",
+        "tags": [
+          "Integrations"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Server-derived MCP user config. `mcpBaseUrl` is the API server base URL and `mcpUserUrl` appends `/mcp-user`."
+          }
+        }
+      }
+    },
     "/api/kv/{key}": {
       "get": {
         "summary": "Get a KV entry by key (namespace resolved from request headers)",
@@ -10989,6 +11026,100 @@
         }
       }
     },
+    "/api/users/{id}/mcp-tokens": {
+      "post": {
+        "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"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "label": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Minted token plaintext, token summary and composed user"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "User not found"
+          }
+        }
+      }
+    },
+    "/api/users/{id}/mcp-tokens/{tokenId}": {
+      "delete": {
+        "summary": "Revoke a user's MCP token",
+        "tags": [
+          "Users"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "tokenId",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Composed user after token revocation"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "User or token not found"
+          }
+        }
+      }
+    },
     "/api/users/{id}/merge": {
       "post": {
         "summary": "Merge another user into this one — moves identities + email aliases, deletes source",
@@ -11263,6 +11394,25 @@
         }
       }
     },
+    "/api/integrations/kapso/webhook": {
+      "post": {
+        "summary": "Handle native Kapso/WhatsApp webhook events",
+        "tags": [
+          "Webhooks"
+        ],
+        "responses": {
+          "200": {
+            "description": "Event received"
+          },
+          "401": {
+            "description": "Invalid signature"
+          },
+          "503": {
+            "description": "Kapso integration not configured"
+          }
+        }
+      }
+    },
     "/api/workflow-runs/{runId}/events": {
       "post": {
         "summary": "Fire a run-scoped event signal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.83.1",
+  "version": "1.84.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/artifact-sdk/server.ts

@@ -22,6 +22,28 @@ export interface ArtifactServer {
   tunnel: ReturnType<typeof createTunnel> extends Promise<infer T> ? T | null : never;
 }
 
+const NativeResponse = globalThis.Response;
+
+type NativeResponseArgs = ConstructorParameters<typeof Response>;
+
+export function createBunResponse(
+  body?: NativeResponseArgs[0],
+  init?: NativeResponseArgs[1],
+): Response {
+  return new NativeResponse(body, init);
+}
+
+export function createBunHonoFetchHandler(app: Hono): (req: Request) => Promise<Response> {
+  return async (req: Request) => {
+    const response = await app.fetch(req);
+    return createBunResponse(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  };
+}
+
 export function createArtifactServer(opts: ArtifactServerOptions): ArtifactServer {
   const agentId = process.env.AGENT_ID || "unknown";
   const apiKey = getApiKey();
@@ -100,7 +122,7 @@ export function createArtifactServer(opts: ArtifactServerOptions): ArtifactServe
 
     async start() {
       actualPort = opts.port || (await getAvailablePort());
-      server = Bun.serve({ port: actualPort, fetch: app.fetch });
+      server = Bun.serve({ port: actualPort, fetch: createBunHonoFetchHandler(app) });
       artifact.port = actualPort;
 
       const subdomain = opts.subdomain || `${agentId}-${opts.name}`;

package/src/be/budget-admission.ts

@@ -8,7 +8,7 @@
 // /api/poll pool, MCP `task-action` `accept`) translate refusals into the
 // `budget_refused` trigger envelope.
 
-import { getBudget, getDailySpendForAgent, getDailySpendGlobal } from "./db";
+import { getBudget, getDailySpendForAgent, getDailySpendForUser, getDailySpendGlobal } from "./db";
 
 export interface BudgetAdmissionAllowed {
   allowed: true;
@@ -16,11 +16,13 @@ export interface BudgetAdmissionAllowed {
 
 export interface BudgetAdmissionRefused {
   allowed: false;
-  cause: "agent" | "global";
+  cause: "agent" | "global" | "user";
   agentSpend?: number;
   agentBudget?: number;
   globalSpend?: number;
   globalBudget?: number;
+  userSpend?: number;
+  userBudget?: number;
   /** ISO 8601 of the next UTC midnight (the moment daily spend rolls over). */
   resetAt: string;
 }
@@ -60,12 +62,17 @@ function nextUtcMidnight(now: Date): string {
  *   0. Kill-switch (`BUDGET_ADMISSION_DISABLED=true`) ⇒ allowed.
  *   1. Global budget set + global daily spend ≥ ceiling ⇒ refused (`global`).
  *   2. Agent budget set + agent daily spend ≥ ceiling ⇒ refused (`agent`).
- *   3. Otherwise ⇒ allowed.
+ *   3. User budget set + user's task spend ≥ ceiling ⇒ refused (`user`).
+ *   4. Otherwise ⇒ allowed.
  *
  * Global is checked first by design: a tripped global budget halts the entire
  * swarm regardless of any single agent's spend.
  */
-export function canClaim(agentId: string, nowUtc: Date): BudgetAdmissionResult {
+export function canClaim(
+  agentId: string,
+  nowUtc: Date,
+  requestedByUserId?: string,
+): BudgetAdmissionResult {
   if (process.env.BUDGET_ADMISSION_DISABLED === "true") {
     if (!killSwitchWarned) {
       killSwitchWarned = true;
@@ -109,6 +116,23 @@ export function canClaim(agentId: string, nowUtc: Date): BudgetAdmissionResult {
     }
   }
 
+  // 3. Per-user budget gate. Only applies to tasks tied to a canonical user.
+  if (requestedByUserId) {
+    const userBudget = getBudget("user", requestedByUserId);
+    if (userBudget !== null) {
+      const userSpend = getDailySpendForUser(requestedByUserId, dateUtc);
+      if (userSpend >= userBudget.dailyBudgetUsd) {
+        return {
+          allowed: false,
+          cause: "user",
+          userSpend,
+          userBudget: userBudget.dailyBudgetUsd,
+          resetAt,
+        };
+      }
+    }
+  }
+
   return { allowed: true };
 }
 

package/src/be/budget-refusal-notify.ts

@@ -18,22 +18,28 @@ import {
   createTaskExtended,
   getAgentById,
   getLeadAgent,
+  getUserById,
   setBudgetRefusalFollowUpTaskId,
 } from "./db";
 
 export interface BudgetRefusalContext {
   /** The task that was refused (provides Slack context, description). */
-  task: Pick<AgentTask, "id" | "task" | "slackChannelId" | "slackThreadTs" | "slackUserId">;
+  task: Pick<
+    AgentTask,
+    "id" | "task" | "requestedByUserId" | "slackChannelId" | "slackThreadTs" | "slackUserId"
+  >;
   /** Refusing agent id. */
   agentId: string;
   /** UTC date `YYYY-MM-DD` used as the dedup key alongside `task.id`. */
   date: string;
   /** Refusal cause. */
-  cause: "agent" | "global";
+  cause: "agent" | "global" | "user";
   agentSpendUsd?: number;
   agentBudgetUsd?: number;
   globalSpendUsd?: number;
   globalBudgetUsd?: number;
+  userSpendUsd?: number;
+  userBudgetUsd?: number;
   /** ISO 8601 of the next UTC midnight (when the daily budget resets). */
   resetAt: string;
 }
@@ -49,6 +55,9 @@ function formatSpendSummary(ctx: BudgetRefusalContext): string {
   if (ctx.cause === "agent") {
     return `${fmt(ctx.agentSpendUsd)} / ${fmt(ctx.agentBudgetUsd)}`;
   }
+  if (ctx.cause === "user") {
+    return `${fmt(ctx.userSpendUsd)} / ${fmt(ctx.userBudgetUsd)}`;
+  }
   return `${fmt(ctx.globalSpendUsd)} / ${fmt(ctx.globalBudgetUsd)}`;
 }
 
@@ -79,6 +88,10 @@ export function emitBudgetRefusalSideEffects(ctx: BudgetRefusalContext, inserted
       if (leadAgent) {
         const refusingAgent = getAgentById(ctx.agentId);
         const agentName = refusingAgent?.name || ctx.agentId.slice(0, 8);
+        const userName = ctx.task.requestedByUserId
+          ? (getUserById(ctx.task.requestedByUserId)?.name ??
+            ctx.task.requestedByUserId.slice(0, 8))
+          : undefined;
         const taskDesc = ctx.task.task.slice(0, 200);
         const spendSummary = formatSpendSummary(ctx);
 
@@ -86,7 +99,8 @@ export function emitBudgetRefusalSideEffects(ctx: BudgetRefusalContext, inserted
           "task.budget.refused",
           {
             cause: ctx.cause,
-            agent_name: agentName,
+            agent_name:
+              ctx.cause === "user" && userName ? `${agentName} for user ${userName}` : agentName,
             task_desc: taskDesc,
             spend_summary: spendSummary,
             reset_at: ctx.resetAt,
@@ -135,6 +149,8 @@ export function emitBudgetRefusalSideEffects(ctx: BudgetRefusalContext, inserted
         agentBudgetUsd: ctx.agentBudgetUsd,
         globalSpendUsd: ctx.globalSpendUsd,
         globalBudgetUsd: ctx.globalBudgetUsd,
+        userSpendUsd: ctx.userSpendUsd,
+        userBudgetUsd: ctx.userBudgetUsd,
         resetAt: ctx.resetAt,
       });
     });

package/src/be/db-queries/oauth.ts

@@ -127,6 +127,49 @@ export function storeOAuthTokens(
     .run(provider, data.accessToken, data.refreshToken ?? null, data.expiresAt, data.scope ?? null);
 }
 
+export function updateOAuthTokensAfterRefresh(
+  provider: string,
+  expectedRefreshToken: string,
+  data: {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    scope?: string | null;
+  },
+): void {
+  const result = getDb()
+    .query(
+      `UPDATE oauth_tokens
+       SET accessToken = ?,
+           refreshToken = ?,
+           expiresAt = ?,
+           scope = COALESCE(?, scope),
+           updatedAt = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE provider = ? AND refreshToken = ?`,
+    )
+    .run(
+      data.accessToken,
+      data.refreshToken,
+      data.expiresAt,
+      data.scope ?? null,
+      provider,
+      expectedRefreshToken,
+    );
+
+  if (result.changes === 1) return;
+
+  const current = getOAuthTokens(provider);
+  if (!current) {
+    throw new Error(`OAuth token refresh persistence failed for ${provider}: token row missing`);
+  }
+  if (current.refreshToken !== expectedRefreshToken) {
+    throw new Error(
+      `OAuth token refresh persistence failed for ${provider}: stored refresh token changed during refresh`,
+    );
+  }
+  throw new Error(`OAuth token refresh persistence failed for ${provider}: no rows updated`);
+}
+
 export function deleteOAuthTokens(provider: string): void {
   getDb().query("DELETE FROM oauth_tokens WHERE provider = ?").run(provider);
 }

package/src/be/db.ts

@@ -1401,6 +1401,8 @@ export interface TaskFilters {
   source?: AgentTaskSource[];
   /** ISO 8601 timestamp; only return tasks where createdAt >= this. */
   createdAfter?: string;
+  /** Only return tasks requested by this canonical user. NULL rows are excluded. */
+  requestedByUserId?: string;
   limit?: number;
   offset?: number;
   includeHeartbeat?: boolean;
@@ -1484,6 +1486,11 @@ export function getAllTasks(
     params.push(filters.createdAfter);
   }
 
+  if (filters?.requestedByUserId) {
+    conditions.push("requestedByUserId = ?");
+    params.push(filters.requestedByUserId);
+  }
+
   // Exclude system/heartbeat tasks by default. The flag is still called
   // `includeHeartbeat` for backward compat with existing API callers, but we
   // also gate boot-triage + heartbeat-checklist behind it since those are
@@ -9684,6 +9691,8 @@ interface BudgetRefusalNotificationRow {
   agent_budget_usd: number | null;
   global_spend_usd: number | null;
   global_budget_usd: number | null;
+  user_spend_usd: number | null;
+  user_budget_usd: number | null;
   follow_up_task_id: string | null;
   createdAt: number;
 }
@@ -9714,6 +9723,8 @@ function rowToBudgetRefusalNotification(
     agentBudgetUsd: row.agent_budget_usd ?? undefined,
     globalSpendUsd: row.global_spend_usd ?? undefined,
     globalBudgetUsd: row.global_budget_usd ?? undefined,
+    userSpendUsd: row.user_spend_usd ?? undefined,
+    userBudgetUsd: row.user_budget_usd ?? undefined,
     followUpTaskId: row.follow_up_task_id ?? undefined,
     createdAt: row.createdAt,
   };
@@ -9964,6 +9975,24 @@ export function getDailySpendGlobal(dateUtc: string): number {
   return row?.total ?? 0;
 }
 
+/**
+ * Sum of `totalCostUsd` across all `session_costs` rows whose task was
+ * requested by a given user on a given UTC calendar day. `dateUtc` MUST be
+ * `'YYYY-MM-DD'` (UTC). Costs are joined through `agent_tasks` deliberately;
+ * `session_costs` stays task/session-scoped and does not grow a userId column.
+ */
+export function getDailySpendForUser(userId: string, dateUtc: string): number {
+  const row = getDb()
+    .prepare<CoalesceSumRow, [string, string]>(
+      `SELECT COALESCE(SUM(sc.totalCostUsd), 0) AS total
+       FROM session_costs sc
+       JOIN agent_tasks t ON sc.taskId = t.id
+       WHERE t.requestedByUserId = ? AND substr(sc.createdAt, 1, 10) = ?`,
+    )
+    .get(userId, dateUtc);
+  return row?.total ?? 0;
+}
+
 export interface RecordBudgetRefusalNotificationInput {
   taskId: string;
   date: string;
@@ -9973,6 +10002,8 @@ export interface RecordBudgetRefusalNotificationInput {
   agentBudgetUsd?: number;
   globalSpendUsd?: number;
   globalBudgetUsd?: number;
+  userSpendUsd?: number;
+  userBudgetUsd?: number;
 }
 
 /**
@@ -9991,8 +10022,8 @@ export function recordBudgetRefusalNotification(input: RecordBudgetRefusalNotifi
   const result = db
     .prepare(
       `INSERT OR IGNORE INTO budget_refusal_notifications
-       (task_id, date, agent_id, cause, agent_spend_usd, agent_budget_usd, global_spend_usd, global_budget_usd, follow_up_task_id, createdAt)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
+       (task_id, date, agent_id, cause, agent_spend_usd, agent_budget_usd, global_spend_usd, global_budget_usd, user_spend_usd, user_budget_usd, follow_up_task_id, createdAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
     )
     .run(
       input.taskId,
@@ -10003,6 +10034,8 @@ export function recordBudgetRefusalNotification(input: RecordBudgetRefusalNotifi
       input.agentBudgetUsd ?? null,
       input.globalSpendUsd ?? null,
       input.globalBudgetUsd ?? null,
+      input.userSpendUsd ?? null,
+      input.userBudgetUsd ?? null,
       now,
     );
 

package/src/be/migrations/074_user_budget_scope.sql

@@ -0,0 +1,85 @@
+-- 074_user_budget_scope.sql
+-- Add per-user budget enforcement for client-side MCP users.
+--
+-- SQLite cannot widen a CHECK constraint in place, so recreate the affected
+-- tables and preserve their data. The `budgets` table gains scope='user'.
+-- `budget_refusal_notifications` gains cause='user' and optional user
+-- spend/budget audit columns so claim-time user-budget refusals can share the
+-- existing dedup + lead-notification rail.
+
+CREATE TABLE budgets_new (
+  scope TEXT NOT NULL,
+  scope_id TEXT NOT NULL,
+  daily_budget_usd REAL NOT NULL,
+  createdAt INTEGER NOT NULL,
+  lastUpdatedAt INTEGER NOT NULL,
+  PRIMARY KEY (scope, scope_id),
+  CHECK (scope IN ('global', 'agent', 'user')),
+  CHECK (daily_budget_usd >= 0)
+);
+
+INSERT INTO budgets_new (scope, scope_id, daily_budget_usd, createdAt, lastUpdatedAt)
+SELECT scope, scope_id, daily_budget_usd, createdAt, lastUpdatedAt
+FROM budgets;
+
+DROP TABLE budgets;
+ALTER TABLE budgets_new RENAME TO budgets;
+
+INSERT OR IGNORE INTO budgets (scope, scope_id, daily_budget_usd, createdAt, lastUpdatedAt)
+SELECT
+  'user',
+  id,
+  dailyBudgetUsd,
+  CAST(strftime('%s', 'now') AS INTEGER) * 1000,
+  CAST(strftime('%s', 'now') AS INTEGER) * 1000
+FROM users
+WHERE dailyBudgetUsd IS NOT NULL;
+
+CREATE TABLE budget_refusal_notifications_new (
+  task_id TEXT NOT NULL,
+  date TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  cause TEXT NOT NULL,
+  agent_spend_usd REAL,
+  agent_budget_usd REAL,
+  global_spend_usd REAL,
+  global_budget_usd REAL,
+  user_spend_usd REAL,
+  user_budget_usd REAL,
+  follow_up_task_id TEXT,
+  createdAt INTEGER NOT NULL,
+  PRIMARY KEY (task_id, date),
+  CHECK (cause IN ('agent', 'global', 'user'))
+);
+
+INSERT INTO budget_refusal_notifications_new (
+  task_id,
+  date,
+  agent_id,
+  cause,
+  agent_spend_usd,
+  agent_budget_usd,
+  global_spend_usd,
+  global_budget_usd,
+  user_spend_usd,
+  user_budget_usd,
+  follow_up_task_id,
+  createdAt
+)
+SELECT
+  task_id,
+  date,
+  agent_id,
+  cause,
+  agent_spend_usd,
+  agent_budget_usd,
+  global_spend_usd,
+  global_budget_usd,
+  NULL,
+  NULL,
+  follow_up_task_id,
+  createdAt
+FROM budget_refusal_notifications;
+
+DROP TABLE budget_refusal_notifications;
+ALTER TABLE budget_refusal_notifications_new RENAME TO budget_refusal_notifications;