pi-llama-cpp 0.12.0 → 0.14.0

package/src/ui/settings/index.ts

@@ -0,0 +1,237 @@
+import type {
+  ExtensionUIContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import type {
+  Component,
+  Focusable,
+  KeybindingsManager,
+  SettingItem,
+  TUI,
+} from "@earendil-works/pi-tui";
+import { SettingsList } from "@earendil-works/pi-tui";
+import type { LlamaSettings } from "../../interfaces/settings";
+import type { LlamaSettingsManager } from "../../managers/settings";
+
+// ─── Options enum ─────────────────────────────────────────────────────────
+
+/**
+ * Identifiers of the editable fields shown in `/models settings`.
+ * Values match the scalar `LlamaSettings` keys.
+ */
+export enum Options {
+  REACT_TO_MODEL_SELECT = "reactToModelSelect",
+  AUTOLOAD_ON_MESSAGE = "autoloadOnMessage",
+  SORT_BY = "sortBy",
+  POLLING_TIMEOUT = "pollingTimeout",
+  SERVER_TIMEOUT = "serverTimeout",
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+type SortByValue = NonNullable<LlamaSettings["sortBy"]>;
+
+export const SORT_VALUES: SortByValue[] = [
+  "asc",
+  "desc",
+  "asc-name",
+  "desc-name",
+  "api",
+];
+
+/** Presets (ms) for `pollingTimeout` */
+export const POLLING_PRESETS = [15000, 30000, 60000, 120000, 300000];
+
+/** Presets (ms) for `serverTimeout` */
+export const SERVER_PRESETS = [500, 1000, 2000, 5000, 10000];
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Formats milliseconds compactly for display (e.g. `500 -> "500ms"`,
+ * `60000 -> "60s"`).
+ */
+export const formatMs = (ms: number): string =>
+  ms % 1000 === 0 ? `${ms / 1000}s` : `${ms}ms`;
+
+/**
+ * Parses a value produced by `formatMs()` back to milliseconds.
+ * Only ever called with values from the preset lists.
+ */
+const parseMs = (value: string): number =>
+  value.endsWith("ms")
+    ? Number(value.slice(0, -2))
+    : Number(value.slice(0, -1)) * 1000;
+
+/**
+ * Builds the `SettingItem[]` for `/models settings` from the current
+ * (merged) values of the scalar `llamaSettings` fields.
+ */
+export const buildSettingsItems = async (
+  settings: LlamaSettingsManager,
+): Promise<SettingItem[]> => {
+  const { pollingTimeout, serverTimeout } = await settings.resolveTimeouts();
+
+  return [
+    {
+      id: Options.REACT_TO_MODEL_SELECT,
+      label: "React to model selection",
+      description: "Load the model when you pick it in Pi (immediate)",
+      currentValue: (await settings.resolveReactToModelSelect()) ? "on" : "off",
+      values: ["on", "off"],
+    },
+    {
+      id: Options.AUTOLOAD_ON_MESSAGE,
+      label: "Autoload on message",
+      description:
+        "Auto-load the selected model when you send a message (immediate)",
+      currentValue: (await settings.resolveAutoloadOnMessage()) ? "on" : "off",
+      values: ["on", "off"],
+    },
+    {
+      id: Options.SORT_BY,
+      label: "Sort models by",
+      description: "Order of models in /models (next open)",
+      currentValue: await settings.resolveSortBy(),
+      values: [...SORT_VALUES],
+    },
+    {
+      id: Options.POLLING_TIMEOUT,
+      label: "Polling timeout",
+      description: "Max model-load wait (next model load)",
+      currentValue: formatMs(pollingTimeout),
+      values: POLLING_PRESETS.map(formatMs),
+    },
+    {
+      id: Options.SERVER_TIMEOUT,
+      label: "Server timeout",
+      description: "Health check / SSE probe timeout (next model load)",
+      currentValue: formatMs(serverTimeout),
+      values: SERVER_PRESETS.map(formatMs),
+    },
+  ];
+};
+
+/**
+ * Persists a change made in the settings menu.
+ * Maps the `SettingsList` id/value pair to the matching `llamaSettings`
+ * key and writes it via `LlamaSettingsManager.setLlamaSetting()`.
+ */
+export const applySettingChange = async (
+  id: string,
+  newValue: string,
+  settings: LlamaSettingsManager,
+): Promise<void> => {
+  switch (id) {
+    case Options.REACT_TO_MODEL_SELECT:
+      await settings.setLlamaSetting("reactToModelSelect", newValue === "on");
+      return;
+    case Options.AUTOLOAD_ON_MESSAGE:
+      await settings.setLlamaSetting("autoloadOnMessage", newValue === "on");
+      return;
+    case Options.SORT_BY:
+      await settings.setLlamaSetting("sortBy", newValue as SortByValue);
+      return;
+    case Options.POLLING_TIMEOUT:
+      await settings.setLlamaSetting("pollingTimeout", parseMs(newValue));
+      return;
+    case Options.SERVER_TIMEOUT:
+      await settings.setLlamaSetting("serverTimeout", parseMs(newValue));
+      return;
+  }
+};
+
+// ─── SettingsEditor ─────────────────────────────────────────────────────────
+
+/** Options passed to the settings editor. */
+export interface SettingsEditorOptions {
+  tui: TUI;
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  settings: LlamaSettingsManager;
+  /** Called when Esc closes the editor. */
+  done: () => void;
+  /** Called on persistence errors. */
+  onError: (message: string) => void;
+}
+
+/**
+ * Interactive settings menu for the scalar `llamaSettings` fields.
+ * Enter/Space cycles the value under the cursor; Esc closes.
+ *
+ * Writes go to the global/project `~/.pi/agent/settings.json` via
+ * `LlamaSettingsManager.setLlamaSetting()`; write errors are notified
+ * and leave the dialog open with values unchanged.
+ */
+export class SettingsEditor implements Component, Focusable {
+  private settingsList: SettingsList | null = null;
+  private isFocused = false;
+
+  constructor(private readonly options: SettingsEditorOptions) {
+    void this.buildList();
+  }
+
+  /**
+   * Opens the editor in a modal `ui.custom` dialog and resolves when the
+   * user closes it (Esc). Write errors are notified via `ui` and leave
+   * the dialog open with values unchanged.
+   */
+  static async show(
+    ui: ExtensionUIContext,
+    settings: LlamaSettingsManager,
+  ): Promise<void> {
+    await ui.custom<void>(
+      (tui, theme, keybindings, done) =>
+        new SettingsEditor({
+          tui,
+          theme,
+          keybindings,
+          settings,
+          done: () => done(undefined),
+          onError: (message) => ui.notify(message, "error"),
+        }),
+    );
+  }
+
+  // -- Component -------------------------------------------------------------
+
+  invalidate(): void {
+    this.settingsList?.invalidate();
+  }
+
+  handleInput(data: string): void {
+    this.settingsList?.handleInput(data);
+  }
+
+  render(width: number): string[] {
+    if (!this.settingsList) return ["Loading..."];
+    return this.settingsList.render(width);
+  }
+
+  // -- Focusable -------------------------------------------------------------
+
+  get focused(): boolean {
+    return this.isFocused;
+  }
+
+  set focused(value: boolean) {
+    this.isFocused = value;
+  }
+
+  // -- internal --------------------------------------------------------------
+
+  private async buildList(): Promise<void> {
+    const items = await buildSettingsItems(this.options.settings);
+    this.settingsList = new SettingsList(
+      items,
+      Math.min(items.length + 2, 15),
+      getSettingsListTheme(),
+      (id, newValue) =>
+        applySettingChange(id, newValue, this.options.settings).catch(
+          (err: unknown) => this.options.onError(String(err)),
+        ),
+      () => this.options.done(),
+    );
+  }
+}

package/src/ui/strings.ts

@@ -94,10 +94,12 @@ export const FIELDS = {
 } as const satisfies Record<string, Field>;
 
 /** Dialog prompt for a field: the `label` plus its parenthetical `note`
- * (or an overriding note, e.g. the add-server wizard's "(optional)").
- */
-export const fieldMessage = (field: Field, note = field.note): string =>
-  note ? `${field.label} ${note}` : field.label;
+ * (or an overriding note, e.g. the add-server wizard's "(optional)"). */
+export class FieldMessages {
+  static of(field: Field, note = field.note): string {
+    return note ? `${field.label} ${note}` : field.label;
+  }
+}
 
 /**
  * Dialog titles. `edit` composes the shared `Edit <term>` title so the
@@ -124,4 +126,6 @@ export const HINTS = {
   emptyServers: "  (a) add server · Esc done",
   /** Hint line when the override entry list is empty */
   emptyOverrideEntries: "  (a) add override · Esc back",
+  /** Row description for a server in the overrides editor */
+  overrideServerRow: "Enter: edit this server's override entries",
 } as const;

package/src/utils/health.ts

@@ -0,0 +1,48 @@
+import { ServerStatus } from "../enums/serverStatus";
+
+/**
+ * Probes a llama-server's `/health` endpoint and classifies the outcome.
+ *
+ * The single source of truth for health classification — both
+ * `Server.isReady` and the UI health indicators delegate here.
+ *
+ * - HTTP success with `{ status: "ok" }`  → `READY`
+ * - The request is still in flight when the deadline passes
+ *   (`AbortSignal.timeout` aborts it)     → `TIMEOUT`
+ * - Anything else (network error, non-JSON or non-ok payload)
+ *                                         → `UNREACHABLE`
+ *
+ * The HTTP status code itself is not inspected: a llama-server answers
+ * `/health` with the payload's `status` field, and both classification
+ * branches key off it (matching the behavior of `ApiClient.get`, which
+ * also ignores status codes and parses the body).
+ *
+ * @param url The bare origin of the llama-server (the endpoint is
+ *   `<url>/health`, without the `/v1` prefix)
+ * @param timeout Maximum time (ms) to wait for the health check
+ * @param apiKey Optional API key, sent as a Bearer token — servers
+ *   behind an API-key gate would otherwise report UNREACHABLE
+ * @returns The classified server status
+ */
+export const checkServerHealth = async (
+  url: string,
+  timeout: number,
+  apiKey?: string,
+): Promise<ServerStatus> => {
+  try {
+    const response = await fetch(`${url}/health`, {
+      signal: AbortSignal.timeout(timeout),
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined,
+    });
+    const data = (await response.json()) as { status?: string };
+    return data.status === "ok" ? ServerStatus.READY : ServerStatus.UNREACHABLE;
+  } catch (error) {
+    // `AbortSignal.timeout` rejects `fetch` with a `TimeoutError`
+    // DOMException (some runtimes surface it as `AbortError` with a
+    // timeout message).
+    const isTimeout =
+      error instanceof Error &&
+      (error.name === "TimeoutError" || error.name === "AbortError");
+    return isTimeout ? ServerStatus.TIMEOUT : ServerStatus.UNREACHABLE;
+  }
+};

package/src/utils/serverIds.ts

@@ -0,0 +1,21 @@
+import { PROVIDER_PREFIX } from "../constants";
+
+/**
+ * Resolves a server's provider ID: the custom ID when set, otherwise the
+ * URL-derived ID (`${PROVIDER_PREFIX}=<url>`).
+ *
+ * Single home for the rule shared by `Server.providerId` (runtime) and
+ * `ServerDisplay.suffix` (editor display row), so the ID shown in the
+ * editors can't drift from the one used at request time.
+ */
+export class ServerIds {
+  /** The URL-derived ID: `<PROVIDER_PREFIX>=<url>`. */
+  static fromUrl(url: string): string {
+    return `${PROVIDER_PREFIX}=${url}`;
+  }
+
+  /** The effective provider ID: `customId` when set, else URL-derived. */
+  static resolve(url: string, customId?: string): string {
+    return customId ?? this.fromUrl(url);
+  }
+}

package/src/utils/settingsStore.ts

@@ -32,7 +32,7 @@ export class SettingsStore {
   }
 
   /** Serializes (2-space indent) and writes atomically via temp file + rename. */
-  async write(root: Record<string, unknown>): Promise<void> {
+  private async write(root: Record<string, unknown>): Promise<void> {
     const tmp = `${this.path}.tmp`;
     await writeFile(tmp, JSON.stringify(root, null, 2), "utf-8");
     await rename(tmp, this.path);

package/src/utils/urlResolver.ts

@@ -0,0 +1,129 @@
+import { LLAMA_SERVER_URL } from "../constants";
+import type { LlamaSettings } from "../interfaces/settings";
+import { ServerUrl } from "./urls";
+
+/**
+ * Settings readers injected by {@link LlamaSettingsManager}. Both reload
+ * settings from disk before reading, so the resolver always sees fresh data.
+ */
+export interface UrlResolverDeps {
+  /** Merged `llamaSettings` (project overrides global). */
+  getLlamaSettings(): Promise<LlamaSettings>;
+  /** Fully merged settings map (used for the legacy `llamaServerUrl` key). */
+  getMergedSettings(): Promise<Record<string, any>>;
+}
+
+/**
+ * Multi-source llama-server URL resolution chain (see REFACTOR.md #4).
+ *
+ * Resolves URLs in priority order:
+ *
+ * 1. `LLAMA_SERVER_URL` env variable
+ * 2. `llamaSettings.servers[].url` (current — project, then global)
+ * 3. `llamaServerUrl` key (legacy — project, then global)
+ * 4. Default URL
+ *
+ * Owns the warnings collected for dropped invalid URL entries; the
+ * settings manager surfaces them via `takeWarnings()`.
+ */
+export class UrlResolver {
+  /** Warnings collected during URL resolution (dropped invalid entries). */
+  private warnings: string[] = [];
+
+  constructor(private readonly deps: UrlResolverDeps) {}
+
+  /**
+   * Returns and clears warnings collected during URL resolution.
+   */
+  takeWarnings(): string[] {
+    const warnings = [...this.warnings];
+    this.warnings.length = 0;
+    return warnings;
+  }
+
+  /**
+   * Resolves the server URLs to use in the following order:
+   *
+   * - `LLAMA_SERVER_URL` env variable
+   * - `llamaSettings` key (current - project, then global)
+   * - `llamaServerUrl` key (legacy - project, then global)
+   * - Default URL
+   *
+   * @returns The list of URLs to use
+   */
+  async resolveUrls(): Promise<string[]> {
+    let response = this.resolveEnvUrls();
+    if (response.length > 0) return response;
+
+    response = await this.resolveServerUrls();
+    if (response.length > 0) return response;
+
+    response = await this.resolveLegacyUrls();
+    if (response.length > 0) return response;
+
+    return [LLAMA_SERVER_URL];
+  }
+
+  /**
+   * Resolves the llama-server URLs from the environment variable.
+   *
+   * @returns A list of detected URLs
+   */
+  private resolveEnvUrls(): string[] {
+    const raw = process.env.LLAMA_SERVER_URL;
+    if (!raw) return [];
+
+    return this.parseUrls(raw);
+  }
+
+  /**
+   * Resolves the llama-server URLs from `llamaSettings.servers`.
+   * Settings are merged, prioritizing project over global settings.
+   * Reloads settings from disk before reading.
+   *
+   * @returns A list of detected URLs
+   */
+  private async resolveServerUrls(): Promise<string[]> {
+    const { servers = [] } = await this.deps.getLlamaSettings();
+    return servers.map((s) => this.parseUrls(s.url)).flat();
+  }
+
+  /**
+   * Resolves the llama-server URLs from `llamaServerUrl` legacy key.
+   * Settings are merged, prioritizing project over global settings.
+   * Reloads settings from disk before reading.
+   *
+   * @returns A list of detected URLs
+   */
+  private async resolveLegacyUrls(): Promise<string[]> {
+    const { llamaServerUrl = null } = await this.deps.getMergedSettings();
+    if (!llamaServerUrl) return [];
+
+    return this.parseUrls(llamaServerUrl);
+  }
+
+  /**
+   * Parses a raw URL string into an array of cleaned URLs.
+   * Splits on semicolons, trims whitespace, filters empty strings, strips
+   * trailing slashes, and drops entries without an http(s) scheme —
+   * collecting a warning for each dropped entry (same validation the
+   * `/models servers` editor applies).
+   *
+   * @returns A sanitized URL
+   */
+  private parseUrls(raw: string): string[] {
+    return raw
+      .split(";")
+      .map(ServerUrl.normalize)
+      .filter((u) => {
+        if (u.length === 0) return false;
+        if (!ServerUrl.isValid(u)) {
+          this.warnings.push(
+            `Ignoring invalid server URL '${u}' (needs http(s)://)`,
+          );
+          return false;
+        }
+        return true;
+      });
+  }
+}

package/src/utils/urls.ts

@@ -1,16 +1,36 @@
 /**
- * Shared URL core: trims surrounding whitespace and strips trailing
- * slashes. Used by the settings parser (`parseUrls`) and the editor
- * validator (`normalizeServerUrl`) so the two can't drift.
+ * Shared server-URL handling: the single place where normalization and
+ * validation live, used by the settings parser (`UrlResolver.parseUrls`,
+ * see `utils/urlResolver`) and the editor field validator
+ * (`ServerFields`) so the two can't drift.
  */
-export const normalizeUrl = (raw: string): string =>
-  raw.trim().replace(/\/+$/, "");
+export class ServerUrl {
+  /** Trims surrounding whitespace and strips trailing slashes — the
+   * same treatment the settings parser applies. */
+  static normalize(raw: string): string {
+    return raw.trim().replace(/\/+$/, "");
+  }
 
-/**
- * True when the URL carries an http(s) scheme — the only schemes
- * llama-server endpoints use. Part of the shared validation applied by
- * both the settings parser (`parseUrls`) and the editor validator
- * (`normalizeServerUrl`).
- */
-export const isValidServerUrl = (url: string): boolean =>
-  /^https?:\/\//i.test(url);
+  /** True when the URL carries an http(s) scheme — the only schemes
+   * llama-server endpoints use. */
+  static isValid(url: string): boolean {
+    return /^https?:\/\//i.test(url);
+  }
+
+  /**
+   * Validates and normalizes a user-entered server URL: `normalize`,
+   * then rejects empty strings, semicolons (the settings parser splits
+   * on them — use separate entries) and values without an http(s) scheme.
+   *
+   * @returns The normalized URL, or `null` when the input is invalid
+   */
+  static parse(raw: string): string | null {
+    // Reference the class explicitly (not `this`) so `parse` can be
+    // passed around as a bare callback (e.g. as a field validator)
+    const url = ServerUrl.normalize(raw);
+    if (url.length === 0 || url.includes(";") || !ServerUrl.isValid(url)) {
+      return null;
+    }
+    return url;
+  }
+}

package/tests/commandManager.test.ts

@@ -3,15 +3,16 @@ 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";
+import { CommandManager } from "../src/managers/command";
+import { ServerManager } from "../src/managers/server";
+import type { LlamaSettingsManager } from "../src/managers/settings";
+import { ServerSettingsList } from "../src/ui/editors/server/serverEditor";
+import { ServerDisplay } from "../src/ui/editors/server/utils";
 import {
   applySettingChange,
   buildSettingsItems,
-  CommandManager,
   formatMs,
-} from "../src/managers/command";
-import { ServerManager } from "../src/managers/server";
-import type { LlamaSettingsManager } from "../src/managers/settings";
-import { ServerSettingsList } from "../src/ui/serverSettingsList";
+} from "../src/ui/settings";
 import {
   createMockCtx,
   createMockModel,
@@ -25,8 +26,27 @@ beforeEach(() => {
   initTheme();
   vi.clearAllMocks();
   mockRpc.mockResolvedValue({ data: [] });
+  // Mock health checks to return "healthy" immediately
+  vi.spyOn(ServerDisplay, "healthEmoji").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;
@@ -234,7 +254,7 @@ describe("CommandManager", () => {
         bold: (text: string) => text,
       }) as unknown as Theme;
 
-    it("should open the editor without touching servers", async () => {
+    it("should re-register providers after the editor closes", async () => {
       const updateSpy = vi
         .spyOn(serverManager, "update")
         .mockResolvedValue(undefined);
@@ -242,8 +262,13 @@ describe("CommandManager", () => {
 
       await commandManager.handleCommand("servers", ctx as any, mockPi as any);
 
-      expect(updateSpy).not.toHaveBeenCalled();
       expect(ctx.ui.custom).toHaveBeenCalledTimes(1);
+      expect(updateSpy).toHaveBeenCalledTimes(1);
+      // Re-registration happens on close, not on open. The mock dialog
+      // resolves immediately, so the update call must come after custom.
+      expect(updateSpy.mock.invocationCallOrder[0]).toBeGreaterThan(
+        vi.mocked(ctx.ui.custom).mock.invocationCallOrder[0],
+      );
     });
 
     it("should notify instead of opening the editor outside the TUI", async () => {
@@ -289,6 +314,8 @@ describe("CommandManager", () => {
       );
 
       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");
 
@@ -302,6 +329,7 @@ describe("CommandManager", () => {
       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" },
@@ -372,6 +400,9 @@ describe("CommandManager", () => {
         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");