pi-llama-cpp 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Pi extension for llama.cpp integration. Supports router, single and legacy models. Supports multiple servers.",
   "keywords": [
     "pi",

package/src/sse/client.ts

@@ -13,6 +13,8 @@ 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
+  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")
@@ -49,6 +51,11 @@ export class SSEClient {
       // 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) => {
@@ -59,6 +66,7 @@ export class SSEClient {
           model: data.model ?? "*",
           data: data.data,
         };
+        this._hasReceivedEvents = true;
         this.dispatch(sseEvent);
       } catch {
         // Invalid JSON, ignore
@@ -79,6 +87,16 @@ export class SSEClient {
     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.

package/src/sse/manager.ts

@@ -46,13 +46,12 @@ export class SSEManager {
     if (this.sseSupported !== null) return this.sseSupported;
 
     try {
-      const headers: Record<string, string> = {};
+      let url = this.sseEndpoint;
       if (this.apiKey) {
-        headers["Authorization"] = `Bearer ${this.apiKey}`;
+        url = `${url}?api_key=${encodeURIComponent(this.apiKey)}`;
       }
-      const response = await fetch(this.sseEndpoint, {
+      const response = await fetch(url, {
         method: "GET",
-        headers,
         signal: AbortSignal.timeout(SERVER_TIMEOUT),
       });
       this.sseSupported =
@@ -162,6 +161,7 @@ export class SSEManager {
   /**
    * 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
@@ -182,6 +182,12 @@ export class SSEManager {
           }
         }
       });
+
+      // 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}`));
+      });
     });
   }
 

package/PLAN.md

@@ -1,349 +0,0 @@
-# Model Download Feature — Implementation Plan
-
-## Overview
-
-Add a `/models-download` command that lets users:
-
-- **Download** a model by typing a HuggingFace repo string (e.g. `ggml-org/gemma-3-4b-it-GGUF:Q4_K_M`)
-- **Cancel** an in-progress download
-- **Delete** a cached model via `/models-download delete`
-
-Download progress is shown in real time via the existing SSE infrastructure. After completion, the user is notified and invited to run `/models` to refresh.
-
-Extra documentation of the server's internals can be found in `~/Proyectos/llama-server/README.md`.
-
----
-
-## Key Insight
-
-When downloading, the model **does not yet exist** in the local model list. The HF repo string itself acts as the model identifier in SSE events. This means:
-
-- Download/cancel/delete are **`Server` operations**, not `BaseModel` methods.
-- SSE subscriptions use the raw HF repo string as the `modelId`.
-- No changes to `BaseModel` are needed.
-
-## Command Structure
-
-The `/models-download` command has three subcommands:
-
-| Subcommand                   | Description                    |
-| ---------------------------- | ------------------------------ |
-| `/models-download` (no args) | Interactive download flow      |
-| `/models-download delete`    | Interactive delete flow        |
-| `/models-download cancel`    | Cancel an in-progress download |
-
-Each subcommand is routed by `DownloadManager.handleCommand(args, ctx, pi)`.
-
----
-
-## Files to Create
-
-### `src/managers/download.ts` — DownloadManager
-
-Orchestrates the download, cancel, and delete workflows.
-
-```
-class DownloadManager
-├── constructor(serverManager, pi)
-├── handleCommand(args, ctx, pi)   → routes to download / delete / cancel flow
-├── handleDownloadFlow(ctx)        → interactive: input HF repo → confirm → download with progress
-├── handleDeleteFlow(ctx)          → interactive: select deletable model → confirm → delete
-├── handleCancelFlow(ctx)          → cancel in-progress download
-└── helpers: selectServer, selectModel
-```
-
-**Dependencies:** `ServerManager` (needs `getServers()` accessor), `pi: ExtensionAPI` (for cleanup notifications).
-
----
-
-## Files to Modify
-
-### 1. `src/server.ts`
-
-Add four methods:
-
-| Method                   | HTTP                                 | Purpose                                   |
-| ------------------------ | ------------------------------------ | ----------------------------------------- |
-| `downloadModel(hfRepo)`  | `POST /models`                       | Trigger download with `{ model: hfRepo }` |
-| `deleteModel(modelId)`   | `DELETE /models?model={id}`          | Remove cached model                       |
-| `cancelDownload(hfRepo)` | `POST /models/unload`                | Cancel in-progress download               |
-| `probeSSESupport()`      | delegates to `SSEManager.probeSSE()` | Check `/models/sse` availability          |
-
-**Note:** All four endpoints are confirmed by the llama-server [API documentation](https://github.com/ggml-org/llama.cpp/blob/main/server/README.md). `POST /models/unload` works for both unloading loaded models AND canceling downloads.
-
-**Also:** Add `ApiClient.do_delete()` for DELETE requests. Unlike `get`/`post`, `delete` does **not** need caching since it's a mutation. No public `delete()` wrapper is needed (unlike `get`/`post`).
-
-```typescript
-// New signature
-async do_delete<T>(endpoint: string): Promise<T>
-```
-
-`do_delete` makes a raw DELETE request with `Authorization: Bearer ${this.apiKey}` (same auth pattern as `do_get`/`do_post`).
-
-**Note:** No changes to `BaseModel`. Download and delete are server-level operations that work with model IDs/strings directly, not model instances.
-
-### 2. `src/managers/server.ts`
-
-Add a public accessor (currently `servers` is private):
-
-```typescript
-getServers(): Server[] {
-  return this.servers;
-}
-```
-
-### 3. `src/interfaces/endpoints/models.ts`
-
-Add `can_remove` and `need_download` to `DataProperty` (they're already there — confirmed). No changes needed.
-
-### 4. `src/index.ts`
-
-- Import and instantiate `DownloadManager`
-- Register the `/models-download` command
-- Pass `serverManager` and `pi` to it
-
-### 5. `src/sse/manager.ts`
-
-Add `subscribeToDownloadStatus(modelId: string): Promise<'success' | 'failed'>` — see implementation details in the SSE Event Mapping section above.
-
-### 6. `src/sse/types.ts`
-
-Add `download_finished` and `download_failed` to `SSEEventType` (they're already there — confirmed). No changes needed.
-
----
-
-## Download Flow (detailed)
-
-```
-User: /models-download
-  │
-  ├─ SSE supported? (probeSSESupport)
-  │   └─ No → notify error, exit
-  │
-  ├─ Always select server (even if only one) → ctx.ui.select("Select server:", [...])
-  │   └─ Format: "Llama.cpp (http://127.0.0.1:8080)"
-  │
-  ├─ ctx.ui.input("Enter HuggingFace model", "user/repo:quant")
-  │   └─ Cancelled → exit
-  │
-  ├─ Basic validation (must contain "/")
-  │   └─ Invalid → notify error, exit
-  │
-  ├─ ctx.ui.confirm("Confirm Download", "Download <repo>?")
-  │   └─ No → exit
-  │
-  ├─ server.downloadModel(hfRepo)
-  │   └─ Response: { success: true } or { error: { code, message, type } }
-  │       └─ If error → notify error, exit
-  │
-  ├─ Subscribe to SSE progress (hfRepo as modelId)
-  │   └─ On each event: ctx.ui.notify("Downloading ... X%", "info")
-  │
-  ├─ Wait for terminal SSE event (download_finished / download_failed)
-  │   ├─ Success → notify "Download complete. Run /models to refresh."
-  │   └─ Failure → notify "Download failed: <reason>"
-  │
-  ├─ Call GET /models to update the model list
-  │
-  └─ Cleanup SSE subscription
-```
-
-### Download Timeout
-
-Downloads can take several minutes. **No timeout** is applied to the download status subscription — the SSE connection will wait indefinitely for `download_finished` or `download_failed`. The `subscribeToProgress` call already handles progress updates in real time.
-
-## Delete Flow (detailed)
-
-```
-User: /models-download delete
-  │
-  ├─ Always select server (even if only one) → ctx.ui.select("Select server:", [...])
-  │   └─ Format: "Llama.cpp (http://127.0.0.1:8080)"
-  │
-  ├─ Fetch fresh model list from server (GET /models)
-  │
-  ├─ Filter models where can_remove === true
-  │   └─ None → notify "No deletable models", exit
-  │   └─ Note: models still downloading are NOT in the list yet, so they cannot be deleted.
-  │
-  ├─ ctx.ui.select("Select model to delete:", [...])
-  │   └─ Cancelled → exit
-  │
-  ├─ ctx.ui.confirm("Confirm Delete", "Delete <name>? This cannot be undone.")
-  │   └─ No → exit
-  │
-  ├─ server.deleteModel(modelId)
-  │   └─ Response: { success: true }
-  │   ├─ Success → notify "Deleted <name>. Run /models to refresh."
-  │   └─ Failure → notify error
-  │
-  └─ Done
-```
-
-## Cancel Download
-
-The `cancelDownload` method on `Server` sends `POST /models/unload` with the HF repo string. Per the llama-server docs, `POST /models/unload` cancels in-progress downloads (it's the same endpoint used to unload loaded models).
-
-Exposed as `/models-download cancel` subcommand. The flow:
-
-```
-User: /models-download cancel
-  │
-  ├─ Always select server (even if only one) → ctx.ui.select("Select server:", [...])
-  │   └─ Format: "Llama.cpp (http://127.0.0.1:8080)"
-  │
-  ├─ ctx.ui.input("Enter HF repo to cancel", "user/repo:quant")
-  │   └─ Cancelled → exit
-  │
-  ├─ server.cancelDownload(hfRepo)
-  │   └─ Sends POST /models/unload with { model: hfRepo }
-  │
-  ├─ Notify: "Download cancelled for <repo>."
-  │
-  └─ Done
-```
-
-**Note:** `cancelDownload` is semantically distinct from `downloadModel` even though they use the same endpoint. It should be a separate method for clarity.
-
----
-
-## SSE Event Mapping
-
-The existing `SSEManager` already handles these event types:
-
-| SSE Event                       | Current handling                                             | Used by       |
-| ------------------------------- | ------------------------------------------------------------ | ------------- |
-| `download_progress`             | `subscribeToProgress()` parses `done/total` → percentage     | Download flow |
-| `status_change` with `progress` | `subscribeToProgress()` parses `value` → percentage + stage  | Download flow |
-| `download_finished`             | Not explicitly handled yet — need to add terminal resolution | Download flow |
-| `download_failed`               | Not explicitly handled yet — need to add terminal rejection  | Download flow |
-
-**Gap:** `SSEManager.subscribeToStatus()` currently only resolves on `status_change` events with `loaded`/`failed`. For downloads, we need it to also resolve on `download_finished`/`download_failed` events. Two options:
-
-- **(A)** Add a new `subscribeToDownloadStatus(modelId)` method that resolves on download terminal events.
-- **(B)** Extend `subscribeToStatus()` to also handle download terminal events.
-
-**Recommendation:** Option (A) — keep concerns separated. The download manager calls `subscribeToDownloadStatus()`.
-
-**`subscribeToDownloadStatus(modelId)` implementation:**
-
-```typescript
-subscribeToDownloadStatus(modelId: string): Promise<'success' | 'failed'> {
-  return new Promise((resolve, reject) => {
-    // No timeout — downloads can take several minutes.
-    // The SSE connection waits indefinitely for a terminal event.
-
-    this.subscribeToSSE(modelId, (event: SSEEvent) => {
-      if (event.event === SSEEventType.download_finished) {
-        resolve('success');
-      } else if (event.event === SSEEventType.download_failed) {
-        reject(new Error(`Download failed for model: ${modelId}`));
-      }
-    });
-  });
-}
-```
-
-- Subscribes to SSE for the HF repo string as `modelId`.
-- Resolves with `"success"` on `download_finished`.
-- Rejects with an error on `download_failed`.
-- The event `data` field contains the model identifier string (e.g., `"ggml-org/gemma-3-4b-it-GGUF:Q4_K_M"`), but we don't need to parse it — the `modelId` parameter already identifies the model.
-
-**SSE Event Payloads** (from llama-server docs):
-
-```json
-// download_finished / download_failed
-{
-  "model": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M"
-}
-```
-
-Both events carry the model identifier in `data`. No additional error details — errors are surfaced via the event type itself (`download_failed` vs `download_finished`).
-
-```json
-// model_remove — sent after successful DELETE /models
-{
-  "model": "ggml-org/gemma-3-4b-it-GGUF:Q4_K_M"
-}
-```
-
-The `model_remove` event is sent by the server after a successful delete. The extension doesn't need to handle it explicitly — the user runs `/models` to refresh the list anyway. But it's good to be aware of it in case we want to auto-refresh later.
-
-```json
-// models_reload — sent after model list changes (download completes, delete completes)
-{
-  "model": "*"
-}
-```
-
-The `models_reload` event uses `"model": "*"` (global event). This is sent after downloads complete and after deletes. We don't need to handle it in v1 — the download flow explicitly calls `GET /models` to refresh. But it's useful context for future auto-refresh features.
-
-**Note:** `SSEManager.probeSSE()` already exists and is cached. `SSEEventType` already includes `download_finished` and `download_failed`. The `subscribeToProgress()` method already handles `download_progress` events. We just need to add a terminal resolver.
-
----
-
-## Notification Types
-
-Pi's `ctx.ui.notify()` accepts `"info" | "warning" | "error"`. There is no `"success"` type. Use `"info"` for success messages.
-
----
-
-## API Response Formats
-
-### `POST /models` (download)
-
-**Success:**
-
-```json
-{ "success": true }
-```
-
-**Error:**
-
-```json
-{
-  "error": {
-    "code": 400,
-    "message": "model validation failed, unable to download",
-    "type": "invalid_request_error"
-  }
-}
-```
-
-### `DELETE /models?model={id}` (delete)
-
-**Success:**
-
-```json
-{ "success": true }
-```
-
-### `POST /models/unload` (cancel download)
-
-Same endpoint as unload — response format not explicitly documented by llama-server. Likely returns `{ success: true }` or an empty object. We'll treat any non-throwing response as success.
-
----
-
-## Server Selection UX
-
-In all three flows (download, delete, cancel), the user always selects a server first — even if there's only one server configured. This keeps the UX consistent and future-proofs the feature.
-
-```typescript
-// Example: server list labels
-const choices = servers.map((s) => `${PROVIDER_NAME} (${s.baseUrl})`);
-// → ["Llama.cpp (http://127.0.0.1:8080)", "Llama.cpp (http://127.0.0.1:8081)"]
-const choice = await ctx.ui.select("Select server:", choices);
-```
-
----
-
-## TODO Comments
-
-Add `// TODO: Verify if download/delete needs to be gated to router mode` in:
-
-- `DownloadManager.handleCommand()`
-- `Server.downloadModel()`
-- `Server.deleteModel()`
-- `Server.cancelDownload()`
-
----