@desplega.ai/agent-swarm 2.5.4 → 2.7.0

package/src/tests/pages-frame-ancestors.test.ts

@@ -0,0 +1,162 @@
+/**
+ * `PAGES_FRAME_ANCESTORS` widens `frame-ancestors` on `/p/:id` for PUBLIC
+ * pages only, so an outside site (for example a blog) can iframe a chart.
+ * Authed and password pages keep the app-origin-only header, and an unset
+ * env leaves every header unchanged.
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+import { unlink } from "node:fs/promises";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { closeDb, initDb } from "../be/db";
+import { handlePages } from "../http/pages";
+import { getPageFrameAncestors, handlePagesPublic } from "../http/pages-public";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { signPageSession } from "../utils/page-session";
+import { listenOnFreePort } from "./test-net";
+
+const TEST_DB_PATH = "./test-pages-frame-ancestors.sqlite";
+const EMBEDDERS = "https://www.agent-swarm.dev https://agent-swarm.dev";
+let BASE = "";
+
+function createTestServer(): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    if (await handlePagesPublic(req, res, pathSegments, queryParams)) return;
+    if (await handlePages(req, res, pathSegments, queryParams, myAgentId)) return;
+    res.writeHead(404);
+    res.end("not found");
+  });
+}
+
+function frameAncestors(res: Response): string {
+  const csp = res.headers.get("content-security-policy") ?? "";
+  return csp.split(";").find((d) => d.trim().startsWith("frame-ancestors ")) ?? "";
+}
+
+describe("PAGES_FRAME_ANCESTORS on /p/:id", () => {
+  let server: Server;
+  const agentId = crypto.randomUUID();
+  const headers = { "Content-Type": "application/json", "X-Agent-ID": agentId };
+  const ORIG = {
+    PAGES_FRAME_ANCESTORS: process.env.PAGES_FRAME_ANCESTORS,
+    APP_URL: process.env.APP_URL,
+    DASHBOARD_URL: process.env.DASHBOARD_URL,
+    PAGE_SESSION_SECRET: process.env.PAGE_SESSION_SECRET,
+  };
+
+  function restore(key: keyof typeof ORIG): void {
+    if (ORIG[key] === undefined) delete process.env[key];
+    else process.env[key] = ORIG[key];
+  }
+
+  async function createPage(
+    slug: string,
+    authMode: "public" | "authed" | "password",
+  ): Promise<string> {
+    const post = await fetch(`${BASE}/api/pages`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug,
+        title: slug,
+        contentType: "text/html",
+        authMode,
+        ...(authMode === "password" ? { password: "swordfish" } : {}),
+        body: "<!doctype html><html><head></head><body><h1>chart</h1></body></html>",
+      }),
+    });
+    expect(post.status).toBe(201);
+    const { id } = (await post.json()) as { id: string };
+    return id;
+  }
+
+  beforeAll(async () => {
+    process.env.PAGE_SESSION_SECRET = "example-test-frame-ancestors-secret";
+    process.env.APP_URL = "https://app.example.test";
+    delete process.env.DASHBOARD_URL;
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    server = createTestServer();
+    const port = await listenOnFreePort(server);
+    BASE = `http://localhost:${port}`;
+  });
+
+  afterEach(() => restore("PAGES_FRAME_ANCESTORS"));
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    closeDb();
+    for (const key of Object.keys(ORIG) as (keyof typeof ORIG)[]) restore(key);
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+  });
+
+  test("public page gets the configured origins", async () => {
+    process.env.PAGES_FRAME_ANCESTORS = EMBEDDERS;
+    const id = await createPage("public-embed", "public");
+    const res = await fetch(`${BASE}/p/${id}`);
+    expect(res.status).toBe(200);
+    const fa = frameAncestors(res);
+    expect(fa).toContain("'self'");
+    expect(fa).toContain("https://app.example.test");
+    expect(fa).toContain("https://www.agent-swarm.dev");
+    expect(fa).toContain("https://agent-swarm.dev");
+  });
+
+  test("authed page keeps the app-origin-only header", async () => {
+    const id = await createPage("authed-embed", "authed");
+    const exp = Math.floor(Date.now() / 1000) + 3600;
+    const cookie = `page_session_${id}=${await signPageSession({ pageId: id, exp })}`;
+
+    const before = frameAncestors(await fetch(`${BASE}/p/${id}`, { headers: { cookie } }));
+    process.env.PAGES_FRAME_ANCESTORS = EMBEDDERS;
+    const res = await fetch(`${BASE}/p/${id}`, { headers: { cookie } });
+    expect(res.status).toBe(200);
+    expect(frameAncestors(res)).toBe(before);
+    expect(frameAncestors(res)).not.toContain("agent-swarm.dev");
+  });
+
+  test("password page keeps the app-origin-only header", async () => {
+    process.env.PAGES_FRAME_ANCESTORS = EMBEDDERS;
+    const id = await createPage("password-embed", "password");
+    const res = await fetch(`${BASE}/p/${id}?key=swordfish`);
+    expect(res.status).toBe(200);
+    expect(frameAncestors(res)).not.toContain("agent-swarm.dev");
+  });
+
+  test("unset env leaves the public header unchanged", async () => {
+    const id = await createPage("public-unset", "public");
+    delete process.env.PAGES_FRAME_ANCESTORS;
+    const unset = frameAncestors(await fetch(`${BASE}/p/${id}`));
+    process.env.PAGES_FRAME_ANCESTORS = "";
+    const blank = frameAncestors(await fetch(`${BASE}/p/${id}`));
+    expect(unset).toContain("https://app.example.test");
+    expect(unset).not.toContain("agent-swarm.dev");
+    expect(blank).toBe(unset);
+  });
+
+  test("parser accepts comma or space lists and drops invalid entries", () => {
+    process.env.PAGES_FRAME_ANCESTORS =
+      "https://www.agent-swarm.dev/, https://*.example.com:8443 blog.example.org,* 'none' https://evil.test;script-src javascript:alert(1) https://x.test/path";
+    expect(getPageFrameAncestors()).toEqual([
+      "https://www.agent-swarm.dev",
+      "https://*.example.com:8443",
+      "blog.example.org",
+    ]);
+  });
+});

package/src/tests/pi-codemode.test.ts

@@ -104,7 +104,8 @@ describe("PiMonoAdapter.createSession — codemode", () => {
     process.env.OPENROUTER_BASE_URL = "http://127.0.0.1:9/api/v1";
     delete process.env.PI_CODEMODE;
     delete process.env.PI_CODEMODE_MODELS;
-    delete process.env.PI_TOOL_DEFERRAL;
+    // Deferral off, so every swarm tool shows up as an active tool name.
+    process.env.PI_TOOL_DEFERRAL = "false";
   });
   afterEach(() => {
     for (const key of envKeys) {

package/src/tests/pi-mono-adapter.test.ts

@@ -1859,3 +1859,57 @@ describe("PiMonoSession context-bound note", () => {
     expect(await lateSteers([assistantTurn(usage(5000))])).toEqual([HELD_NOTE_TEXT]);
   });
 });
+
+describe("PiMonoSession — per-call usage line", () => {
+  function assistantEnd(content: unknown[], usage?: unknown): AgentSessionEvent {
+    return {
+      type: "message_end",
+      message: { role: "assistant", content, stopReason: "stop", ...(usage ? { usage } : {}) },
+    } as unknown as AgentSessionEvent;
+  }
+
+  test("one call_usage raw_log line per assistant message_end with usage", async () => {
+    const { events } = await runWithEvents([
+      assistantEnd([{ type: "toolCall", id: "call-1", name: "bash", arguments: {} }], {
+        input: 120,
+        cacheRead: 9_000,
+        cacheWrite: 400,
+        output: 60,
+        reasoning: 12,
+        totalTokens: 9_580,
+      }),
+      {
+        type: "message_end",
+        message: { role: "user", content: [{ type: "text", text: "tool output" }] },
+      } as unknown as AgentSessionEvent,
+      // No usage (some providers omit it): no line.
+      assistantEnd([{ type: "text", text: "thinking out loud" }]),
+      assistantEnd([{ type: "text", text: "Done" }], { input: 5, cacheRead: 9_500, output: 3 }),
+    ]);
+
+    const raw = events.flatMap((e) =>
+      e.type === "raw_log" ? [JSON.parse(e.content) as Record<string, unknown>] : [],
+    );
+    const usageLines = raw.filter((line) => line.type === "call_usage");
+    expect(usageLines).toEqual([
+      {
+        type: "call_usage",
+        harness: "pi",
+        usage: { input: 120, cacheRead: 9_000, cacheWrite: 400, output: 60, reasoning: 12 },
+      },
+      {
+        type: "call_usage",
+        harness: "pi",
+        usage: { input: 5, cacheRead: 9_500, cacheWrite: 0, output: 3, reasoning: 0 },
+      },
+    ]);
+    // The usage line precedes the call's own text line.
+    const done = raw.findIndex(
+      (line) => line.type === "assistant" && JSON.stringify(line).includes('"Done"'),
+    );
+    expect(done).toBeGreaterThan(0);
+    expect(raw[done - 1]).toEqual(usageLines[1]);
+    // Token counts only: no message content rides on the line.
+    expect(JSON.stringify(usageLines)).not.toContain("tool output");
+  });
+});

package/src/tests/pi-native-mcp.test.ts

@@ -30,6 +30,17 @@ describe("toPiMcpServers", () => {
     });
   });
 
+  test("deferred maps every installed server to deferred exposure", () => {
+    const servers = toPiMcpServers(
+      {
+        local: { command: "context-mode" },
+        remote: { url: "https://mcp.example.com/mcp" },
+      },
+      { deferred: true },
+    );
+    expect(Object.values(servers).map((s) => s.exposure)).toEqual(["deferred", "deferred"]);
+  });
+
   test("no installed servers maps to an empty set", () => {
     expect(toPiMcpServers(null)).toEqual({});
   });
@@ -70,7 +81,8 @@ describe("PiMonoAdapter.createSession — native MCP for installed servers", ()
     process.env.OPENROUTER_API_KEY = "example-test-key";
     // The session prompts on creation; keep that request off the network.
     process.env.OPENROUTER_BASE_URL = "http://127.0.0.1:9/api/v1";
-    delete process.env.PI_TOOL_DEFERRAL;
+    // Direct exposure, so installed tools show up as active tool names.
+    process.env.PI_TOOL_DEFERRAL = "false";
     mkdirSync(join(dir, "agent"), { recursive: true });
   });
   afterEach(() => {

package/src/tests/pi-tool-exposure.test.ts

@@ -176,8 +176,8 @@ describe("pi resource loader trust", () => {
 });
 
 describe("PI_TOOL_DEFERRAL flag", () => {
-  test("defaults off and parses boolean literals", () => {
-    expect(isPiToolDeferralEnabled({})).toBe(false);
+  test("defaults on and parses boolean literals", () => {
+    expect(isPiToolDeferralEnabled({})).toBe(true);
     expect(isPiToolDeferralEnabled({ PI_TOOL_DEFERRAL: "true" })).toBe(true);
     expect(isPiToolDeferralEnabled({ PI_TOOL_DEFERRAL: "1" })).toBe(true);
     expect(isPiToolDeferralEnabled({ PI_TOOL_DEFERRAL: "false" })).toBe(false);
@@ -187,9 +187,9 @@ describe("PI_TOOL_DEFERRAL flag", () => {
     "traits.hasToolSearch follows the flag live",
     withEnv("PI_TOOL_DEFERRAL", undefined, () => {
       const adapter = new PiMonoAdapter();
-      expect(adapter.traits.hasToolSearch).toBe(false);
-      process.env.PI_TOOL_DEFERRAL = "true";
       expect(adapter.traits.hasToolSearch).toBe(true);
+      process.env.PI_TOOL_DEFERRAL = "false";
+      expect(adapter.traits.hasToolSearch).toBe(false);
     }),
   );
 });
@@ -259,8 +259,8 @@ describe("PiMonoAdapter.createSession — tool deferral wiring", () => {
   }
 
   test(
-    "flag on: non-core tools deferred and tool_search enabled by default",
-    withEnv("PI_TOOL_DEFERRAL", "true", async () => {
+    "flag unset: non-core tools deferred and tool_search enabled by default",
+    withEnv("PI_TOOL_DEFERRAL", undefined, async () => {
       const opts = await captureSessionOptions();
       const tools = opts.customTools as ToolDefinition[];
       expect(Object.fromEntries(tools.map((t) => [t.name, t.exposure]))).toEqual({
@@ -274,8 +274,8 @@ describe("PiMonoAdapter.createSession — tool deferral wiring", () => {
   );
 
   test(
-    "flag off: every tool declared and no tool_search",
-    withEnv("PI_TOOL_DEFERRAL", undefined, async () => {
+    "flag false: every tool declared and no tool_search",
+    withEnv("PI_TOOL_DEFERRAL", "false", async () => {
       const opts = await captureSessionOptions();
       const tools = opts.customTools as ToolDefinition[];
       expect(tools.map((t) => t.exposure)).toEqual([undefined, undefined, undefined]);

package/src/tests/probe-tool-schema-tokens.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  bareToolName,
+  controlReached,
+  countSwarmTools,
+  hasControlResult,
+  inputTokens,
+  toolNames,
+  turnOne,
+  withSessionDirs,
+} from "../../scripts/probe-tool-schema-tokens";
+
+describe("probe-tool-schema-tokens", () => {
+  let dir = "";
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("matches swarm tools under every harness naming", () => {
+    const swarm = new Set(["get_swarm", "store_progress"]);
+    expect(bareToolName("mcp__agent_swarm__get_swarm")).toBe("get_swarm");
+    expect(bareToolName("agent-swarm_store-progress")).toBe("store_progress");
+    expect(
+      countSwarmTools(["get-swarm", "mcp__agent_swarm__store_progress", "bash", "read"], swarm),
+    ).toBe(2);
+  });
+
+  test("lists tools in chat-completions and namespaced responses bodies", () => {
+    expect(toolNames({ tools: [{ type: "function", function: { name: "get-swarm" } }] })).toEqual([
+      "get-swarm",
+    ]);
+    const responses = {
+      input: [
+        {
+          type: "additional_tools",
+          tools: [{ type: "namespace", name: "functions", tools: [{ name: "exec" }] }],
+        },
+      ],
+      tools: [{ name: "wait" }],
+    };
+    expect(toolNames(responses).sort()).toEqual(["exec", "wait"]);
+  });
+
+  test("reads the last reported input token count from a stream", () => {
+    const sse = 'data: {"usage":null}\n\ndata: {"usage":{"prompt_tokens":90776}}\n';
+    expect(inputTokens(sse)).toBe(90776);
+    expect(inputTokens('{"response":{"usage":{"input_tokens":16629}}}')).toBe(16629);
+    expect(inputTokens("data: [DONE]")).toBeNull();
+  });
+
+  test("turn one skips side requests for other models", () => {
+    dir = mkdtempSync(join(tmpdir(), "probe-tool-schema-"));
+    writeFileSync(join(dir, "req-1.json"), JSON.stringify({ model: "openai/gpt-6-luna" }));
+    writeFileSync(join(dir, "res-1.txt"), '{"usage":{"prompt_tokens":453}}');
+    writeFileSync(
+      join(dir, "req-2.json"),
+      JSON.stringify({ model: "deepseek/deepseek-v4.1-flash", tools: [{ name: "bash" }] }),
+    );
+    writeFileSync(join(dir, "res-2.txt"), '{"usage":{"prompt_tokens":33115}}');
+    expect(turnOne(dir, "openrouter/deepseek/deepseek-v4.1-flash")).toEqual({
+      tokens: 33115,
+      names: ["bash"],
+    });
+  });
+
+  const found = "Found 5 agent(s) in the swarm. Requested by session: s1";
+
+  test("control passes only on a get-swarm tool output", () => {
+    dir = mkdtempSync(join(tmpdir(), "probe-tool-schema-"));
+    // The schema alone carries "in the swarm" in get-swarm's description.
+    const schemaOnly = {
+      model: "m",
+      tools: [
+        {
+          type: "function",
+          function: { name: "agent-swarm_get-swarm", description: "Lists agents in the swarm." },
+        },
+      ],
+      messages: [{ role: "user", content: "Call get-swarm. Found 5 agent(s) in the swarm." }],
+    };
+    expect(hasControlResult(schemaOnly)).toBe(false);
+    writeFileSync(join(dir, "req-1.json"), JSON.stringify(schemaOnly));
+    expect(controlReached(dir)).toBe(false);
+
+    const chat = {
+      ...schemaOnly,
+      messages: [
+        {
+          role: "assistant",
+          tool_calls: [{ id: "c1", type: "function", function: { name: "agent-swarm_get-swarm" } }],
+        },
+        { role: "tool", tool_call_id: "c1", content: [{ type: "text", text: found }] },
+      ],
+    };
+    expect(hasControlResult(chat)).toBe(true);
+    writeFileSync(join(dir, "req-2.json"), JSON.stringify(chat));
+    expect(controlReached(dir)).toBe(true);
+  });
+
+  test("control reads Responses items and rejects other tools and failed calls", () => {
+    const responses = (name: string, output: string) => ({
+      input: [
+        { type: "function_call", name, call_id: "call_1", arguments: "{}" },
+        { type: "function_call_output", call_id: "call_1", output },
+      ],
+    });
+    expect(hasControlResult(responses("mcp__agent_swarm__get_swarm", found))).toBe(true);
+    expect(hasControlResult(responses("mcp__agent_swarm__get_tasks", found))).toBe(false);
+    expect(hasControlResult(responses("mcp__agent_swarm__get_swarm", "Agent ID required."))).toBe(
+      false,
+    );
+    // An output for a different call id does not count.
+    const mismatched = responses("mcp__agent_swarm__get_swarm", found);
+    mismatched.input[1] = { type: "function_call_output", call_id: "call_2", output: found };
+    expect(hasControlResult(mismatched)).toBe(false);
+  });
+
+  test("session dirs: home is removed on success and on error, captures stay", async () => {
+    dir = mkdtempSync(join(tmpdir(), "probe-tool-schema-"));
+    let home = "";
+    const capDir = await withSessionDirs(dir, "ok", async (cap, h) => {
+      home = h;
+      writeFileSync(join(h, "config.toml"), "x");
+      writeFileSync(join(cap, "req-1.json"), "{}");
+      return cap;
+    });
+    expect(existsSync(home)).toBe(false);
+    expect(existsSync(join(capDir, "req-1.json"))).toBe(true);
+
+    await expect(
+      withSessionDirs(dir, "boom", async (cap, h) => {
+        home = h;
+        writeFileSync(join(h, "config.toml"), "x");
+        writeFileSync(join(cap, "req-1.json"), "{}");
+        throw new Error("codex exec exited 1");
+      }),
+    ).rejects.toThrow("codex exec exited 1");
+    expect(existsSync(home)).toBe(false);
+    expect(existsSync(join(dir, "boom-cap", "req-1.json"))).toBe(true);
+  });
+});

package/src/tests/prompt-template-session.test.ts

@@ -25,6 +25,7 @@ const SYSTEM_TEMPLATES = [
   "system.agent.context.bound_note",
   "system.agent.cursor.first_message",
   "system.agent.lead",
+  "system.agent.lead.docs",
   "system.agent.memory",
   "system.agent.memory.remote",
   "system.agent.outputs",
@@ -118,11 +119,11 @@ describe("Session templates: registration", () => {
     expect(sessionSystemEventTypes("session")).toEqual([...SESSION_TEMPLATES].sort());
   });
 
-  test("registers 32 system and session templates in total", () => {
+  test("registers 33 system and session templates in total", () => {
     const all = getAllTemplateDefinitions();
     const sessionSystem = all.filter((d) => d.category === "system" || d.category === "session");
-    // 27 system blocks + 5 session composites.
-    expect(sessionSystem.length).toBe(32);
+    // 28 system blocks + 5 session composites.
+    expect(sessionSystem.length).toBe(33);
   });
 
   test("drops the v1 blocks that prompt v2 deleted", () => {

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));
+  });
+});