pi-llama-cpp 0.7.2 → 0.8.1

package/README.md

@@ -13,6 +13,7 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with running [lla
 - **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 by separating URLs with semicolons
 - **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)
 
 ### Status Indicators
 
@@ -200,9 +201,11 @@ This keeps the server in sync with the active model in Pi, regardless of how the
 
 ### Loading Models
 
-When you trigger a load, switch, or retry action, the extension polls the server to track progress. If a model takes longer than **60 seconds** to load, the polling times out with an error.
+When you trigger a load, switch, or retry action, the extension uses SSE (Server-Sent Events) to receive real-time progress updates from the server. If SSE is not available, it falls back to polling.
 
-> **Note:** The timeout is only for the polling. The model might still be loading.
+If loading takes longer than **60 seconds**, the operation times out with an error.
+
+> **Note:** The timeout only applies to the progress detection. The model might still be loading in the background.
 
 ### Model Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Pi extension for llama.cpp integration. Supports router, single and legacy models. Supports multiple servers.",
   "keywords": [
     "pi",
@@ -36,7 +36,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.0.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "vitest": "^4.1.9"
   }

package/src/api/client.ts

@@ -0,0 +1,121 @@
+import { POLLING_INTERVAL } from "../constants";
+import { Cache } from "../utils/cache";
+import { Mutex } from "../utils/mutex";
+
+/**
+ * HTTP client for llama-server with caching and deduplication.
+ */
+export class ApiClient {
+  private cache = new Cache(POLLING_INTERVAL / 2);
+  private mutex = new Mutex();
+
+  /**
+   * Creates a new ApiClient.
+   *
+   * @param baseUrl The base URL of the llama-server
+   * @param apiKey The API key for authentication
+   */
+  constructor(
+    private readonly baseUrl: string,
+    private readonly apiKey: string,
+  ) {}
+
+  /**
+   * Makes a cached, deduplicated GET request to the llama-server.
+   * Results are cached for half the polling interval and in-flight requests are deduplicated.
+   *
+   * @param endpoint The endpoint path to fetch (e.g. "/health")
+   * @returns The parsed JSON response from the server
+   */
+  async get<T>(endpoint: string): Promise<T> {
+    const cached = this.cache.get<T>(endpoint);
+    if (cached !== undefined) return cached;
+
+    return this.mutex.getOrCreate(endpoint, async () => {
+      const data = (await this.do_get<T>(endpoint)) as T;
+      this.cache.set(endpoint, data);
+      return data;
+    });
+  }
+
+  /**
+   * Makes a cached, deduplicated POST request to the llama-server.
+   * Results are cached for half the polling interval and in-flight requests are deduplicated.
+   *
+   * @param endpoint The endpoint path to post to
+   * @param body The optional request body
+   * @returns The parsed JSON response from the server
+   */
+  async post<T>(endpoint: string, body?: Record<string, unknown>): Promise<T> {
+    const key = this.cacheKey(endpoint, body);
+    const cached = this.cache.get<T>(key);
+    if (cached !== undefined) return cached;
+
+    return this.mutex.getOrCreate(key, async () => {
+      const data = (await this.do_post<T>(endpoint, body)) as T;
+      this.cache.set(key, data);
+      return data;
+    });
+  }
+
+  /**
+   * Clears the entire cache.
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * 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
+   */
+  private async do_get<T>(endpoint: string): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+
+    return res.json();
+  }
+
+  /**
+   * Makes a raw POST request to the llama-server.
+   * This bypasses caching and deduplication.
+   *
+   * @param endpoint The endpoint path to post to
+   * @param body The optional request body
+   * @returns The parsed JSON response from the server
+   */
+  private async do_post<T>(
+    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,
+    });
+
+    return res.json();
+  }
+
+  /**
+   * Sets a cache key
+   *
+   * @param endpoint The endpoint path to post to
+   * @param body The optional request body
+   * @returns The cache key
+   */
+  private cacheKey(endpoint: string, body?: Record<string, unknown>): string {
+    return body ? `${endpoint}:${JSON.stringify(body)}` : endpoint;
+  }
+}

package/src/constants.ts

@@ -44,7 +44,7 @@ export const POLLING_TIMEOUT = 60000;
 export const READABLE_TIMEOUT = 15000;
 
 /**
- * Timeout (ms) for server verification before assuming failure
+ * Timeout (ms) for server verification and SSE support probe
  */
 export const SERVER_TIMEOUT = 1000;
 

package/src/interfaces/endpoints/models.ts

@@ -40,6 +40,9 @@ export interface DataProperty {
   created: number;
   status?: StatusProperty;
   architecture?: ArchitectureProperty;
+  source?: string;
+  can_remove?: boolean;
+  need_download?: boolean;
   meta?: MetaProperty;
 }
 

package/src/interfaces/endpoints/props.ts

@@ -2,28 +2,56 @@
  * The structure of llama-server's /props endpoint
  */
 export interface PropsEndpoint {
-  role?: "router";
-  error?: PropsError;
+  role: "router";
+  max_instances: number;
+  models_autoload: boolean;
+  model_alias: string;
+  model_path: string;
   default_generation_settings: Record<string, any>;
+  ui_settings: Record<string, any>;
+  build_info: string;
+  cors_proxy_enabled: boolean;
+}
+
+/**
+ * The structure of llama-server's /props?model=<id> endpoint
+ */
+export interface PropsModelEndpoint {
+  error?: PropsError;
+  default_generation_settings: {
+    params: Record<string, any>;
+    n_ctx: number;
+  };
   total_slots: number;
   model_alias: string;
   model_path: string;
   modalities: {
     vision: boolean;
+    video: boolean;
     audio: boolean;
   };
   media_marker: string;
   endpoint_slots: boolean;
   endpoint_props: boolean;
   endpoint_metrics: boolean;
-  webui: boolean;
-  webui_settings: Record<string, any>;
+  ui: boolean;
+  ui_settings: Record<string, any>;
   chat_template: string;
-  chat_template_caps: Record<string, boolean>;
+  chat_template_caps: {
+    supports_object_arguments: boolean;
+    supports_parallel_tool_calls: boolean;
+    supports_preserve_reasoning: boolean;
+    supports_string_content: boolean;
+    supports_system_role: boolean;
+    supports_tool_calls: boolean;
+    supports_tools: boolean;
+    supports_typed_content: boolean;
+  };
   bos_token: string;
   eos_token: string;
   build_info: string;
   is_sleeping: boolean;
+  cors_proxy_enabled: boolean;
 }
 
 export interface PropsError {

package/src/managers/command.ts

@@ -134,6 +134,17 @@ export class CommandManager {
       ctx.ui.notify(`Loading ${model.name}...`, "info");
       EventManager.inflightModel = model;
 
+      // Subscribe to progress events
+      const cleanupProgress = this.serverManager
+        .getServer(model)
+        .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);
@@ -171,7 +182,10 @@ export class CommandManager {
         .load()
         .then(onSuccess)
         .catch(onFailure)
-        .finally(EventManager.resetInflightModel);
+        .finally(() => {
+          cleanupProgress();
+          EventManager.resetInflightModel();
+        });
     }
   }
 

package/src/managers/server.ts

@@ -117,6 +117,16 @@ export class ServerManager {
     return warnings;
   }
 
+  /**
+   * Returns the server for a given model.
+   *
+   * @param model - The model to find the server for
+   * @returns The server containing the model
+   */
+  getServer(model: BaseModel): Server {
+    return this.servers.find((s) => s.baseUrl === model.serverUrl)!;
+  }
+
   /**
    * Returns all models from all servers.
    *

package/src/models/baseModel.ts

@@ -87,9 +87,11 @@ export abstract class BaseModel {
       const model = data.find((d) => d.id === this.id);
       if (!model) return ["text"];
 
-      const { input_modalities } = model.architecture!;
+      const input_modalities: ("text" | "image" | "audio")[] = model
+        .architecture?.input_modalities ?? ["text"];
+
       const response = input_modalities.filter(
-        (mod) => mod === "text" || mod === "image",
+        (mod): mod is "text" | "image" => mod === "text" || mod === "image",
       );
 
       return response;
@@ -189,14 +191,25 @@ export abstract class BaseModel {
   }
 
   /**
-   * Loads the model in llama-server
+   * Loads the model in llama-server.
+   * Uses SSE status events when available, falling back to polling.
    */
   async load(): Promise<void> {
     const status = await this.getStatus();
     if (status === Status.LOADED || status === Status.SLEEPING) return;
 
     await this.server.postRequest("load", this.id);
-    await this.pollStatus();
+
+    if (await this.server.sseManager.probeSSE()) {
+      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}`);
+      }
+    } else {
+      await this.pollStatus();
+    }
   }
 
   /**

package/src/server.ts

@@ -1,25 +1,35 @@
-import { POLLING_INTERVAL, PROVIDER_NAME, PROVIDER_PREFIX } from "./constants";
+import { ApiClient } from "./api/client";
+import { PROVIDER_NAME, PROVIDER_PREFIX } from "./constants";
 import { Mode } from "./enums/mode";
 import { ServerStatus } from "./enums/serverStatus";
 import { HealthEndpoint } from "./interfaces/endpoints/health";
 import { ModelsEndpoint } from "./interfaces/endpoints/models";
-import { PropsEndpoint } from "./interfaces/endpoints/props";
+import {
+  PropsEndpoint,
+  PropsModelEndpoint,
+} from "./interfaces/endpoints/props";
 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 { Cache } from "./utils/cache";
-import { Mutex } from "./utils/mutex";
+import { SSEManager } from "./sse/manager";
 
 export class Server {
   public readonly models: BaseModel[] = [];
   private configResolver = new ConfigResolver();
-  private cache = new Cache(POLLING_INTERVAL / 2);
-  private mutex = new Mutex();
+  private apiClient!: ApiClient;
+  private sse!: SSEManager;
 
   constructor(readonly baseUrl: string) {}
 
+  /**
+   * Provides access to the SSE manager for direct subscriptions.
+   */
+  get sseManager(): SSEManager {
+    return this.sse;
+  }
+
   /**
    * Generates a unique provider ID from a server URL.
    */
@@ -47,7 +57,9 @@ export class Server {
    * Clears the cache first so we always fetch fresh data.
    */
   async initialize() {
-    this.cache.clear();
+    const apiKey = await this.getApiKey();
+    this.apiClient = new ApiClient(this.baseUrl, apiKey);
+    this.sse = new SSEManager(this.baseUrl, apiKey);
     const { data } = await this.fetchModels();
     const mode = await this.detectServerMode();
 
@@ -87,6 +99,8 @@ 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),
@@ -113,7 +127,7 @@ export class Server {
    * @returns The health status
    */
   async fetchServerHealth(): Promise<HealthEndpoint> {
-    return await this.rpc<HealthEndpoint>("/health");
+    return await this.apiClient.get<HealthEndpoint>("/health");
   }
 
   /**
@@ -122,7 +136,7 @@ export class Server {
    * @return The models from the server
    */
   async fetchModels(): Promise<ModelsEndpoint> {
-    return await this.rpc<ModelsEndpoint>("/v1/models");
+    return await this.apiClient.get<ModelsEndpoint>("/v1/models");
   }
 
   /**
@@ -131,7 +145,7 @@ export class Server {
    * @return The properties of the server
    */
   async fetchServerProps(): Promise<PropsEndpoint> {
-    return await this.rpc<PropsEndpoint>("/props?autoload=false");
+    return await this.apiClient.get<PropsEndpoint>("/props?autoload=false");
   }
 
   /**
@@ -140,8 +154,8 @@ export class Server {
    * @param modelId The ID of the model
    * @return The properties of the specified model
    */
-  async fetchModelProps(modelId: string): Promise<PropsEndpoint> {
-    return await this.rpc<PropsEndpoint>(
+  async fetchModelProps(modelId: string): Promise<PropsModelEndpoint> {
+    return await this.apiClient.get<PropsModelEndpoint>(
       `/props?model=${modelId}&autoload=false`,
     );
   }
@@ -156,78 +170,9 @@ export class Server {
     resource: "load" | "unload",
     model: string,
   ): Promise<ModelsEndpoint> {
-    this.cache.clear();
-    return await this.rpc<ModelsEndpoint>(`/models/${resource}`, { model });
-  }
-
-  /**
-   * Makes a cached, deduplicated request to the llama-server.
-   * Results are cached for half the {@link POLLING_INTERVAL} and in-flight requests are deduplicated.
-   *
-   * @param endpoint The endpoint path to fetch (e.g. "/health")
-   * @param body The optional request body for POST requests
-   * @returns The parsed JSON response from the server
-   */
-  private async rpc<T>(
-    endpoint: string,
-    body?: Record<string, unknown>,
-  ): Promise<T> {
-    const key = this.cacheKey(endpoint, body);
-
-    // Check cache
-    const cached = this.cache.get<T>(key);
-    if (cached !== undefined) {
-      return cached;
-    }
-
-    // Deduplicate in-flight requests
-    return this.mutex.getOrCreate(key, async () => {
-      const data = await this.fetch<T>(endpoint, body);
-      this.cache.set(key, data);
-      return data;
+    this.apiClient.clearCache();
+    return await this.apiClient.post<ModelsEndpoint>(`/models/${resource}`, {
+      model,
     });
   }
-
-  /**
-   * Makes an HTTP request to the llama-server and returns the parsed JSON response.
-   *
-   * @param endpoint The endpoint path to fetch (e.g. "/health")
-   * @param body The optional request body for POST requests
-   * @returns The parsed JSON response from the server
-   */
-  private async fetch<T>(
-    endpoint: string,
-    body?: Record<string, unknown>,
-  ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-    const apiKey = await this.getApiKey();
-
-    const data = {
-      method: body ? "POST" : "GET",
-      headers: body ? { "Content-Type": "application/json" } : undefined,
-      body: body ? JSON.stringify(body) : undefined,
-    };
-
-    const res = await fetch(url, {
-      ...data,
-      headers: {
-        ...data.headers,
-        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-      },
-    });
-
-    const response: T = await res.json();
-    return response;
-  }
-
-  /**
-   * Generates a cache key from the endpoint and body.
-   *
-   * @param endpoint The endpoint path (e.g. "/health")
-   * @param body The optional request body for POST requests
-   * @returns A key used for caching
-   */
-  private cacheKey(endpoint: string, body?: Record<string, unknown>): string {
-    return body ? `${endpoint}:${JSON.stringify(body)}` : endpoint;
-  }
 }

package/src/sse/client.ts

@@ -0,0 +1,158 @@
+import { POLLING_INTERVAL } from "../constants";
+import type { SSECallback, SSECleanup, SSEEvent } from "./types";
+
+/**
+ * SSE client for llama-server's /models/sse endpoint.
+ *
+ * Uses a single shared EventSource per server instance.
+ * Supports multiple model subscriptions with automatic event routing.
+ * Handles reconnection by re-subscribing all callbacks.
+ */
+export class SSEClient {
+  private eventSource: EventSource | null = null;
+  private subscribers: Map<string, SSECallback> = new Map();
+  private connected: boolean = false;
+  private reconnecting: boolean = false; // tracks if EventSource auto-reconnect is in progress
+  private _onConnectFailed: (() => void) | null = null;
+  private _hasReceivedEvents: boolean = false;
+
+  /**
+   * @param sseEndpoint - The full SSE endpoint URL (e.g., "http://127.0.0.1:8080/models/sse")
+   * @param apiKey - Optional API key for authenticated servers
+   */
+  constructor(
+    private readonly sseEndpoint: string,
+    private readonly apiKey?: string,
+  ) {}
+
+  /**
+   * Connects to the SSE endpoint.
+   *
+   * @returns true if the connection was established successfully
+   */
+  async connect(): Promise<boolean> {
+    if (this.connected) return true;
+
+    const url = this.buildUrl();
+
+    try {
+      this.eventSource = new EventSource(url);
+    } catch {
+      this.connected = false;
+      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;
+      this.reconnecting = true;
+
+      // Notify subscriber if connection fails before any event is received
+      if (!this._hasReceivedEvents && this._onConnectFailed) {
+        this._onConnectFailed();
+      }
+    };
+
+    this.eventSource.onmessage = (event: MessageEvent) => {
+      try {
+        const data = JSON.parse(event.data);
+        const sseEvent: SSEEvent = {
+          event: data.event ?? "unknown",
+          model: data.model ?? "*",
+          data: data.data,
+        };
+        this._hasReceivedEvents = true;
+        this.dispatch(sseEvent);
+      } catch {
+        // Invalid JSON, ignore
+      }
+    };
+
+    // Wait a bit for the connection to establish
+    await new Promise<void>((resolve) => {
+      const timeout = setTimeout(() => resolve(), POLLING_INTERVAL);
+      this.eventSource!.onopen = () => {
+        clearTimeout(timeout);
+        this.connected = true;
+        this.reconnecting = false;
+        resolve();
+      };
+    });
+
+    return this.connected;
+  }
+
+  /**
+   * Sets a callback to be called when the connection fails before
+   * any event is received. Useful for rejecting promises early.
+   *
+   * @param callback - Called once when connection fails
+   */
+  setOnConnectFailed(callback: () => void): void {
+    this._onConnectFailed = callback;
+  }
+
+  /**
+   * Subscribes to SSE events for a specific model.
+   * Auto-connects if not already connected.
+   *
+   * @param modelId - The model ID to subscribe to
+   * @param callback - Callback to receive SSE events
+   * @returns A cleanup function to unsubscribe
+   */
+  subscribe(modelId: string, callback: SSECallback): SSECleanup {
+    this.subscribers.set(modelId, callback);
+
+    if (!this.connected && !this.reconnecting) {
+      this.connect();
+    }
+
+    return () => {
+      this.subscribers.delete(modelId);
+    };
+  }
+
+  /**
+   * Disconnects from the SSE endpoint and clears all subscriptions.
+   */
+  disconnect(): void {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.connected = false;
+    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.
+   */
+  private dispatch(event: SSEEvent): void {
+    // Dispatch to model-specific subscriber
+    const modelCallback = this.subscribers.get(event.model);
+    if (modelCallback) {
+      modelCallback(event);
+    }
+
+    // Also dispatch to wildcard subscriber if present
+    const wildcardCallback = this.subscribers.get("*");
+    if (wildcardCallback && event.model !== "*") {
+      wildcardCallback(event);
+    }
+  }
+}

package/src/sse/manager.ts

@@ -0,0 +1,208 @@
+import { POLLING_TIMEOUT, SERVER_TIMEOUT } from "../constants";
+import { SSEClient } from "./client";
+import {
+  DownloadProgressData,
+  ProgressData,
+  SSECallback,
+  SSECleanup,
+  SSEEvent,
+  SSEEventType,
+  StatusChangeData,
+} from "./types";
+
+/**
+ * Manages SSE connections and event routing for a single llama-server instance.
+ *
+ * Handles:
+ * - Shared EventSource connection
+ * - Model-based event subscription with callback aggregation
+ * - Progress parsing and callback dispatch
+ */
+export class SSEManager {
+  private sseClient: SSEClient | null = null;
+  private sseSubscribers: Map<string, SSECleanup> = new Map();
+  private modelCallbacks: Map<string, SSECallback[]> = new Map();
+  private sseSupported: boolean | null = null;
+
+  constructor(
+    private readonly baseUrl: string,
+    private readonly apiKey: string,
+  ) {}
+
+  /**
+   * The SSE endpoint URL.
+   */
+  private get sseEndpoint(): string {
+    return `${this.baseUrl}/models/sse`;
+  }
+
+  /**
+   * Probes the SSE endpoint to check if it's supported.
+   * Result is cached for the lifetime of the manager.
+   *
+   * @returns true if SSE is supported
+   */
+  async probeSSE(): Promise<boolean> {
+    if (this.sseSupported !== null) return this.sseSupported;
+
+    try {
+      let url = this.sseEndpoint;
+      if (this.apiKey) {
+        url = `${url}?api_key=${encodeURIComponent(this.apiKey)}`;
+      }
+      const response = await fetch(url, {
+        method: "GET",
+        signal: AbortSignal.timeout(SERVER_TIMEOUT),
+      });
+      this.sseSupported =
+        response.ok &&
+        !!response.headers.get("content-type")?.includes("text/event-stream");
+    } catch {
+      this.sseSupported = false;
+    }
+
+    return this.sseSupported;
+  }
+
+  /**
+   * Subscribes to SSE events for a specific model.
+   * Uses a shared SSE connection per server.
+   * Aggregates multiple callbacks into one SSEClient subscription.
+   *
+   * @param modelId - The model ID to subscribe to
+   * @param callback - Callback to receive SSE events
+   * @returns A cleanup function to unsubscribe
+   */
+  private subscribeToSSE(
+    modelId: string,
+    callback: (event: SSEEvent) => void,
+  ): SSECleanup {
+    // Aggregate callbacks for this model
+    const callbacks = this.modelCallbacks.get(modelId) ?? [];
+    callbacks.push(callback);
+    this.modelCallbacks.set(modelId, callbacks);
+
+    // Create SSE client if not already created
+    this.sseClient ??= new SSEClient(this.sseEndpoint, this.apiKey);
+
+    // Subscribe a single dispatching callback to the SSE client
+    if (!this.sseSubscribers.has(modelId)) {
+      const dispatch = (event: SSEEvent) => {
+        for (const cb of callbacks) cb(event);
+      };
+      const cleanup = this.sseClient!.subscribe(modelId, dispatch);
+      this.sseSubscribers.set(modelId, cleanup);
+    }
+
+    return () => {
+      const list = this.modelCallbacks.get(modelId);
+      if (list) {
+        const idx = list.indexOf(callback);
+        if (idx !== -1) list.splice(idx, 1);
+        if (list.length === 0) {
+          this.modelCallbacks.delete(modelId);
+          const cleanup = this.sseSubscribers.get(modelId);
+          if (cleanup) cleanup();
+          this.sseSubscribers.delete(modelId);
+        }
+      }
+    };
+  }
+
+  /**
+   * Subscribes to SSE progress events for a specific model.
+   * Parses SSE events and calls the progress callback with percentage and stage.
+   *
+   * @param modelId - The model ID to subscribe to
+   * @param onProgress - Callback to receive progress updates (percentage 0-100, stage name)
+   * @returns A cleanup function to unsubscribe
+   */
+  subscribeToProgress(
+    modelId: string,
+    onProgress: (percentage: number, stage?: string) => void,
+  ): SSECleanup {
+    // Track download progress across multiple URLs
+    let totalDownloaded = 0;
+    let totalToDownload = 0;
+
+    return this.subscribeToSSE(modelId, (event: SSEEvent) => {
+      if (event.event === SSEEventType.status_change && event.data) {
+        const data = event.data as unknown as StatusChangeData;
+
+        if (data.status === "loading" && data.progress) {
+          const progress = data.progress as ProgressData;
+          const percentage = Math.round(progress.value * 100);
+          onProgress(percentage, progress.current);
+        } else if (data.status === "loaded" || data.status === "failed") {
+          // Reset download tracking on final state
+          totalDownloaded = 0;
+          totalToDownload = 0;
+        }
+      } else if (event.event === SSEEventType.download_progress && event.data) {
+        const downloadData = event.data as DownloadProgressData;
+        totalDownloaded = 0;
+        totalToDownload = 0;
+
+        for (const urlData of Object.values(downloadData)) {
+          totalDownloaded += urlData.done;
+          totalToDownload += urlData.total;
+        }
+
+        if (totalToDownload > 0) {
+          const percentage = Math.round(
+            (totalDownloaded / totalToDownload) * 100,
+          );
+          onProgress(percentage, "downloading");
+        }
+      }
+    });
+  }
+
+  /**
+   * Subscribes to SSE status change events for a specific model.
+   * Resolves with the final status string once the model reaches a terminal state.
+   * Rejects immediately if the connection fails before any event is received.
+   *
+   * @param modelId - The model ID to subscribe to
+   * @returns Promise that resolves with the final status string
+   */
+  subscribeToStatus(modelId: string): Promise<StatusChangeData> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error(`SSE status timeout for model: ${modelId}`)),
+        POLLING_TIMEOUT,
+      );
+
+      this.subscribeToSSE(modelId, (event: SSEEvent) => {
+        if (event.event === SSEEventType.status_change && event.data) {
+          const data = event.data as unknown as StatusChangeData;
+          if (["loaded", "unloaded", "failed"].includes(data.status)) {
+            clearTimeout(timeout);
+            resolve(data);
+          }
+        }
+      });
+
+      // Reject immediately if the connection fails before any event is received
+      this.sseClient?.setOnConnectFailed(() => {
+        clearTimeout(timeout);
+        reject(new Error(`SSE connection failed for model: ${modelId}`));
+      });
+    });
+  }
+
+  /**
+   * Disconnects the SSE client and cleans up all subscriptions.
+   */
+  disconnect(): void {
+    for (const cleanup of this.sseSubscribers.values()) {
+      cleanup();
+    }
+    this.sseSubscribers.clear();
+    this.modelCallbacks.clear();
+    if (this.sseClient) {
+      this.sseClient.disconnect();
+      this.sseClient = null;
+    }
+  }
+}

package/src/sse/types.ts

@@ -0,0 +1,65 @@
+/**
+ * SSE event types from llama-server's /models/sse endpoint
+ */
+
+/**
+ * Possible event types from the SSE stream
+ */
+export const SSEEventType = {
+  status_change: "status_change",
+  download_progress: "download_progress",
+  download_finished: "download_finished",
+  download_failed: "download_failed",
+  models_reload: "models_reload",
+  model_remove: "model_remove",
+} as const;
+
+export type SSEEventType = (typeof SSEEventType)[keyof typeof SSEEventType];
+
+/**
+ * A parsed SSE event from the /models/sse endpoint
+ */
+export interface SSEEvent {
+  event: SSEEventType;
+  model: string; // model ID or "*" for global events
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Progress data sent during model loading
+ */
+export interface ProgressData {
+  stages: string[];
+  current: string;
+  value: number; // 0.0 to 1.0
+}
+
+/**
+ * Data payload for status_change events
+ */
+export interface StatusChangeData {
+  status: string;
+  exit_code?: number;
+  info?: Record<string, unknown>;
+  progress?: ProgressData;
+}
+
+/**
+ * Data payload for download_progress events
+ */
+export interface DownloadProgressData {
+  [url: string]: {
+    done: number;
+    total: number;
+  };
+}
+
+/**
+ * Subscriber callback type for SSE events
+ */
+export type SSECallback = (event: SSEEvent) => void;
+
+/**
+ * Cleanup function to unsubscribe from SSE events
+ */
+export type SSECleanup = () => void;