@desplega.ai/agent-swarm 2.5.4 → 2.6.0

package/src/tests/provider-key-probes.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { checkProviderPoolKey } from "../utils/provider-key-probes";
+
+describe("API pool key probes", () => {
+  const realFetch = globalThis.fetch;
+  const originalNodeEnv = process.env.NODE_ENV;
+  const originalPrivateUrls = process.env.ALLOW_PRIVATE_NETWORK_URLS;
+
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+    if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+    else process.env.NODE_ENV = originalNodeEnv;
+    if (originalPrivateUrls === undefined) delete process.env.ALLOW_PRIVATE_NETWORK_URLS;
+    else process.env.ALLOW_PRIVATE_NETWORK_URLS = originalPrivateUrls;
+  });
+
+  test("uses the supplied OpenRouter URL and forbids redirects", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init });
+      return new Response("{}", { status: calls.length === 1 ? 404 : 200 });
+    }) as typeof fetch;
+    expect(
+      await checkProviderPoolKey("OPENROUTER_API_KEY", "fake-abcde", {
+        OPENROUTER_BASE_URL: "https://gateway.example/v1/",
+      }),
+    ).toMatchObject({ ok: true });
+    expect(calls.map((call) => call.url)).toEqual([
+      "https://gateway.example/v1/key",
+      "https://gateway.example/v1/models",
+    ]);
+    expect(calls.every((call) => call.init?.redirect === "manual")).toBe(true);
+  });
+
+  test("rejects a private registry URL before sending credentials", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.ALLOW_PRIVATE_NETWORK_URLS;
+    const fetch = mock(async () => new Response("{}"));
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch;
+    const result = await checkProviderPoolKey("NAN_API_KEY", "fake-abcde", {
+      NAN_BASE_URL: "https://127.0.0.1/v1",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.httpStatus).toBeUndefined();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  test("supports registry aliases and configured URLs", async () => {
+    const fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toBe("https://gateway.example/v1/models");
+      expect(init?.headers).toEqual({ Authorization: "Bearer fake-abcde" });
+      expect(init?.redirect).toBe("manual");
+      return new Response("Unauthorized", { status: 401 });
+    });
+    globalThis.fetch = fetch as typeof globalThis.fetch;
+    expect(
+      await checkProviderPoolKey("HELMCODE_API_NAN", "fake-abcde", {
+        NAN_BASE_URL: "https://gateway.example/v1",
+      }),
+    ).toMatchObject({ ok: false, httpStatus: 401 });
+  });
+
+  test.each([
+    [200, "{}", true, false],
+    [403, '{"error":{"type":"permission_error"}}', true, false],
+    [403, '{"error":{"type":"other"}}', false, false],
+    [401, "Unauthorized", false, false],
+    [429, "Throttled", true, true],
+    [503, "Unavailable", true, true],
+  ])("preserves Claude OAuth semantics for HTTP %i", async (status, body, ok, skipped) => {
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      expect(String(url)).toBe("https://api.anthropic.com/api/oauth/profile");
+      expect(init?.redirect).toBe("manual");
+      expect(init?.signal).toBeInstanceOf(AbortSignal);
+      return new Response(body, { status });
+    }) as typeof fetch;
+    const result = await checkProviderPoolKey("CLAUDE_CODE_OAUTH_TOKEN", "fake-abcde", {});
+    expect(result.ok).toBe(ok);
+    expect(result.skipped === true).toBe(skipped);
+    if (!ok) expect(result.httpStatus).toBe(status);
+  });
+
+  test("checks an Anthropic key at its gateway, keeping the URL path prefix", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init });
+      return new Response("Unauthorized", { status: 401 });
+    }) as unknown as typeof fetch;
+    const result = await checkProviderPoolKey("ANTHROPIC_API_KEY", "fake-abcde", {
+      ANTHROPIC_BASE_URL: "https://gateway.example/api",
+    });
+    expect(result).toMatchObject({ ok: false, httpStatus: 401 });
+    expect(calls.map((call) => call.url)).toEqual(["https://gateway.example/api/v1/models"]);
+    expect(new Headers(calls[0]?.init?.headers).get("x-api-key")).toBe("fake-abcde");
+    expect(calls[0]?.init?.redirect).toBe("manual");
+
+    globalThis.fetch = mock(async () => new Response("{}")) as unknown as typeof fetch;
+    expect(
+      await checkProviderPoolKey("ANTHROPIC_API_KEY", "fake-abcde", {
+        ANTHROPIC_BASE_URL: "https://gateway.example/api",
+      }),
+    ).toMatchObject({ ok: true });
+  });
+
+  test("a gateway that lists no models leaves the Anthropic key unchecked", async () => {
+    globalThis.fetch = mock(
+      async () => new Response("Not found", { status: 404 }),
+    ) as unknown as typeof fetch;
+    expect(
+      await checkProviderPoolKey("ANTHROPIC_API_KEY", "fake-abcde", {
+        ANTHROPIC_BASE_URL: "https://gateway.example",
+      }),
+    ).toMatchObject({ ok: true, skipped: true });
+  });
+
+  test("an Anthropic key stays on api.anthropic.com when the gateway uses ANTHROPIC_AUTH_TOKEN", async () => {
+    const urls: string[] = [];
+    globalThis.fetch = mock(async (url: string | URL | Request) => {
+      urls.push(String(url));
+      return new Response("{}");
+    }) as unknown as typeof fetch;
+    expect(
+      await checkProviderPoolKey("ANTHROPIC_API_KEY", "fake-abcde", {
+        ANTHROPIC_BASE_URL: "https://gateway.example",
+        ANTHROPIC_AUTH_TOKEN: "gateway-token",
+      }),
+    ).toMatchObject({ ok: true });
+    expect(urls).toEqual(["https://api.anthropic.com/v1/models"]);
+  });
+
+  test("a private Anthropic gateway gets no credentials and no rejection", async () => {
+    process.env.NODE_ENV = "production";
+    delete process.env.ALLOW_PRIVATE_NETWORK_URLS;
+    const fetch = mock(async () => new Response("{}"));
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch;
+    const result = await checkProviderPoolKey("ANTHROPIC_API_KEY", "fake-abcde", {
+      ANTHROPIC_BASE_URL: "http://127.0.0.1:4000",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.httpStatus).toBeUndefined();
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  test("skips keys without an API-safe probe", async () => {
+    const fetch = mock(async () => new Response("{}"));
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch;
+    for (const keyType of ["DEVIN_API_KEY", "AMP_API_KEY", "CURSOR_API_KEY"]) {
+      expect(await checkProviderPoolKey(keyType, "fake-abcde", {})).toMatchObject({
+        ok: true,
+        skipped: true,
+      });
+    }
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  test("reports network errors without exposing the submitted key", async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error("Rejected fake-abcde");
+    }) as unknown as typeof fetch;
+    const result = await checkProviderPoolKey("OPENAI_API_KEY", "fake-abcde", {});
+    expect(result.ok).toBe(false);
+    expect(result.error).not.toContain("fake-abcde");
+  });
+
+  test.each([
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    "NAN_API_KEY",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+  ])("redacts a long echoed %s before truncating the provider error", async (keyType) => {
+    const apiKey = "Z".repeat(240);
+    globalThis.fetch = mock(
+      async () => new Response(`Rejected ${apiKey}`, { status: 403 }),
+    ) as unknown as typeof fetch;
+    const result = await checkProviderPoolKey(keyType, apiKey, {});
+    expect(result).toMatchObject({ ok: false, httpStatus: 403 });
+    expect(result.error).toContain("[REDACTED]");
+    expect(result.error).not.toContain(apiKey.slice(0, 40));
+  });
+});

package/src/tests/rbac-e2e-helpers.test.ts

@@ -1,9 +1,23 @@
 import { expect, test } from "bun:test";
 import { closeSync, openSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { type SwarmServer, waitForListen } from "./rbac-e2e-helpers";
+import {
+  makeScratchDir,
+  removeScratchDir,
+  type SwarmServer,
+  spawnSwarmServer,
+  waitForListen,
+} from "./rbac-e2e-helpers";
+import {
+  getFreePort,
+  listenOnFreePort,
+  PortInUseError,
+  SERVER_BOOT_HOOK_TIMEOUT_MS,
+  startOnFreePort,
+} from "./test-net";
 
 test("waitForListen includes a bounded server log when the process exits early", async () => {
   const dir = await mkdtemp(join(tmpdir(), "rbac-e2e-helper-"));
@@ -51,3 +65,76 @@ test("waitForListen includes a bounded server log when the process exits early",
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+test("startOnFreePort retries only PortInUseError, up to its attempt bound", async () => {
+  const ports = [41001, 41002, 41003, 41004];
+  const getPort = async () => ports.shift() ?? 0;
+  const tried: number[] = [];
+
+  const port = await startOnFreePort(
+    async (p) => {
+      tried.push(p);
+      if (p === 41001) throw new PortInUseError("taken");
+      return p;
+    },
+    { getPort },
+  );
+  expect(port).toBe(41002);
+  expect(tried).toEqual([41001, 41002]);
+
+  const other = await startOnFreePort(
+    async () => {
+      throw new Error("boot crashed");
+    },
+    { getPort },
+  ).catch((error: unknown) => error);
+  expect((other as Error).message).toBe("boot crashed");
+  expect(ports).toEqual([41004]);
+
+  let calls = 0;
+  const exhausted = await startOnFreePort(
+    async () => {
+      calls++;
+      throw new PortInUseError(`taken ${calls}`);
+    },
+    { getPort: async () => 0 },
+  ).catch((error: unknown) => error);
+  expect(exhausted).toBeInstanceOf(PortInUseError);
+  expect((exhausted as Error).message).toBe("taken 3");
+  expect(calls).toBe(3);
+});
+
+test(
+  "spawnSwarmServer starts again on a new port when its first port is taken",
+  async () => {
+    const dir = await makeScratchDir();
+    const holder = createServer();
+    const heldPort = await listenOnFreePort(holder);
+    let server: SwarmServer | undefined;
+    try {
+      const offered: number[] = [];
+      server = await spawnSwarmServer({
+        dbPath: join(dir, "test.sqlite"),
+        logPath: join(dir, "server.log"),
+        getPort: async () => {
+          const port = offered.length === 0 ? heldPort : await getFreePort();
+          offered.push(port);
+          return port;
+        },
+      });
+
+      expect(offered).toHaveLength(2);
+      expect(offered[0]).toBe(heldPort);
+      expect(server.port).toBe(offered[1]);
+      expect(server.port).not.toBe(heldPort);
+      expect((await fetch(`${server.base}/docs`)).ok).toBe(true);
+      const log = await Bun.file(server.logPath).text();
+      expect(log).toContain(`Is port ${heldPort} in use?`);
+    } finally {
+      await server?.stop();
+      holder.close();
+      await removeScratchDir(dir);
+    }
+  },
+  SERVER_BOOT_HOOK_TIMEOUT_MS * 2,
+);

package/src/tests/rbac-e2e-helpers.ts

@@ -14,7 +14,7 @@ import { openSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { getFreePort } from "./test-net";
+import { getFreePort, PORT_IN_USE_LOG, PortInUseError, startOnFreePort } from "./test-net";
 
 // Re-exported for the suites that imported it from here before test-net.ts existed.
 export { getFreePort };
@@ -50,6 +50,9 @@ export async function removeScratchDir(dir: string): Promise<void> {
  * Spawn `bun src/http.ts` against `dbPath` on a free port. Integrations are
  * disabled; both API-key env vars are pinned so a developer's shell env can't
  * leak in (AGENT_SWARM_API_KEY takes precedence in getApiKey()).
+ *
+ * With waitForListen, a child that exits because another process took its
+ * port during boot is started again on a new port (startOnFreePort).
  */
 export async function spawnSwarmServer(opts: {
   dbPath: string;
@@ -57,9 +60,38 @@ export async function spawnSwarmServer(opts: {
   env?: Record<string, string>;
   /** Poll /docs until the server accepts requests (default true). */
   waitForListen?: boolean;
+  /** Port source for each attempt (default getFreePort). Tests use it to force a taken port. */
+  getPort?: () => Promise<number>;
 }): Promise<SwarmServer> {
-  const port = await getFreePort();
   const logFd = openSync(opts.logPath, "a");
+  return startOnFreePort(
+    async (port) => {
+      const log = Bun.file(opts.logPath);
+      const logStart = (await log.exists()) ? log.size : 0;
+      const server = launchSwarmServer(opts, port, logFd);
+      if (opts.waitForListen === false) return server;
+      try {
+        await waitForListen(server);
+      } catch (error) {
+        if (server.proc.exitCode !== null) {
+          const attemptLog = await Bun.file(opts.logPath).slice(logStart).text();
+          if (PORT_IN_USE_LOG.test(attemptLog)) {
+            throw new PortInUseError((error as Error).message, { cause: error });
+          }
+        }
+        throw error;
+      }
+      return server;
+    },
+    { getPort: opts.getPort },
+  );
+}
+
+function launchSwarmServer(
+  opts: { dbPath: string; logPath: string; env?: Record<string, string> },
+  port: number,
+  logFd: number,
+): SwarmServer {
   const proc = Bun.spawn(["bun", "src/http.ts"], {
     cwd: REPO_ROOT,
     stdout: logFd,
@@ -93,12 +125,10 @@ export async function spawnSwarmServer(opts: {
       ...opts.env,
     },
   });
-  const base = `http://localhost:${port}`;
-
-  const server: SwarmServer = {
+  return {
     proc,
     port,
-    base,
+    base: `http://localhost:${port}`,
     dbPath: opts.dbPath,
     logPath: opts.logPath,
     async stop() {
@@ -107,11 +137,6 @@ export async function spawnSwarmServer(opts: {
       return proc.exitCode;
     },
   };
-
-  if (opts.waitForListen !== false) {
-    await waitForListen(server);
-  }
-  return server;
 }
 
 export async function waitForListen(server: SwarmServer, deadlineMs = 90_000): Promise<void> {

package/src/tests/script-connections.test.ts

@@ -651,6 +651,8 @@ describe("script connections", () => {
       markMigrationApplied(database, "240_workflow_run_parent_step_attempt.sql");
       // 241 indexes skills, which this migration-112-only fixture does not create.
       markMigrationApplied(database, "241_skills_meta_fts.sql");
+      // 244 alters api_key_status, which this migration-112-only fixture does not create.
+      markMigrationApplied(database, "244_api_key_validation.sql");
 
       const id = crypto.randomUUID();
       const now = new Date().toISOString();

package/src/tests/script-runs-retention.test.ts

@@ -0,0 +1,212 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDbClient, initDb } from "../be/db";
+import {
+  DB_RETENTION_TABLES,
+  getDbRetentionStats,
+  resetDbRetentionForTests,
+  runDbRetentionTick,
+  sweepStatements,
+} from "../be/db-retention";
+
+const TEST_DB_PATH = "./test-script-runs-retention.sqlite";
+const DAYS_KEY = "SCRIPT_RUNS_RETENTION_DAYS";
+// With 1 day of retention the cutoff is 2026-08-22T12:00:00.000Z.
+const NOW = new Date("2026-08-23T12:00:00.000Z");
+const OLD_ISO = "2026-08-01T00:00:00.000Z";
+const OLD_SPACED = "2026-08-01 00:00:00";
+const RECENT_ISO = "2026-08-23T11:00:00.000Z";
+
+const SCRIPT_RUNS = DB_RETENTION_TABLES.find((table) => table.table === "script_runs");
+if (!SCRIPT_RUNS) throw new Error("script_runs is not in the retention allowlist");
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"])
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => undefined);
+}
+
+async function insertRun(
+  id: string,
+  status: string,
+  startedAt: string,
+  options: { kind?: "inline" | "workflow"; idempotencyKey?: string } = {},
+): Promise<void> {
+  await getDbClient().run(
+    `INSERT INTO script_runs (id, agentId, scriptName, source, args, status, startedAt, kind, idempotencyKey)
+     VALUES (?, 'agent-1', 'retention-test', 'export default () => 1', '{}', ?, ?, ?, ?)`,
+    [id, status, startedAt, options.kind ?? "inline", options.idempotencyKey ?? null],
+  );
+}
+
+async function insertJournal(runId: string, stepKey: string): Promise<void> {
+  await getDbClient().run(
+    "INSERT INTO script_run_journal (id, runId, stepKey, stepType, status) VALUES (?, ?, ?, 'tool', 'completed')",
+    [`${runId}-${stepKey}`, runId, stepKey],
+  );
+}
+
+async function runIds(): Promise<string[]> {
+  const rows = await getDbClient().query<{ id: string }>("SELECT id FROM script_runs ORDER BY id");
+  return rows.map((row) => row.id);
+}
+
+async function journalRunIds(): Promise<string[]> {
+  const rows = await getDbClient().query<{ runId: string }>(
+    "SELECT DISTINCT runId FROM script_run_journal ORDER BY runId",
+  );
+  return rows.map((row) => row.runId);
+}
+
+beforeAll(async () => {
+  closeDb();
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  await resetDbRetentionForTests();
+  delete process.env[DAYS_KEY];
+  delete process.env.DB_RETENTION_DRY_RUN;
+  closeDb();
+  await removeDbFiles();
+});
+
+beforeEach(async () => {
+  await resetDbRetentionForTests();
+  delete process.env[DAYS_KEY];
+  delete process.env.DB_RETENTION_DRY_RUN;
+  await getDbClient().run("DELETE FROM script_run_journal");
+  await getDbClient().run("DELETE FROM script_runs");
+});
+
+describe("script_runs age-based retention", () => {
+  test("is opt-in: an unset key deletes nothing", async () => {
+    await insertRun("old-completed", "completed", OLD_ISO);
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await runIds()).toEqual(["old-completed"]);
+    expect(getDbRetentionStats().scriptRuns).toBeUndefined();
+  });
+
+  test("deletes old finished runs and keeps running, paused, recent and keyed runs", async () => {
+    for (const status of ["completed", "failed", "cancelled", "aborted_limit"]) {
+      await insertRun(`old-${status}-iso`, status, OLD_ISO);
+      await insertRun(`old-${status}-spaced`, status, OLD_SPACED, { kind: "workflow" });
+    }
+    await insertRun("old-running", "running", OLD_SPACED, { kind: "workflow" });
+    await insertRun("old-paused", "paused", OLD_SPACED, { kind: "workflow" });
+    await insertRun("old-keyed", "completed", OLD_SPACED, {
+      kind: "workflow",
+      idempotencyKey: "launch-once",
+    });
+    await insertRun("recent-completed", "completed", RECENT_ISO);
+    process.env[DAYS_KEY] = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await runIds()).toEqual(["old-keyed", "old-paused", "old-running", "recent-completed"]);
+    expect(getDbRetentionStats().scriptRuns).toMatchObject({
+      rowsDeleted: 8,
+      drained: true,
+      backlogRemaining: 0,
+      dryRun: false,
+    });
+  });
+
+  test("journal rows leave with their run and stay with a surviving one", async () => {
+    await insertRun("old-done", "completed", OLD_SPACED, { kind: "workflow" });
+    await insertRun("old-paused", "paused", OLD_SPACED, { kind: "workflow" });
+    for (const step of ["a", "b", "c"]) {
+      await insertJournal("old-done", step);
+      await insertJournal("old-paused", step);
+    }
+    process.env[DAYS_KEY] = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await runIds()).toEqual(["old-paused"]);
+    expect(await journalRunIds()).toEqual(["old-paused"]);
+    const journal = await getDbClient().get<{ n: number }>(
+      "SELECT COUNT(*) AS n FROM script_run_journal",
+    );
+    expect(journal?.n).toBe(3);
+  });
+
+  test("never deletes a row early across the two stored timestamp formats", async () => {
+    // Cutoff: 2026-08-22T12:00:00.000Z, compared as '2026-08-22 12:00:00'.
+    await insertRun("spaced-before", "completed", "2026-08-22 11:59:59", { kind: "workflow" });
+    await insertRun("spaced-at", "completed", "2026-08-22 12:00:00", { kind: "workflow" });
+    await insertRun("iso-previous-day", "completed", "2026-08-21T23:59:59.999Z");
+    // Older than the cutoff, but on the cutoff's own date: kept until a later tick.
+    await insertRun("iso-cutoff-day", "completed", "2026-08-22T11:00:00.000Z");
+    await insertRun("iso-after", "completed", "2026-08-22T12:00:00.001Z");
+    process.env[DAYS_KEY] = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await runIds()).toEqual(["iso-after", "iso-cutoff-day", "spaced-at"]);
+
+    // A day later every one of them is past the cutoff's date.
+    await runDbRetentionTick({ now: new Date("2026-08-24T00:00:00.000Z") });
+
+    expect(await runIds()).toEqual([]);
+  });
+
+  test("dry run counts the would-delete rows without deleting", async () => {
+    await insertRun("old-completed", "completed", OLD_ISO);
+    await insertRun("old-failed", "failed", OLD_SPACED, { kind: "workflow" });
+    await insertRun("old-running", "running", OLD_SPACED, { kind: "workflow" });
+    process.env[DAYS_KEY] = "1";
+    process.env.DB_RETENTION_DRY_RUN = "true";
+
+    await runDbRetentionTick({ now: NOW });
+
+    expect(await runIds()).toHaveLength(3);
+    expect(getDbRetentionStats().scriptRuns).toMatchObject({
+      rowsDeleted: 0,
+      backlogRemaining: 2,
+      dryRun: true,
+    });
+  });
+
+  test("drains a backlog larger than one batch within the batch ceiling", async () => {
+    await getDbClient().run(
+      `WITH RECURSIVE n(v) AS (SELECT 1 UNION ALL SELECT v + 1 FROM n WHERE v < 1200)
+       INSERT INTO script_runs (id, agentId, source, status, startedAt)
+       SELECT 'bulk-' || v, 'agent-1', 'x', 'completed', ? FROM n`,
+      [OLD_ISO],
+    );
+    process.env[DAYS_KEY] = "1";
+
+    await runDbRetentionTick({ now: NOW });
+
+    const stats = getDbRetentionStats().scriptRuns;
+    expect(await runIds()).toEqual([]);
+    expect(stats?.rowsDeleted).toBe(1200);
+    expect(stats?.batches).toBeGreaterThan(1);
+    expect(stats?.batchSize).toBeLessThanOrEqual(500);
+  });
+
+  test("the delete, the backlog count and the journal cascade all use an index", async () => {
+    const statements = sweepStatements(SCRIPT_RUNS, 30, NOW);
+    const client = getDbClient();
+
+    for (const [sql, params] of [
+      [statements.deleteSql, [...statements.params, 100]],
+      [statements.backlogSql, statements.params],
+    ] as const) {
+      const plan = await client.query<{ detail: string }>(`EXPLAIN QUERY PLAN ${sql}`, [...params]);
+      const detail = plan.map((row) => row.detail).join("\n");
+      expect(detail).toContain("USING COVERING INDEX idx_script_runs_status_startedAt");
+      expect(detail).not.toMatch(/SCAN script_runs(?! USING)/);
+    }
+
+    // ON DELETE CASCADE looks up journal rows of every deleted run by runId.
+    const fkPlan = await client.query<{ detail: string }>(
+      "EXPLAIN QUERY PLAN SELECT rowid FROM script_run_journal WHERE runId = ?",
+      ["x"],
+    );
+    expect(fkPlan.map((row) => row.detail).join("\n")).toContain("idx_srj_runId");
+  });
+});

package/src/tests/sdk-allowlist.test.ts

@@ -98,6 +98,45 @@ describe("script SDK allowlist", () => {
     }
   });
 
+  test("workflow_getRun forwards fields to the run route and rejects an unknown value", async () => {
+    const requests: URL[] = [];
+    const httpServer = Bun.serve({
+      port: 0,
+      fetch(req) {
+        requests.push(new URL(req.url));
+        return Response.json({ run: { id: "run-1" }, steps: [] });
+      },
+    });
+    const config = new SwarmConfig({
+      system: {
+        apiKey: { value: "sdk-test-key", isSecret: true },
+        agentId: { value: "sdk-test-agent", isSecret: false },
+        mcpBaseUrl: { value: `http://127.0.0.1:${httpServer.port}`, isSecret: false },
+      },
+      user: {},
+    });
+    const sdk = createSwarmSdk(config);
+
+    try {
+      await sdk.workflow_getRun({ id: "run-1", fields: "slim" });
+      await sdk.workflow_getRun({ id: "run-1" });
+      expect(requests.map((url) => url.pathname)).toEqual([
+        "/api/workflow-runs/run-1",
+        "/api/workflow-runs/run-1",
+      ]);
+      expect(requests[0]?.searchParams.get("fields")).toBe("slim");
+      // Omitted `fields` sends no query, so the route keeps its full default.
+      expect(requests[1]?.search).toBe("");
+
+      await expect(sdk.workflow_getRun({ id: "run-1", fields: "tiny" })).rejects.toThrow(
+        '`fields` must be "full" or "slim"',
+      );
+      expect(requests).toHaveLength(2);
+    } finally {
+      httpServer.stop(true);
+    }
+  });
+
   test("approval_cancel posts to the cancel route with the reason", async () => {
     let request: { method: string; path: string; body: unknown } | undefined;
     const httpServer = Bun.serve({