@desplega.ai/agent-swarm 1.92.2 → 1.94.0

package/src/tests/approval-requests.test.ts

@@ -577,11 +577,8 @@ describe("Approval Requests", () => {
       });
 
       expect(result.status).toBe("success");
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).async).toBe(true);
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).waitFor).toBe("approval.resolved");
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).correlationId).toBeTruthy();
 
       // Verify the request was created in DB
@@ -616,9 +613,7 @@ describe("Approval Requests", () => {
       });
 
       expect(result.status).toBe("success");
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).async).toBe(true);
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).correlationId).toBe(existingId);
     });
 
@@ -650,7 +645,6 @@ describe("Approval Requests", () => {
       });
 
       expect(result.status).toBe("success");
-      // biome-ignore lint/suspicious/noExplicitAny: test assertion on untyped executor result
       expect((result as any).async).toBeUndefined();
       expect(result.output).toBeDefined();
       expect(result.output!.requestId).toBe(existingId);

package/src/tests/aws-error-classifier.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for `classifyAwsSdkError` in `src/utils/aws-error-classifier.ts`.
+ *
+ * Exercises all four error categories and the no-match path.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { classifyAwsSdkError } from "../utils/aws-error-classifier";
+
+describe("classifyAwsSdkError — aws-auth", () => {
+  test("ExpiredTokenException", () => {
+    const r = classifyAwsSdkError(
+      "ExpiredTokenException: The security token included in the request is expired",
+    );
+    expect(r).not.toBeNull();
+    expect(r!.category).toBe("aws-auth");
+    expect(r!.message).toContain("aws sso login");
+  });
+
+  test("ExpiredToken (without Exception suffix)", () => {
+    const r = classifyAwsSdkError("ExpiredToken: token expired");
+    expect(r?.category).toBe("aws-auth");
+  });
+
+  test("CredentialsProviderError", () => {
+    const r = classifyAwsSdkError("CredentialsProviderError: Could not load credentials");
+    expect(r?.category).toBe("aws-auth");
+  });
+
+  test("Unable to locate credentials", () => {
+    const r = classifyAwsSdkError(
+      'Unable to locate credentials. You can configure credentials by running "aws configure".',
+    );
+    expect(r?.category).toBe("aws-auth");
+  });
+
+  test("security token ... expired (lower-case)", () => {
+    const r = classifyAwsSdkError("The security token included in the request is expired");
+    expect(r?.category).toBe("aws-auth");
+  });
+
+  test("InvalidSignatureException", () => {
+    const r = classifyAwsSdkError(
+      "InvalidSignatureException: The request signature we calculated does not match the signature you provided",
+    );
+    expect(r?.category).toBe("aws-auth");
+  });
+
+  test("UnrecognizedClientException", () => {
+    const r = classifyAwsSdkError(
+      "UnrecognizedClientException: The security token included in the request is invalid",
+    );
+    expect(r?.category).toBe("aws-auth");
+  });
+});
+
+describe("classifyAwsSdkError — aws-throttle", () => {
+  test("ThrottlingException", () => {
+    const r = classifyAwsSdkError("ThrottlingException: Rate exceeded");
+    expect(r?.category).toBe("aws-throttle");
+    expect(r!.message).toContain("quota");
+  });
+
+  test("TooManyRequestsException", () => {
+    const r = classifyAwsSdkError("TooManyRequestsException: Too many requests");
+    expect(r?.category).toBe("aws-throttle");
+  });
+
+  test("ServiceQuotaExceededException", () => {
+    const r = classifyAwsSdkError(
+      "ServiceQuotaExceededException: You have exceeded your request quota for this service",
+    );
+    expect(r?.category).toBe("aws-throttle");
+  });
+
+  test("Rate exceeded (standalone phrase)", () => {
+    const r = classifyAwsSdkError("Rate exceeded. Reduce your request rate.");
+    expect(r?.category).toBe("aws-throttle");
+  });
+});
+
+describe("classifyAwsSdkError — aws-access", () => {
+  test("AccessDeniedException with bedrock:InvokeModel", () => {
+    const r = classifyAwsSdkError(
+      "AccessDeniedException: User: arn:aws:iam::123:user/dev is not authorized to perform: bedrock:InvokeModel on resource: arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-v2",
+    );
+    expect(r?.category).toBe("aws-access");
+    expect(r!.message).toContain("bedrock:InvokeModel");
+  });
+
+  test("not authorized to perform (phrase match)", () => {
+    const r = classifyAwsSdkError("User is not authorized to perform: bedrock:InvokeModel");
+    expect(r?.category).toBe("aws-access");
+  });
+});
+
+describe("classifyAwsSdkError — aws-model", () => {
+  test("ValidationException", () => {
+    const r = classifyAwsSdkError(
+      "ValidationException: Invocation of model ID anthropic.claude-v99 with on-demand throughput isn't supported",
+    );
+    expect(r?.category).toBe("aws-model");
+    expect(r!.message).toContain("MODEL_OVERRIDE");
+  });
+
+  test("ResourceNotFoundException", () => {
+    const r = classifyAwsSdkError("ResourceNotFoundException: Could not find model");
+    expect(r?.category).toBe("aws-model");
+  });
+
+  test("ModelTimeoutException", () => {
+    const r = classifyAwsSdkError(
+      "ModelTimeoutException: The model timed out processing your request",
+    );
+    expect(r?.category).toBe("aws-model");
+  });
+
+  test("ModelNotReadyException", () => {
+    const r = classifyAwsSdkError("ModelNotReadyException: The model is not ready for inference");
+    expect(r?.category).toBe("aws-model");
+  });
+});
+
+describe("classifyAwsSdkError — priority ordering", () => {
+  test("aws-auth wins over aws-model when both match (ExpiredToken + ValidationException)", () => {
+    // Should not happen in practice, but priority must be deterministic
+    const r = classifyAwsSdkError("ExpiredTokenException and also ValidationException");
+    expect(r?.category).toBe("aws-auth");
+  });
+});
+
+describe("classifyAwsSdkError — no-match", () => {
+  test("returns null for empty string", () => {
+    expect(classifyAwsSdkError("")).toBeNull();
+  });
+
+  test("returns null for unrelated error", () => {
+    expect(classifyAwsSdkError("TypeError: Cannot read property 'foo' of undefined")).toBeNull();
+  });
+
+  test("returns null for generic network error", () => {
+    expect(classifyAwsSdkError("ECONNREFUSED 127.0.0.1:3013")).toBeNull();
+  });
+
+  test("returns null for Claude API error (not AWS)", () => {
+    expect(classifyAwsSdkError("401 Unauthorized: Invalid API key")).toBeNull();
+  });
+});

package/src/tests/claude-managed-adapter.test.ts

@@ -794,6 +794,18 @@ describe("ClaudeManagedAdapter (Phase 4) — repo provisioning + cost data", ()
   });
 
   test("CLAUDE_MANAGED_MODEL_PRICING covers sonnet, opus, haiku at minimum", () => {
+    expect(CLAUDE_MANAGED_MODEL_PRICING["claude-fable-5"]).toEqual({
+      inputPerMillion: 10.0,
+      outputPerMillion: 50.0,
+      cacheReadPerMillion: 1.0,
+      cacheWritePerMillion: 12.5,
+    });
+    expect(CLAUDE_MANAGED_MODEL_PRICING["claude-mythos-5"]).toEqual({
+      inputPerMillion: 10.0,
+      outputPerMillion: 50.0,
+      cacheReadPerMillion: 1.0,
+      cacheWritePerMillion: 12.5,
+    });
     expect(CLAUDE_MANAGED_MODEL_PRICING["claude-sonnet-4-6"]).toBeDefined();
     expect(CLAUDE_MANAGED_MODEL_PRICING["claude-opus-4-7"]).toBeDefined();
     expect(CLAUDE_MANAGED_MODEL_PRICING["claude-haiku-4-5"]).toBeDefined();

package/src/tests/claude-managed-setup.test.ts

@@ -59,7 +59,6 @@ describe("runClaudeManagedSetupFlow — happy path", () => {
     const log = mock((_msg: string) => undefined);
 
     const result = await runClaudeManagedSetupFlow(baseConfig, {
-      // biome-ignore lint/suspicious/noExplicitAny: fake client subset for mock
       client: client as any,
       fetchConfig,
       upsert,
@@ -132,7 +131,6 @@ describe("runClaudeManagedSetupFlow — happy path", () => {
     await runClaudeManagedSetupFlow(
       { ...baseConfig, mcpBaseUrl: "https://swarm.example.com/" },
       {
-        // biome-ignore lint/suspicious/noExplicitAny: fake client subset for mock
         client: client as any,
         fetchConfig: mock(async () => null),
         upsert: mock(async () => undefined),
@@ -175,7 +173,6 @@ describe("runClaudeManagedSetupFlow — idempotent re-run", () => {
     const uploadOne = mock(async () => null);
 
     const result = await runClaudeManagedSetupFlow(baseConfig, {
-      // biome-ignore lint/suspicious/noExplicitAny: fake client subset for mock
       client: client as any,
       fetchConfig,
       upsert,
@@ -208,7 +205,6 @@ describe("runClaudeManagedSetupFlow — idempotent re-run", () => {
     await runClaudeManagedSetupFlow(
       { ...baseConfig, force: true },
       {
-        // biome-ignore lint/suspicious/noExplicitAny: fake client subset for mock
         client: client as any,
         fetchConfig,
         upsert,

package/src/tests/codex-pool.test.ts

@@ -24,11 +24,7 @@ import {
   credentialsToAuthJson,
 } from "../providers/codex-oauth/auth-json.js";
 import { materializeCodexAuthJson } from "../providers/codex-oauth/auth-json-fs.js";
-import {
-  loadAllCodexOAuthSlots,
-  persistCodexOAuth,
-  storeCodexOAuth,
-} from "../providers/codex-oauth/storage.js";
+import { loadAllCodexOAuthSlots, persistCodexOAuth } from "../providers/codex-oauth/storage.js";
 import type { CodexOAuthCredentials } from "../providers/codex-oauth/types.js";
 
 // ─── Fixtures ────────────────────────────────────────────────────────────────
@@ -117,7 +113,7 @@ afterEach(() => {
 describe("Scenario 1 — 3-slot round-trip with availability filter", () => {
   it("selects from available slots [1,2] and materialises the correct creds into auth.json", async () => {
     // Mock API: three slots in config store.
-    globalThis.fetch = async (url: string | URL | Request) => {
+    globalThis.fetch = async (_url: string | URL | Request) => {
       return makeConfigResponse();
       // (available-indices endpoint not called by loadAllCodexOAuthSlots)
     };

package/src/tests/context-window.test.ts

@@ -8,6 +8,13 @@ import {
 } from "../utils/context-window";
 
 describe("getContextWindowSize", () => {
+  test("returns 1M for fable and mythos models", () => {
+    expect(getContextWindowSize("claude-fable-5")).toBe(1_000_000);
+    expect(getContextWindowSize("claude-mythos-5")).toBe(1_000_000);
+    expect(getContextWindowSize("fable")).toBe(1_000_000);
+    expect(getContextWindowSize("mythos")).toBe(1_000_000);
+  });
+
   test("returns 1M for opus models", () => {
     expect(getContextWindowSize("claude-opus-4-8")).toBe(1_000_000);
     expect(getContextWindowSize("claude-opus-4-7")).toBe(1_000_000);

package/src/tests/http-api-integration.test.ts

@@ -25,7 +25,6 @@ async function api(
   method: string,
   path: string,
   opts: { body?: unknown; agentId?: string; headers?: Record<string, string> } = {},
-  // biome-ignore lint/suspicious/noExplicitAny: test helper needs flexible body type
 ): Promise<{ status: number; body: any; ok: boolean }> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
@@ -41,7 +40,6 @@ async function api(
   });
 
   const text = await res.text();
-  // biome-ignore lint/suspicious/noExplicitAny: body can be parsed JSON or raw text
   let body: any;
   try {
     body = JSON.parse(text);
@@ -427,9 +425,9 @@ describe("Tasks", () => {
     expect(status).toBe(404);
   });
 
-  test("PUT /api/tasks/:id/claude-session — update session ID", async () => {
+  test("PUT /api/tasks/:id/session — update session ID", async () => {
     const sessionId = randomUUID();
-    const { status, body } = await put(`/api/tasks/${ids.task2}/claude-session`, {
+    const { status, body } = await put(`/api/tasks/${ids.task2}/session`, {
       agentId: ids.workerAgent,
       body: { claudeSessionId: sessionId },
     });
@@ -437,8 +435,8 @@ describe("Tasks", () => {
     expect(body.claudeSessionId).toBe(sessionId);
   });
 
-  test("PUT /api/tasks/:id/claude-session — missing fields returns 400", async () => {
-    const { status } = await put(`/api/tasks/${ids.task2}/claude-session`, {
+  test("PUT /api/tasks/:id/session — missing fields returns 400", async () => {
+    const { status } = await put(`/api/tasks/${ids.task2}/session`, {
       body: {},
     });
     expect(status).toBe(400);
@@ -1014,6 +1012,25 @@ describe("Schedule CRUD", () => {
     expect(body.task.id).toBeDefined();
   });
 
+  test("POST /api/schedules/:id/run — propagates modelTier to the created task", async () => {
+    const { body: created } = await post("/api/schedules", {
+      body: {
+        name: "model-tier-manual-run",
+        taskTemplate: "Run model tier integration test",
+        cronExpression: "0 * * * *",
+        modelTier: "smart",
+      },
+    });
+
+    const { status, body } = await post(`/api/schedules/${created.id}/run`);
+    expect(status).toBe(200);
+    expect(body.task).toBeDefined();
+    expect(body.task.model).toBeUndefined();
+    expect(body.task.modelTier).toBe("smart");
+
+    await del(`/api/schedules/${created.id}`);
+  });
+
   test("POST /api/schedules/:id/run — disabled schedule returns 400", async () => {
     // Disable the schedule first
     await put(`/api/schedules/${scheduleId}`, {

package/src/tests/memory-edges.test.ts

@@ -48,7 +48,6 @@ async function api(
   method: string,
   path: string,
   opts: { body?: unknown; agentId?: string } = {},
-  // biome-ignore lint/suspicious/noExplicitAny: test helper
 ): Promise<{ status: number; body: any }> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
@@ -61,7 +60,6 @@ async function api(
     body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
   });
   const text = await res.text();
-  // biome-ignore lint/suspicious/noExplicitAny: body may be JSON or text
   let body: any;
   try {
     body = JSON.parse(text);

package/src/tests/memory-rate-endpoint.test.ts

@@ -41,7 +41,6 @@ async function api(
   method: string,
   path: string,
   opts: { body?: unknown; agentId?: string } = {},
-  // biome-ignore lint/suspicious/noExplicitAny: test helper
 ): Promise<{ status: number; body: any }> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
@@ -54,7 +53,6 @@ async function api(
     body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
   });
   const text = await res.text();
-  // biome-ignore lint/suspicious/noExplicitAny: body may be JSON or text
   let body: any;
   try {
     body = JSON.parse(text);

package/src/tests/memory-rater-e2e.test.ts

@@ -64,7 +64,6 @@ async function api(
   method: string,
   path: string,
   opts: { body?: unknown; agentId?: string; sourceTaskId?: string } = {},
-  // biome-ignore lint/suspicious/noExplicitAny: test helper
 ): Promise<{ status: number; body: any }> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
@@ -78,7 +77,6 @@ async function api(
     body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
   });
   const text = await res.text();
-  // biome-ignore lint/suspicious/noExplicitAny: body may be JSON or text
   let body: any;
   try {
     body = JSON.parse(text);

package/src/tests/memory-store.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
-import { closeDb, createAgent, getDb, initDb } from "../be/db";
+import { closeDb, createAgent, getDb, initDb, isSqliteVecAvailable } from "../be/db";
 import { serializeEmbedding } from "../be/embedding";
 import { SqliteMemoryStore } from "../be/memory/providers/sqlite-store";
 
@@ -19,6 +19,16 @@ describe("SqliteMemoryStore", () => {
     return embedding;
   }
 
+  function skipVecAssertionsWhenUnavailable(): boolean {
+    if (isSqliteVecAvailable()) return false;
+
+    const health = store.getHealth();
+    expect(health.sqliteVec.extensionLoaded).toBe(false);
+    expect(health.retrievalMode).toBe("fallback");
+    expect(health.reasons).toContain("sqlite_vec_extension_unavailable");
+    return true;
+  }
+
   beforeAll(async () => {
     for (const suffix of ["", "-wal", "-shm"]) {
       try {
@@ -221,6 +231,8 @@ describe("SqliteMemoryStore", () => {
     });
 
     test("uses sqlite-vec for 512d embeddings with scope-filter parity", () => {
+      if (skipVecAssertionsWhenUnavailable()) return;
+
       for (let i = 0; i < 6; i++) {
         const otherAgent = store.store({
           agentId: agentB,
@@ -256,6 +268,8 @@ describe("SqliteMemoryStore", () => {
 
   describe("memory_vec population", () => {
     test("populates existing embeddings on startup and reports health counts", () => {
+      if (skipVecAssertionsWhenUnavailable()) return;
+
       const raw = store.store({
         agentId: agentA,
         scope: "agent",
@@ -282,6 +296,8 @@ describe("SqliteMemoryStore", () => {
     });
 
     test("rebuilds an old non-cosine memory_vec table from agent_memory", () => {
+      if (skipVecAssertionsWhenUnavailable()) return;
+
       const raw = store.store({
         agentId: agentA,
         scope: "agent",
@@ -473,6 +489,8 @@ describe("SqliteMemoryStore", () => {
     });
 
     test("also removes corresponding vec rows", () => {
+      if (skipVecAssertionsWhenUnavailable()) return;
+
       const db = getDb();
       const emb = vector({ 0: 0.9, 100: 0.1 });
 

package/src/tests/memory.test.ts

@@ -479,6 +479,57 @@ describe("Memory System", () => {
       const page2 = store.list(listAgent, { scope: "agent", limit: 3, offset: 3 });
       expect(page2.length).toBe(2);
     });
+
+    test("counts memories with the same filters used by list", () => {
+      const countAgent = "eeee0000-0000-4000-8000-000000000105";
+      createAgent({ id: countAgent, name: "Count Agent", isLead: false, status: "idle" });
+
+      store.store({
+        agentId: countAgent,
+        scope: "agent",
+        name: "Count match 1",
+        content: "Content",
+        source: "file_index",
+        sourcePath: "/workspace/src/MemoryPage.tsx",
+      });
+      store.store({
+        agentId: countAgent,
+        scope: "swarm",
+        name: "Count match 2",
+        content: "Content",
+        source: "file_index",
+        sourcePath: "/workspace/SRC/memory-page.tsx",
+      });
+      store.store({
+        agentId: countAgent,
+        scope: "agent",
+        name: "Wrong source",
+        content: "Content",
+        source: "manual",
+        sourcePath: "/workspace/src/MemoryPage.tsx",
+      });
+      store.store({
+        agentId: agentA,
+        scope: "agent",
+        name: "Wrong owner",
+        content: "Content",
+        source: "file_index",
+        sourcePath: "/workspace/src/MemoryPage.tsx",
+      });
+
+      const filters = {
+        scope: "all" as const,
+        isLead: true,
+        ownerAgentId: countAgent,
+        source: "file_index" as const,
+        sourcePath: "src/memory",
+      };
+
+      expect(store.count("", filters)).toBe(2);
+      expect(store.list("", { ...filters, limit: 1, offset: 0 })).toHaveLength(1);
+      expect(store.list("", { ...filters, limit: 1, offset: 1 })).toHaveLength(1);
+      expect(store.list("", { ...filters, limit: 1, offset: 2 })).toHaveLength(0);
+    });
   });
 
   describe("store.delete (deleteMemory)", () => {

package/src/tests/metrics-http.test.ts

@@ -76,7 +76,60 @@ describe("Metrics HTTP API", () => {
     const body = (await res.json()) as { metrics: Metric[]; total: number };
     expect(body.total).toBeGreaterThanOrEqual(1);
     const starter = body.metrics.find((metric) => metric.slug === "swarm-operations-overview");
-    expect(starter?.definition.widgets.map((widget) => widget.viz.type)).toContain("multi-line");
+    expect(starter?.definition.layout?.columns).toBe(3);
+    expect(starter?.definition.widgets.map((widget) => widget.id)).toEqual([
+      "tasks-created-per-day",
+      "usage-by-user",
+      "usage-by-model",
+      "avg-cost-per-task-by-model",
+      "avg-task-time-by-model",
+      "cost-per-minute-by-model",
+      "cost-per-minute-by-agent",
+      "agent-performance",
+      "task-outcomes-by-day",
+      "recent-task-outcomes",
+    ]);
+    expect(
+      starter?.definition.variables?.find((variable) => variable.key === "userFilter"),
+    ).toMatchObject({
+      type: "select",
+      defaultValue: "all",
+      optionsQuery: { valueKey: "id", labelKey: "label" },
+    });
+    expect(
+      starter?.definition.variables?.find((variable) => variable.key === "agentFilter"),
+    ).toMatchObject({
+      type: "select",
+      defaultValue: "all",
+      optionsQuery: { valueKey: "id", labelKey: "label" },
+    });
+
+    const run = await fetch(`${BASE}/api/metrics/definitions/${starter!.id}/run`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ variables: {} }),
+    });
+    expect(run.status).toBe(200);
+    const runBody = (await run.json()) as MetricRunResponse & {
+      metric: Metric;
+      variables: Record<string, string>;
+    };
+    expect(runBody.variables.userFilter).toBe("all");
+    expect(runBody.variables.agentFilter).toBe("all");
+    expect(
+      runBody.metric.definition.variables?.find((variable) => variable.key === "userFilter")
+        ?.options?.[0],
+    ).toEqual({
+      label: "All requesters",
+      value: "all",
+    });
+    expect(
+      runBody.metric.definition.variables?.find((variable) => variable.key === "agentFilter")
+        ?.options?.[0],
+    ).toEqual({
+      label: "All agents",
+      value: "all",
+    });
   });
 
   test("create, run, update snapshots prior definition", async () => {
@@ -221,8 +274,79 @@ describe("Metrics HTTP API", () => {
     expect(runBody.widgets[0]?.result.rows[0]).toHaveProperty("count");
   });
 
+  test("run resolves dynamic select variable options from read-only SQL", async () => {
+    const created = await fetch(`${BASE}/api/metrics/definitions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug: "dynamic-variable-options",
+        title: "Dynamic Variable Options",
+        definition: {
+          version: 1,
+          variables: [
+            {
+              key: "agent",
+              label: "Agent",
+              type: "select",
+              optionsQuery: {
+                sql: "SELECT 'agent-a' AS id, 'Agent A' AS name UNION ALL SELECT 'agent-b' AS id, 'Agent B' AS name",
+                valueKey: "id",
+                labelKey: "name",
+              },
+            },
+          ],
+          widgets: [
+            {
+              id: "selected-agent",
+              title: "Selected agent",
+              query: {
+                sql: "SELECT ? AS agent",
+                params: ["{{agent}}"],
+                maxRows: 10,
+              },
+              viz: { type: "table", columns: [{ key: "agent", label: "Agent" }] },
+            },
+          ],
+        },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string; version: number };
+
+    const run = await fetch(`${BASE}/api/metrics/definitions/${id}/run`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ variables: { agent: "agent-b" } }),
+    });
+    expect(run.status).toBe(200);
+    const runBody = (await run.json()) as MetricRunResponse & {
+      metric: Metric;
+      variables: Record<string, string>;
+    };
+    expect(runBody.variables.agent).toBe("agent-b");
+    expect(runBody.metric.definition.variables?.[0]?.options).toEqual([
+      { label: "Agent A", value: "agent-a" },
+      { label: "Agent B", value: "agent-b" },
+    ]);
+    expect(runBody.widgets[0]?.result.rows[0]).toEqual({ agent: "agent-b" });
+
+    const defaultedRun = await fetch(`${BASE}/api/metrics/definitions/${id}/run`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ variables: {} }),
+    });
+    expect(defaultedRun.status).toBe(200);
+    const defaultedBody = (await defaultedRun.json()) as { variables: Record<string, string> };
+    expect(defaultedBody.variables.agent).toBe("agent-a");
+  });
+
   test("saved metric SQL rejects writes and multiple statements", async () => {
-    for (const sql of ["DELETE FROM agent_tasks", "SELECT 1; SELECT 2"]) {
+    for (const [sql, target] of [
+      ["DELETE FROM agent_tasks", "widget"],
+      ["SELECT 1; SELECT 2", "widget"],
+      ["DELETE FROM agents", "variable"],
+      ["SELECT 1; SELECT 2", "variable"],
+    ] as const) {
       const res = await fetch(`${BASE}/api/metrics/definitions`, {
         method: "POST",
         headers,
@@ -230,11 +354,21 @@ describe("Metrics HTTP API", () => {
           title: "Bad Metric",
           definition: {
             version: 1,
+            variables:
+              target === "variable"
+                ? [
+                    {
+                      key: "agent",
+                      type: "select",
+                      optionsQuery: { sql, valueKey: "id" },
+                    },
+                  ]
+                : undefined,
             widgets: [
               {
                 id: "bad",
                 title: "Bad",
-                query: { sql },
+                query: { sql: target === "widget" ? sql : "SELECT 1 AS x" },
                 viz: { type: "stat", value: "x" },
               },
             ],