pi-llama-cpp 0.1.2 → 0.2.1

package/README.md

@@ -5,12 +5,22 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with a running [l
 ## Features
 
 - **Auto-detect models** — discovers all models available on your running llama.cpp server
-- **Live status indicators** — see which models are loaded, loading, failed, or unloaded with color-coded icons
+- **Live status indicators** — see which models are loaded, loading, failed, sleeping, or unloaded with color-coded icons
 - **Load / unload / switch** — manage models directly from the Pi command palette
 - **Multi-model router support** — works with both single-model and multi-model llama.cpp server configurations
-- **Image model support** — detects multimodal models automatically
+- **Image capabilities detection** — detects multimodal models automatically
 - **Flexible URL resolution** — configures the server URL via project config, environment variable, or global settings
 
+### Status Indicators
+
+| Icon | Status | Description |
+|------|--------|-------------|
+| 🟢 | Loaded | Model is active and ready to use |
+| 🟡 | Loading | Model is currently being loaded |
+| 🔴 | Failed | Model failed to load |
+| 🔵 | Sleeping | Model is loaded but inactive (router mode) |
+| ⚪ | Unloaded | Model is not loaded on the server |
+
 ## Installation
 
 This package is a Pi extension. Install it with
@@ -51,15 +61,15 @@ The extension resolves the llama.cpp server URL using the following priority ord
 
 ### API Key
 
-If your llama.cpp server requires authentication, use `/login` in Pi, select the "API key" option, and choose the `llama-server` provider.
+If your llama.cpp server requires authentication, use `/login` in Pi, select the "API key" option, and choose the `Llama.cpp` provider from the list.
 
-Alternatively, configure the API key in `~/.pi/agent/auth.json`:
+Alternatively, configure the API key in `~/.pi/agent/auth.json` using the provider ID `llama-server`:
 
 ```json
 {
   "llama-server": {
-    "type": "bearer",
-    "key": "your-api-key-here"
+    "type": "api_key",
+    "key": "<your-api-key-here>"
   }
 }
 ```
@@ -68,15 +78,17 @@ Alternatively, configure the API key in `~/.pi/agent/auth.json`:
 
 ### Prerequisites
 
-Make sure your llama.cpp server is running with the appropriate flags. For multi-model support (model router), start the server with:
+Make sure your llama.cpp server is running with the appropriate flags.
+
+- For multi-model support (model router), start the server with:
 
 ```bash
-llama-server --models-preset path/to/presets.ini
+llama-server --models-preset path/to/presets.ini ...
 ```
 
-(You can use both `--fit-ctx` and `--ctx-size` in the preset — the extension checks both.)
+The extension reads the context size from the preset file using the `ctx-size` and/or `fit-ctx` keys.
 
-For single-model mode, a standard invocation works:
+- For single-model mode, start the server with:
 
 ```bash
 llama-server --model path/to/model.gguf --ctx-size 128000 ...
@@ -86,7 +98,9 @@ llama-server --model path/to/model.gguf --ctx-size 128000 ...
 
 | Command   | Description                                                                                |
 | --------- | ------------------------------------------------------------------------------------------ |
-| `/models` | Browse llama-server models with live status. Select a model to load, switch, or unload it. |
+| `/models` | Browse your models with live status. Select a model to load, switch, or unload it.         |
+
+> **Note:** When the llama.cpp server is unreachable, `/models` is still available but displays an error notification with the configured server URL.
 
 ### Model Actions
 
@@ -95,10 +109,15 @@ When browsing models via the `/models` command, you can:
 - **Load & switch** — Load an unloaded model and switch to it
 - **Switch model** — Switch to a model that is already loaded
 - **Unload** — Unload a loaded model to free memory
+- **Retry** — Retry loading a failed model
+- **Info** — View model details (ID, capabilities, context size)
+- **Cancel** — Cancel the current operation
+
+> **Note:** In single-model mode, only **Info** and **Cancel** are available, since there is only one model loaded on the server.
 
 ### Model Selection Event
 
-When Pi switches models (e.g., via `model_select`), the extension automatically loads the selected model on the llama.cpp server. This keeps the server in sync with the active model in Pi.
+When Pi switches models (via `model_select`), the extension automatically loads the selected model on the llama.cpp server. This keeps the server in sync with the active model in Pi.
 
 ### Model Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Pi extension for llama.cpp integration. Supports both router and single modes",
   "keywords": [
     "pi",
@@ -20,7 +20,19 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./src/index.ts"
     ]
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-organize-imports"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "prettier-plugin-organize-imports": "^4.3.0"
   }
 }

package/src/constants.ts

@@ -1,7 +1,12 @@
+/**
+ * This provider's id
+ */
+export const PROVIDER_ID = "llama-server";
+
 /**
  * This provider's name
  */
-export const PROVIDER_NAME = "llama-server";
+export const PROVIDER_NAME = "Llama.cpp";
 
 /**
  * The default URL if the resolver couldn't find it

package/src/enums/{actions.ts → action.ts}

@@ -1,7 +1,9 @@
 /** The possible actions for the /models command */
-export enum Actions {
+export enum Action {
   SWITCH = "Switch model",
+  RETRY = "Retry",
   LOAD = "Load & switch",
   UNLOAD = "Unload",
+  INFO = "Info",
   CANCEL = "Cancel",
 }

package/src/enums/mode.ts

@@ -0,0 +1,5 @@
+/** The possible modes of llama-server models */
+export enum Mode {
+  ROUTER = "router",
+  SINGLE = "single",
+}

package/src/enums/status.ts

@@ -3,5 +3,6 @@ export enum Status {
   LOADED = "loaded",
   LOADING = "loading",
   FAILED = "failed",
+  SLEEPING = "sleeping",
   UNLOADED = "unloaded",
 }

package/src/events.ts

@@ -1,7 +1,7 @@
 import { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { PROVIDER_NAME } from "./constants";
-import { listModels } from "./tools/retriever";
 import { ModelSelectEvent } from "./interfaces/IModelSelectEvent";
+import { listModels } from "./tools/retriever";
 
 /**
  * Reacts to a new model event triggered by Pi

package/src/handlers.ts

@@ -2,50 +2,116 @@ import type {
   ExtensionAPI,
   ExtensionCommandContext,
 } from "@mariozechner/pi-coding-agent";
+import { PROVIDER_ID, PROVIDER_NAME } from "./constants";
+import { Action } from "./enums/action";
+import { Mode } from "./enums/mode";
 import { Status } from "./enums/status";
 import { BaseModel } from "./models/baseModel";
-import { Actions } from "./enums/actions";
-import { PROVIDER_NAME } from "./constants";
 
 /**
- * Defines a handler when llama-server is running
+ * Select a model from the list. Returns null if user cancels.
+ *
  * @param ctx Pi context
- * @returns The action and model, if detected
+ * @param models A list of models
+ * @returns The selected model
  */
-const modelSelectionHandler = async (
+const selectModel = async (
   ctx: ExtensionCommandContext,
   models: BaseModel[],
-): Promise<{ action: Actions; model: BaseModel } | null> => {
-  // Setup the labels
+): Promise<BaseModel | null> => {
   const labels = await Promise.all(models.map((m) => m.getLabel()));
-
-  // Detect the selected model
   const choice = await ctx.ui.select(`${PROVIDER_NAME} models:`, labels);
   if (!choice) return null;
-
   const idx = labels.indexOf(choice);
-  const model = models[idx];
-
-  // Define the actions that the user can do
-  const allActions = {
-    [Status.LOADED]: [Actions.UNLOAD, Actions.CANCEL],
-    [Status.LOADING]: [Actions.CANCEL],
-    [Status.FAILED]: [Actions.SWITCH, Actions.CANCEL],
-    [Status.UNLOADED]: [Actions.SWITCH, Actions.CANCEL],
+  return models[idx];
+};
+
+/**
+ * Get available actions for a model based on its mode and status.
+ *
+ * @param model The selected model
+ * @returns
+ */
+const getActionsForModel = async (model: BaseModel): Promise<Array<Action>> => {
+  const routerModeActions: Record<Status, Array<Action>> = {
+    [Status.LOADED]: [Action.SWITCH, Action.UNLOAD, Action.INFO, Action.CANCEL],
+    [Status.LOADING]: [Action.CANCEL],
+    [Status.FAILED]: [Action.RETRY, Action.CANCEL],
+    [Status.SLEEPING]: [Action.UNLOAD, Action.INFO, Action.CANCEL],
+    [Status.UNLOADED]: [Action.LOAD, Action.CANCEL],
+  };
+
+  const singleModeActions: Record<Status, Array<Action>> = {
+    [Status.LOADED]: [Action.INFO, Action.CANCEL],
+    [Status.LOADING]: [Action.CANCEL],
+    [Status.FAILED]: [Action.CANCEL],
+    [Status.SLEEPING]: [Action.CANCEL],
+    [Status.UNLOADED]: [Action.CANCEL],
   };
 
+  const allActions =
+    model.mode === Mode.ROUTER ? routerModeActions : singleModeActions;
+
   const status = await model.getStatus();
-  const actions = allActions[status];
+  return allActions[status];
+};
+
+/**
+ * Selects an action for a model.
+ *
+ * @param ctx Pi context
+ * @param model The selected model
+ * @param actions Possible actions to execute
+ * @returns The action, or null if user cancels
+ */
+const selectAction = async (
+  ctx: ExtensionCommandContext,
+  model: BaseModel,
+  actions: Array<Action>,
+): Promise<Action | null> => {
+  const labels = actions.map((a) => String(a));
+  const choice = await ctx.ui.select(`${model.name}`, labels);
+  if (!choice) return null;
+
+  const idx = labels.indexOf(choice);
+  return actions[idx];
+};
+
+/**
+ * Handles the menu for model selection
+ * Loops: select model → select action → handle action.
+ *
+ * Escape on actions menu goes back to model selection.
+ * Escape on model selection exits.
+ *
+ * @param ctx Pi context
+ * @returns The action and model, if detected
+ */
+const modelSelectionHandler = async (
+  ctx: ExtensionCommandContext,
+  models: BaseModel[],
+): Promise<{ action: Action; model: BaseModel } | null> => {
+  while (true) {
+    // Select the model
+    const model = await selectModel(ctx, models);
+    if (!model) return null;
 
-  const action = (await ctx.ui.select(`${model.id}`, actions)) as Actions;
-  if (!action || action === Actions.CANCEL) return null;
+    // Select the action
+    const actions = await getActionsForModel(model);
+    const action = await selectAction(ctx, model, actions);
+    if (action === null) {
+      // Escape key pressed => back to model selection
+      continue;
+    }
 
-  // Send the selected action with the corresponding model
-  return { action, model };
+    // Return the selected action and model
+    return { action, model };
+  }
 };
 
 /**
  * Handles the /models command
+ *
  * @param ctx The context used by Pi
  * @param pi The Pi extension
  */
@@ -60,25 +126,40 @@ export const modelsCommandHandler = async (
   // Detect the model
   const { action, model } = event;
 
-  // Execute the selected action
-  if (action === Actions.UNLOAD) {
+  // Action: Cancel
+  if (!action || action === Action.CANCEL) return;
+
+  // Action: Info
+  if (action === Action.INFO) {
+    const info = await model.getInfo();
+    ctx.ui.notify(`${info}`, "info");
+    return;
+  }
+
+  // Action: Unload
+  if (action === Action.UNLOAD) {
     await model.unload();
-    ctx.ui.notify(`Unloaded ${model.id}`, "info");
-  } else {
-    const status = await model.getStatus();
-    if (status === Status.LOADED) return;
+    ctx.ui.notify(`Unloaded ${model.name}`, "info");
+    return;
+  }
 
-    ctx.ui.notify(`Loading ${model.id}...`, "info");
+  // Actions: Load/Switch/Retry
+  const loadActions = [Action.LOAD, Action.SWITCH, Action.RETRY];
+  if (loadActions.includes(action)) {
+    ctx.ui.notify(`Loading ${model.name}...`, "info");
 
-    // Load the model without blocking the UI
     const onSuccess = async () => {
-      const piModel = ctx.modelRegistry.find(PROVIDER_NAME, model.id);
+      const piModel = ctx.modelRegistry.find(PROVIDER_ID, model.id);
       if (!piModel) {
-        throw new Error(`Cannot find model ${model.id} in pi registry`);
+        throw new Error(`Cannot find model ${model.name} in pi registry`);
+      }
+
+      if ((await model.getStatus()) === Status.FAILED) {
+        throw new Error("Failed to load model");
       }
 
       await pi.setModel(piModel);
-      ctx.ui.notify(`Model ${model.id} ready`, "info");
+      ctx.ui.notify(`Model ${model.name} ready`, "info");
     };
 
     const onFailure = (err: any) => {
@@ -86,6 +167,7 @@ export const modelsCommandHandler = async (
       ctx.ui.notify(message, "error");
     };
 
+    // Load the model without blocking the UI
     model.load().then(onSuccess).catch(onFailure);
   }
 };

package/{index.ts → src/index.ts}

@@ -2,11 +2,11 @@ import type {
   ExtensionAPI,
   ExtensionCommandContext,
 } from "@mariozechner/pi-coding-agent";
-import { modelsCommandHandler } from "./src/handlers";
-import { isServerReady, listModels } from "./src/tools/retriever";
-import { resolveApiKey, resolveUrl } from "./src/tools/resolver";
-import { PROVIDER_NAME } from "./src/constants";
-import { onModelSelect } from "./src/events";
+import { PROVIDER_ID, PROVIDER_NAME } from "./constants";
+import { onModelSelect } from "./events";
+import { modelsCommandHandler } from "./handlers";
+import { resolveApiKey, resolveUrl } from "./tools/resolver";
+import { isServerReady, listModels } from "./tools/retriever";
 
 export default async function (pi: ExtensionAPI) {
   // Command registration
@@ -36,7 +36,8 @@ export default async function (pi: ExtensionAPI) {
   });
 
   // Provider registration
-  pi.registerProvider(PROVIDER_NAME, {
+  pi.registerProvider(PROVIDER_ID, {
+    name: PROVIDER_NAME,
     baseUrl: `${url}/v1`,
     api: "openai-completions",
     apiKey: await resolveApiKey(),

package/src/interfaces/IAuthFile.ts

@@ -1,8 +1,10 @@
 import { PROVIDER_NAME } from "../constants";
 
+export interface IAuth {
+  type: string;
+  key: string;
+}
+
 export interface IAuthFile {
-  [PROVIDER_NAME]: {
-    type: string;
-    key: string;
-  };
+  [PROVIDER_NAME]: IAuth;
 }

package/src/interfaces/IRouterModel.ts

@@ -1,3 +1,11 @@
+interface IRouterModelStatus {
+  value: string;
+  args: string[];
+  preset: string;
+  exit_code?: number;
+  failed?: boolean;
+}
+
 export interface IRouterModel {
   id: string;
   aliases?: string[];
@@ -5,5 +13,5 @@ export interface IRouterModel {
   object: string;
   owned_by: string;
   created: number;
-  status: { value: string; args: string[] };
+  status: IRouterModelStatus;
 }

package/src/models/baseModel.ts

@@ -1,5 +1,6 @@
 import type { ProviderModelConfig } from "@mariozechner/pi-coding-agent";
 import { MAX_TOKENS, POLLING_INTERVAL, POLLING_TIMEOUT } from "../constants";
+import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
 import { rpc } from "../tools/retriever";
 
@@ -8,6 +9,7 @@ export abstract class BaseModel {
     loaded: Status.LOADED,
     loading: Status.LOADING,
     failed: Status.FAILED,
+    sleeping: Status.SLEEPING,
     unloaded: Status.UNLOADED,
   };
 
@@ -15,9 +17,12 @@ export abstract class BaseModel {
     [Status.LOADED]: "🟢",
     [Status.LOADING]: "🟡",
     [Status.FAILED]: "🔴",
+    [Status.SLEEPING]: "🔵",
     [Status.UNLOADED]: "⚪",
   };
 
+  abstract get mode(): Mode;
+
   abstract get id(): string;
 
   abstract get name(): string;
@@ -43,13 +48,31 @@ export abstract class BaseModel {
   abstract getContextSize(): Promise<number>;
 
   /**
-   * Returns the corresponding label of our load status
+   * Sets up a label for the model selection screen
+   * @returns A label structured as "<icon> <name>"
    */
   async getLabel(): Promise<string> {
     const status = await this.getStatus();
     return `${this.labelIcons[status]} ${this.name}`;
   }
 
+  /**
+   * Returns a human-readable information about the model
+   * @returns A string with the model information
+   */
+  async getInfo(): Promise<string> {
+    const messages = [
+      `ID           : ${this.id}`,
+      `Model        : ${this.name}`,
+      `Reasoning    : ${this.reasoning}`,
+      `Capabilities : ${this.capabilities.join(", ")}`,
+      `Context size : ${await this.getContextSize()}`,
+    ];
+
+    const response = `${messages.join("\n")}\n`;
+    return response;
+  }
+
   /**
    * Converts the llama-server model into a configuration object used by Pi
    * @returns A Pi configuration object

package/src/models/routerModel.ts

@@ -1,7 +1,8 @@
-import { IRouterModel } from "../interfaces/IRouterModel";
 import { DEFAULT_CTX } from "../constants";
-import { rpc } from "../tools/retriever";
+import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
+import { IRouterModel } from "../interfaces/IRouterModel";
+import { rpc } from "../tools/retriever";
 import { BaseModel } from "./baseModel";
 
 export class RouterModel extends BaseModel {
@@ -9,6 +10,10 @@ export class RouterModel extends BaseModel {
     super();
   }
 
+  get mode(): Mode {
+    return Mode.ROUTER;
+  }
+
   get id(): string {
     return this.model.id;
   }
@@ -25,12 +30,16 @@ export class RouterModel extends BaseModel {
   async getStatus(): Promise<Status> {
     const { data } = await rpc<{ data: IRouterModel[] }>("/models");
     const model = data.find((m) => m.id === this.id);
-    if (!model) return Status.UNLOADED;
+    if (!model) return Status.FAILED;
+
+    const status = this.statusMapper[model.status.value];
+    if (status === Status.UNLOADED) {
+      if (this.model.status.failed) return Status.FAILED;
 
-    const response = this.statusMapper[model.status.value];
-    if (!response) return Status.UNLOADED;
+      return Status.UNLOADED;
+    }
 
-    return response;
+    return status;
   }
 
   async getContextSize(): Promise<number> {

package/src/models/singleModel.ts

@@ -1,7 +1,8 @@
-import { ISingleModel } from "../interfaces/ISingleModel";
 import { DEFAULT_CTX } from "../constants";
-import { rpc } from "../tools/retriever";
+import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
+import { ISingleModel } from "../interfaces/ISingleModel";
+import { rpc } from "../tools/retriever";
 import { BaseModel } from "./baseModel";
 
 export class SingleModel extends BaseModel {
@@ -9,6 +10,10 @@ export class SingleModel extends BaseModel {
     super();
   }
 
+  get mode(): Mode {
+    return Mode.SINGLE;
+  }
+
   get id(): string {
     return this.model.name;
   }

package/src/tools/resolver.ts

@@ -1,7 +1,7 @@
-import { DEFAULT_LLAMA_SERVER_URL, PROVIDER_NAME } from "../constants";
-import { access, readFile, constants } from "node:fs/promises";
+import { access, constants, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { IAuthFile } from "../interfaces/IAuthFile";
+import { DEFAULT_LLAMA_SERVER_URL, PROVIDER_ID } from "../constants";
+import { IAuth, IAuthFile } from "../interfaces/IAuthFile";
 
 // The URL is detected once, to reuse forever
 let resolvedUrl: string | undefined;
@@ -42,10 +42,10 @@ const readContents = async <T>(filePath: string): Promise<T | null> => {
  * @param key Key to extract from the parsed JSON
  * @returns The string value, or null if file/key missing or invalid
  */
-const readConfigValue = async <T>(
+const readConfigValue = async <T, U>(
   filePath: string,
   key: string,
-): Promise<string | null> => {
+): Promise<U> => {
   const cfg = await readContents<T>(filePath);
   return (cfg as Record<string, any>)?.[key] || null;
 };
@@ -60,8 +60,11 @@ export const resolveApiKey = async (): Promise<string> => {
   const authPath = join(process.env.HOME || ".", ".pi", "agent", "auth.json");
   if (!(await fileExists(authPath))) return placeholder;
 
-  const response = await readConfigValue<IAuthFile>(authPath, PROVIDER_NAME);
-  return response ?? placeholder;
+  const cfg = await readConfigValue<IAuthFile, IAuth | null>(
+    authPath,
+    PROVIDER_ID,
+  );
+  return cfg?.key ?? placeholder;
 };
 
 /**
@@ -77,7 +80,11 @@ const resolveGlobalUrl = async (): Promise<string | null> => {
   );
 
   if (!(await fileExists(globalPath))) return null;
-  return readConfigValue<Record<string, string>>(globalPath, "llamaServerUrl");
+
+  return readConfigValue<Record<string, string>, string>(
+    globalPath,
+    "llamaServerUrl",
+  );
 };
 
 /**
@@ -89,7 +96,7 @@ const resolveProjectUrl = async (cwd: string): Promise<string | null> => {
   const projectPath = join(cwd, ".pi", "llama-server.json");
 
   if (!(await fileExists(projectPath))) return null;
-  return readConfigValue<Record<string, string>>(projectPath, "url");
+  return readConfigValue<Record<string, string>, string>(projectPath, "url");
 };
 
 /**

package/src/tools/retriever.ts

@@ -1,8 +1,8 @@
-import { ISingleModel } from "../interfaces/ISingleModel";
 import { IRouterModel } from "../interfaces/IRouterModel";
-import { SingleModel } from "../models/singleModel";
-import { RouterModel } from "../models/routerModel";
+import { ISingleModel } from "../interfaces/ISingleModel";
 import { BaseModel } from "../models/baseModel";
+import { RouterModel } from "../models/routerModel";
+import { SingleModel } from "../models/singleModel";
 import { resolveApiKey, resolveUrl } from "./resolver";
 
 /**

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}