pi-llama-cpp 0.10.0 → 0.11.0

package/src/managers/settings.ts

@@ -10,16 +10,33 @@ import {
   POLLING_TIMEOUT,
   REACT_TO_MODEL_SELECT,
   SERVER_TIMEOUT,
+  SETTINGS_KEY,
+  SORT_BY,
   THINKING_BUDGETS,
+  type SortBy,
 } from "../constants";
-import { LlamaSettings } from "../interfaces/settings";
+import { LlamaServer, LlamaSettings } from "../interfaces/settings";
 import { Server } from "../server";
-
-const SETTINGS_KEY = "llamaSettings";
+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
    */
@@ -38,6 +55,14 @@ export class LlamaSettingsManager {
     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:
    *
@@ -99,17 +124,27 @@ export class LlamaSettingsManager {
 
   /**
    * Parses a raw URL string into an array of cleaned URLs.
-   * Splits on semicolons, trims whitespace, filters empty strings,
-   * and strips trailing slashes.
+   * 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((u) => u.trim())
-      .filter((u) => u.length > 0)
-      .map((u) => u.replace(/\/+$/, ""));
+      .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;
+      });
   }
 
   /**
@@ -121,19 +156,16 @@ export class LlamaSettingsManager {
    * @returns A list of Server objects
    */
   resolveServers(): Server[] {
-    const { pollingTimeout, serverTimeout } = this.resolveTimeouts();
     const urls = this.resolveUrls();
     const serverConfigs = this.llamaSettings.servers ?? [];
 
     return urls.map((url) => {
       const config = serverConfigs.find((s) => s.url === url);
-      return new Server(
-        url,
-        config?.id,
-        config?.name,
-        serverTimeout,
-        pollingTimeout,
-      );
+      return new Server(this, {
+        baseUrl: url,
+        customId: config?.id,
+        customName: config?.name,
+      });
     });
   }
 
@@ -198,6 +230,36 @@ export class LlamaSettingsManager {
       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();
+  }
 }
 
 /**

package/src/models/baseModel.ts

@@ -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]: "🟡",

package/src/server.ts

@@ -1,10 +1,8 @@
 import { ApiClient } from "./api/client";
 import {
   API_KEY_PLACEHOLDER,
-  POLLING_TIMEOUT,
   PROVIDER_NAME,
   PROVIDER_PREFIX,
-  SERVER_TIMEOUT,
 } from "./constants";
 import { Mode } from "./enums/mode";
 import { ServerStatus } from "./enums/serverStatus";
@@ -14,25 +12,67 @@ import {
   PropsEndpoint,
   PropsModelEndpoint,
 } from "./interfaces/endpoints/props";
-import { settings } from "./managers/settings";
+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 { 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 apiClient!: ApiClient;
+  private apiClient: ApiClient;
   private sse!: SSEManager;
 
   constructor(
-    readonly baseUrl: string,
-    private readonly customId?: string,
-    private readonly customName?: string,
-    readonly serverTimeout: number = SERVER_TIMEOUT,
-    readonly pollingTimeout: number = POLLING_TIMEOUT,
-  ) {}
+    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.
@@ -46,7 +86,7 @@ export class Server {
    * Uses custom ID if provided, otherwise falls back to URL-based ID.
    */
   get providerId(): string {
-    return this.customId ?? `${PROVIDER_PREFIX}=${this.baseUrl}`;
+    return this.options.customId ?? `${PROVIDER_PREFIX}=${this.baseUrl}`;
   }
 
   /**
@@ -54,8 +94,8 @@ export class Server {
    * Uses custom name as suffix if provided.
    */
   get providerName(): string {
-    if (this.customName) {
-      return `${PROVIDER_NAME} (${this.customName})`;
+    if (this.options.customName) {
+      return `${PROVIDER_NAME} (${this.options.customName})`;
     }
     return `${PROVIDER_NAME} (${this.baseUrl})`;
   }
@@ -68,12 +108,12 @@ export class Server {
    */
   getApiKey(): string {
     // Try custom ID first
-    if (this.customId) {
-      const key = settings.resolveApiKey(this.customId);
+    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 settings.resolveApiKey(`${PROVIDER_PREFIX}=${this.baseUrl}`);
+    return this.settings.resolveApiKey(`${PROVIDER_PREFIX}=${this.baseUrl}`);
   }
 
   /**
@@ -81,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, this.serverTimeout);
+    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 = {
@@ -94,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;
@@ -123,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.
    */

package/src/sse/manager.ts

@@ -1,5 +1,5 @@
-import { POLLING_TIMEOUT, SERVER_TIMEOUT } from "../constants";
-import { SSEClient } from "./client";
+import type { Server } from "../server";
+import { SSEClient, buildSSEUrl } from "./client";
 import {
   DownloadProgressData,
   ProgressData,
@@ -25,16 +25,31 @@ export class SSEManager {
   private sseSupported: boolean | null = null;
 
   constructor(
-    private readonly baseUrl: string,
+    private readonly server: Server,
     private readonly apiKey: string,
-    readonly serverTimeout: number = SERVER_TIMEOUT,
   ) {}
 
+  /**
+   * Maximum time (ms) for server verification and SSE support probe.
+   * Delegates to the owning {@link Server}.
+   */
+  get serverTimeout(): number {
+    return this.server.serverTimeout;
+  }
+
+  /**
+   * Maximum time (ms) to wait for model loading before giving up.
+   * Delegates to the owning {@link Server}.
+   */
+  get pollingTimeout(): number {
+    return this.server.pollingTimeout;
+  }
+
   /**
    * The SSE endpoint URL.
    */
   private get sseEndpoint(): string {
-    return `${this.baseUrl}/models/sse`;
+    return `${this.server.baseUrl}/models/sse`;
   }
 
   /**
@@ -47,10 +62,7 @@ export class SSEManager {
     if (this.sseSupported !== null) return this.sseSupported;
 
     try {
-      let url = this.sseEndpoint;
-      if (this.apiKey) {
-        url = `${url}?api_key=${encodeURIComponent(this.apiKey)}`;
-      }
+      const url = buildSSEUrl(this.sseEndpoint, this.apiKey);
       const response = await fetch(url, {
         method: "GET",
         signal: AbortSignal.timeout(this.serverTimeout),
@@ -171,7 +183,7 @@ export class SSEManager {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(
         () => reject(new Error(`SSE status timeout for model: ${modelId}`)),
-        POLLING_TIMEOUT,
+        this.pollingTimeout,
       );
 
       this.subscribeToSSE(modelId, (event: SSEEvent) => {