pi-llama-cpp 0.13.0 → 0.15.0

package/README.md

@@ -17,14 +17,13 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with running [lla
 
 ### Status Indicators
 
-| Icon | Status       | Description                            |
-| ---- | ------------ | -------------------------------------- |
-| 🟢   | Loaded       | Model is active and ready to use       |
-| 🟡   | Loading      | Model is currently being loaded        |
-| 🔴   | Failed       | Model failed to load                   |
-| 🔵   | Sleeping     | Model is available, but inactive       |
-| ⚪   | Unloaded     | Model is not loaded on the server      |
-| ⛔   | Unauthorized | Model can't be used (API key required) |
+| Icon | Status   | Description                       |
+| ---- | -------- | --------------------------------- |
+| 🟢   | Loaded   | Model is active and ready to use  |
+| 🟡   | Loading  | Model is currently being loaded   |
+| 🔴   | Failed   | Model failed to load              |
+| 🔵   | Sleeping | Model is available, but inactive  |
+| ⚪   | Unloaded | Model is not loaded on the server |
 
 > **Note**: The `Sleeping` status only shows when you start your server with `llama-server --sleep-idle-seconds <n> ...`.
 > This is a **llama.cpp server flag** that tells the server to put idle models to sleep after `n` seconds.
@@ -36,11 +35,12 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with running [lla
 
 When browsing servers via `/models servers`, each server URL is prefixed with a health indicator:
 
-| Icon | Status      | Description                                   |
-| ---- | ----------- | --------------------------------------------- |
-| 🟢   | Healthy     | Server responded successfully to health check |
-| 🟡   | Timeout     | Server health check timed out                 |
-| 🔴   | Unreachable | Server could not be reached                   |
+| Icon | Status       | Description                                   |
+| ---- | ------------ | --------------------------------------------- |
+| 🟢   | Healthy      | Server responded successfully to health check |
+| 🟡   | Timeout      | Server health check timed out                 |
+| 🔴   | Unreachable  | Server could not be reached                   |
+| ⛔   | Unauthorized | Server requires an API key                    |
 
 ## Installation
 
@@ -128,6 +128,7 @@ With this config, the servers will appear in Pi as **Llama.cpp (Local Server)**
 | `sortBy`             | string  | `"asc"` | Sort order for models (see below)                             |
 | `pollingTimeout`     | number  | `60000` | Max time (ms) to wait for model loading before giving up      |
 | `serverTimeout`      | number  | `1000`  | Timeout (ms) for server health checks and SSE probes          |
+| `showServerUrls`     | boolean | `true`  | Show `[Server: <url>]` suffix in the /models model list       |
 
 > **Note:** `serverTimeout` controls individual HTTP request timeouts (health checks, SSE probe). `pollingTimeout` controls the total wait time for a model to finish loading. Increase `serverTimeout` for slow/high-latency servers, and `pollingTimeout` for large models or slow hardware.
 
@@ -138,11 +139,11 @@ Run `/models settings` to edit the scalar settings above without hand-editing JS
 #### Server list editor
 
 Run `/models servers` to add, edit or remove entries of `llamaSettings.servers`
-without hand-editing JSON. Each server URL is prefixed with a health indicator
-(🟢 healthy, 🟡 timeout, 🔴 unreachable) that reflects the result of a
-health check against the server. Each change is written immediately to the **project**
-`.pi/settings.json` if it exists, otherwise to **global**
-`~/.pi/agent/settings.json`.
+without hand-editing JSON. Each server URL is prefixed with a status indicator
+(🟢 healthy, 🟡 timeout, 🔴 unreachable, ⛔ unauthorized) that reflects the
+result of a health check and an auth probe against the server. Each change is
+written immediately to the **project** `.pi/settings.json` if it exists,
+otherwise to **global** `~/.pi/agent/settings.json`.
 
 Changes take effect immediately after closing the editor: new servers
 register their providers, removed ones leave pi's registry right away,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Pi extension for llama.cpp integration. Supports router, single and legacy models. Supports multiple servers.",
   "keywords": [
     "pi",
@@ -38,8 +38,8 @@
   },
   "type": "module",
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.3",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   }
 }

package/src/api/client.ts

@@ -1,5 +1,18 @@
 import { POLLING_INTERVAL } from "../constants";
 
+/**
+ * Error thrown by the API client when the server rejects a request.
+ */
+export class ApiError extends Error {
+  constructor(
+    public readonly type: "authentication" | "server" | "unknown",
+    public readonly statusCode: number,
+  ) {
+    super(`API error (${statusCode})`);
+    this.name = "ApiError";
+  }
+}
+
 /**
  * How long GET responses stay cached: half the polling interval, so a poll
  * tick always reaches the server while multiple reads within one tick
@@ -126,6 +139,8 @@ export class ApiClient {
    *
    * @param endpoint The endpoint path to fetch (e.g. "/health")
    * @returns The parsed JSON response from the server
+   * @throws ApiError with status 401 when the server rejects the request
+   *   due to authentication (invalid/missing API key).
    */
   private async do_get<T>(endpoint: string): Promise<T> {
     const url = `${this.baseUrl}${endpoint}`;
@@ -134,6 +149,10 @@ export class ApiClient {
       headers: { Authorization: `Bearer ${this.apiKey}` },
     });
 
+    if (res.status === 401) {
+      throw new ApiError("authentication", res.status);
+    }
+
     return res.json();
   }
 
@@ -144,6 +163,8 @@ export class ApiClient {
    * @param endpoint The endpoint path to post to
    * @param body The optional request body
    * @returns The parsed JSON response from the server
+   * @throws ApiError with status 401 when the server rejects the request
+   *   due to authentication (invalid/missing API key).
    */
   private async do_post<T>(
     endpoint: string,
@@ -160,6 +181,10 @@ export class ApiClient {
       body: body ? JSON.stringify(body) : undefined,
     });
 
+    if (res.status === 401) {
+      throw new ApiError("authentication", res.status);
+    }
+
     return res.json();
   }
 }

package/src/constants.ts

@@ -77,9 +77,9 @@ export const AUTOLOAD_ON_MESSAGE = false;
 export const SORT_BY = "asc";
 
 /**
- * Sort order options for model lists.
+ * Default for showServerUrls — show server URLs in /models by default.
  */
-export type SortBy = "asc" | "desc" | "asc-name" | "desc-name" | "api";
+export const SHOW_SERVER_URLS = true;
 
 /**
  * Thinking budgets to send to the server, depending on user-selected level in Pi.

package/src/enums/status.ts

@@ -5,5 +5,4 @@ export enum Status {
   FAILED = "failed",
   SLEEPING = "sleeping",
   UNLOADED = "unloaded",
-  UNAUTHORIZED = "unauthorized",
 }

package/src/index.ts

@@ -11,9 +11,10 @@ import { ModelSelectEvent } from "./interfaces/events";
 import { CommandManager } from "./managers/command";
 import { EventManager } from "./managers/events";
 import { ServerManager } from "./managers/server";
-import { settings } from "./managers/settings";
+import { createSettingsManager } from "./managers/settings";
 
 export default async function (pi: ExtensionAPI) {
+  const settings = createSettingsManager();
   const serverManager = new ServerManager(settings);
   const eventManager = new EventManager(serverManager, settings);
   const commandManager = new CommandManager(serverManager, settings);

package/src/interfaces/endpoints/models.ts

@@ -10,7 +10,7 @@ export interface ModelsEndpoint {
   data: DataProperty[];
 }
 
-export interface ModelProperty {
+interface ModelProperty {
   name: string;
   model: string;
   modified_at: string;

package/src/interfaces/settings.ts

@@ -1,5 +1,5 @@
 import type { ModelCost, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
-import type { SortBy } from "../constants";
+import type { SortBy } from "./sortBy";
 
 /**
  * Per-model overrides applied on top of what llama-server reports.
@@ -132,4 +132,10 @@ export interface LlamaSettings {
    * @default "asc"
    */
   sortBy?: SortBy;
+  /**
+   * Whether to show the `[Server: <url>]` suffix in the /models model list.
+   * When `false`, only model names are shown without server annotations.
+   * @default true
+   */
+  showServerUrls?: boolean;
 }

package/src/interfaces/sortBy.ts

@@ -0,0 +1,4 @@
+/**
+ * Sort order options for model lists.
+ */
+export type SortBy = "asc" | "desc" | "asc-name" | "desc-name" | "api";

package/src/managers/command/models.ts

@@ -0,0 +1,254 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { PROVIDER_NAME } from "../../constants";
+import { Action } from "../../enums/action";
+import { Mode } from "../../enums/mode";
+import { Status } from "../../enums/status";
+import { BaseModel } from "../../models/baseModel";
+import { errorMessage } from "../../utils/errors";
+import { EventManager } from "../events";
+import type { ServerManager } from "../server";
+import type { LlamaSettingsManager } from "../settings";
+
+/**
+ * Interactive model selection/action flow for the `/models` command.
+ *
+ * Owns the select-model → select-action loop and the per-status action
+ * tables, plus the non-blocking model load pipeline (progress events,
+ * inflight tracking, success/failure handling).
+ *
+ * Split out of `CommandManager`: command routing stays there;
+ * this class is the self-contained interactive concern.
+ * `ServerManager` is injected so load/refresh paths can reach the
+ * server registry without coupling the menu to command routing.
+ */
+export class ModelsMenu {
+  constructor(
+    private readonly serverManager: ServerManager,
+    private readonly settings: LlamaSettingsManager,
+  ) {}
+
+  /**
+   * Runs the interactive model selection menu.
+   */
+  async show(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+    const event = await this.selectionLoop(
+      ctx,
+      await this.serverManager.getAllModels(),
+    );
+
+    if (!event) return;
+    const { action, model } = event;
+
+    // Action: Cancel
+    if (!action || action === Action.CANCEL) return;
+
+    // Action: Info
+    if (action === Action.INFO) {
+      const info = await model.getInfo();
+      ctx.ui.notify(`${info}`, "info");
+      return;
+    }
+
+    // Action: Unload
+    if (action === Action.UNLOAD) {
+      await model.unload();
+      ctx.ui.notify(`Unloaded ${model.name}`, "info");
+      return;
+    }
+
+    // Action: Switch
+    if (action === Action.SWITCH) {
+      const { serverId } = model;
+      const piModel = ctx.modelRegistry.find(serverId, model.id);
+      if (!piModel)
+        throw new Error(`Cannot find model ${model.name} in pi registry`);
+
+      await pi.setModel(piModel);
+      ctx.ui.notify(`Model ${model.name} ready`, "info");
+      return;
+    }
+
+    // Actions: Load / Load & Switch / Retry
+    const loadActions = [Action.LOAD, Action.LOAD_AND_SWITCH, Action.RETRY];
+    if (loadActions.includes(action)) {
+      ctx.ui.notify(`Loading ${model.name}...`, "info");
+      // Mark the load as in-flight so session_before_switch can warn about
+      // it (see EventManager.inflightModel for the coupling rationale)
+      EventManager.inflightModel = model;
+
+      // Subscribe to progress events; skip when the server is gone
+      // (removed/edited away mid-load → getServer returns undefined)
+      const server = this.serverManager.getServer(model);
+      const cleanupProgress =
+        server?.sseManager.subscribeToProgress(
+          model.id,
+          (percentage, stage) => {
+            const stageText = stage ? ` (${stage})` : "";
+            ctx.ui.notify(
+              `Loading ${model.name}... [${percentage}%${stageText}]`,
+              "info",
+            );
+          },
+        ) ?? (() => {});
+
+      const onSuccess = async () => {
+        const { serverId } = model;
+        const piModel = ctx.modelRegistry.find(serverId, model.id);
+        if (!piModel)
+          throw new Error(`Cannot find model ${model.name} in pi registry`);
+
+        // Verify failure
+        if ((await model.getStatus()) === Status.FAILED)
+          throw new Error(`Failed to load model ${model.name}`);
+
+        // Select the model if asked
+        if (action === Action.LOAD_AND_SWITCH) await pi.setModel(piModel);
+
+        ctx.ui.notify(`Model ${model.name} ready`, "info");
+      };
+
+      const onFailure = (err: any) => {
+        const message = errorMessage(err);
+
+        try {
+          ctx.ui.notify(message, "error");
+        } catch {
+          // ctx went stale between error and notification
+        }
+      };
+
+      const onFinished = async () => {
+        cleanupProgress();
+        EventManager.resetInflightModel();
+
+        // Re-scan providers to ensure accuracy of loaded models
+        await this.serverManager.update(pi);
+
+        // Force TUI refresh so Pi picks up the updated model states
+        ctx.ui.setStatus(PROVIDER_NAME, " ");
+        ctx.ui.setStatus(PROVIDER_NAME, undefined);
+      };
+
+      // Load the model without blocking the UI
+      model.load().then(onSuccess).catch(onFailure).finally(onFinished);
+    }
+  }
+
+  /**
+   * Handles the menu for model selection.
+   * Loops: select model → select action → handle action.
+   *
+   * Escape on actions menu goes back to model selection.
+   * Escape on model selection exits.
+   *
+   * @returns The selected action and model
+   */
+  private async selectionLoop(
+    ctx: ExtensionCommandContext,
+    models: BaseModel[],
+  ): Promise<{ action: Action; model: BaseModel } | null> {
+    while (true) {
+      // Select the model
+      const model = await this.selectModel(ctx, models);
+      if (!model) return null;
+
+      // Select the action
+      const actions = await this.getActionsForModel(model);
+      const action = await this.selectAction(ctx, model, actions);
+      if (action === null) {
+        // Escape key pressed => back to model selection
+        continue;
+      }
+
+      // Return the selected action and model
+      return { action, model };
+    }
+  }
+
+  /**
+   * Select a model from the list. Returns null if user cancels.
+   *
+   * @returns The model selected by the user
+   */
+  private async selectModel(
+    ctx: ExtensionCommandContext,
+    models: BaseModel[],
+  ): Promise<BaseModel | null> {
+    const showServerUrls = await this.settings.resolveShowServerUrls();
+
+    const labels = await Promise.all(
+      models.map(async (model) => ({
+        label: (await model.getLabel()).trim(),
+        serverUrl: model.serverUrl,
+      })),
+    );
+
+    // Count grapheme clusters (not UTF-16 code units) so emoji padding aligns visually
+    const graphemeLength = (str: string) =>
+      [...new Intl.Segmenter().segment(str)].length;
+
+    // Decorate the label so the spacing makes it seem more like a table
+    const maxLength = Math.max(
+      ...labels.map(({ label }) => graphemeLength(label)),
+    );
+    const choices = labels.map(({ label, serverUrl }) => {
+      const extraPadding = 2;
+      const padLen = maxLength - graphemeLength(label) + extraPadding;
+      const serverSuffix = showServerUrls ? ` [Server: ${serverUrl}]` : "";
+      return `${label}${" ".repeat(padLen)}${serverSuffix}`;
+    });
+
+    const choice = await ctx.ui.select(`${PROVIDER_NAME} models:`, choices);
+    if (!choice) return null;
+    const idx = choices.indexOf(choice);
+
+    return models[idx];
+  }
+
+  /**
+   * Get available actions for a model based on its mode and status.
+   *
+   * @returns A mapping of actions for each status
+   */
+  private async getActionsForModel(model: BaseModel): Promise<Array<Action>> {
+    const base = [Action.INFO, Action.CANCEL];
+
+    const actions: Record<Status, Array<Action>> = {
+      [Status.LOADED]:
+        model.mode === Mode.ROUTER
+          ? [Action.SWITCH, Action.UNLOAD, ...base]
+          : [Action.SWITCH, ...base],
+      [Status.LOADING]: [...base],
+      [Status.FAILED]: [Action.RETRY, ...base],
+      [Status.SLEEPING]:
+        model.mode === Mode.ROUTER
+          ? [Action.SWITCH, Action.UNLOAD, ...base]
+          : [Action.SWITCH, ...base],
+      [Status.UNLOADED]: [Action.LOAD_AND_SWITCH, Action.LOAD, ...base],
+    };
+
+    const status = await model.getStatus();
+    return actions[status];
+  }
+
+  /**
+   * Selects an action for a model.
+   *
+   * @returns The selected action
+   */
+  private async selectAction(
+    ctx: ExtensionCommandContext,
+    model: BaseModel,
+    actions: Array<Action>,
+  ): Promise<Action | null> {
+    const labels = actions.map((a) => String(a));
+    const choice = await ctx.ui.select(`${model.name}`, labels);
+    if (!choice) return null;
+
+    const idx = labels.indexOf(choice);
+    return actions[idx];
+  }
+}