pi-llama-cpp 0.9.2 → 0.11.0

package/src/managers/settings.ts

@@ -0,0 +1,268 @@
+import { ApiKeyCredential, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import {
+  readStoredCredential,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  API_KEY_PLACEHOLDER,
+  AUTOLOAD_ON_MESSAGE,
+  LLAMA_SERVER_URL,
+  POLLING_TIMEOUT,
+  REACT_TO_MODEL_SELECT,
+  SERVER_TIMEOUT,
+  SETTINGS_KEY,
+  SORT_BY,
+  THINKING_BUDGETS,
+  type SortBy,
+} from "../constants";
+import { LlamaServer, LlamaSettings } from "../interfaces/settings";
+import { Server } from "../server";
+import { SettingsStore } from "../utils/settingsStore";
+import { isValidServerUrl, normalizeUrl } from "../utils/urls";
+
+export class LlamaSettingsManager {
+  private settingsManager = SettingsManager.create(process.cwd());
+
+  constructor(private readonly store: SettingsStore = new SettingsStore()) {}
+
+  /** Warnings collected during URL resolution (dropped invalid entries). */
+  private warnings: string[] = [];
+
+  /**
+   * Returns and clears warnings collected during URL resolution.
+   */
+  takeWarnings(): string[] {
+    const warnings = [...this.warnings];
+    this.warnings.length = 0;
+    return warnings;
+  }
+
+  /**
+   * Convenience getter for merged project/global settings
+   */
+  private get mergedSettings(): Record<string, any> {
+    const merged = {
+      ...this.settingsManager.getGlobalSettings(),
+      ...this.settingsManager.getProjectSettings(),
+    } as Record<string, any>;
+    return merged;
+  }
+
+  /**
+   * Convenience getter for the `llamaSettings` key
+   */
+  private get llamaSettings(): LlamaSettings {
+    return this.mergedSettings[SETTINGS_KEY] ?? {};
+  }
+
+  /**
+   * Convenience getter for the merged `servers` list (project overrides
+   * global, per-key merge)
+   */
+  get llamaServers(): LlamaServer[] {
+    return this.llamaSettings.servers ?? [];
+  }
+
+  /**
+   * 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
+   */
+  resolveUrls(): string[] {
+    let response = this.resolveEnvUrls();
+    if (response.length > 0) return response;
+
+    response = this.resolveServerUrls();
+    if (response.length > 0) return response;
+
+    response = 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.
+   *
+   * @returns A list of detected URLs
+   */
+  private resolveServerUrls(): string[] {
+    const { servers = [] } = this.llamaSettings;
+    return servers.map((s) => this.parseUrls(s.url)).flat();
+  }
+
+  /**
+   * Resolves the llama-server URLs from `llamaSettings.servers`.
+   * Settings are merged, prioritizing project over global settings.
+   *
+   * @returns A list of detected URLs
+   */
+  private resolveLegacyUrls(): string[] {
+    const { llamaServerUrl = null } = this.mergedSettings;
+    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(normalizeUrl)
+      .filter((u) => {
+        if (u.length === 0) return false;
+        if (!isValidServerUrl(u)) {
+          this.warnings.push(
+            `Ignoring invalid server URL '${u}' (needs http(s)://)`,
+          );
+          return false;
+        }
+        return true;
+      });
+  }
+
+  /**
+   * Resolves the servers that this extension will use.
+   * Uses `resolveUrls()` as the source of truth for URLs (env > settings >
+   * legacy > default), then applies `id`/`name` from `llamaSettings.servers`
+   * as overrides when available.
+   *
+   * @returns A list of Server objects
+   */
+  resolveServers(): Server[] {
+    const urls = this.resolveUrls();
+    const serverConfigs = this.llamaSettings.servers ?? [];
+
+    return urls.map((url) => {
+      const config = serverConfigs.find((s) => s.url === url);
+      return new Server(this, {
+        baseUrl: url,
+        customId: config?.id,
+        customName: config?.name,
+      });
+    });
+  }
+
+  /**
+   * Resolves API key for the provider ID using Pi's stored credentials.
+   *
+   * @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;
+  }
+
+  /**
+   * Resolves the current thinking level from Pi.
+   *
+   * @returns The thinking level
+   */
+  resolveThinkingLevel(): ModelThinkingLevel | undefined {
+    return this.settingsManager.getDefaultThinkingLevel();
+  }
+
+  /**
+   * Resolves the effective thinking budgets from settings.
+   *
+   * @returns An object with selected budgets for thinking levels
+   */
+  resolveThinkingBudgets(): Record<ModelThinkingLevel, number> {
+    const settingsBudgets = this.settingsManager.getThinkingBudgets() ?? {};
+    return {
+      ...THINKING_BUDGETS,
+      ...settingsBudgets,
+    };
+  }
+
+  /**
+   * Resolves whether the extension should react to model selection events.
+   *
+   * @returns `true` if the extension should load the model on model_select
+   */
+  resolveReactToModelSelect(): boolean {
+    return this.llamaSettings.reactToModelSelect ?? REACT_TO_MODEL_SELECT;
+  }
+
+  /**
+   * Resolves whether the extension should auto-load models on message.
+   *
+   * @returns `true` if the extension should auto-load models
+   */
+  resolveAutoloadOnMessage(): boolean {
+    return this.llamaSettings.autoloadOnMessage ?? AUTOLOAD_ON_MESSAGE;
+  }
+
+  /**
+   * Resolves the timeout settings for polling and server checks.
+   *
+   * @returns Object with polling and server timeout values
+   */
+  resolveTimeouts(): { pollingTimeout: number; serverTimeout: number } {
+    return {
+      pollingTimeout: this.llamaSettings.pollingTimeout ?? POLLING_TIMEOUT,
+      serverTimeout: this.llamaSettings.serverTimeout ?? SERVER_TIMEOUT,
+    };
+  }
+
+  /**
+   * Resolves the sort order for model lists.
+   *
+   * @returns The sort order: "asc", "desc", "asc-name", "desc-name", or "api"
+   */
+  resolveSortBy(): SortBy {
+    return this.llamaSettings.sortBy ?? SORT_BY;
+  }
+
+  /**
+   * Persists one llamaSettings field to the global settings file and
+   * reloads the in-memory settings so resolvers see the change immediately.
+   *
+   * Rejects if the file can't be read (e.g. invalid JSON) or written —
+   * in-memory state stays consistent (reload only on success).
+   */
+  async setLlamaSetting<K extends keyof LlamaSettings>(
+    key: K,
+    value: LlamaSettings[K],
+  ): Promise<void> {
+    await this.store.updateKey(SETTINGS_KEY, (current) => {
+      const merged =
+        typeof current === "object" && current !== null
+          ? (current as Record<string, unknown>)
+          : {};
+      return { ...merged, [key]: value };
+    });
+    await this.settingsManager.reload();
+  }
+}
+
+/**
+ * Shared singleton instance used across the extension.
+ */
+export const settings = new LlamaSettingsManager();

package/src/models/baseModel.ts

@@ -1,5 +1,5 @@
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_CTX, POLLING_INTERVAL, POLLING_TIMEOUT } from "../constants";
+import { FALLBACK_CTX, POLLING_INTERVAL } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
 import { DataProperty } from "../interfaces/endpoints/models";
@@ -16,14 +16,6 @@ export abstract class BaseModel {
     protected readonly server: Server,
   ) {}
 
-  protected readonly statusMapper: Record<string, Status> = {
-    loaded: Status.LOADED,
-    loading: Status.LOADING,
-    failed: Status.FAILED,
-    sleeping: Status.SLEEPING,
-    unloaded: Status.UNLOADED,
-  };
-
   protected readonly labelIcons: Record<Status, string> = {
     [Status.LOADED]: "🟢",
     [Status.LOADING]: "🟡",
@@ -130,9 +122,9 @@ export abstract class BaseModel {
       const { data } = await this.server.fetchModels();
       const { n_ctx } = data.find((m) => m.id === this.id)?.meta!;
 
-      return n_ctx ?? DEFAULT_CTX;
+      return n_ctx ?? FALLBACK_CTX;
     } catch {
-      return DEFAULT_CTX;
+      return FALLBACK_CTX;
     }
   }
 
@@ -202,11 +194,31 @@ export abstract class BaseModel {
     await this.server.postRequest("load", this.id);
 
     if (await this.server.sseManager.probeSSE()) {
-      const { status, exit_code } =
-        await this.server.sseManager.subscribeToStatus(this.id);
+      try {
+        const { status, exit_code } =
+          await this.server.sseManager.subscribeToStatus(this.id);
 
-      if (status === "failed" || (status === "unloaded" && exit_code !== 0)) {
-        throw new Error(`Model loading failed: ${this.id}`);
+        if (status === "failed" || (status === "unloaded" && exit_code !== 0)) {
+          throw new Error(`Model loading failed: ${this.id}`);
+        }
+      } catch (err) {
+        // A real failed status from the server stays fatal.
+        if (
+          err instanceof Error &&
+          err.message.startsWith("Model loading failed")
+        ) {
+          throw err;
+        }
+        // An SSE timeout or connection failure is not proof the load failed:
+        // subscribeToStatus timers are only cleared by a terminal event on
+        // the same SSE connection, so a timer orphaned by a server restart
+        // or reconnect can fire during a later, healthy load. Check the
+        // model's real status over HTTP before surfacing an error.
+        await this.pollStatus();
+        const finalStatus = await this.getStatus();
+        if (finalStatus !== Status.LOADED && finalStatus !== Status.SLEEPING) {
+          throw new Error(`Model loading failed: ${this.id}`);
+        }
       }
     } else {
       await this.pollStatus();
@@ -224,14 +236,17 @@ export abstract class BaseModel {
    * Polls llama-server to check when the model is loaded
    *
    * @param startTime The initial polling timestamp
-   * @param timeout The maximum amount of ms before timeout. Defaults to POLLING_TIMEOUT
+   * @param timeout The maximum amount of ms before timeout. Defaults to server's pollingTimeout
    * @param interval The polling interval. Defaults to POLLING_INTERVAL
    */
   async pollStatus(
     startTime: number = Date.now(),
-    timeout: number = POLLING_TIMEOUT,
+    timeout?: number,
     interval: number = POLLING_INTERVAL,
   ): Promise<void> {
+    if (timeout === undefined) {
+      timeout = this.server.pollingTimeout;
+    }
     while ((await this.getStatus()) === Status.LOADING) {
       // Force a timeout if we wasted too much time polling
       if (Date.now() - startTime > timeout) {

package/src/models/legacyModel.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_CTX } from "../constants";
+import { FALLBACK_CTX } from "../constants";
 import { Mode } from "../enums/mode";
 import { SingleModel } from "./singleModel";
 
@@ -25,7 +25,7 @@ export class LegacyModel extends SingleModel {
     const [{ max_model_len }] = data;
     const contextSize = max_model_len === 0 ? n_ctx : max_model_len;
 
-    return contextSize ?? DEFAULT_CTX;
+    return contextSize ?? FALLBACK_CTX;
   }
 
   /**

package/src/models/routerModel.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_CTX, POLLING_INTERVAL, POLLING_TIMEOUT } from "../constants";
+import { FALLBACK_CTX, POLLING_INTERVAL } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
 import { BaseModel } from "./baseModel";
@@ -41,7 +41,7 @@ export class RouterModel extends BaseModel {
       }
     }
 
-    const timeout = POLLING_TIMEOUT - elapsed;
+    const timeout = this.server.pollingTimeout - elapsed;
     return await super.pollStatus(startTime, timeout);
   }
 
@@ -60,7 +60,7 @@ export class RouterModel extends BaseModel {
     const response =
       this.extractFrom("--ctx-size") ??
       this.extractFrom("--fit-ctx") ??
-      DEFAULT_CTX;
+      FALLBACK_CTX;
 
     return response;
   }

package/src/server.ts

@@ -1,5 +1,9 @@
 import { ApiClient } from "./api/client";
-import { PROVIDER_NAME, PROVIDER_PREFIX } from "./constants";
+import {
+  API_KEY_PLACEHOLDER,
+  PROVIDER_NAME,
+  PROVIDER_PREFIX,
+} from "./constants";
 import { Mode } from "./enums/mode";
 import { ServerStatus } from "./enums/serverStatus";
 import { HealthEndpoint } from "./interfaces/endpoints/health";
@@ -8,20 +12,67 @@ import {
   PropsEndpoint,
   PropsModelEndpoint,
 } from "./interfaces/endpoints/props";
+import type { ServerOptions } from "./interfaces/server";
+import type { LlamaSettingsManager } from "./managers/settings";
 import { BaseModel } from "./models/baseModel";
 import { LegacyModel } from "./models/legacyModel";
 import { RouterModel } from "./models/routerModel";
 import { SingleModel } from "./models/singleModel";
-import { ConfigResolver } from "./resolver";
 import { SSEManager } from "./sse/manager";
 
+/**
+ * Optional constructor collaborators for {@link Server} — the seam tests use
+ * to run the real Server against fake clients.
+ *
+ * Both are factories because their arguments only exist around construction:
+ * the API key is (re-)resolved by the Server, and SSEManager needs its owner.
+ * Factories must stay pure functions of their arguments — `initialize()`
+ * re-invokes both on every scan (the ApiClient rebuild picks up a fresh key,
+ * by design), so captured per-server state would leak across re-scans.
+ */
+export type ServerDeps = {
+  createApiClient?: (apiKey: string) => ApiClient;
+  createSSEManager?: (server: Server, apiKey: string) => SSEManager;
+};
+
 export class Server {
   public readonly models: BaseModel[] = [];
-  private configResolver = new ConfigResolver();
-  private apiClient!: ApiClient;
+  private apiClient: ApiClient;
   private sse!: SSEManager;
 
-  constructor(readonly baseUrl: string) {}
+  constructor(
+    private readonly settings: LlamaSettingsManager,
+    private readonly options: ServerOptions,
+    private readonly deps: ServerDeps = {},
+  ) {
+    // Eager client: `isReady` may run before `initialize()` (health probing
+    // in ServerManager), so no lazy fallback is needed. initialize()
+    // rebuilds the client to re-resolve the API key.
+    this.apiClient =
+      deps.createApiClient?.(this.getApiKey()) ??
+      new ApiClient(options.baseUrl, this.getApiKey());
+  }
+
+  /** Base URL of this server endpoint. */
+  get baseUrl(): string {
+    return this.options.baseUrl;
+  }
+
+  /**
+   * Maximum time (ms) for server verification and SSE support probe.
+   * Resolved live from the injected settings manager.
+   */
+  get serverTimeout(): number {
+    return this.settings.resolveTimeouts().serverTimeout;
+  }
+
+  /**
+   * Maximum time (ms) to wait for model loading before giving up.
+   * Resolved live from the injected settings manager.
+   */
+  get pollingTimeout(): number {
+    return this.settings.resolveTimeouts().pollingTimeout;
+  }
 
   /**
    * Provides access to the SSE manager for direct subscriptions.
@@ -32,24 +83,37 @@ export class Server {
 
   /**
    * Generates a unique provider ID from a server URL.
+   * Uses custom ID if provided, otherwise falls back to URL-based ID.
    */
   get providerId(): string {
-    return `${PROVIDER_PREFIX}=${this.baseUrl}`;
+    return this.options.customId ?? `${PROVIDER_PREFIX}=${this.baseUrl}`;
   }
 
   /**
    * Generates a human-readable provider name from a server URL.
+   * Uses custom name as suffix if provided.
    */
   get providerName(): string {
+    if (this.options.customName) {
+      return `${PROVIDER_NAME} (${this.options.customName})`;
+    }
     return `${PROVIDER_NAME} (${this.baseUrl})`;
   }
 
   /**
-   * Retrieves the API key from the resolver
+   * Retrieves the API key from the config resolver.
+   * Tries custom ID first, then falls back to URL-based ID.
+   *
    * @returns The API key
    */
-  async getApiKey(): Promise<string> {
-    return await this.configResolver.resolveApiKey(this.providerId);
+  getApiKey(): string {
+    // Try custom ID first
+    if (this.options.customId) {
+      const key = this.settings.resolveApiKey(this.options.customId);
+      if (key !== API_KEY_PLACEHOLDER) return key;
+    }
+    // Fall back to URL-based ID
+    return this.settings.resolveApiKey(`${PROVIDER_PREFIX}=${this.baseUrl}`);
   }
 
   /**
@@ -57,11 +121,15 @@ export class Server {
    * Clears the cache first so we always fetch fresh data.
    */
   async initialize() {
-    const apiKey = await this.getApiKey();
-    this.apiClient = new ApiClient(this.baseUrl, apiKey);
-    this.sse = new SSEManager(this.baseUrl, apiKey);
+    const apiKey = this.getApiKey();
+    this.apiClient =
+      this.deps.createApiClient?.(apiKey) ??
+      new ApiClient(this.baseUrl, apiKey);
+    this.sse =
+      this.deps.createSSEManager?.(this, apiKey) ??
+      new SSEManager(this, apiKey);
     const { data } = await this.fetchModels();
-    const mode = await this.detectServerMode();
+    const mode = await this.detectServerMode(data);
 
     // Setup models
     const modelCtor = {
@@ -70,22 +138,21 @@ export class Server {
       [Mode.SINGLE]: SingleModel,
     }[mode];
 
-    const models: BaseModel[] = data
-      .map((m) => new modelCtor(m, this))
-      .sort((a, b) => (a.id > b.id ? 1 : a.id === b.id ? 0 : -1));
+    const models: BaseModel[] = data.map((m) => new modelCtor(m, this));
 
     this.models.length = 0;
     this.models.push(...models);
   }
 
   /**
-   * Detects the mode of the server
+   * Detects the mode of the server from the models data already fetched by
+   * {@link initialize} — no second /v1/models round-trip.
    *
+   * @param data Models endpoint data fetched by initialize()
    * @returns The detected mode
    */
-  private async detectServerMode(): Promise<Mode> {
+  private async detectServerMode(data: ModelsEndpoint["data"]): Promise<Mode> {
     const { role } = await this.fetchServerProps();
-    const { data } = await this.fetchModels();
 
     if (role === "router") return Mode.ROUTER;
     if ("max_model_len" in data[0]) return Mode.LEGACY;
@@ -99,8 +166,6 @@ export class Server {
    * @returns The server status
    */
   async isReady(timeout: number): Promise<ServerStatus> {
-    this.apiClient ??= new ApiClient(this.baseUrl, await this.getApiKey());
-
     try {
       const timeoutPromise = new Promise<never>((_, reject) =>
         setTimeout(() => reject(new Error("timeout")), timeout),

package/src/sse/client.ts

@@ -1,6 +1,18 @@
 import { POLLING_INTERVAL } from "../constants";
 import type { SSECallback, SSECleanup, SSEEvent } from "./types";
 
+/**
+ * Builds the full SSE endpoint URL, appending the API key as a query
+ * parameter when one is set. Shared by {@link SSEClient} and
+ * {@link SSEManager.probeSSE} so the two can't drift.
+ */
+export const buildSSEUrl = (endpoint: string, apiKey?: string): string => {
+  if (apiKey) {
+    return `${endpoint}?api_key=${encodeURIComponent(apiKey)}`;
+  }
+  return endpoint;
+};
+
 /**
  * SSE client for llama-server's /models/sse endpoint.
  *
@@ -13,6 +25,10 @@ export class SSEClient {
   private subscribers: Map<string, SSECallback> = new Map();
   private connected: boolean = false;
   private reconnecting: boolean = false; // tracks if EventSource auto-reconnect is in progress
+  /**
+   * Single shared slot — each setOnConnectFailed call overwrites the
+   * previous callback (see there for the constraint this imposes).
+   */
   private _onConnectFailed: (() => void) | null = null;
   private _hasReceivedEvents: boolean = false;
 
@@ -28,12 +44,16 @@ export class SSEClient {
   /**
    * Connects to the SSE endpoint.
    *
+   * No current caller consumes the result: `subscribe()` triggers the
+   * connection without awaiting it, and connection failures before the
+   * first event are surfaced through the `setOnConnectFailed` callback.
+   *
    * @returns true if the connection was established successfully
    */
   async connect(): Promise<boolean> {
     if (this.connected) return true;
 
-    const url = this.buildUrl();
+    const url = buildSSEUrl(this.sseEndpoint, this.apiKey);
 
     try {
       this.eventSource = new EventSource(url);
@@ -42,11 +62,6 @@ export class SSEClient {
       return false;
     }
 
-    this.eventSource.onopen = () => {
-      this.connected = true;
-      this.reconnecting = false;
-    };
-
     this.eventSource.onerror = () => {
       // EventSource will auto-reconnect; we just track state
       this.connected = false;
@@ -91,6 +106,13 @@ export class SSEClient {
    * Sets a callback to be called when the connection fails before
    * any event is received. Useful for rejecting promises early.
    *
+   * Single shared slot: each call overwrites the previous callback, so at
+   * most one caller may depend on it at a time. The only caller today is
+   * `SSEManager.subscribeToStatus`, which must therefore not be invoked
+   * twice concurrently on the same client — the second registration would
+   * take over the failure signal and the first promise would only reject
+   * via its own timeout.
+   *
    * @param callback - Called once when connection fails
    */
   setOnConnectFailed(callback: () => void): void {
@@ -129,16 +151,6 @@ export class SSEClient {
     this.subscribers.clear();
   }
 
-  /**
-   * Builds the full URL with optional API key query param.
-   */
-  private buildUrl(): string {
-    if (this.apiKey) {
-      return `${this.sseEndpoint}?api_key=${encodeURIComponent(this.apiKey)}`;
-    }
-    return this.sseEndpoint;
-  }
-
   /**
    * Dispatches an SSE event to all matching subscribers.
    */