pi-llama-cpp 0.13.0 → 0.15.0

package/src/ui/settings/index.ts

@@ -0,0 +1,248 @@
+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",
+  SHOW_SERVER_URLS = "showServerUrls",
+}
+
+// ─── 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),
+    },
+    {
+      id: Options.SHOW_SERVER_URLS,
+      label: "Show server URLs",
+      description: "Show [Server: <url>] in /models (next open)",
+      currentValue: (await settings.resolveShowServerUrls()) ? "on" : "off",
+      values: ["on", "off"],
+    },
+  ];
+};
+
+/**
+ * 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;
+    case Options.SHOW_SERVER_URLS:
+      await settings.setLlamaSetting("showServerUrls", newValue === "on");
+      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

@@ -1,3 +1,5 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 import { LLAMA_SERVER_URL } from "../constants";
 
 /**
@@ -94,10 +96,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 +128,21 @@ 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;
+
+/**
+ * Generates a warning message for servers that require an API key.
+ * Centralized so both the runtime manager and the editor wizard use
+ * identical wording.
+ */
+export const authRequiredMessage = (
+  baseUrl: string,
+  providerId: string,
+): string =>
+  [
+    "[pi-llama-cpp]",
+    `Server at '${baseUrl}' requires a valid API key.`,
+    `Configure the key via '/login ${providerId}' or in '${getAgentDir()}/auth.json'.`,
+  ].join("\n");

package/src/utils/health.ts

@@ -1,4 +1,5 @@
 import { ServerStatus } from "../enums/serverStatus";
+import type { HealthEndpoint } from "../interfaces/endpoints/health";
 
 /**
  * Probes a llama-server's `/health` endpoint and classifies the outcome.
@@ -34,7 +35,7 @@ export const checkServerHealth = async (
       signal: AbortSignal.timeout(timeout),
       headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined,
     });
-    const data = (await response.json()) as { status?: string };
+    const data = (await response.json()) as HealthEndpoint;
     return data.status === "ok" ? ServerStatus.READY : ServerStatus.UNREACHABLE;
   } catch (error) {
     // `AbortSignal.timeout` rejects `fetch` with a `TimeoutError`

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
+ *
+ * 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 → command/commandManager.test.ts}

@@ -2,17 +2,17 @@ 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";
+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 * as serverListEditor from "../src/ui/serverListEditor";
-import { ServerSettingsList } from "../src/ui/serverSettingsList";
+} from "../../src/ui/settings";
 import {
   createMockCtx,
   createMockModel,
@@ -20,14 +20,15 @@ import {
   createMockServer,
   makeSettingsStub,
   mockRpc,
-} from "./mocks";
+} from "../mocks";
 
 beforeEach(() => {
   initTheme();
   vi.clearAllMocks();
   mockRpc.mockResolvedValue({ data: [] });
-  // Mock health checks to return "healthy" immediately
-  vi.spyOn(serverListEditor, "getServerHealthEmoji").mockResolvedValue("🟢");
+  // Mock health checks and auth probes to return immediately
+  vi.spyOn(ServerDisplay, "healthEmoji").mockResolvedValue("🟢");
+  vi.spyOn(ServerDisplay, "authEmoji").mockResolvedValue("");
 });
 
 /**
@@ -163,6 +164,7 @@ describe("CommandManager", () => {
         "sortBy",
         "pollingTimeout",
         "serverTimeout",
+        "showServerUrls",
       ]);
       // Booleans are displayed as on/off
       expect(items[0].values).toEqual(["on", "off"]);
@@ -203,6 +205,18 @@ describe("CommandManager", () => {
         "serverTimeout",
         500,
       );
+
+      await applySettingChange("showServerUrls", "on", settingsStub);
+      expect(settingsStub.setLlamaSetting).toHaveBeenCalledWith(
+        "showServerUrls",
+        true,
+      );
+
+      await applySettingChange("showServerUrls", "off", settingsStub);
+      expect(settingsStub.setLlamaSetting).toHaveBeenCalledWith(
+        "showServerUrls",
+        false,
+      );
     });
   });
 
@@ -254,7 +268,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);
@@ -262,8 +276,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 () => {
@@ -559,5 +578,62 @@ describe("CommandManager", () => {
       expect(choices).toHaveLength(2);
       expect(choices[1]).toContain("model-b");
     });
+
+    it("should omit server URLs when showServerUrls is false", async () => {
+      const models = [createMockModel("model-a")];
+      const mockPi = createMockPi();
+      const servers = models.map((model) =>
+        createMockServer({
+          baseUrl: model.serverUrl,
+          models: [model],
+        }),
+      );
+      const settingsStub = makeSettingsStub({
+        resolveServers: vi.fn(async () => servers),
+        resolveShowServerUrls: vi.fn(async () => false),
+      });
+      const serverManager = new ServerManager(settingsStub);
+      const commandManager = new CommandManager(serverManager, settingsStub);
+
+      const ctx = createMockCtx((prompt, options) => {
+        if (prompt.includes("models")) return options[0];
+        return Action.INFO;
+      });
+
+      await commandManager.handleCommand("", ctx as any, mockPi as any);
+
+      const choices = vi.mocked(ctx.ui.select).mock.calls[0][1] as string[];
+      expect(choices).toHaveLength(1);
+      expect(choices[0]).toBe("model-a  ");
+      expect(choices[0]).not.toContain("[Server:");
+    });
+
+    it("should include server URLs when showServerUrls is true", async () => {
+      const models = [createMockModel("model-a")];
+      const mockPi = createMockPi();
+      const servers = models.map((model) =>
+        createMockServer({
+          baseUrl: model.serverUrl,
+          models: [model],
+        }),
+      );
+      const settingsStub = makeSettingsStub({
+        resolveServers: vi.fn(async () => servers),
+        resolveShowServerUrls: vi.fn(async () => true),
+      });
+      const serverManager = new ServerManager(settingsStub);
+      const commandManager = new CommandManager(serverManager, settingsStub);
+
+      const ctx = createMockCtx((prompt, options) => {
+        if (prompt.includes("models")) return options[0];
+        return Action.INFO;
+      });
+
+      await commandManager.handleCommand("", ctx as any, mockPi as any);
+
+      const choices = vi.mocked(ctx.ui.select).mock.calls[0][1] as string[];
+      expect(choices).toHaveLength(1);
+      expect(choices[0]).toContain("[Server: http://127.0.0.1:8080]");
+    });
   });
 });