pi-llama-cpp 0.14.0 → 0.16.0

package/README.md

@@ -12,6 +12,7 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with running [lla
 - **Flexible URL resolution** — configures the server via `llamaSettings` (project/global), environment variable, or legacy `llamaServerUrl`
 - **Auth support** — allows to login into a llama.cpp server that was secured with an API key
 - **Multiple server support** — connect to multiple llama.cpp servers simultaneously via `llamaSettings.servers` or semicolon-separated URLs
+- **Basic llama-swap support** — auto-detects and provides basic integration with [llama-swap](https://github.com/mostlygeek/llama-swap) gateways
 - **Thinking budget support** — configurable token budgets for model reasoning/thinking, mapped to Pi's thinking levels
 - **Real-time progress tracking** — live loading progress via SSE (falls back to polling)
 
@@ -35,11 +36,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
 
@@ -127,6 +129,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.
 
@@ -137,11 +140,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,
@@ -205,17 +208,48 @@ Each server gets its own provider (e.g., **Llama.cpp (http://127.0.0.1:8080)**)
 If your llama.cpp server requires authentication, use `/login` in Pi, select the "API key" option, and choose the provider from the list that correlates with the server needing the API key.
 
 Alternatively, configure the API key in `~/.pi/agent/auth.json`:
-Use the provider ID `llama-server=<url>` (or your custom `id` if you set one in `llamaSettings.servers`):
+Use the provider ID `llama-server=<url>` (or your custom `id` if you set one in `llamaSettings.servers`).
+
+The `key` field supports several formats:
+
+| Format            | Example                                      | Description                                |
+| ----------------- | -------------------------------------------- | ------------------------------------------ |
+| **Literal**       | `"sk-abc123"`                                | API key stored directly                    |
+| **Env ref**       | `"$OPENAI_API_KEY"` or `"${OPENAI_API_KEY}"` | Resolved from `process.env` or `env` field |
+| **Shell command** | `"!cat ~/.secrets/llama-key"`                | Stdout of the command is used              |
+| **Escape**        | `"$$literal"`                                | `$$` → literal `$`, `$!` → literal `!`     |
 
 ```json
 {
   "llama-server=http://127.0.0.1:8080": {
     "type": "api_key",
-    "key": "<key-for-server-1>"
+    "key": "sk-abc123"
   },
   "llama-server=https://some-url-for-llama-cpp": {
     "type": "api_key",
-    "key": "<key-for-server-2>"
+    "key": "$LLAMA_API_KEY"
+  },
+  "llama-server=https://secure-server": {
+    "type": "api_key",
+    "key": "!cat ~/.secrets/llama-key"
+  },
+  "llama-server=https://braced-ref": {
+    "type": "api_key",
+    "key": "${API_KEY}"
+  }
+}
+```
+
+For env ref formats, you can also store the variable value alongside the key using the `env` field:
+
+```json
+{
+  "llama-server=http://127.0.0.1:8080": {
+    "type": "api_key",
+    "key": "$MY_KEY",
+    "env": {
+      "MY_KEY": "sk-abc123"
+    }
   }
 }
 ```
@@ -244,6 +278,10 @@ llama-server --model path/to/model.gguf ...
 
 > **Note:** The ik_llama.cpp fork is not legacy at all, but it uses an old way of describing models compared to llama.cpp.
 
+- For llama-swap mode, point the extension at a running [llama-swap](https://github.com/mostlygeek/llama-swap) instance instead of a raw llama.cpp server. The extension auto-detects this mode via the `src` field in the server props response.
+
+> **Note:** llama-swap support is basic — only model listing, status, load/unload, and capability detection are implemented.
+
 The extension determines the context size as follows:
 
 - A per-model `contextSize` override (see [Model Overrides](#model-overrides)) takes precedence over everything below
@@ -252,6 +290,7 @@ The extension determines the context size as follows:
   - When not loaded, reads `--ctx-size` and/or `--fit-ctx` from the server arguments (which can also originate from the **presets.ini** file the llama.cpp server uses to load its models).
 - **Single mode** — reads `meta.n_ctx` from the `/v1/models` endpoint
 - **Legacy mode** — reads `max_model_len` from `/v1/models`, falling back to `n_ctx` from `/props`
+- **Llama-swap mode** — reads `meta.n_ctx` from the llama-swap server via `/v1/models`
 - Falls back to `128000` if not available
 
 ### Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.14.0",
+  "version": "0.16.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.6.2",
+    "@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

@@ -81,6 +81,30 @@ export class ApiClient {
     );
   }
 
+  /**
+   * Makes a raw GET request that does not parse JSON. Useful for endpoints
+   * that return empty or non-JSON responses.
+   *
+   * @param endpoint The endpoint path to fetch
+   */
+  async rawGet(endpoint: string): Promise<void> {
+    return this.do_request<void>(endpoint, "GET", undefined, false);
+  }
+
+  /**
+   * Makes a raw POST request that does not parse JSON. Useful for endpoints
+   * that return empty or non-JSON responses.
+   *
+   * @param endpoint The endpoint path to post to
+   * @param body The optional request body
+   */
+  async rawPost(
+    endpoint: string,
+    body?: Record<string, unknown>,
+  ): Promise<void> {
+    return this.do_request<void>(endpoint, "POST", body, false);
+  }
+
   /**
    * Clears the entire cache.
    */
@@ -134,26 +158,54 @@ export class ApiClient {
   }
 
   /**
-   * Makes a raw GET request to the llama-server.
+   * Makes a raw request to the llama-server.
    * This bypasses caching and deduplication.
    *
-   * @param endpoint The endpoint path to fetch (e.g. "/health")
-   * @returns The parsed JSON response from the server
+   * @param endpoint The endpoint path
+   * @param method The HTTP method
+   * @param body The optional request body
+   * @param parseJson Whether to parse the response as JSON (default: true)
+   * @returns The parsed JSON response, or void if parseJson is false
    * @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> {
+  private async do_request<T>(
+    endpoint: string,
+    method: "GET" | "POST",
+    body?: Record<string, unknown>,
+    parseJson = true,
+  ): Promise<T | void> {
     const url = `${this.baseUrl}${endpoint}`;
 
     const res = await fetch(url, {
-      headers: { Authorization: `Bearer ${this.apiKey}` },
+      method,
+      headers: {
+        ...(method === "POST"
+          ? { "Content-Type": "application/json" }
+          : undefined),
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      ...(body ? { body: JSON.stringify(body) } : undefined),
     });
 
     if (res.status === 401) {
       throw new ApiError("authentication", res.status);
     }
 
-    return res.json();
+    return parseJson ? ((await res.json()) as T) : (undefined as T);
+  }
+
+  /**
+   * Makes a raw GET request to the llama-server.
+   * This bypasses caching and deduplication.
+   *
+   * @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> {
+    return this.do_request<T>(endpoint, "GET") as Promise<T>;
   }
 
   /**
@@ -170,21 +222,6 @@ export class ApiClient {
     endpoint: string,
     body?: Record<string, unknown>,
   ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-
-    if (res.status === 401) {
-      throw new ApiError("authentication", res.status);
-    }
-
-    return res.json();
+    return this.do_request<T>(endpoint, "POST", body) as Promise<T>;
   }
 }

package/src/constants.ts

@@ -76,6 +76,11 @@ export const AUTOLOAD_ON_MESSAGE = false;
  */
 export const SORT_BY = "asc";
 
+/**
+ * Default for showServerUrls — show server URLs in /models by default.
+ */
+export const SHOW_SERVER_URLS = true;
+
 /**
  * Thinking budgets to send to the server, depending on user-selected level in Pi.
  */

package/src/enums/mode.ts

@@ -3,4 +3,5 @@ export enum Mode {
   ROUTER = "router",
   SINGLE = "single",
   LEGACY = "legacy",
+  LLAMASWAP = "llama-swap",
 }

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

@@ -67,4 +67,10 @@ interface MetaProperty {
   n_embd: number;
   n_params: number;
   size: number;
+
+  // llama-swap extension
+  llamaswap?: {
+    aliases: string[];
+    type: string;
+  };
 }

package/src/interfaces/endpoints/props.ts

@@ -13,6 +13,20 @@ export interface PropsEndpoint {
   cors_proxy_enabled: boolean;
 }
 
+/**
+ * llama-swap returns a different shape for /props (without a model ID):
+ * an error response with a `src` that we can use as a trick to detect it.
+ */
+export interface LlamaSwapPropsError {
+  src: "llama-swap";
+  error: {
+    message: string;
+    type: string;
+    param: null;
+    code: string;
+  };
+}
+
 /**
  * The structure of llama-server's /props?model=<id> endpoint
  */

package/src/interfaces/settings.ts

@@ -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/managers/command/models.ts

@@ -10,6 +10,7 @@ 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.
@@ -24,7 +25,10 @@ import type { ServerManager } from "../server";
  * server registry without coupling the menu to command routing.
  */
 export class ModelsMenu {
-  constructor(private readonly serverManager: ServerManager) {}
+  constructor(
+    private readonly serverManager: ServerManager,
+    private readonly settings: LlamaSettingsManager,
+  ) {}
 
   /**
    * Runs the interactive model selection menu.
@@ -173,6 +177,8 @@ export class ModelsMenu {
     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(),
@@ -191,7 +197,8 @@ export class ModelsMenu {
     const choices = labels.map(({ label, serverUrl }) => {
       const extraPadding = 2;
       const padLen = maxLength - graphemeLength(label) + extraPadding;
-      return `${label}${" ".repeat(padLen)} [Server: ${serverUrl}]`;
+      const serverSuffix = showServerUrls ? ` [Server: ${serverUrl}]` : "";
+      return `${label}${" ".repeat(padLen)}${serverSuffix}`;
     });
 
     const choice = await ctx.ui.select(`${PROVIDER_NAME} models:`, choices);
@@ -210,10 +217,9 @@ export class ModelsMenu {
     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.LOADED]: [Mode.ROUTER, Mode.LLAMASWAP].includes(model.mode)
+        ? [Action.SWITCH, Action.UNLOAD, ...base]
+        : [Action.SWITCH, ...base],
       [Status.LOADING]: [...base],
       [Status.FAILED]: [Action.RETRY, ...base],
       [Status.SLEEPING]:

package/src/managers/command.ts

@@ -51,7 +51,7 @@ export class CommandManager {
     private readonly serverManager: ServerManager,
     private readonly settings: LlamaSettingsManager,
   ) {
-    this.modelsMenu = new ModelsMenu(serverManager);
+    this.modelsMenu = new ModelsMenu(serverManager, settings);
   }
 
   /**
@@ -108,6 +108,11 @@ export class CommandManager {
       this.notifyNotFound(ctx, url);
     }
 
+    // Notify about other warnings (e.g. unauthorized servers)
+    for (const warning of this.serverManager.getWarnings()) {
+      ctx.ui.notify(warning, "warning");
+    }
+
     if (args === "unload") {
       const models = await this.serverManager.getAllModels();
       await Promise.all(models.map((model) => model.unload()));

package/src/managers/server.ts

@@ -1,10 +1,14 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
 import { ApiError } from "../api/client";
 import { API_TYPE, PROVIDER_NAME } from "../constants";
 import { ServerStatus } from "../enums/serverStatus";
 import type { SortBy } from "../interfaces/sortBy";
 import { BaseModel } from "../models/baseModel";
 import { Server } from "../server";
+import { authRequiredMessage } from "../ui/strings";
 import type { LlamaSettingsManager } from "./settings";
 
 /** Model-list comparator: negative if a sorts first, positive if b does. */
@@ -45,6 +49,7 @@ export class ServerManager {
    */
   async update(pi: ExtensionAPI, timeout?: number) {
     this.failedUrls.length = 0;
+    this.warnings.length = 0;
 
     // Surface warnings from strict URL parsing (dropped invalid entries)
     this.warnings.push(...this.settings.takeWarnings());
@@ -60,9 +65,9 @@ export class ServerManager {
     }
 
     // Unregister providers that disappeared (removed or edited away);
-    // no-op for providers that were never registered
+    // `seen` tracks all kept providerIds, so we skip those still present.
     for (const old of this.servers) {
-      if (fresh.some((f) => f.providerId === old.providerId)) continue;
+      if (seen.has(old.providerId)) continue;
       pi.unregisterProvider(old.providerId);
       // Optional chain is intentional despite the non-optional type: `sse`
       // is undefined until initialize() runs (async-constructor hack — see Server)
@@ -79,34 +84,7 @@ export class ServerManager {
 
     // Initialization and registration
     for (const server of registrableServers) {
-      try {
-        await server.initialize();
-        await this.registerProvider(server, pi);
-      } catch (err) {
-        if (err instanceof ApiError && err.type === "authentication") {
-          // Register the provider with an empty model list so the user can
-          // still configure the API key via `/login` or `auth.json`. On the
-          // next scan the provider will re-initialize and discover models.
-          // Don't add to `failedUrls` — the server IS reachable, auth just
-          // isn't configured yet, so the health indicator should stay green.
-          const message = [
-            "[pi-llama-cpp]",
-            `Server at '${server.baseUrl}' requires a valid API key.`,
-            "Configure the key via `/login` or in `~/.pi/agent/auth.json`.",
-          ].join("\n");
-          this.warnings.push(message);
-          pi.registerProvider(server.providerId, {
-            name: server.providerName,
-            baseUrl: server.apiBaseUrl,
-            api: API_TYPE,
-            apiKey: server.getApiKey(),
-            models: [],
-          });
-          continue;
-        }
-        this.failedUrls.push(server.baseUrl);
-        continue;
-      }
+      await this.registerProvider(server, pi);
     }
   }
 
@@ -151,23 +129,37 @@ export class ServerManager {
   }
 
   /**
-   * Creates a Pi provider for the given server.
+   * Initializes the server and creates a Pi provider.
+   * Handles auth errors by registering with an empty model list so the user
+   * can still configure the API key via `/login` or `auth.json`.
    *
    * @param server The server
    * @param pi The Pi API
    */
   private async registerProvider(server: Server, pi: ExtensionAPI) {
-    const { apiBaseUrl, models, providerId, providerName } = server;
-    const apiKey = server.getApiKey();
-    const modelConfigs = await Promise.all(
-      models.map((m) => m.toProviderConfig()),
-    );
+    const { apiBaseUrl, apiKey, baseUrl, models, providerId, providerName } =
+      server;
+    let modelConfigs: ProviderModelConfig[] = [];
+
+    try {
+      await server.initialize();
+      modelConfigs = await Promise.all(models.map((m) => m.toProviderConfig()));
+    } catch (err) {
+      if (err instanceof ApiError && err.type === "authentication") {
+        // Don't add to `failedUrls` — the server IS reachable, auth just
+        // isn't configured yet, so the health indicator should stay green.
+        this.warnings.push(authRequiredMessage(baseUrl, providerId));
+      } else {
+        this.failedUrls.push(baseUrl);
+        return;
+      }
+    }
 
     pi.registerProvider(providerId, {
       name: providerName,
       baseUrl: apiBaseUrl,
       api: API_TYPE,
-      apiKey: apiKey,
+      apiKey,
       models: modelConfigs,
     });
   }

package/src/managers/settings.ts

@@ -13,6 +13,7 @@ import {
   REACT_TO_MODEL_SELECT,
   SERVER_TIMEOUT,
   SETTINGS_KEY,
+  SHOW_SERVER_URLS,
   SORT_BY,
   THINKING_BUDGETS,
 } from "../constants";
@@ -23,6 +24,7 @@ import {
 } from "../interfaces/settings";
 import type { SortBy } from "../interfaces/sortBy";
 import { Server } from "../server";
+import { CredentialResolver } from "../utils/credentialResolver";
 import { SettingsStore } from "../utils/settingsStore";
 import { UrlResolver } from "../utils/urlResolver";
 
@@ -46,6 +48,9 @@ export class LlamaSettingsManager {
     }
   }
 
+  /** Delegates credential key resolution (see `utils/credentialResolver`). */
+  private credentialResolver = new CredentialResolver();
+
   /** Delegated multi-source URL resolution chain (see `utils/urlResolver`). */
   private urlResolver = new UrlResolver({
     getLlamaSettings: () => this.getLlamaSettings(),
@@ -148,12 +153,16 @@ export class LlamaSettingsManager {
 
   /**
    * Resolves API key for the provider ID using Pi's stored credentials.
+   * Delegates to `CredentialResolver` for key format handling.
    *
+   * @param providerId The provider ID
    * @returns The API key to use for the provider
    */
   resolveApiKey(providerId: string): string {
     const credential = readStoredCredential(providerId) as ApiKeyCredential;
-    return credential?.key ?? API_KEY_PLACEHOLDER;
+    if (!credential?.key) return API_KEY_PLACEHOLDER;
+
+    return this.credentialResolver.resolve(credential.key, credential.env);
   }
 
   /**
@@ -226,6 +235,15 @@ export class LlamaSettingsManager {
     return (await this.getLlamaSettings()).sortBy ?? SORT_BY;
   }
 
+  /**
+   * Resolves whether to show server URLs in the /models model list.
+   *
+   * @returns `true` if server URLs should be shown
+   */
+  async resolveShowServerUrls(): Promise<boolean> {
+    return (await this.getLlamaSettings()).showServerUrls ?? SHOW_SERVER_URLS;
+  }
+
   /**
    * Persists one llamaSettings field to settings and reloads the in-memory
    * settings so resolvers see the change immediately.
@@ -262,6 +280,8 @@ export class LlamaSettingsManager {
 }
 
 /**
- * Shared singleton instance used across the extension.
+ * Creates a new LlamaSettingsManager instance.
  */
-export const settings = new LlamaSettingsManager();
+export function createSettingsManager(): LlamaSettingsManager {
+  return new LlamaSettingsManager();
+}

package/src/models/legacyModel.ts

@@ -3,7 +3,7 @@ import { Mode } from "../enums/mode";
 import { SingleModel } from "./singleModel";
 
 export class LegacyModel extends SingleModel {
-  get mode(): Mode {
+  override get mode(): Mode {
     return Mode.LEGACY;
   }
 
@@ -13,7 +13,7 @@ export class LegacyModel extends SingleModel {
    *
    * @returns The context size
    */
-  protected async getContextSize(): Promise<number> {
+  protected override async getContextSize(): Promise<number> {
     const props = await this.server.fetchModelProps(this.id);
     const models = await this.server.fetchModels();
 
@@ -34,7 +34,7 @@ export class LegacyModel extends SingleModel {
    *
    * @returns An array of capabilities, as expected by Pi
    */
-  protected async getCapabilities(): Promise<("text" | "image")[]> {
+  protected override async getCapabilities(): Promise<("text" | "image")[]> {
     try {
       return await super.getCapabilities();
     } catch {