pi-llama-cpp 0.2.1 → 0.2.3

package/README.md

@@ -18,9 +18,13 @@ A [Pi Coding Agent](https://pi.dev/) extension that integrates with a running [l
 | 🟢 | 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) |
+| 🔵 | Sleeping | Model is available, but inactive |
 | ⚪ | Unloaded | Model is not loaded on the server |
 
+> **Note**: The `Sleeping` status only shows when you start your server with `llama-server --sleep-idle-seconds <n> ...`.
+This is a **llama.cpp server flag** that tells the server to put idle models to sleep after `n` seconds.
+The model awakens automatically when you send a message.
+
 ## Installation
 
 This package is a Pi extension. Install it with
@@ -65,6 +69,8 @@ If your llama.cpp server requires authentication, use `/login` in Pi, select the
 
 Alternatively, configure the API key in `~/.pi/agent/auth.json` using the provider ID `llama-server`:
 
+> **Note**: The provider is displayed as **Llama.cpp** in the Pi UI, but its internal identifier is `llama-server` — use this ID when configuring `auth.json` or other programmatic access.
+
 ```json
 {
   "llama-server": {
@@ -86,21 +92,24 @@ Make sure your llama.cpp server is running with the appropriate flags.
 llama-server --models-preset path/to/presets.ini ...
 ```
 
-The extension reads the context size from the preset file using the `ctx-size` and/or `fit-ctx` keys.
-
 - For single-model mode, start the server with:
 
 ```bash
-llama-server --model path/to/model.gguf --ctx-size 128000 ...
+llama-server --model path/to/model.gguf ...
 ```
 
+The extension determines the context size as follows:
+- **Router mode** — reads from the preset file's `ctx-size` and/or `fit-ctx` keys
+- **Single mode** — reads from the `/slots` endpoint (stores it in cache afterwards)
+- Falls back to `128000` if not available
+
 ### Commands
 
 | Command   | Description                                                                                |
 | --------- | ------------------------------------------------------------------------------------------ |
 | `/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.
+> **Note:** When the llama.cpp server is unreachable, `/models` is still available but shows the description `Llama.cpp models (offline)` and displays an error notification with the configured server URL.
 
 ### Model Actions
 
@@ -117,13 +126,20 @@ When browsing models via the `/models` command, you can:
 
 ### Model Selection Event
 
-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.
+When you switch models via Pi's model picker (instead of using the `/models` command), the extension listens for the `model_select` event, which also loads the requested model before the conversation begins.
+
+This keeps the server in sync with the active model in Pi, regardless of how the switch was initiated — you don't need to manually load models before using them.
+
+### 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.
+> **Note:** The timeout is only for the polling. The model might still be loading.
 
 ### Model Configuration
 
 Each model exposed to Pi includes the following defaults:
 
-- **`maxTokens`** — `16384` (maximum tokens per response)
+- **`maxTokens`** — `32000` (maximum possible tokens per response according to Pi's source code)
 - **`reasoning`** — `true` (assumed, as llama.cpp's `/models` endpoint does not expose it)
 - **`cost`** — all zero (local model)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.2.1",
-  "description": "Pi extension for llama.cpp integration. Supports both router and single modes",
+  "version": "0.2.3",
+  "description": "Pi extension for llama.cpp integration. Supports both router and single modes.",
   "keywords": [
     "pi",
     "pi-package",
@@ -23,6 +23,10 @@
       "./src/index.ts"
     ]
   },
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
   "prettier": {
     "plugins": [
       "prettier-plugin-organize-imports"
@@ -33,6 +37,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "prettier-plugin-organize-imports": "^4.3.0"
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "vitest": "^4.1.5"
   }
 }

package/src/constants.ts

@@ -13,6 +13,11 @@ export const PROVIDER_NAME = "Llama.cpp";
  */
 export const DEFAULT_LLAMA_SERVER_URL = "http://127.0.0.1:8080";
 
+/**
+ * The placeholder api-key if it couldn't be resolved
+ */
+export const API_KEY_PLACEHOLDER = "sk-placeholder";
+
 /**
  * The default context if the server didn't expose it
  */
@@ -21,7 +26,7 @@ export const DEFAULT_CTX = 128000;
 /**
  * Maximum number of tokens a model can generate in a single response
  */
-export const MAX_TOKENS = 16384;
+export const MAX_TOKENS = 32000;
 
 /**
  * Polling interval (ms) for checking model load status

package/src/events.ts

@@ -1,6 +1,6 @@
 import { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { PROVIDER_NAME } from "./constants";
-import { ModelSelectEvent } from "./interfaces/IModelSelectEvent";
+import { PROVIDER_ID } from "./constants";
+import { ModelSelectEvent } from "./interfaces/events";
 import { listModels } from "./tools/retriever";
 
 /**
@@ -12,7 +12,7 @@ export const onModelSelect = async (
   event: ModelSelectEvent,
   ctx: ExtensionContext,
 ) => {
-  if (event.model.provider !== PROVIDER_NAME) return;
+  if (event.model.provider !== PROVIDER_ID) return;
 
   const models = await listModels();
   const model = models.find((m) => m.id === event.model.id);

package/src/handlers.ts

@@ -35,7 +35,7 @@ const selectModel = async (
 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.LOADING]: [Action.INFO, Action.CANCEL],
     [Status.FAILED]: [Action.RETRY, Action.CANCEL],
     [Status.SLEEPING]: [Action.UNLOAD, Action.INFO, Action.CANCEL],
     [Status.UNLOADED]: [Action.LOAD, Action.CANCEL],
@@ -45,7 +45,7 @@ const getActionsForModel = async (model: BaseModel): Promise<Array<Action>> => {
     [Status.LOADED]: [Action.INFO, Action.CANCEL],
     [Status.LOADING]: [Action.CANCEL],
     [Status.FAILED]: [Action.CANCEL],
-    [Status.SLEEPING]: [Action.CANCEL],
+    [Status.SLEEPING]: [Action.INFO, Action.CANCEL],
     [Status.UNLOADED]: [Action.CANCEL],
   };
 

package/src/interfaces/auth.ts

@@ -0,0 +1,10 @@
+import { PROVIDER_ID } from "../constants";
+
+interface Auth {
+  type: string;
+  key: string;
+}
+
+export interface AuthFile {
+  [PROVIDER_ID]: Auth;
+}

package/src/interfaces/endpoints/health.ts

@@ -0,0 +1,6 @@
+/**
+ * The structure of llama-server's /health endpoint
+ */
+export interface HealthEndpoint {
+  status: "ok";
+}

package/src/interfaces/endpoints/models.ts

@@ -0,0 +1,60 @@
+/**
+ * The structure of llama-server's /models endpoint
+ *
+ * In single mode, the `models` property is not returned
+ * In router mode, everything is used
+ */
+export interface ModelsEndpoint {
+  models?: ModelProperty[];
+  object: string;
+  data: DataProperty[];
+}
+
+export interface ModelProperty {
+  name: string;
+  model: string;
+  modified_at: string;
+  size: string;
+  digest: string;
+  type: string;
+  description: string;
+  tags: string[];
+  capabilities: string[];
+  parameters: string;
+  details: {
+    parent_model: string;
+    format: string;
+    family: string;
+    families: string[];
+    parameter_size: string;
+    quantization_level: string;
+  };
+}
+
+export interface DataProperty {
+  id: string;
+  aliases?: string[];
+  tags: string[];
+  object: string;
+  owned_by: string;
+  created: number;
+  status?: StatusProperty;
+  meta?: MetaProperty;
+}
+
+interface StatusProperty {
+  value: string;
+  args: string[];
+  preset: string;
+  exit_code?: number;
+  failed?: boolean;
+}
+
+interface MetaProperty {
+  vocab_type: number;
+  n_vocab: number;
+  n_ctx_train: number;
+  n_embd: number;
+  n_params: number;
+  size: number;
+}

package/src/interfaces/endpoints/props.ts

@@ -0,0 +1,29 @@
+
+/**
+ * The structure of llama-server's /props endpoint
+ *
+ * In single mode, applies to /props
+ * In router mode, applies to /props?model=<id>
+ */
+export interface PropsEndpoint {
+  default_generation_settings: Record<string, any>;
+  total_slots: number;
+  model_alias: string;
+  model_path: string;
+  modalities: {
+    vision: boolean;
+    audio: boolean;
+  };
+  media_marker: string;
+  endpoint_slots: boolean;
+  endpoint_props: boolean;
+  endpoint_metrics: boolean;
+  webui: boolean;
+  webui_settings: Record<string, any>;
+  chat_template: string;
+  chat_template_caps: Record<string, boolean>;
+  bos_token: string;
+  eos_token: string;
+  build_info: string;
+  is_sleeping: boolean;
+}

package/src/interfaces/endpoints/slots.ts

@@ -0,0 +1,15 @@
+/**
+ * The structure of llama-server's /slots endpoint
+ *
+ * In single mode, applies to /slots
+ * In router mode, applies to /slots?model=<id>
+ */
+export interface SlotsEndpoint {
+  id: number;
+  n_ctx: number;
+  speculative: boolean;
+  is_processing: boolean;
+  id_task?: number;
+  params?: Array<Record<string, any>>;
+  next_token?: Array<Record<string, any>>;
+}

package/src/models/baseModel.ts

@@ -2,9 +2,12 @@ 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 { DataProperty } from "../interfaces/endpoints/models";
 import { rpc } from "../tools/retriever";
 
 export abstract class BaseModel {
+  constructor(protected readonly model: DataProperty) {}
+
   protected readonly statusMapper: Record<string, Status> = {
     loaded: Status.LOADED,
     loading: Status.LOADING,
@@ -23,9 +26,13 @@ export abstract class BaseModel {
 
   abstract get mode(): Mode;
 
-  abstract get id(): string;
+  get id(): string {
+    return this.model.id;
+  }
 
-  abstract get name(): string;
+  get name(): string {
+    return this.model.aliases?.[0] || this.model.id;
+  }
 
   get reasoning(): boolean {
     // We don't have a way to detect this, so we'll fallback to true
@@ -67,6 +74,7 @@ export abstract class BaseModel {
       `Reasoning    : ${this.reasoning}`,
       `Capabilities : ${this.capabilities.join(", ")}`,
       `Context size : ${await this.getContextSize()}`,
+      `Status       : ${await this.getStatus()}`,
     ];
 
     const response = `${messages.join("\n")}\n`;
@@ -104,31 +112,26 @@ export abstract class BaseModel {
   /**
    * Unloads the model from llama-server
    */
-
   async unload(): Promise<void> {
     await rpc("/models/unload", { model: this.id });
   }
 
   /**
    * Polls llama-server to check when the model is loaded
+   *
+   * @param startTime The initial polling timestamp
    */
-  async pollStatus(): Promise<void> {
-    const startTime = Date.now();
-
-    // Check loading status
-    try {
-      while ((await this.getStatus()) === Status.LOADING) {
-        // Force a timeout if we wasted too much time polling
-        if (Date.now() - startTime > POLLING_TIMEOUT) {
-          const message = `Model loading timed out after ${POLLING_TIMEOUT} ms: ${this.id}`;
-          throw new Error(message);
-        }
-
-        await new Promise((r) => setTimeout(r, POLLING_INTERVAL));
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+  async pollStatus(startTime = Date.now()): Promise<void> {
+    const status = await this.getStatus();
+    if (status !== Status.LOADING) return;
+
+    // Force a timeout if we wasted too much time polling
+    if (Date.now() - startTime > POLLING_TIMEOUT) {
+      const message = `Model loading timed out after ${POLLING_TIMEOUT} ms: ${this.id}`;
       throw new Error(message);
     }
+
+    await new Promise((r) => setTimeout(r, POLLING_INTERVAL));
+    await this.pollStatus(startTime);
   }
 }

package/src/models/routerModel.ts

@@ -1,40 +1,32 @@
 import { DEFAULT_CTX } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
-import { IRouterModel } from "../interfaces/IRouterModel";
+import { DataProperty, ModelsEndpoint } from "../interfaces/endpoints/models";
 import { rpc } from "../tools/retriever";
 import { BaseModel } from "./baseModel";
 
 export class RouterModel extends BaseModel {
-  constructor(private readonly model: IRouterModel) {
-    super();
+  constructor(protected readonly model: DataProperty) {
+    super(model);
   }
 
   get mode(): Mode {
     return Mode.ROUTER;
   }
 
-  get id(): string {
-    return this.model.id;
-  }
-
-  get name(): string {
-    return this.model.aliases?.[0] || this.model.id;
-  }
-
   get capabilities(): ["text"] | ["image"] {
-    const hasImage = this.model.status.args?.includes("--mmproj") ?? false;
+    const hasImage = this.model.status?.args?.includes("--mmproj") ?? false;
     return hasImage ? ["image"] : ["text"];
   }
 
   async getStatus(): Promise<Status> {
-    const { data } = await rpc<{ data: IRouterModel[] }>("/models");
+    const { data } = await rpc<ModelsEndpoint>("/models");
     const model = data.find((m) => m.id === this.id);
     if (!model) return Status.FAILED;
 
-    const status = this.statusMapper[model.status.value];
+    const status = this.statusMapper[model.status!.value];
     if (status === Status.UNLOADED) {
-      if (this.model.status.failed) return Status.FAILED;
+      if (this.model.status!.failed) return Status.FAILED;
 
       return Status.UNLOADED;
     }
@@ -58,7 +50,7 @@ export class RouterModel extends BaseModel {
    * @returns The value
    */
   private extractFrom(arg: string): number | null {
-    const args = this.model.status.args;
+    const args = this.model.status!.args;
     if (!args) return null;
 
     const ctxIdx = args.indexOf(arg);

package/src/models/singleModel.ts

@@ -1,41 +1,50 @@
 import { DEFAULT_CTX } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
-import { ISingleModel } from "../interfaces/ISingleModel";
+import { DataProperty, ModelProperty } from "../interfaces/endpoints/models";
+import { PropsEndpoint } from "../interfaces/endpoints/props";
+import { SlotsEndpoint } from "../interfaces/endpoints/slots";
 import { rpc } from "../tools/retriever";
 import { BaseModel } from "./baseModel";
 
 export class SingleModel extends BaseModel {
-  constructor(private readonly model: ISingleModel) {
-    super();
+  private contextSize?: number;
+
+  constructor(
+    protected readonly model: DataProperty,
+    private readonly extra: ModelProperty,
+  ) {
+    super(model);
   }
 
   get mode(): Mode {
     return Mode.SINGLE;
   }
 
-  get id(): string {
-    return this.model.name;
-  }
-
-  get name(): string {
-    return this.model.name;
-  }
-
   get capabilities(): ["text"] | ["image"] {
-    const hasImage = this.model.capabilities.includes("multimodal");
+    const hasImage = this.extra.capabilities.includes("multimodal");
     return hasImage ? ["image"] : ["text"];
   }
 
   async getStatus(): Promise<Status> {
     // In single-mode, the extension will only work when the model is fully loaded
+    const { is_sleeping } = await rpc<PropsEndpoint>("/props");
+    if (is_sleeping) return Status.SLEEPING;
+
     return Status.LOADED;
   }
 
   async getContextSize(): Promise<number> {
-    const slots = await rpc<{ n_ctx: number }[]>("/slots");
-    const [{ n_ctx }] = slots;
+    // Avoid calling the endpoint if we already have the value
+    if (this.contextSize) return this.contextSize;
+
+    try {
+      const [{ n_ctx }] = await rpc<SlotsEndpoint[]>("/slots");
+      this.contextSize = n_ctx;
 
-    return n_ctx ?? DEFAULT_CTX;
+      return this.contextSize;
+    } catch {
+      return DEFAULT_CTX;
+    }
   }
 }

package/src/tools/resolver.ts

@@ -1,7 +1,11 @@
 import { access, constants, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { DEFAULT_LLAMA_SERVER_URL, PROVIDER_ID } from "../constants";
-import { IAuth, IAuthFile } from "../interfaces/IAuthFile";
+import {
+  API_KEY_PLACEHOLDER,
+  DEFAULT_LLAMA_SERVER_URL,
+  PROVIDER_ID,
+} from "../constants";
+import { AuthFile } from "../interfaces/auth";
 
 // The URL is detected once, to reuse forever
 let resolvedUrl: string | undefined;
@@ -42,12 +46,12 @@ 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, U>(
+const readConfigValue = async <T>(
   filePath: string,
-  key: string,
-): Promise<U> => {
+  key: keyof T,
+): Promise<T[keyof T] | null> => {
   const cfg = await readContents<T>(filePath);
-  return (cfg as Record<string, any>)?.[key] || null;
+  return cfg?.[key] ?? null;
 };
 
 /**
@@ -55,16 +59,11 @@ const readConfigValue = async <T, U>(
  * @returns The API key, as defined by the auth.json file
  */
 export const resolveApiKey = async (): Promise<string> => {
-  const placeholder = "sk-placeholder";
-
   const authPath = join(process.env.HOME || ".", ".pi", "agent", "auth.json");
-  if (!(await fileExists(authPath))) return placeholder;
+  if (!(await fileExists(authPath))) return API_KEY_PLACEHOLDER;
 
-  const cfg = await readConfigValue<IAuthFile, IAuth | null>(
-    authPath,
-    PROVIDER_ID,
-  );
-  return cfg?.key ?? placeholder;
+  const cfg = await readConfigValue<AuthFile>(authPath, PROVIDER_ID);
+  return cfg?.key ?? API_KEY_PLACEHOLDER;
 };
 
 /**
@@ -81,10 +80,7 @@ const resolveGlobalUrl = async (): Promise<string | null> => {
 
   if (!(await fileExists(globalPath))) return null;
 
-  return readConfigValue<Record<string, string>, string>(
-    globalPath,
-    "llamaServerUrl",
-  );
+  return readConfigValue<Record<string, string>>(globalPath, "llamaServerUrl");
 };
 
 /**
@@ -96,7 +92,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>, string>(projectPath, "url");
+  return readConfigValue<Record<string, string>>(projectPath, "url");
 };
 
 /**

package/src/tools/retriever.ts

@@ -1,5 +1,5 @@
-import { IRouterModel } from "../interfaces/IRouterModel";
-import { ISingleModel } from "../interfaces/ISingleModel";
+import { HealthEndpoint } from "../interfaces/endpoints/health";
+import { ModelsEndpoint } from "../interfaces/endpoints/models";
 import { BaseModel } from "../models/baseModel";
 import { RouterModel } from "../models/routerModel";
 import { SingleModel } from "../models/singleModel";
@@ -11,7 +11,7 @@ import { resolveApiKey, resolveUrl } from "./resolver";
  */
 export const isServerReady = async (): Promise<boolean> => {
   try {
-    const { status } = await rpc<{ status: string }>("/health");
+    const { status } = await rpc<HealthEndpoint>("/health");
     return status === "ok";
   } catch {
     return false;
@@ -59,13 +59,11 @@ export const rpc = async <T>(
  * @returns The list of models
  */
 export const listModels = async (): Promise<BaseModel[]> => {
-  const { models, data } = await rpc<{
-    models?: ISingleModel[];
-    data: IRouterModel[];
-  }>("/models");
+  const { models, data } = await rpc<ModelsEndpoint>("/models");
 
   if (models) {
-    return models.map((m) => new SingleModel(m));
+    const [extra] = models;
+    return data.map((m) => new SingleModel(m, extra));
   }
 
   const response = data

package/tests/handlers.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from "vitest";
+import { Action } from "../src/enums/action";
+import { Mode } from "../src/enums/mode";
+import { Status } from "../src/enums/status";
+import { DataProperty } from "../src/interfaces/endpoints/models";
+
+// Mock the retriever module before importing anything that depends on it
+vi.mock("../src/tools/retriever", () => ({
+  rpc: vi.fn(),
+  isServerReady: vi.fn(),
+  listModels: vi.fn(),
+}));
+
+class TestModel {
+  constructor(
+    private readonly model: DataProperty,
+    private readonly _mode: Mode,
+    private readonly _status: Status,
+  ) {}
+
+  get mode(): Mode {
+    return this._mode;
+  }
+
+  get capabilities(): ["text"] | ["image"] {
+    return ["text"];
+  }
+
+  async getStatus(): Promise<Status> {
+    return this._status;
+  }
+
+  async getContextSize(): Promise<number> {
+    return 4096;
+  }
+}
+
+const createModel = (
+  mode: Mode,
+  status: Status,
+  overrides: Partial<DataProperty> = {},
+) =>
+  new TestModel(
+    {
+      id: "test",
+      tags: [],
+      object: "model",
+      owned_by: "test",
+      created: Date.now(),
+      ...overrides,
+    },
+    mode,
+    status,
+  );
+
+/**
+ * Replicates the getActionsForModel logic from handlers.ts for testing
+ * without needing the full Pi extension context.
+ */
+const getActionsForModel = async (model: TestModel): Promise<Array<Action>> => {
+  const routerModeActions: Record<Status, Array<Action>> = {
+    [Status.LOADED]: [Action.SWITCH, Action.UNLOAD, Action.INFO, Action.CANCEL],
+    [Status.LOADING]: [Action.INFO, 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.INFO, Action.CANCEL],
+    [Status.UNLOADED]: [Action.CANCEL],
+  };
+
+  const allActions =
+    model.mode === Mode.ROUTER ? routerModeActions : singleModeActions;
+
+  const status = await model.getStatus();
+  return allActions[status];
+};
+
+describe("Action availability", () => {
+  const actionMatrix: Array<{
+    mode: Mode;
+    status: Status;
+    expected: Action[];
+  }> = [
+    // Router mode
+    {
+      mode: Mode.ROUTER,
+      status: Status.LOADED,
+      expected: [Action.SWITCH, Action.UNLOAD, Action.INFO, Action.CANCEL],
+    },
+    {
+      mode: Mode.ROUTER,
+      status: Status.LOADING,
+      expected: [Action.INFO, Action.CANCEL],
+    },
+    {
+      mode: Mode.ROUTER,
+      status: Status.FAILED,
+      expected: [Action.RETRY, Action.CANCEL],
+    },
+    {
+      mode: Mode.ROUTER,
+      status: Status.SLEEPING,
+      expected: [Action.UNLOAD, Action.INFO, Action.CANCEL],
+    },
+    {
+      mode: Mode.ROUTER,
+      status: Status.UNLOADED,
+      expected: [Action.LOAD, Action.CANCEL],
+    },
+    // Single mode
+    {
+      mode: Mode.SINGLE,
+      status: Status.LOADED,
+      expected: [Action.INFO, Action.CANCEL],
+    },
+    { mode: Mode.SINGLE, status: Status.LOADING, expected: [Action.CANCEL] },
+    { mode: Mode.SINGLE, status: Status.FAILED, expected: [Action.CANCEL] },
+    {
+      mode: Mode.SINGLE,
+      status: Status.SLEEPING,
+      expected: [Action.INFO, Action.CANCEL],
+    },
+    { mode: Mode.SINGLE, status: Status.UNLOADED, expected: [Action.CANCEL] },
+  ];
+
+  it.each(actionMatrix)(
+    "should return correct actions for $mode/$status",
+    async ({ mode, status, expected }) => {
+      const model = createModel(mode, status);
+      const actions = await getActionsForModel(model);
+      expect(actions).toEqual(expected);
+    },
+  );
+
+  it("should always include CANCEL regardless of mode or status", async () => {
+    for (const mode of [Mode.ROUTER, Mode.SINGLE]) {
+      for (const status of Object.values(Status)) {
+        const model = createModel(mode, status);
+        const actions = await getActionsForModel(model);
+        expect(actions).toContain(Action.CANCEL);
+      }
+    }
+  });
+
+  it("should not include mode-exclusive actions", async () => {
+    const singleLoaded = createModel(Mode.SINGLE, Status.LOADED);
+    expect(await getActionsForModel(singleLoaded)).not.toContain(Action.SWITCH);
+    expect(await getActionsForModel(singleLoaded)).not.toContain(Action.LOAD);
+
+    const singleFailed = createModel(Mode.SINGLE, Status.FAILED);
+    expect(await getActionsForModel(singleFailed)).not.toContain(Action.RETRY);
+  });
+});

package/tests/resolver.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  API_KEY_PLACEHOLDER,
+  DEFAULT_LLAMA_SERVER_URL,
+  PROVIDER_ID,
+} from "../src/constants";
+
+describe("URL resolution fallback chain", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    delete process.env.LLAMA_SERVER_URL;
+  });
+
+  it("should return default URL when no config is found", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockRejectedValue(new Error("ENOENT")),
+      constants: { F_OK: 0 },
+      readFile: vi.fn().mockResolvedValue(""),
+    }));
+
+    const { resolveUrl } = await import("../src/tools/resolver");
+    const result = await resolveUrl("/tmp/test-project");
+
+    expect(result).toBe(DEFAULT_LLAMA_SERVER_URL);
+  });
+
+  it("should prioritize project config over env variable", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockImplementation(async (path: string) => {
+        if (path.includes("llama-server.json")) return undefined;
+        throw new Error("ENOENT");
+      }),
+      constants: { F_OK: 0 },
+      readFile: vi
+        .fn()
+        .mockResolvedValue(JSON.stringify({ url: "http://localhost:9999" })),
+    }));
+
+    process.env.LLAMA_SERVER_URL = "http://env-url:8080";
+
+    const { resolveUrl } = await import("../src/tools/resolver");
+    const result = await resolveUrl("/tmp/test-project");
+
+    expect(result).toBe("http://localhost:9999");
+  });
+
+  it("should use env variable when no project config exists", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockRejectedValue(new Error("ENOENT")),
+      constants: { F_OK: 0 },
+      readFile: vi.fn().mockResolvedValue(""),
+    }));
+
+    process.env.LLAMA_SERVER_URL = "http://env-url:8080";
+
+    const { resolveUrl } = await import("../src/tools/resolver");
+    const result = await resolveUrl("/tmp/test-project");
+
+    expect(result).toBe("http://env-url:8080");
+  });
+
+  it("should use global settings when no project config or env exists", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockImplementation(async (path: string) => {
+        if (path.includes("settings.json")) return undefined;
+        throw new Error("ENOENT");
+      }),
+      constants: { F_OK: 0 },
+      readFile: vi
+        .fn()
+        .mockResolvedValue(
+          JSON.stringify({ llamaServerUrl: "http://global:8080" }),
+        ),
+    }));
+
+    const { resolveUrl } = await import("../src/tools/resolver");
+    const result = await resolveUrl("/tmp/test-project");
+
+    expect(result).toBe("http://global:8080");
+  });
+
+  it("should strip trailing slashes from resolved URL", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockImplementation(async (path: string) => {
+        if (path.includes("llama-server.json")) return undefined;
+        throw new Error("ENOENT");
+      }),
+      constants: { F_OK: 0 },
+      readFile: vi
+        .fn()
+        .mockResolvedValue(JSON.stringify({ url: "http://localhost:8080/" })),
+    }));
+
+    const { resolveUrl } = await import("../src/tools/resolver");
+    const result = await resolveUrl("/tmp/test-project");
+
+    expect(result).toBe("http://localhost:8080");
+  });
+});
+
+describe("API key resolution", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+  });
+
+  it("should return placeholder when auth file does not exist", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockRejectedValue(new Error("ENOENT")),
+      constants: { F_OK: 0 },
+      readFile: vi.fn().mockResolvedValue(""),
+    }));
+
+    const { resolveApiKey } = await import("../src/tools/resolver");
+    const result = await resolveApiKey();
+
+    expect(result).toBe(API_KEY_PLACEHOLDER);
+  });
+
+  it("should return placeholder when provider key is missing", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockResolvedValue(undefined),
+      constants: { F_OK: 0 },
+      readFile: vi
+        .fn()
+        .mockResolvedValue(
+          JSON.stringify({ "other-provider": { key: "other-key" } }),
+        ),
+    }));
+
+    const { resolveApiKey } = await import("../src/tools/resolver");
+    const result = await resolveApiKey();
+
+    expect(result).toBe(API_KEY_PLACEHOLDER);
+  });
+
+  it("should return the provider key when present", async () => {
+    vi.doMock("node:fs/promises", () => ({
+      access: vi.fn().mockResolvedValue(undefined),
+      constants: { F_OK: 0 },
+      readFile: vi
+        .fn()
+        .mockResolvedValue(
+          JSON.stringify({ [PROVIDER_ID]: { key: "test-api-key" } }),
+        ),
+    }));
+
+    const { resolveApiKey } = await import("../src/tools/resolver");
+    const result = await resolveApiKey();
+
+    expect(result).toBe("test-api-key");
+  });
+});

package/tests/routerModel.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from "vitest";
+import { Mode } from "../src/enums/mode";
+import { DataProperty } from "../src/interfaces/endpoints/models";
+import { RouterModel } from "../src/models/routerModel";
+
+// Helper to create a mock DataProperty
+const createModel = (overrides: Partial<DataProperty> = {}): DataProperty => ({
+  id: "test-model",
+  aliases: ["test-alias"],
+  tags: [],
+  object: "model",
+  owned_by: "test",
+  created: Date.now(),
+  ...overrides,
+});
+
+describe("RouterModel context size extraction", () => {
+  it("should extract --ctx-size value", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: [
+            "--model",
+            "gguf",
+            "--ctx-size",
+            "4096",
+            "--batch-size",
+            "512",
+          ],
+          preset: "default",
+        },
+      }),
+    );
+
+    // Access the private method via any
+    const extractFrom = (model as any).extractFrom.bind(model);
+    expect(extractFrom("--ctx-size")).toBe(4096);
+  });
+
+  it("should extract --fit-ctx value when --ctx-size is not present", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--fit-ctx", "8192"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const extractFrom = (model as any).extractFrom.bind(model);
+    expect(extractFrom("--fit-ctx")).toBe(8192);
+  });
+
+  it("should return null when argument is not found", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--batch-size", "512"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const extractFrom = (model as any).extractFrom.bind(model);
+    expect(extractFrom("--ctx-size")).toBeNull();
+    expect(extractFrom("--fit-ctx")).toBeNull();
+  });
+
+  it("should return null when argument has no following value", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--ctx-size"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const extractFrom = (model as any).extractFrom.bind(model);
+    expect(extractFrom("--ctx-size")).toBeNull();
+  });
+
+  it("should return null when argument value is not a valid number", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--ctx-size", "not-a-number"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const extractFrom = (model as any).extractFrom.bind(model);
+    expect(extractFrom("--ctx-size")).toBeNull();
+  });
+
+  it("should prefer --ctx-size over --fit-ctx", async () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--ctx-size", "4096", "--fit-ctx", "8192"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const ctxSize = await model.getContextSize();
+    expect(ctxSize).toBe(4096);
+  });
+
+  it("should return DEFAULT_CTX when no context size args are present", async () => {
+    const { DEFAULT_CTX } = await import("../src/constants");
+
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf"],
+          preset: "default",
+        },
+      }),
+    );
+
+    const ctxSize = await model.getContextSize();
+    expect(ctxSize).toBe(DEFAULT_CTX);
+  });
+});
+
+describe("RouterModel capabilities detection", () => {
+  it("should detect image capability when --mmproj is present", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf", "--mmproj", "mmproj.gguf"],
+          preset: "default",
+        },
+      }),
+    );
+
+    expect(model.capabilities).toEqual(["image"]);
+  });
+
+  it("should detect text-only capability when --mmproj is absent", () => {
+    const model = new RouterModel(
+      createModel({
+        status: {
+          value: "loaded",
+          args: ["--model", "gguf"],
+          preset: "default",
+        },
+      }),
+    );
+
+    expect(model.capabilities).toEqual(["text"]);
+  });
+
+  it("should default to text when status is undefined", () => {
+    const model = new RouterModel(createModel({ status: undefined }));
+
+    expect(model.capabilities).toEqual(["text"]);
+  });
+});
+
+describe("RouterModel mode", () => {
+  it("should always return ROUTER mode", () => {
+    const model = new RouterModel(createModel());
+    expect(model.mode).toBe(Mode.ROUTER);
+  });
+});

package/tests/singleModel.test.ts

@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { DEFAULT_CTX } from "../src/constants";
+import { Mode } from "../src/enums/mode";
+import { Status } from "../src/enums/status";
+import { ModelProperty } from "../src/interfaces/endpoints/models";
+import { SingleModel } from "../src/models/singleModel";
+
+const mockRpc = vi.fn();
+
+vi.mock("../src/tools/retriever", () => ({
+  rpc: (...args: unknown[]) => mockRpc(...args),
+  isServerReady: vi.fn(),
+  listModels: vi.fn(),
+}));
+
+beforeEach(() => {
+  mockRpc.mockClear();
+});
+
+const createModel = (extra: Partial<ModelProperty> = {}): SingleModel =>
+  new SingleModel(
+    {
+      id: "test",
+      tags: [],
+      object: "model",
+      owned_by: "test",
+      created: Date.now(),
+    },
+    {
+      name: "test",
+      model: "test.gguf",
+      modified_at: new Date().toISOString(),
+      size: "1B",
+      digest: "abc123",
+      type: "model",
+      description: "test",
+      tags: [],
+      capabilities: [],
+      parameters: "",
+      details: {
+        parent_model: "",
+        format: "",
+        family: "",
+        families: [],
+        parameter_size: "",
+        quantization_level: "",
+      },
+      ...extra,
+    },
+  );
+
+describe("SingleModel mode", () => {
+  it("should always return SINGLE mode", () => {
+    const model = createModel();
+    expect(model.mode).toBe(Mode.SINGLE);
+  });
+});
+
+describe("SingleModel capabilities", () => {
+  it("should detect image capability when multimodal", () => {
+    const model = createModel({ capabilities: ["multimodal"] });
+    expect(model.capabilities).toEqual(["image"]);
+  });
+
+  it("should detect text-only capability when not multimodal", () => {
+    const model = createModel({ capabilities: [] });
+    expect(model.capabilities).toEqual(["text"]);
+  });
+});
+
+describe("SingleModel getStatus", () => {
+  it("should return LOADED when not sleeping", async () => {
+    mockRpc.mockResolvedValueOnce({ is_sleeping: false });
+
+    const model = createModel();
+    const status = await model.getStatus();
+
+    expect(status).toBe(Status.LOADED);
+    expect(mockRpc).toHaveBeenCalledWith("/props");
+  });
+
+  it("should return SLEEPING when is_sleeping is true", async () => {
+    mockRpc.mockResolvedValueOnce({ is_sleeping: true });
+
+    const model = createModel();
+    const status = await model.getStatus();
+
+    expect(status).toBe(Status.SLEEPING);
+  });
+});
+
+describe("SingleModel getContextSize", () => {
+  it("should return n_ctx from /slots endpoint", async () => {
+    mockRpc.mockResolvedValueOnce([{ n_ctx: 8192 }]);
+
+    const model = createModel();
+    const ctxSize = await model.getContextSize();
+
+    expect(ctxSize).toBe(8192);
+    expect(mockRpc).toHaveBeenCalledWith("/slots");
+  });
+
+  it("should cache the context size on first call", async () => {
+    mockRpc.mockResolvedValueOnce([{ n_ctx: 4096 }]);
+
+    const model = createModel();
+    const first = await model.getContextSize();
+    const second = await model.getContextSize();
+
+    expect(first).toBe(4096);
+    expect(second).toBe(4096);
+    expect(mockRpc).toHaveBeenCalledTimes(1);
+  });
+
+  it("should return DEFAULT_CTX when /slots fails", async () => {
+    mockRpc.mockRejectedValueOnce(new Error("Connection refused"));
+
+    const model = createModel();
+    const ctxSize = await model.getContextSize();
+
+    expect(ctxSize).toBe(DEFAULT_CTX);
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+  },
+});

package/src/interfaces/IAuthFile.ts

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

package/src/interfaces/IRouterModel.ts

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

package/src/interfaces/ISingleModel.ts

@@ -1,20 +0,0 @@
-export interface ISingleModel {
-  name: string;
-  model: string;
-  modified_at: string;
-  size: string;
-  digest: string;
-  type: string;
-  description: string;
-  tags: string[];
-  capabilities: string[];
-  parameters: string;
-  details: {
-    parent_model: string;
-    format: string;
-    family: string;
-    families: string[];
-    parameter_size: string;
-    quantization_level: string;
-  };
-}