pi-llama-cpp 0.14.0 → 0.16.0

package/src/ui/editors/override/fields/capabilities.ts

@@ -0,0 +1,36 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { FIELDS } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+
+/** The override's `capabilities` list (finite: fixed label options). */
+export class CapabilitiesField extends OverrideField {
+  readonly id = "capabilities";
+  readonly type = "finite";
+  readonly field = FIELDS.capabilities;
+  override readonly options = ["text", "text | image"];
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.override.capabilities?.join(" | ") ?? "text";
+  }
+
+  readonly validate: InputValidator = (raw) =>
+    this.options?.includes(raw) ? raw : null;
+
+  apply(override: ModelOverride, value: string): void {
+    override.capabilities =
+      value === "text | image"
+        ? ["text", "image"]
+        : value === "text"
+          ? ["text"]
+          : undefined;
+  }
+
+  /** Appears in the summary only when non-empty. */
+  override summaryPart(override: ModelOverride): string | null {
+    return override.capabilities?.length
+      ? `capabilities: ${override.capabilities.join(",")}`
+      : null;
+  }
+}

package/src/ui/editors/override/fields/cost.ts

@@ -0,0 +1,64 @@
+import type { ModelCost, ModelCostRates } from "@earendil-works/pi-ai";
+import type { ModelOverride } from "../../../../interfaces/settings";
+import type { Field } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+import { parseNonNegative } from "./numeric";
+
+/**
+ * One `ModelCostRates` key of the override's `cost` object (absorbs the
+ * former `CostFieldDefFactory` and the standalone `parseCostValue` /
+ * `applyCostFieldValue` helpers): owns the cost parse and immutable
+ * apply in the same place as its display format.
+ */
+export class CostField extends OverrideField {
+  readonly type = "input";
+  override readonly field: Field;
+
+  constructor(
+    readonly id: string,
+    private readonly key: keyof ModelCostRates,
+    field: Field,
+    /** Short term used in the entry-row summary (e.g. `cache read`). */
+    private readonly summaryTerm: string,
+  ) {
+    super();
+    this.field = field;
+  }
+
+  displayValue(entry: OverrideEntry): string {
+    return String(entry.override.cost?.[this.key] ?? 0);
+  }
+
+  readonly validate: InputValidator = (raw) => {
+    const parsed = parseNonNegative(raw);
+    return parsed === null ? null : String(parsed);
+  };
+
+  apply(override: ModelOverride, value: string): void {
+    const nextCost = this.applyCost(override.cost, Number(value));
+    if (nextCost) override.cost = nextCost;
+    else delete override.cost;
+  }
+
+  /** Returns a copy of `cost` with this field set to `value`. A `0` (or
+   * non-finite) value removes the field — unset cost fields default to
+   * zero at read time — and when no fields remain, returns `undefined`
+   * so the whole `cost` object can be dropped. Immutable. */
+  private applyCost(
+    cost: ModelOverride["cost"],
+    value: number,
+  ): Partial<ModelCost> | undefined {
+    const next = { ...cost };
+    if (isFinite(value) && value > 0) next[this.key] = value;
+    else delete next[this.key];
+    return Object.keys(next).length > 0 ? next : undefined;
+  }
+
+  /** Appears in the summary only when a non-zero cost is set. */
+  override summaryPart(override: ModelOverride): string | null {
+    const value = override.cost?.[this.key];
+    return value ? `${this.summaryTerm}: $${value}` : null;
+  }
+}

package/src/ui/editors/override/fields/index.ts

@@ -0,0 +1,68 @@
+import type { ModelCostRates } from "@earendil-works/pi-ai";
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { FIELDS } from "../../../strings";
+import { OverrideField } from "./base";
+import { CapabilitiesField } from "./capabilities";
+import { CostField } from "./cost";
+import { NumericField } from "./numeric";
+import { PatternField } from "./pattern";
+import { ReasoningField } from "./reasoning";
+
+/** Cost field specs: [ModelCostRates key, FIELDS entry, summary term] */
+const COST_FIELDS: [
+  keyof ModelCostRates,
+  (
+    | typeof FIELDS.inputCost
+    | typeof FIELDS.outputCost
+    | typeof FIELDS.cacheReadCost
+    | typeof FIELDS.cacheWriteCost
+  ),
+  string,
+][] = [
+  ["input", FIELDS.inputCost, "input"],
+  ["output", FIELDS.outputCost, "output"],
+  ["cacheRead", FIELDS.cacheReadCost, "cache read"],
+  ["cacheWrite", FIELDS.cacheWriteCost, "cache write"],
+];
+
+/**
+ * The field registry for model override entries: the complete list of
+ * editable fields (order defines the row order in the settings list)
+ * plus id-based lookup. Throws on an unknown id — the registry is
+ * static, so a miss is a programming error.
+ */
+export class OverrideFields {
+  static readonly all: OverrideField[] = [
+    new PatternField(),
+    ...COST_FIELDS.map(
+      ([key, field, term]) => new CostField(`cost.${key}`, key, field, term),
+    ),
+    new CapabilitiesField(),
+    new ReasoningField(),
+    new NumericField("contextSize", FIELDS.contextSize),
+    new NumericField("maxTokens", FIELDS.maxTokens),
+  ];
+
+  static byId(id: string): OverrideField {
+    const field = this.all.find((f) => f.id === id);
+    if (!field) throw new Error(`Unknown override field: ${id}`);
+    return field;
+  }
+}
+
+/**
+ * Builds the entry-row summary shown in the override entry list
+ * (`input: $0.2, output: $0.6, cache read: $0.01, …`), composed from the
+ * {@link OverrideFields} registry — adding a field to the registry makes
+ * it show up here too, so the summary can't lag the edit menu. Fields
+ * with unset/zero values are omitted for brevity (each field decides via
+ * {@link OverrideField.summaryPart}); `—` when nothing is set.
+ */
+export class OverrideSummary {
+  static of(override: ModelOverride): string {
+    const parts = OverrideFields.all
+      .map((field) => field.summaryPart(override))
+      .filter((part): part is string => part !== null);
+    return parts.length > 0 ? parts.join(", ") : "—";
+  }
+}

package/src/ui/editors/override/fields/numeric.ts

@@ -0,0 +1,55 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import type { Field } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+
+/** Parses a non-negative number; blank input means zero (unset fields
+ * default to zero at read time). Returns `null` when invalid. */
+export function parseNonNegative(raw: string): number | null {
+  const n = Number(raw.trim());
+  return isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * Non-negative numeric field (`contextSize`, `maxTokens`): keeps the
+ * display format, validator and apply logic in a single place so the
+ * three can't drift (e.g. the validator accepting `0` while the apply
+ * drops it — unset fields default to zero at read time, so all render
+ * as `0`).
+ */
+export class NumericField extends OverrideField {
+  readonly type = "input";
+  override readonly field: Field;
+
+  constructor(
+    readonly id: "maxTokens" | "contextSize",
+    field: Field,
+  ) {
+    super();
+    this.field = field;
+  }
+
+  displayValue(entry: OverrideEntry): string {
+    return String(entry.override[this.id] ?? 0);
+  }
+
+  /** Accepts finite, non-negative numbers (blank means zero). */
+  readonly validate: InputValidator = (raw) => {
+    const n = parseNonNegative(raw);
+    return n === null ? null : String(n);
+  };
+
+  /** Applies the committed value; non-positive values remove the key. */
+  apply(override: ModelOverride, value: string): void {
+    const n = Number(value);
+    if (isFinite(n) && n > 0) override[this.id] = n;
+    else delete override[this.id];
+  }
+
+  /** Appears in the summary only when set. */
+  override summaryPart(override: ModelOverride): string | null {
+    const value = override[this.id];
+    return value === undefined ? null : `${this.id}: ${value}`;
+  }
+}

package/src/ui/editors/override/fields/pattern.ts

@@ -0,0 +1,24 @@
+import { FIELDS } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+
+/**
+ * The entry's pattern key. Renames are handled by the editor
+ * (`OverrideEntryListEditor.applyFieldChange`), so {@link apply}
+ * inherits the base no-op.
+ */
+export class PatternField extends OverrideField {
+  readonly id = "pattern";
+  readonly type = "input";
+  readonly field = FIELDS.pattern;
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.pattern;
+  }
+
+  readonly validate: InputValidator = (raw) => {
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  };
+}

package/src/ui/editors/override/fields/reasoning.ts

@@ -0,0 +1,33 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { FIELDS } from "../../../strings";
+import { OverrideEntry } from "../entry";
+import type { InputValidator } from "./base";
+import { OverrideField } from "./base";
+
+/** The override's `reasoning` flag (finite: true/false, default true). */
+export class ReasoningField extends OverrideField {
+  readonly id = "reasoning";
+  readonly type = "finite";
+  readonly field = FIELDS.reasoning;
+  override readonly options = ["true", "false"];
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.override.reasoning === false ? "false" : "true";
+  }
+
+  readonly validate: InputValidator = (raw) =>
+    this.options?.includes(raw) ? raw : null;
+
+  apply(override: ModelOverride, value: string): void {
+    if (value === "true") override.reasoning = true;
+    else if (value === "false") override.reasoning = false;
+    else delete override.reasoning;
+  }
+
+  /** Appears in the summary only when explicitly set. */
+  override summaryPart(override: ModelOverride): string | null {
+    return override.reasoning === undefined
+      ? null
+      : `reasoning: ${override.reasoning}`;
+  }
+}

package/src/ui/editors/override/itemBuilder.ts

@@ -2,7 +2,8 @@ import type { SettingItem } from "@earendil-works/pi-tui";
 import { FieldMessages, TITLES } from "../../strings";
 import { ItemBuilder } from "../itemBuilder";
 import { OverrideEntry } from "./entry";
-import { OverrideFields, type OverrideField } from "./fields";
+import type { OverrideField } from "./fields/base";
+import { OverrideFields } from "./fields/index";
 
 /**
  * Builds `SettingItem` objects for override entry field submenus.
@@ -11,7 +12,7 @@ export class OverrideItemBuilder extends ItemBuilder<
   OverrideEntry,
   OverrideField
 > {
-  protected get fields(): readonly OverrideField[] {
+  protected override get fields(): readonly OverrideField[] {
     return OverrideFields.all;
   }
 
@@ -20,9 +21,8 @@ export class OverrideItemBuilder extends ItemBuilder<
    * an `InputDialog` submenu (validating against the field definition)
    * for "input" fields.
    */
-  protected decorate(
+  protected override decorate(
     def: OverrideField,
-    entry: OverrideEntry,
     base: SettingItem,
   ): SettingItem {
     if (def.type === "finite") {

package/src/ui/editors/server/fields.ts

@@ -26,7 +26,7 @@ class UrlField extends ServerField {
   readonly field = FIELDS.serverUrl;
   readonly validate = ServerUrl.parse;
 
-  currentValue(server: LlamaServer): string {
+  override currentValue(server: LlamaServer): string {
     return server.url;
   }
 
@@ -51,7 +51,7 @@ class OptionalTextField extends ServerField {
     this.field = field;
   }
 
-  currentValue(server: LlamaServer): string {
+  override currentValue(server: LlamaServer): string {
     return server[this.id] ?? "";
   }
 

package/src/ui/editors/server/itemBuilder.ts

@@ -10,7 +10,7 @@ import { ServerDisplay } from "./utils";
  * Builds `SettingItem` objects for server rows and their field-edit submenus.
  */
 export class ServerItemBuilder extends ItemBuilder<LlamaServer, ServerField> {
-  protected get fields(): readonly ServerField[] {
+  protected override get fields(): readonly ServerField[] {
     return ServerFields.all;
   }
 
@@ -18,9 +18,8 @@ export class ServerItemBuilder extends ItemBuilder<LlamaServer, ServerField> {
    * Adds the field-edit submenu: an `InputDialog` validating against the
    * field definition.
    */
-  protected decorate(
+  protected override decorate(
     def: ServerField,
-    server: LlamaServer,
     base: SettingItem,
   ): SettingItem {
     return {

package/src/ui/editors/server/serverEditor.ts

@@ -3,11 +3,12 @@ import type { SettingItem, SettingsList } from "@earendil-works/pi-tui";
 import { SERVER_TIMEOUT } from "../../../constants";
 import type { LlamaServer } from "../../../interfaces/settings";
 import type { LlamaSettingsManager } from "../../../managers/settings";
-import { TITLES } from "../../strings";
+import { ServerIds } from "../../../utils/serverIds";
+import { TITLES, authRequiredMessage } from "../../strings";
 import type { ServerSettingsListOptions } from "../editorOptions";
 import { ListEditor } from "../listEditor";
 import { SettingsListFactory } from "../settingsListFactory";
-import { ServerEntryMutator } from "./handlers";
+import { ServerFields } from "./fields";
 import { ServerItemBuilder } from "./itemBuilder";
 import { ServerDisplay } from "./utils";
 import { ServerWizard } from "./wizard";
@@ -58,26 +59,42 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
           done: () => done(undefined),
           onError: (message) => ui.notify(message, "error"),
           serverTimeout,
+          authResolver: async (server) => {
+            // Mirror Server.getApiKey(): use ServerIds.resolve to get
+            // the provider ID (customId or llama-server=<url>), then
+            // resolve the key from the credential store.
+            return settings.resolveApiKey(
+              ServerIds.resolve(server.url, server.id),
+            );
+          },
+          ui,
         }),
     );
   }
 
   // -- abstract hooks -------------------------------------------------------
 
-  protected async buildSettingsList(): Promise<SettingsList> {
+  protected override async buildSettingsList(): Promise<SettingsList> {
     const builder = new ServerItemBuilder(this.dialogs);
     const serverTimeout = this.options.serverTimeout ?? SERVER_TIMEOUT;
-    const healthEmojis = await Promise.all(
-      this.options.servers.map((server) =>
-        ServerDisplay.healthEmoji(server.url, serverTimeout),
-      ),
+    // Run auth + health probes in parallel; ⛔ wins if auth fails,
+    // otherwise fall back to the health emoji.
+    const probes = await Promise.all(
+      this.options.servers.map(async (server) => {
+        const apiKey = (await this.options.authResolver?.(server)) ?? "";
+        const [authEmoji, healthEmoji] = await Promise.all([
+          ServerDisplay.authEmoji(server.url, apiKey, serverTimeout),
+          ServerDisplay.healthEmoji(server.url, serverTimeout),
+        ]);
+        return authEmoji || healthEmoji;
+      }),
     );
     const items: SettingItem[] = this.options.servers.map((server, i) =>
       builder.buildRow(
         server,
         i,
         (field, value) => this.handleFieldChange(field, value),
-        healthEmojis[i],
+        probes[i],
         // Opening delegates input to the submenu; closing flushes a
         // rebuild deferred by a field commit (see commitFieldChange)
         (open) => this.trackSubmenu(open),
@@ -92,10 +109,13 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
   /** Handle a field commit from a server row's submenu. */
   private handleFieldChange(field: string, value: string): void {
     const idx = this.selectedIndex;
-    const next = new ServerEntryMutator(
-      this.options.servers,
-      idx,
-    ).applyFieldChange(field, value);
+    const server = this.options.servers[idx];
+    const updated = server
+      ? ServerFields.byId(field).apply(server, value)
+      : server;
+    const next = server
+      ? this.options.servers.map((s, i) => (i === idx ? updated : s))
+      : this.options.servers;
 
     this.commitFieldChange(next, idx, () => {
       // Refresh the row's suffix in place; the full rebuild (row labels
@@ -111,7 +131,7 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
     });
   }
 
-  protected beginAdd(): void {
+  protected override beginAdd(): void {
     const wizard = new ServerWizard(this.dialogs, (dialog) =>
       this.openDialog(dialog),
     );
@@ -124,7 +144,7 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
     );
   }
 
-  protected deleteSelected(): void {
+  protected override deleteSelected(): void {
     const idx = this.selectedIndex;
     const next = this.options.servers.filter((_, i) => i !== idx);
     void this.persistSnapshot(next, () => {
@@ -132,21 +152,17 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
     });
   }
 
-  protected readonly emptyHintKey = "emptyServers" as const;
-
-  protected getCurrentCount(): number {
-    return this.options.servers.length;
-  }
+  protected override readonly emptyHintKey = "emptyServers" as const;
 
-  protected getRowId(index: number): string {
+  protected override getRowId(index: number): string {
     return `server-${index}`;
   }
 
-  protected getRowLabel(index: number): string {
+  protected override getRowLabel(index: number): string {
     return this.options.servers[index]?.url ?? "";
   }
 
-  protected get deleteTitle(): string {
+  protected override get deleteTitle(): string {
     return TITLES.deleteServer;
   }
 
@@ -157,5 +173,25 @@ export class ServerSettingsList extends ListEditor<ServerSettingsListOptions> {
     await this.persistSnapshot(next, () => {
       void this.rebuildList(next.length - 1);
     });
+
+    // Warn the user if the newly added server requires an API key
+    await this.warnIfAuthRequired(server);
+  }
+
+  /**
+   * Probes the server to check if it requires an API key. If so, notifies
+   * the user so they know to configure one via `/login` or `auth.json`.
+   */
+  private async warnIfAuthRequired(server: LlamaServer): Promise<void> {
+    const ui = this.options.ui;
+    if (!ui) return;
+
+    const serverTimeout = this.options.serverTimeout ?? SERVER_TIMEOUT;
+    const apiKey = (await this.options.authResolver?.(server)) ?? "";
+
+    if (await ServerDisplay.requiresApiKey(server.url, apiKey, serverTimeout)) {
+      const providerId = ServerIds.resolve(server.url, server.id);
+      ui.notify(authRequiredMessage(server.url, providerId), "warning");
+    }
   }
 }

package/src/ui/editors/server/utils.ts

@@ -1,8 +1,12 @@
+import { ENDPOINT_PREFIX } from "../../../constants";
 import { ServerStatus } from "../../../enums/serverStatus";
 import type { LlamaServer } from "../../../interfaces/settings";
 import { checkServerHealth } from "../../../utils/health";
 import { ServerIds } from "../../../utils/serverIds";
 
+/** Emoji shown when a server requires an API key (401 on /v1/models). */
+const UNAUTHORIZED_EMOJI = "⛔";
+
 /**
  * Display concerns for a server row in the top-level list: the dim
  * `(...)` suffix after the URL and the health-status icon.
@@ -33,6 +37,52 @@ export class ServerDisplay {
   static async healthEmoji(url: string, timeout: number): Promise<string> {
     return SERVER_STATUS_ICONS[await checkServerHealth(url, timeout)];
   }
+
+  /**
+   * Checks if the server requires an API key by probing `/v1/models`.
+   *
+   * @param url - The server URL to check
+   * @param apiKey - The API key to send (may be a placeholder)
+   * @param timeout - Maximum time (ms) to wait for the request
+   * @returns `true` if the server responded with 401, `false` otherwise
+   */
+  static async requiresApiKey(
+    url: string,
+    apiKey: string,
+    timeout: number,
+  ): Promise<boolean> {
+    try {
+      const response = await fetch(`${url}${ENDPOINT_PREFIX}/models`, {
+        signal: AbortSignal.timeout(timeout),
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      return response.status === 401;
+    } catch {
+      // Timeout or network error — the server is unreachable, so no auth
+      // indicator is needed (the health emoji will cover that).
+      return false;
+    }
+  }
+
+  /**
+   * Probes the server's `/v1/models` endpoint to check if authentication
+   * is required. Returns ⛔ when the server responds with 401, empty string
+   * otherwise.
+   *
+   * @param url - The server URL to check
+   * @param apiKey - The API key to send (may be a placeholder)
+   * @param timeout - Maximum time (ms) to wait for the request
+   * @returns The emoji indicator (⛔ if 401, "" otherwise)
+   */
+  static async authEmoji(
+    url: string,
+    apiKey: string,
+    timeout: number,
+  ): Promise<string> {
+    return (await this.requiresApiKey(url, apiKey, timeout))
+      ? UNAUTHORIZED_EMOJI
+      : "";
+  }
 }
 
 /**

package/src/ui/settings/index.ts

@@ -26,6 +26,7 @@ export enum Options {
   SORT_BY = "sortBy",
   POLLING_TIMEOUT = "pollingTimeout",
   SERVER_TIMEOUT = "serverTimeout",
+  SHOW_SERVER_URLS = "showServerUrls",
 }
 
 // ─── Constants ──────────────────────────────────────────────────────────────
@@ -110,6 +111,13 @@ export const buildSettingsItems = async (
       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"],
+    },
   ];
 };
 
@@ -139,6 +147,9 @@ export const applySettingChange = async (
     case Options.SERVER_TIMEOUT:
       await settings.setLlamaSetting("serverTimeout", parseMs(newValue));
       return;
+    case Options.SHOW_SERVER_URLS:
+      await settings.setLlamaSetting("showServerUrls", newValue === "on");
+      return;
   }
 };
 

package/src/ui/strings.ts

@@ -1,3 +1,5 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 import { LLAMA_SERVER_URL } from "../constants";
 
 /**
@@ -129,3 +131,18 @@ export const HINTS = {
   /** 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");