pi-llama-cpp 0.11.0 → 0.13.0

package/tests/commandManager.test.ts

@@ -1,4 +1,5 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { initTheme } from "@earendil-works/pi-coding-agent";
 import type { KeybindingsManager, TUI } from "@earendil-works/pi-tui";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { Action } from "../src/enums/action";
@@ -10,8 +11,8 @@ import {
 } from "../src/managers/command";
 import { ServerManager } from "../src/managers/server";
 import type { LlamaSettingsManager } from "../src/managers/settings";
-import type { Server } from "../src/server";
-import { ServerListEditor } from "../src/ui/serverListEditor";
+import * as serverListEditor from "../src/ui/serverListEditor";
+import { ServerSettingsList } from "../src/ui/serverSettingsList";
 import {
   createMockCtx,
   createMockModel,
@@ -22,10 +23,30 @@ import {
 } from "./mocks";
 
 beforeEach(() => {
+  initTheme();
   vi.clearAllMocks();
   mockRpc.mockResolvedValue({ data: [] });
+  // Mock health checks to return "healthy" immediately
+  vi.spyOn(serverListEditor, "getServerHealthEmoji").mockResolvedValue("🟢");
 });
 
+/**
+ * Waits for a ServerSettingsList to finish its async initialization
+ * (health checks + SettingsList construction).
+ */
+const waitForEditor = (editor: ServerSettingsList): Promise<void> =>
+  new Promise((resolve) => {
+    const check = () => {
+      // @ts-expect-error settingsList is private
+      if (editor.settingsList) {
+        resolve();
+      } else {
+        setTimeout(check, 10);
+      }
+    };
+    check();
+  });
+
 describe("CommandManager", () => {
   let serverManager: ServerManager;
   let commandManager: CommandManager;
@@ -42,12 +63,13 @@ describe("CommandManager", () => {
   describe("getArgumentCompletions", () => {
     it("should provide completions for /models", () => {
       const completions = commandManager.getArgumentCompletions("");
-      expect(completions).toHaveLength(4);
+      expect(completions).toHaveLength(5);
       expect(completions?.map((c) => c.value)).toEqual([
         "info",
         "unload",
-        "servers",
         "settings",
+        "servers",
+        "overrides",
       ]);
     });
 
@@ -64,7 +86,7 @@ describe("CommandManager", () => {
 
     it("should provide the server/settings completions by prefix", () => {
       const completions = commandManager.getArgumentCompletions("s");
-      expect(completions?.map((c) => c.value)).toEqual(["servers", "settings"]);
+      expect(completions?.map((c) => c.value)).toEqual(["settings", "servers"]);
     });
   });
 
@@ -77,7 +99,7 @@ describe("CommandManager", () => {
         models: [model1, model2],
       });
       const unloadSettings = makeSettingsStub({
-        resolveServers: vi.fn((): Server[] => [server]),
+        resolveServers: vi.fn(async () => [server]),
       });
       serverManager = new ServerManager(unloadSettings);
       commandManager = new CommandManager(serverManager, unloadSettings);
@@ -107,7 +129,7 @@ describe("CommandManager", () => {
         models: [model1, model2],
       });
       const infoSettings = makeSettingsStub({
-        resolveServers: vi.fn((): Server[] => [server]),
+        resolveServers: vi.fn(async () => [server]),
       });
       serverManager = new ServerManager(infoSettings);
       commandManager = new CommandManager(serverManager, infoSettings);
@@ -133,8 +155,8 @@ describe("CommandManager", () => {
       expect(formatMs(1500)).toBe("1500ms");
     });
 
-    it("should build one item per editable scalar field", () => {
-      const items = buildSettingsItems(settingsStub);
+    it("should build one item per editable scalar field", async () => {
+      const items = await buildSettingsItems(settingsStub);
       expect(items.map((i) => i.id)).toEqual([
         "reactToModelSelect",
         "autoloadOnMessage",
@@ -220,7 +242,9 @@ describe("CommandManager", () => {
         matches: vi.fn(
           (data: string, name: string) =>
             (data === ENTER && name === "tui.select.confirm") ||
-            (data === ESC && name === "tui.select.cancel"),
+            (data === ESC && name === "tui.select.cancel") ||
+            (data === "\x1b[A" && name === "tui.select.up") ||
+            (data === "\x1b[B" && name === "tui.select.down"),
         ),
       }) as unknown as KeybindingsManager;
 
@@ -256,7 +280,7 @@ describe("CommandManager", () => {
 
     it("should wire the editor to the merged servers and the write path", async () => {
       const editorSettings = makeSettingsStub({
-        llamaServers: [{ url: "http://seed:1" }],
+        getLlamaServers: vi.fn(async () => [{ url: "http://seed:1" }]),
       });
       commandManager = new CommandManager(serverManager, editorSettings);
       const ctx = createMockCtx(() => null);
@@ -269,7 +293,7 @@ describe("CommandManager", () => {
         theme: Theme,
         kb: KeybindingsManager,
         done: (result: undefined) => void,
-      ) => ServerListEditor;
+      ) => ServerSettingsList;
       const done = vi.fn();
       const editor = factory(
         { requestRender: vi.fn() } as unknown as TUI,
@@ -284,14 +308,23 @@ describe("CommandManager", () => {
         done,
       );
 
-      expect(editor).toBeInstanceOf(ServerListEditor);
+      expect(editor).toBeInstanceOf(ServerSettingsList);
+      // Wait for async health checks to complete
+      await waitForEditor(editor);
       // Seeded with the merged snapshot
       expect(editor.render(80).join("\n")).toContain("http://seed:1");
 
-      // Add a server through the editor → setLlamaSetting("servers", …)
+      // Add a server through the wizard (URL → ID → name) →
+      // setLlamaSetting("servers", …) persists only after the final step
       editor.handleInput("a");
+      expect(editor.render(80).join("\n")).toContain("Add server · 1/3");
       for (const ch of "http://new:2") editor.handleInput(ch);
       editor.handleInput(ENTER);
+      expect(editor.render(80).join("\n")).toContain("Add server · 2/3");
+      editor.handleInput(ENTER); // skip optional ID
+      expect(editor.render(80).join("\n")).toContain("Add server · 3/3");
+      editor.handleInput(ENTER); // skip optional name → persist
+      // Wait for async persist and rebuild
       await new Promise((resolve) => setTimeout(resolve, 0));
       expect(editorSettings.setLlamaSetting).toHaveBeenCalledWith("servers", [
         { url: "http://seed:1" },
@@ -302,6 +335,89 @@ describe("CommandManager", () => {
       editor.handleInput(ESC);
       expect(done).toHaveBeenCalledTimes(1);
     });
+
+    it("should persist nothing when the add wizard is cancelled", async () => {
+      const editorSettings = makeSettingsStub({
+        getLlamaServers: vi.fn(async () => [{ url: "http://seed:1" }]),
+      });
+      commandManager = new CommandManager(serverManager, editorSettings);
+      const ctx = createMockCtx(() => null);
+
+      await commandManager.handleCommand("servers", ctx as any, mockPi as any);
+
+      const factory = vi.mocked(ctx.ui.custom).mock.calls[0][0] as (
+        tui: TUI,
+        theme: Theme,
+        kb: KeybindingsManager,
+        done: (result: undefined) => void,
+      ) => ServerSettingsList;
+      const editor = factory(
+        { requestRender: vi.fn() } as unknown as TUI,
+        createMockTheme(),
+        createMockKeybindings(),
+        vi.fn(),
+      );
+
+      // Walk to wizard step 2, then abort — nothing must be persisted
+      editor.handleInput("a");
+      for (const ch of "http://new:2") editor.handleInput(ch);
+      editor.handleInput(ENTER);
+      editor.handleInput(ESC);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(editorSettings.setLlamaSetting).not.toHaveBeenCalled();
+      // Back to the list view
+      expect(editor.render(80).join("\n")).toContain("http://seed:1");
+    });
+
+    it("should delete the selected server after confirming", async () => {
+      const editorSettings = makeSettingsStub({
+        getLlamaServers: vi.fn(async () => [
+          { url: "http://seed:1" },
+          { url: "http://doomed:2" },
+        ]),
+      });
+      commandManager = new CommandManager(serverManager, editorSettings);
+      const ctx = createMockCtx(() => null);
+
+      await commandManager.handleCommand("servers", ctx as any, mockPi as any);
+
+      const factory = vi.mocked(ctx.ui.custom).mock.calls[0][0] as (
+        tui: TUI,
+        theme: Theme,
+        kb: KeybindingsManager,
+        done: (result: undefined) => void,
+      ) => ServerSettingsList;
+      const editor = factory(
+        { requestRender: vi.fn() } as unknown as TUI,
+        createMockTheme(),
+        createMockKeybindings(),
+        vi.fn(),
+      );
+
+      // Wait for async health checks to complete
+      await waitForEditor(editor);
+
+      // Move to the second row and open the confirm dialog
+      editor.handleInput("\x1b[B");
+      editor.handleInput("d");
+      expect(editor.render(80).join("\n")).toContain(
+        'Delete "http://doomed:2"?',
+      );
+
+      // Esc keeps the server
+      editor.handleInput(ESC);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(editorSettings.setLlamaSetting).not.toHaveBeenCalled();
+
+      // Re-open and confirm the default "Delete" selection
+      editor.handleInput("d");
+      editor.handleInput(ENTER);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(editorSettings.setLlamaSetting).toHaveBeenCalledWith("servers", [
+        { url: "http://seed:1" },
+      ]);
+    });
   });
 
   describe("/models interactive menu", () => {
@@ -321,7 +437,7 @@ describe("CommandManager", () => {
         }),
       );
       const settingsStub = makeSettingsStub({
-        resolveServers: vi.fn((): Server[] => servers),
+        resolveServers: vi.fn(async () => servers),
       });
       const serverManager = new ServerManager(settingsStub);
       return {
@@ -432,7 +548,7 @@ describe("CommandManager", () => {
         baseUrl: "http://127.0.0.1:8081",
         models: [modelB],
       });
-      vi.mocked(settingsStub.resolveServers).mockReturnValue([
+      vi.mocked(settingsStub.resolveServers).mockResolvedValue([
         ...servers,
         serverB,
       ]);

package/tests/dialog.test.ts

@@ -0,0 +1,228 @@
+import { initTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+  getKeybindings,
+  type KeybindingsManager,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ConfirmDialog, InputDialog } from "../src/ui/dialog";
+import { createOverrideSettingsList } from "../src/ui/overrideSettingsList";
+import { ServerSettingsList } from "../src/ui/serverSettingsList";
+
+beforeEach(() => {
+  initTheme();
+  vi.clearAllMocks();
+});
+
+const ESC = "\x1b";
+const ENTER = "\r";
+
+const createMockTheme = (): Theme =>
+  ({
+    fg: (_color: string, text: string) => text,
+    bold: (text: string) => text,
+  }) as unknown as Theme;
+
+const createMockTui = (): TUI => ({ requestRender: vi.fn() }) as unknown as TUI;
+
+const createKeybindings = (): KeybindingsManager => getKeybindings();
+
+describe("InputDialog", () => {
+  const build = (
+    overrides: Partial<ConstructorParameters<typeof InputDialog>[0]> = {},
+  ) => {
+    const onSubmit = vi.fn();
+    const onCancel = vi.fn();
+    const dialog = new InputDialog({
+      theme: createMockTheme(),
+      tui: createMockTui(),
+      title: "Dialog title",
+      message: "Server URL",
+      placeholder: "http://127.0.0.1:8080",
+      validate: (raw) => (raw.startsWith("http") ? raw : null),
+      onSubmit,
+      onCancel,
+      ...overrides,
+    });
+    return { dialog, onSubmit, onCancel };
+  };
+
+  it("renders the framed title, message, placeholder and key hints", () => {
+    const { dialog } = build();
+    const rendered = dialog.render(60).join("\n");
+    expect(rendered).toContain("Dialog title");
+    expect(rendered).toContain("Server URL");
+    expect(rendered).toContain("e.g., http://127.0.0.1:8080");
+  });
+
+  it("submits the validated value on Enter", () => {
+    const { dialog, onSubmit, onCancel } = build({
+      initialValue: "http://x:1",
+    });
+    dialog.handleInput(ENTER);
+    expect(onSubmit).toHaveBeenCalledWith("http://x:1");
+    expect(onCancel).not.toHaveBeenCalled();
+  });
+
+  it("keeps the dialog open with an error on invalid input", () => {
+    const { dialog, onSubmit, onCancel } = build();
+    for (const ch of "no-scheme") dialog.handleInput(ch);
+    dialog.handleInput(ENTER);
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(dialog.render(60).join("\n")).toContain('Invalid value "no-scheme"');
+
+    // Esc still cancels after an error
+    dialog.handleInput(ESC);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancels on Esc without submitting", () => {
+    const { dialog, onSubmit, onCancel } = build({
+      initialValue: "http://x:1",
+    });
+    dialog.handleInput(ESC);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});
+
+describe("ConfirmDialog", () => {
+  const build = () => {
+    const onConfirm = vi.fn();
+    const onCancel = vi.fn();
+    const dialog = new ConfirmDialog({
+      theme: createMockTheme(),
+      tui: createMockTui(),
+      title: "Delete server",
+      message: 'Delete "http://x:1"?',
+      onConfirm,
+      onCancel,
+    });
+    return { dialog, onConfirm, onCancel };
+  };
+
+  it("renders the framed message and both options", () => {
+    const { dialog } = build();
+    const rendered = dialog.render(60).join("\n");
+    expect(rendered).toContain("Delete server");
+    expect(rendered).toContain('Delete "http://x:1"?');
+    expect(rendered).toContain("Delete");
+    expect(rendered).toContain("Cancel");
+  });
+
+  it("confirms with Enter on the default selection", () => {
+    const { dialog, onConfirm, onCancel } = build();
+    dialog.handleInput(ENTER);
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    expect(onCancel).not.toHaveBeenCalled();
+  });
+
+  it("cancels on Esc", () => {
+    const { dialog, onConfirm, onCancel } = build();
+    dialog.handleInput(ESC);
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+});
+
+describe("ServerSettingsList add wizard", () => {
+  const buildEditor = (servers: { url: string; id?: string }[] = []) => {
+    const persist = vi.fn().mockResolvedValue(undefined);
+    const done = vi.fn();
+    const onError = vi.fn();
+    const editor = new ServerSettingsList({
+      tui: createMockTui(),
+      theme: createMockTheme(),
+      keybindings: createKeybindings(),
+      servers: servers as never[],
+      persist,
+      done,
+      onError,
+    });
+    return { editor, persist, done, onError };
+  };
+
+  it("persists only the URL when the optional steps are skipped", async () => {
+    const { editor, persist } = buildEditor();
+
+    editor.handleInput("a");
+    for (const ch of "http://x:1") editor.handleInput(ch);
+    editor.handleInput(ENTER); // URL → ID
+    editor.handleInput(ENTER); // skip ID → name
+    editor.handleInput(ENTER); // skip name → persist
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(persist).toHaveBeenCalledWith([{ url: "http://x:1" }]);
+  });
+
+  it("persists the URL and ID when the ID step is filled", async () => {
+    const { editor, persist } = buildEditor();
+
+    editor.handleInput("a");
+    for (const ch of "http://x:1") editor.handleInput(ch);
+    editor.handleInput(ENTER);
+    for (const ch of "my-id") editor.handleInput(ch);
+    editor.handleInput(ENTER); // ID → name
+    editor.handleInput(ENTER); // skip name → persist
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(persist).toHaveBeenCalledWith([{ url: "http://x:1", id: "my-id" }]);
+  });
+
+  it("rejects an invalid URL at step 1 and aborts cleanly on Esc", async () => {
+    const { editor, persist } = buildEditor();
+
+    editor.handleInput("a");
+    for (const ch of "not-a-url") editor.handleInput(ch);
+    editor.handleInput(ENTER);
+    expect(persist).not.toHaveBeenCalled();
+    expect(editor.render(80).join("\n")).toContain('Invalid value "not-a-url"');
+
+    editor.handleInput(ESC);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(persist).not.toHaveBeenCalled();
+    // Back at the (empty) list view
+    expect(editor.render(80).join("\n")).toContain("(a) add server");
+  });
+});
+
+describe("OverrideEntryListEditor cost re-prefill", () => {
+  const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+  it("re-entering a cost field prefills the just-saved value", async () => {
+    const persist = vi.fn().mockResolvedValue(undefined);
+    const list = createOverrideSettingsList({
+      tui: createMockTui(),
+      theme: createMockTheme(),
+      keybindings: createKeybindings(),
+      servers: [
+        {
+          url: "http://x:1",
+          overrides: { "gpt-*": { cost: { input: 0.2 } } },
+        },
+      ] as never[],
+      persist,
+      done: vi.fn(),
+      onError: vi.fn(),
+      onChanged: vi.fn(),
+    });
+
+    const DOWN = "\x1b[B"; // tui.select.down
+    const CLEAR = "\x15"; // tui.editor.deleteToLineStart
+
+    list.handleInput(ENTER); // drill into the server row
+    list.handleInput(ENTER); // open the field submenu (cursor: pattern)
+    list.handleInput(DOWN); // cursor: cost.input
+    list.handleInput(ENTER); // open the input dialog (prefilled "0.2")
+    list.handleInput(CLEAR);
+    for (const ch of "0.5") list.handleInput(ch);
+    list.handleInput(ENTER); // commit
+    await flush();
+
+    // Re-enter the field: the prefill must be the saved value
+    list.handleInput(ENTER);
+    const rendered = list.render(80).join("\n");
+    expect(rendered).toContain("0.5");
+    expect(rendered).not.toContain("0.2");
+  });
+});

package/tests/events.test.ts

@@ -299,7 +299,7 @@ describe("EventManager.onBeforeProviderRequest", () => {
 
 describe("EventManager.onModelSelect", () => {
   beforeEach(() => {
-    vi.mocked(settingsStub.resolveReactToModelSelect).mockReturnValue(true);
+    vi.mocked(settingsStub.resolveReactToModelSelect).mockResolvedValue(true);
   });
 
   it("should load the model when reactToModelSelect is true", async () => {
@@ -319,7 +319,7 @@ describe("EventManager.onModelSelect", () => {
   });
 
   it("should return early when reactToModelSelect is false", async () => {
-    vi.mocked(settingsStub.resolveReactToModelSelect).mockReturnValue(false);
+    vi.mocked(settingsStub.resolveReactToModelSelect).mockResolvedValue(false);
 
     const server = createMockServer({
       models: ["model-a"].map((id) => createMockModel(id)),
@@ -339,7 +339,7 @@ describe("EventManager.onModelSelect", () => {
 
 describe("EventManager.autoLoadIfNeeded", () => {
   it("should load the model when autoloadOnMessage is true and model is UNLOADED", async () => {
-    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockReturnValue(true);
+    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockResolvedValue(true);
 
     const server = createMockServer({
       models: [
@@ -358,7 +358,7 @@ describe("EventManager.autoLoadIfNeeded", () => {
   });
 
   it("should not load the model when autoloadOnMessage is false", async () => {
-    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockReturnValue(false);
+    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockResolvedValue(false);
 
     const server = createMockServer({
       models: [
@@ -377,7 +377,7 @@ describe("EventManager.autoLoadIfNeeded", () => {
   });
 
   it("should not load the model when model is already LOADED", async () => {
-    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockReturnValue(true);
+    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockResolvedValue(true);
 
     const server = createMockServer({
       models: [
@@ -396,7 +396,7 @@ describe("EventManager.autoLoadIfNeeded", () => {
   });
 
   it("should not load the model when model is SLEEPING", async () => {
-    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockReturnValue(true);
+    vi.mocked(settingsStub.resolveAutoloadOnMessage).mockResolvedValue(true);
 
     const server = createMockServer({
       models: [
@@ -427,7 +427,7 @@ describe("EventManager with a live ServerManager", () => {
       ],
     });
 
-    vi.mocked(settingsStub.resolveServers).mockReturnValue([serverA]);
+    vi.mocked(settingsStub.resolveServers).mockResolvedValue([serverA]);
     const serverManager = new ServerManager(settingsStub);
     const mockPi = { registerProvider: vi.fn(), unregisterProvider: vi.fn() };
     await serverManager.update(mockPi as any);
@@ -435,7 +435,10 @@ describe("EventManager with a live ServerManager", () => {
     const eventManager = new EventManager(serverManager, settingsStub);
 
     // Second scan adds serverB — no manager re-construction
-    vi.mocked(settingsStub.resolveServers).mockReturnValue([serverA, serverB]);
+    vi.mocked(settingsStub.resolveServers).mockResolvedValue([
+      serverA,
+      serverB,
+    ]);
     await serverManager.update(mockPi as any);
 
     // onBeforeProviderRequest sees the new server's models
@@ -447,7 +450,7 @@ describe("EventManager with a live ServerManager", () => {
     expect(result.thinking_budget_tokens).toBe(THINKING_BUDGETS.medium);
 
     // onModelSelect sees the new server's models too
-    vi.mocked(settingsStub.resolveReactToModelSelect).mockReturnValue(true);
+    vi.mocked(settingsStub.resolveReactToModelSelect).mockResolvedValue(true);
     const selectCtx = createMockCtx();
     await eventManager.onModelSelect(
       { model: { provider: serverB.providerId, id: "model-b" } } as any,

package/tests/health.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ServerStatus } from "../src/enums/serverStatus";
+import { checkServerHealth } from "../src/utils/health";
+
+/**
+ * Stubs `global.fetch` for one test. The probe only reads the parsed body,
+ * so a fake response is just a `json()` accessor.
+ */
+const stubFetch = (
+  impl: (url: string, init?: RequestInit) => Promise<unknown>,
+) => vi.stubGlobal("fetch", vi.fn(impl));
+
+const okResponse = () => ({ json: async () => ({ status: "ok" }) });
+
+const URL_ = "http://127.0.0.1:8080";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("checkServerHealth", () => {
+  it("should return READY when the payload status is ok", async () => {
+    stubFetch(async () => ({ json: async () => ({ status: "ok" }) }));
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.READY);
+  });
+
+  it("should return UNREACHABLE when the payload status is not ok", async () => {
+    stubFetch(async () => ({ json: async () => ({ status: "error" }) }));
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.UNREACHABLE);
+  });
+
+  it("should return UNREACHABLE when the payload has no status field", async () => {
+    // llama-server answers a loading model with a 503 + error payload
+    stubFetch(async () => ({
+      json: async () => ({ error: { message: "Loading model" } }),
+    }));
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.UNREACHABLE);
+  });
+
+  it("should return UNREACHABLE when the body is not JSON", async () => {
+    stubFetch(async () => ({
+      json: async () => {
+        throw new Error("Unexpected token");
+      },
+    }));
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.UNREACHABLE);
+  });
+
+  it("should return UNREACHABLE on a network error", async () => {
+    stubFetch(async () => {
+      throw new Error("connection refused");
+    });
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.UNREACHABLE);
+  });
+
+  it("should return TIMEOUT when the fetch aborts with TimeoutError", async () => {
+    stubFetch(async () => {
+      throw new DOMException("The operation timed out.", "TimeoutError");
+    });
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.TIMEOUT);
+  });
+
+  it("should return TIMEOUT when the fetch aborts with AbortError", async () => {
+    // Some runtimes surface the timeout as a plain AbortError
+    stubFetch(async () => {
+      throw new DOMException("The user aborted a request.", "AbortError");
+    });
+
+    expect(await checkServerHealth(URL_, 1000)).toBe(ServerStatus.TIMEOUT);
+  });
+
+  it("should hit <url>/health", async () => {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
+      okResponse(),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await checkServerHealth(URL_, 1000);
+
+    expect(fetchMock).toHaveBeenCalledWith(`${URL_}/health`, {
+      signal: expect.any(AbortSignal),
+      headers: undefined,
+    });
+  });
+
+  it("should send the API key as a Bearer token when provided", async () => {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
+      okResponse(),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await checkServerHealth(URL_, 1000, "secret-key");
+
+    expect(fetchMock).toHaveBeenCalledWith(`${URL_}/health`, {
+      signal: expect.any(AbortSignal),
+      headers: { Authorization: "Bearer secret-key" },
+    });
+  });
+
+  it("should omit the Authorization header when no key is given", async () => {
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) =>
+      okResponse(),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await checkServerHealth(URL_, 1000);
+
+    expect(fetchMock.mock.calls[0]?.[1]?.headers).toBeUndefined();
+  });
+});