@desplega.ai/agent-swarm 1.71.2 → 1.72.0

package/src/commands/runner.ts

@@ -19,16 +19,21 @@ import {
   type ProviderSessionConfig,
 } from "../providers/index.ts";
 import { initTelemetry, telemetry } from "../telemetry.ts";
-import type { RepoGuidelines } from "../types.ts";
+import type { ProviderName, RepoGuidelines } from "../types.ts";
+import { computeBudgetBackoffMs } from "../utils/budget-backoff.ts";
 import { getContextWindowSize } from "../utils/context-window.ts";
 import { type CredentialSelection, resolveCredentialPools } from "../utils/credentials.ts";
 import { parseRateLimitResetTime } from "../utils/error-tracker.ts";
 import { prettyPrintLine, prettyPrintStderr } from "../utils/pretty-print.ts";
+import { scrubSecrets } from "../utils/secret-scrubber.ts";
 import { detectVcsProvider } from "../vcs/index.ts";
 import { interpolate } from "../workflows/template.ts";
 // Side-effect import: registers runner trigger/resumption templates
 import "./templates.ts";
 
+/** Throttle interval for progress updates (3 seconds). */
+const PROGRESS_THROTTLE_MS = 3000;
+
 /** Save PM2 process list for persistence across container restarts */
 async function savePm2State(role: string): Promise<void> {
   try {
@@ -527,6 +532,7 @@ export async function ensureTaskFinished(
   taskId: string,
   exitCode: number,
   failureReason?: string,
+  providerOutput?: string,
 ): Promise<void> {
   const headers: Record<string, string> = {
     "X-Agent-ID": config.agentId,
@@ -543,6 +549,9 @@ export async function ensureTaskFinished(
 
   if (status === "failed") {
     body.failureReason = failureReason || `Claude process exited with code ${exitCode}`;
+  } else if (providerOutput) {
+    // Provider already supplied structured output (e.g. Devin) — use directly.
+    body.output = providerOutput;
   } else {
     // Try structured output fallback if the task has an outputSchema
     const adapterType = process.env.HARNESS_PROVIDER || "claude";
@@ -810,21 +819,28 @@ async function resumeTaskViaAPI(config: ApiConfig, taskId: string): Promise<bool
 async function buildResumePrompt(
   task: { id: string; task: string; progress?: string },
   fmt: (cmd: string) => string = (cmd) => `/${cmd}`,
+  options?: { hasMcp?: boolean },
 ): Promise<string> {
+  const hasMcp = options?.hasMcp !== false;
+  const completionInstructions = hasMcp
+    ? '\n\nWhen done, use `store-progress` with status: "completed" and include your output.'
+    : "";
   if (task.progress) {
     const result = await resolveTemplateAsync("task.resumption.with_progress", {
-      work_on_task_cmd: fmt("work-on-task"),
-      task_id: task.id,
+      work_on_task_cmd: hasMcp ? fmt("work-on-task") : "",
+      task_id: hasMcp ? task.id : "",
       task_description: task.task,
       progress: task.progress,
+      completion_instructions: completionInstructions,
     });
     return result.text;
   }
 
   const result = await resolveTemplateAsync("task.resumption.no_progress", {
-    work_on_task_cmd: fmt("work-on-task"),
-    task_id: task.id,
+    work_on_task_cmd: hasMcp ? fmt("work-on-task") : "",
+    task_id: hasMcp ? task.id : "",
     task_description: task.task,
+    completion_instructions: completionInstructions,
   });
   return result.text;
 }
@@ -1032,13 +1048,18 @@ async function saveProviderSessionId(
   apiKey: string,
   taskId: string,
   claudeSessionId: string,
+  provider?: ProviderName,
+  providerMeta?: Record<string, unknown>,
 ): Promise<void> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  const body: Record<string, unknown> = { claudeSessionId };
+  if (provider !== undefined) body.provider = provider;
+  if (providerMeta !== undefined) body.providerMeta = providerMeta;
   await fetch(`${apiUrl}/api/tasks/${taskId}/claude-session`, {
     method: "PUT",
     headers,
-    body: JSON.stringify({ claudeSessionId }),
+    body: JSON.stringify(body),
   });
 }
 
@@ -1250,7 +1271,8 @@ interface Trigger {
     | "task_offered"
     | "unread_mentions"
     | "pool_tasks_available"
-    | "channel_activity";
+    | "channel_activity"
+    | "budget_refused";
   taskId?: string;
   task?: unknown;
   mentionsCount?: number;
@@ -1275,6 +1297,16 @@ interface Trigger {
   }>;
   cursorUpdates?: Array<{ channelId: string; ts: string }>; // Deferred cursor commits for channel_activity
   requestedBy?: { name: string; email?: string };
+  // Phase 4 — budget_refused fields. The server emits this envelope from
+  // /api/poll and MCP task-action accept when an admission gate refuses to
+  // let the agent claim a task. Worker reads cause + reset/spend/budget for
+  // structured logging and back-off; never reaches buildPromptForTrigger.
+  cause?: "agent" | "global";
+  agentSpend?: number;
+  agentBudget?: number;
+  globalSpend?: number;
+  globalBudget?: number;
+  resetAt?: string; // ISO 8601, next UTC midnight
 }
 
 /** Options for polling */
@@ -1372,7 +1404,9 @@ async function buildPromptForTrigger(
   trigger: Trigger,
   defaultPrompt: string,
   fmt: (cmd: string) => string = (cmd) => `/${cmd}`,
+  options?: { hasMcp?: boolean },
 ): Promise<string> {
+  const hasMcp = options?.hasMcp !== false;
   switch (trigger.type) {
     case "task_assigned": {
       // Use the work-on-task command with task ID and description
@@ -1382,10 +1416,13 @@ async function buildPromptForTrigger(
           : null;
       const taskDescSection = taskDesc ? `\n\nTask: "${taskDesc}"` : "";
 
-      // Build output instructions — use outputSchema if present, otherwise generic
+      // Build output instructions — use outputSchema if present, otherwise generic.
+      // Skip store-progress references for providers without MCP (e.g. Devin).
       const taskObj = trigger.task as Record<string, unknown> | undefined;
       let outputInstructions: string;
-      if (taskObj?.outputSchema && typeof taskObj.outputSchema === "object") {
+      if (!hasMcp) {
+        outputInstructions = "";
+      } else if (taskObj?.outputSchema && typeof taskObj.outputSchema === "object") {
         outputInstructions = `\n\n**Required Output Format**: When completing this task, you MUST call store-progress with output that is valid JSON conforming to this schema:\n\`\`\`json\n${JSON.stringify(taskObj.outputSchema, null, 2)}\n\`\`\`\nCall store-progress with status "completed" and your JSON output. If your output doesn't match the schema, the tool call will fail and you should fix and retry.`;
       } else {
         outputInstructions =
@@ -1399,8 +1436,8 @@ async function buildPromptForTrigger(
         : "";
 
       const result = await resolveTemplateAsync("task.trigger.assigned", {
-        work_on_task_cmd: fmt("work-on-task"),
-        task_id: trigger.taskId,
+        work_on_task_cmd: hasMcp ? fmt("work-on-task") : "",
+        task_id: hasMcp ? trigger.taskId : "",
         task_desc_section: taskDescSection + requestedBySection,
         output_instructions: outputInstructions,
       });
@@ -1415,13 +1452,16 @@ async function buildPromptForTrigger(
           : null;
       const taskDescSection = taskDesc ? `\n\nA task has been offered to you:\n"${taskDesc}"` : "";
       const result = await resolveTemplateAsync("task.trigger.offered", {
-        review_offered_task_cmd: fmt("review-offered-task"),
-        task_id: trigger.taskId,
+        review_offered_task_cmd: hasMcp ? fmt("review-offered-task") : "",
+        task_id: hasMcp ? trigger.taskId : "",
         task_desc_section: taskDescSection,
       });
       return result.text;
     }
 
+    // NOTE: unread_mentions, pool_tasks_available, and channel_activity triggers
+    // reference MCP tools (read-messages, get-tasks, task-action, slack-reply, etc.)
+    // and are not currently fired for providers without MCP (e.g. Devin).
     case "unread_mentions": {
       const result = await resolveTemplateAsync("task.trigger.unread_mentions", {
         mention_count: trigger.count || "unread",
@@ -1461,6 +1501,28 @@ async function buildPromptForTrigger(
       return result.text;
     }
 
+    case "budget_refused": {
+      // DEFENSIVE: refusals are normally handled in the poll loop *before*
+      // reaching buildPromptForTrigger (the loop short-circuits on
+      // `trigger.type === "budget_refused"` to apply back-off + continue).
+      // This branch exists purely to keep the switch exhaustive in TypeScript
+      // and as future-refactor protection. It should never run in tested
+      // paths. Returning the default prompt is the safe no-op behavior.
+      const payload = JSON.stringify({
+        type: trigger.type,
+        cause: trigger.cause,
+        agentSpend: trigger.agentSpend,
+        agentBudget: trigger.agentBudget,
+        globalSpend: trigger.globalSpend,
+        globalBudget: trigger.globalBudget,
+        resetAt: trigger.resetAt,
+      });
+      console.warn(
+        `[runner] buildPromptForTrigger received budget_refused (defensive branch — should be handled in poll loop): ${scrubSecrets(payload)}`,
+      );
+      return defaultPrompt;
+    }
+
     default:
       return defaultPrompt;
   }
@@ -1549,6 +1611,7 @@ async function spawnProviderProcess(
     taskId?: string;
     model?: string;
     cwd?: string;
+    vcsRepo?: string;
   },
   logDir: string,
   isYolo: boolean,
@@ -1590,6 +1653,7 @@ async function spawnProviderProcess(
     apiUrl: opts.apiUrl,
     apiKey: opts.apiKey,
     cwd: opts.cwd || process.cwd(),
+    vcsRepo: opts.vcsRepo,
     logFile: opts.logFile,
     additionalArgs: opts.additionalArgs,
     iteration: opts.iteration,
@@ -1665,7 +1729,6 @@ async function spawnProviderProcess(
 
   // Auto-progress throttle: don't update more than once per 3 seconds
   let lastProgressTime = 0;
-  const PROGRESS_THROTTLE_MS = 3000;
 
   // Context usage throttle: max 1 snapshot per 30 seconds
   let lastContextPostTime = 0;
@@ -1675,9 +1738,14 @@ async function spawnProviderProcess(
     switch (event.type) {
       case "session_init":
         if (realTaskId) {
-          saveProviderSessionId(opts.apiUrl, opts.apiKey, realTaskId, event.sessionId).catch(
-            (err) => console.warn(`[runner] Failed to save session ID: ${err}`),
-          );
+          saveProviderSessionId(
+            opts.apiUrl,
+            opts.apiKey,
+            realTaskId,
+            event.sessionId,
+            event.provider,
+            event.providerMeta,
+          ).catch((err) => console.warn(`[runner] Failed to save session ID: ${err}`));
         } else {
           // Pool task: save provider session ID on active session so it can be
           // propagated to the real task when the agent claims one
@@ -1835,6 +1903,19 @@ async function spawnProviderProcess(
       case "raw_stderr":
         prettyPrintStderr(event.content, opts.role);
         break;
+
+      case "progress": {
+        if (effectiveTaskId && opts.apiUrl) {
+          const now = Date.now();
+          if (now - lastProgressTime >= PROGRESS_THROTTLE_MS) {
+            lastProgressTime = now;
+            updateProgressViaAPI(opts.apiUrl, opts.apiKey, effectiveTaskId, event.message).catch(
+              () => {},
+            );
+          }
+        }
+        break;
+      }
     }
   });
 
@@ -1986,13 +2067,26 @@ async function runProviderIteration(
 
   const session = await adapter.createSession(config);
 
+  let lastAiLoopProgressTime = 0;
   session.onEvent((event) => {
     if (event.type === "raw_log") prettyPrintLine(event.content, opts.role);
     if (event.type === "raw_stderr") prettyPrintStderr(event.content, opts.role);
     if (event.type === "session_init" && opts.taskId) {
-      saveProviderSessionId(opts.apiUrl, opts.apiKey, opts.taskId, event.sessionId).catch((err) =>
-        console.warn(`[runner] Failed to save session ID: ${err}`),
-      );
+      saveProviderSessionId(
+        opts.apiUrl,
+        opts.apiKey,
+        opts.taskId,
+        event.sessionId,
+        event.provider,
+        event.providerMeta,
+      ).catch((err) => console.warn(`[runner] Failed to save session ID: ${err}`));
+    }
+    if (event.type === "progress" && opts.taskId) {
+      const now = Date.now();
+      if (now - lastAiLoopProgressTime >= PROGRESS_THROTTLE_MS) {
+        lastAiLoopProgressTime = now;
+        updateProgressViaAPI(opts.apiUrl, opts.apiKey, opts.taskId, event.message).catch(() => {});
+      }
     }
   });
 
@@ -2074,7 +2168,14 @@ async function checkCompletedProcesses(
           ).catch(() => {});
         }
       }
-      await ensureTaskFinished(apiConfig, role, taskId, result.exitCode, failureReason);
+      await ensureTaskFinished(
+        apiConfig,
+        role,
+        taskId,
+        result.exitCode,
+        failureReason,
+        result.output,
+      );
 
       ensure({
         id: "worker_process_finished",
@@ -2272,22 +2373,28 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   let currentTaskSlackContext: BasePromptArgs["slackContext"] | undefined;
 
   // Generate base prompt (identity fields injected after profile fetch below)
+  const { traits } = adapter;
   const buildSystemPrompt = async () => {
     return getBasePrompt({
       role,
       agentId,
       swarmUrl,
       capabilities,
+      traits,
       name: agentProfileName,
       description: agentDescription,
-      soulMd: agentSoulMd,
-      identityMd: agentIdentityMd,
-      toolsMd: agentToolsMd,
-      claudeMd: agentClaudeMd,
+      ...(traits.hasLocalEnvironment && {
+        soulMd: agentSoulMd,
+        identityMd: agentIdentityMd,
+        toolsMd: agentToolsMd,
+        claudeMd: agentClaudeMd,
+      }),
       repoContext: currentRepoContext,
       slackContext: currentTaskSlackContext,
-      skillsSummary: agentSkillsSummary,
-      mcpServersSummary: agentMcpServersSummary,
+      ...(traits.hasMcp && {
+        skillsSummary: agentSkillsSummary,
+        mcpServersSummary: agentMcpServersSummary,
+      }),
     });
   };
 
@@ -2738,7 +2845,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           }
 
           // Build prompt with resume context + memory injection
-          let resumePrompt = await buildResumePrompt(task, adapter.formatCommand.bind(adapter));
+          let resumePrompt = await buildResumePrompt(task, adapter.formatCommand.bind(adapter), {
+            hasMcp: adapter.traits.hasMcp,
+          });
 
           // Inject relevant memories for resumed tasks
           const resumeMemoryContext = await fetchRelevantMemories(
@@ -2841,6 +2950,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
                 taskId: task.id,
                 model: (task as { model?: string }).model,
                 cwd: resumeCwd,
+                vcsRepo: task.vcsRepo,
               },
               logDir,
               isYolo,
@@ -2887,6 +2997,11 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       }
     }
 
+    // Phase 4 — exponential back-off state for `budget_refused` triggers.
+    // Resets to 0 on any non-refused outcome. Lives outside the loop so
+    // state persists across iterations.
+    let consecutiveBudgetRefusals = 0;
+
     // Track last finished task check for leads (to avoid re-processing)
     while (true) {
       // Ping server on each iteration to keep status updated
@@ -2957,6 +3072,36 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         });
 
         if (trigger) {
+          // Phase 4 — server refused to admit a claim because the agent or
+          // global budget is exhausted. Log a structured payload (scrubbed
+          // at egress per project convention) and back off exponentially.
+          // We deliberately `continue` BEFORE the empty-poll counter logic
+          // below — refusals are not empty polls.
+          if (trigger.type === "budget_refused") {
+            consecutiveBudgetRefusals++;
+            const backoffMs = computeBudgetBackoffMs(consecutiveBudgetRefusals, PollIntervalMs);
+            const refusalPayload = JSON.stringify({
+              event: "budget_refused",
+              cause: trigger.cause,
+              agentSpend: trigger.agentSpend,
+              agentBudget: trigger.agentBudget,
+              globalSpend: trigger.globalSpend,
+              globalBudget: trigger.globalBudget,
+              resetAt: trigger.resetAt,
+              consecutiveRefusals: consecutiveBudgetRefusals,
+              backoffMs,
+            });
+            console.log(
+              `[${role}] budget_refused — backing off ${backoffMs}ms: ${scrubSecrets(refusalPayload)}`,
+            );
+            await Bun.sleep(backoffMs);
+            continue;
+          }
+
+          // Any other non-null trigger means we're being admitted normally —
+          // reset the back-off so the next refusal starts at base interval.
+          consecutiveBudgetRefusals = 0;
+
           console.log(`[${role}] Trigger received: ${trigger.type}`);
 
           if (
@@ -2985,6 +3130,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
             trigger,
             prompt,
             adapter.formatCommand.bind(adapter),
+            { hasMcp: adapter.traits.hasMcp },
           );
 
           // Enrich prompt with relevant memories from past sessions
@@ -3147,6 +3293,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
                 taskId: trigger.taskId,
                 model: taskModel,
                 cwd: effectiveCwd,
+                vcsRepo: taskVcsRepo,
               },
               logDir,
               isYolo,

package/src/commands/templates.ts

@@ -111,14 +111,16 @@ Task: "{{task_description}}"
 Previous Progress:
 {{progress}}
 
-Continue from where you left off. Review the progress above and complete the remaining work.
-
-When done, use \`store-progress\` with status: "completed" and include your output.`,
+Continue from where you left off. Review the progress above and complete the remaining work.{{completion_instructions}}`,
   variables: [
     { name: "work_on_task_cmd", description: "Formatted /work-on-task command" },
     { name: "task_id", description: "Task ID" },
     { name: "task_description", description: "Original task description" },
     { name: "progress", description: "Previous progress text" },
+    {
+      name: "completion_instructions",
+      description: "Completion instructions (empty for providers without MCP)",
+    },
   ],
   category: "task_lifecycle",
 });
@@ -132,13 +134,15 @@ registerTemplate({
 
 Task: "{{task_description}}"
 
-No progress was saved before the interruption. Start the task fresh but be aware files may have been partially modified.
-
-When done, use \`store-progress\` with status: "completed" and include your output.`,
+No progress was saved before the interruption. Start the task fresh but be aware files may have been partially modified.{{completion_instructions}}`,
   variables: [
     { name: "work_on_task_cmd", description: "Formatted /work-on-task command" },
     { name: "task_id", description: "Task ID" },
     { name: "task_description", description: "Original task description" },
+    {
+      name: "completion_instructions",
+      description: "Completion instructions (empty for providers without MCP)",
+    },
   ],
   category: "task_lifecycle",
 });

package/src/http/budgets.ts

@@ -0,0 +1,219 @@
+// Phase 6: REST CRUD for daily USD budgets per (scope, scopeId).
+//
+// Auth defaults to apiKey via the `route()` factory (existing convention).
+// Every PUT and DELETE writes a row to `agent_log` with eventType
+// `budget.upserted` / `budget.deleted` so compliance reviewers can audit
+// "who set what budget when". The raw API key is NEVER logged — we record a
+// short SHA-256 fingerprint instead, scrubbed via `scrubSecrets` for safety.
+
+import { createHash } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  createLogEntry,
+  deleteBudget,
+  getBudget,
+  getBudgets,
+  getRecentBudgetRefusalNotifications,
+  upsertBudget,
+} from "../be/db";
+import { BudgetRefusalNotificationSchema, BudgetSchema, BudgetScopeSchema } from "../types";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Short SHA-256 fingerprint of the bearer token for audit-log purposes. Never
+ * logs the raw key — only the first 8 hex chars of the digest. Defense in
+ * depth: also runs the result through `scrubSecrets` so any future change
+ * that accidentally puts the raw key here cannot leak it through logs.
+ */
+function apiKeyFingerprint(req: IncomingMessage): string {
+  const authHeader = req.headers.authorization;
+  const providedKey = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+  if (!providedKey) return "";
+  const digest = createHash("sha256").update(providedKey).digest("hex").slice(0, 8);
+  return scrubSecrets(digest);
+}
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const ScopeIdSchema = z
+  .string()
+  .max(255)
+  .describe("Scope identifier — empty string for global, agent UUID otherwise");
+
+const listBudgets = route({
+  method: "get",
+  path: "/api/budgets",
+  pattern: ["api", "budgets"],
+  summary: "List all configured budget rows",
+  tags: ["Budgets"],
+  responses: {
+    200: { description: "Budget list", schema: z.object({ budgets: z.array(BudgetSchema) }) },
+  },
+});
+
+const listBudgetRefusals = route({
+  method: "get",
+  path: "/api/budgets/refusals",
+  pattern: ["api", "budgets", "refusals"],
+  summary: "List recent budget refusal notifications",
+  tags: ["Budgets"],
+  query: z.object({
+    limit: z.coerce.number().int().positive().max(500).optional(),
+  }),
+  responses: {
+    200: {
+      description: "Recent budget refusals (newest first)",
+      schema: z.object({ refusals: z.array(BudgetRefusalNotificationSchema) }),
+    },
+  },
+});
+
+const getBudgetByScope = route({
+  method: "get",
+  path: "/api/budgets/{scope}/{scopeId}",
+  pattern: ["api", "budgets", null, null],
+  summary: "Get a single budget row",
+  tags: ["Budgets"],
+  params: z.object({ scope: BudgetScopeSchema, scopeId: ScopeIdSchema }),
+  responses: {
+    200: { description: "Budget row", schema: BudgetSchema },
+    404: { description: "Budget not configured" },
+  },
+});
+
+const upsertBudgetRoute = route({
+  method: "put",
+  path: "/api/budgets/{scope}/{scopeId}",
+  pattern: ["api", "budgets", null, null],
+  summary: "Create or update a budget row",
+  tags: ["Budgets"],
+  params: z.object({ scope: BudgetScopeSchema, scopeId: ScopeIdSchema }),
+  body: z.object({
+    dailyBudgetUsd: z.number().nonnegative(),
+  }),
+  responses: {
+    200: { description: "Budget upserted", schema: BudgetSchema },
+    400: { description: "Validation error" },
+  },
+});
+
+const deleteBudgetRoute = route({
+  method: "delete",
+  path: "/api/budgets/{scope}/{scopeId}",
+  pattern: ["api", "budgets", null, null],
+  summary: "Delete a budget row",
+  tags: ["Budgets"],
+  params: z.object({ scope: BudgetScopeSchema, scopeId: ScopeIdSchema }),
+  responses: {
+    204: { description: "Budget deleted" },
+    404: { description: "Budget not configured" },
+  },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleBudgets(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+  _myAgentId: string | undefined,
+): Promise<boolean> {
+  // GET /api/budgets — list
+  if (listBudgets.match(req.method, pathSegments)) {
+    const parsed = await listBudgets.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    json(res, { budgets: getBudgets() });
+    return true;
+  }
+
+  // GET /api/budgets/refusals — must come BEFORE the {scope}/{scopeId} routes
+  // since those use a 4-segment pattern; this is 3 segments so they are
+  // disjoint, but conceptually the literal must win over the wildcards.
+  if (listBudgetRefusals.match(req.method, pathSegments)) {
+    const parsed = await listBudgetRefusals.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const limit = parsed.query.limit ?? 50;
+    json(res, { refusals: getRecentBudgetRefusalNotifications(limit) });
+    return true;
+  }
+
+  // The single-row routes share the pattern `["api", "budgets", :scope, :scopeId]`.
+  // URL-encoded empty `scopeId` ('') is used for the global scope; the
+  // route-def `pattern` already requires a non-empty segment, so callers
+  // targeting global must pass `'-'` or any non-empty placeholder. To support
+  // the spec's "scopeId='' for global" we accept the literal `_global` and
+  // map it back here.
+  // Note: HTTP path segments cannot be empty strings (filter(Boolean) drops
+  // them), so we use `_global` as the wire-format placeholder.
+
+  if (getBudgetByScope.match(req.method, pathSegments)) {
+    const parsed = await getBudgetByScope.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const scopeId = parsed.params.scopeId === "_global" ? "" : parsed.params.scopeId;
+    const row = getBudget(parsed.params.scope, scopeId);
+    if (!row) {
+      jsonError(res, "Budget not configured", 404);
+      return true;
+    }
+    json(res, row);
+    return true;
+  }
+
+  if (upsertBudgetRoute.match(req.method, pathSegments)) {
+    const parsed = await upsertBudgetRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const scopeId = parsed.params.scopeId === "_global" ? "" : parsed.params.scopeId;
+
+    const before = getBudget(parsed.params.scope, scopeId);
+    const updated = upsertBudget(parsed.params.scope, scopeId, parsed.body.dailyBudgetUsd);
+
+    createLogEntry({
+      eventType: "budget.upserted",
+      metadata: {
+        scope: parsed.params.scope,
+        scopeId,
+        before: before ? { dailyBudgetUsd: before.dailyBudgetUsd } : null,
+        after: { dailyBudgetUsd: updated.dailyBudgetUsd },
+        apiKeyFingerprint: apiKeyFingerprint(req),
+      },
+    });
+
+    json(res, updated);
+    return true;
+  }
+
+  if (deleteBudgetRoute.match(req.method, pathSegments)) {
+    const parsed = await deleteBudgetRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const scopeId = parsed.params.scopeId === "_global" ? "" : parsed.params.scopeId;
+
+    const before = getBudget(parsed.params.scope, scopeId);
+    const deleted = deleteBudget(parsed.params.scope, scopeId);
+    if (!deleted) {
+      jsonError(res, "Budget not configured", 404);
+      return true;
+    }
+
+    createLogEntry({
+      eventType: "budget.deleted",
+      metadata: {
+        scope: parsed.params.scope,
+        scopeId,
+        before: before ? { dailyBudgetUsd: before.dailyBudgetUsd } : null,
+        apiKeyFingerprint: apiKeyFingerprint(req),
+      },
+    });
+
+    res.writeHead(204);
+    res.end();
+    return true;
+  }
+
+  return false;
+}