pi-llama-cpp 0.2.2 → 0.3.0

package/README.md

@@ -99,8 +99,8 @@ 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)
+- **Router mode** — when loaded, reads `meta.n_ctx` from the `/models` endpoint; when not loaded, reads `--ctx-size` and/or `--fit-ctx` from the model's status `args` array
+- **Single mode** — reads `meta.n_ctx` from the `/models` endpoint
 - Falls back to `128000` if not available
 
 ### Commands
@@ -145,6 +145,6 @@ Each model exposed to Pi includes the following defaults:
 
 ## Dependencies
 
-| Dependency                      | Purpose                               |
-| ------------------------------- | ------------------------------------- |
-| `@mariozechner/pi-coding-agent` | Pi Coding Agent SDK (peer dependency) |
+| Dependency                        | Purpose                               |
+| --------------------------------- | ------------------------------------- |
+| `@earendil-works/pi-coding-agent` | Pi Coding Agent SDK (peer dependency) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.2.2",
-  "description": "Pi extension for llama.cpp integration. Supports both router and single modes",
+  "version": "0.3.0",
+  "description": "Pi extension for llama.cpp integration. Supports both router and single modes.",
   "keywords": [
     "pi",
     "pi-package",
@@ -23,16 +23,21 @@
       "./src/index.ts"
     ]
   },
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
   "prettier": {
     "plugins": [
       "prettier-plugin-organize-imports"
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "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/{handlers.ts → commands/models.ts}

@@ -1,12 +1,13 @@
 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";
+} from "@earendil-works/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 { resolveUrl } from "../tools/resolver";
 
 /**
  * Select a model from the list. Returns null if user cancels.
@@ -109,13 +110,25 @@ const modelSelectionHandler = async (
   }
 };
 
+/**
+ * Handles the /models command when the server is unreachable.
+ *
+ * @param ctx The context used by Pi
+ */
+export const notFoundCommand = async (
+  ctx: ExtensionCommandContext,
+): Promise<void> => {
+  const url = await resolveUrl(ctx.cwd);
+  ctx.ui.notify(`${PROVIDER_NAME} unreachable at ${url}`, "error");
+};
+
 /**
  * Handles the /models command
  *
  * @param ctx The context used by Pi
  * @param pi The Pi extension
  */
-export const modelsCommandHandler = async (
+export const modelsCommand = async (
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
   models: BaseModel[],

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
  */

package/src/events.ts

@@ -1,4 +1,4 @@
-import { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { PROVIDER_ID } from "./constants";
 import { ModelSelectEvent } from "./interfaces/events";
 import { listModels } from "./tools/retriever";

package/src/index.ts

@@ -1,47 +1,34 @@
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
-} from "@mariozechner/pi-coding-agent";
-import { PROVIDER_ID, PROVIDER_NAME } from "./constants";
+} from "@earendil-works/pi-coding-agent";
+import { modelsCommand, notFoundCommand } from "./commands/models";
+import { PROVIDER_NAME } from "./constants";
 import { onModelSelect } from "./events";
-import { modelsCommandHandler } from "./handlers";
-import { resolveApiKey, resolveUrl } from "./tools/resolver";
-import { isServerReady, listModels } from "./tools/retriever";
+import { registerLlamaCppProvider } from "./tools/provider";
+import { isServerReady } from "./tools/retriever";
 
 export default async function (pi: ExtensionAPI) {
-  // Command registration
+  // Server verification
   if (!(await isServerReady())) {
     pi.registerCommand("models", {
       description: `${PROVIDER_NAME} models (offline)`,
-      handler: async (
-        _: string,
-        ctx: ExtensionCommandContext,
-      ): Promise<void> => {
-        const url = await resolveUrl(ctx.cwd);
-        ctx.ui.notify(`${PROVIDER_NAME} unreachable at ${url}`, "error");
+      handler: async (_: string, ctx: ExtensionCommandContext) => {
+        await notFoundCommand(ctx);
       },
     });
 
     return;
   }
 
-  const cwd = process.cwd();
-  const url = await resolveUrl(cwd);
-  const serverModels = await listModels();
+  // Provider registration
+  const serverModels = await registerLlamaCppProvider(pi);
 
+  // Command: /models
   pi.registerCommand("models", {
     description: `Browse ${PROVIDER_NAME} models (live status)`,
     handler: async (_: string, ctx: ExtensionCommandContext) =>
-      await modelsCommandHandler(ctx, pi, serverModels),
-  });
-
-  // Provider registration
-  pi.registerProvider(PROVIDER_ID, {
-    name: PROVIDER_NAME,
-    baseUrl: `${url}/v1`,
-    api: "openai-completions",
-    apiKey: await resolveApiKey(),
-    models: await Promise.all(serverModels.map((m) => m.toProviderConfig())),
+      await modelsCommand(ctx, pi, serverModels),
   });
 
   // Events registration

package/src/interfaces/auth.ts

@@ -1,6 +1,6 @@
 import { PROVIDER_ID } from "../constants";
 
-export interface Auth {
+interface Auth {
   type: string;
   key: string;
 }

package/src/interfaces/endpoints/models.ts

@@ -53,6 +53,7 @@ interface StatusProperty {
 interface MetaProperty {
   vocab_type: number;
   n_vocab: number;
+  n_ctx: number;
   n_ctx_train: number;
   n_embd: number;
   n_params: number;

package/src/models/baseModel.ts

@@ -1,8 +1,14 @@
-import type { ProviderModelConfig } from "@mariozechner/pi-coding-agent";
-import { MAX_TOKENS, POLLING_INTERVAL, POLLING_TIMEOUT } from "../constants";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_CTX,
+  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 { DataProperty, ModelsEndpoint } from "../interfaces/endpoints/models";
+import { PropsEndpoint } from "../interfaces/endpoints/props";
 import { rpc } from "../tools/retriever";
 
 export abstract class BaseModel {
@@ -40,9 +46,21 @@ export abstract class BaseModel {
   }
 
   /**
-   * Detects if the model can load images
+   * Detects the capabilities of the model
+   *
+   * @returns An array of capabilities, as expected by Pi
    */
-  abstract get capabilities(): ["text"] | ["image"];
+  async getCapabilities(): Promise<["text"] | ["image"]> {
+    try {
+      const { modalities } = await rpc<PropsEndpoint>(
+        `/props?model=${this.id}`,
+      );
+
+      return modalities.vision ? ["image"] : ["text"];
+    } catch {
+      return ["text"];
+    }
+  }
 
   /**
    * Gets the load status of the model
@@ -52,7 +70,17 @@ export abstract class BaseModel {
   /**
    * Gets the context size of a particular model
    */
-  abstract getContextSize(): Promise<number>;
+  async getContextSize(): Promise<number> {
+    try {
+      const { data } = await rpc<ModelsEndpoint>(`/models`);
+      const model = data.find((d) => d.id === this.id);
+
+      const response = model?.meta?.n_ctx;
+      return response ?? DEFAULT_CTX;
+    } catch {
+      return DEFAULT_CTX;
+    }
+  }
 
   /**
    * Sets up a label for the model selection screen
@@ -72,7 +100,7 @@ export abstract class BaseModel {
       `ID           : ${this.id}`,
       `Model        : ${this.name}`,
       `Reasoning    : ${this.reasoning}`,
-      `Capabilities : ${this.capabilities.join(", ")}`,
+      `Capabilities : ${(await this.getCapabilities()).join(", ")}`,
       `Context size : ${await this.getContextSize()}`,
       `Status       : ${await this.getStatus()}`,
     ];
@@ -90,7 +118,7 @@ export abstract class BaseModel {
       id: this.id,
       name: this.name,
       reasoning: this.reasoning,
-      input: this.capabilities,
+      input: await this.getCapabilities(),
       contextWindow: await this.getContextSize(),
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
       maxTokens: MAX_TOKENS,
@@ -112,31 +140,23 @@ 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));
+  async pollStatus(startTime = Date.now()): Promise<void> {
+    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);
       }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new Error(message);
+      await new Promise((r) => setTimeout(r, POLLING_INTERVAL));
     }
   }
 }

package/src/models/routerModel.ts

@@ -1,24 +1,15 @@
 import { DEFAULT_CTX } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
-import { DataProperty, ModelsEndpoint } from "../interfaces/endpoints/models";
+import { ModelsEndpoint } from "../interfaces/endpoints/models";
 import { rpc } from "../tools/retriever";
 import { BaseModel } from "./baseModel";
 
 export class RouterModel extends BaseModel {
-  constructor(protected readonly model: DataProperty) {
-    super(model);
-  }
-
   get mode(): Mode {
     return Mode.ROUTER;
   }
 
-  get capabilities(): ["text"] | ["image"] {
-    const hasImage = this.model.status!.args?.includes("--mmproj") ?? false;
-    return hasImage ? ["image"] : ["text"];
-  }
-
   async getStatus(): Promise<Status> {
     const { data } = await rpc<ModelsEndpoint>("/models");
     const model = data.find((m) => m.id === this.id);
@@ -34,14 +25,28 @@ export class RouterModel extends BaseModel {
     return status;
   }
 
+  async getCapabilities(): Promise<["text"] | ["image"]> {
+    // We can get the real capabilities if the model is already loaded
+    if ((await this.getStatus()) === Status.LOADED) {
+      return super.getCapabilities();
+    }
+
+    const hasImage = this.model.status?.args?.includes("--mmproj") ?? false;
+    return hasImage ? ["image"] : ["text"];
+  }
+
   async getContextSize(): Promise<number> {
-    let response = this.extractFrom("--ctx-size");
-    if (response) return response;
+    // We can get a more accurate context size if the model is already loaded
+    if ((await this.getStatus()) === Status.LOADED) {
+      return super.getContextSize();
+    }
 
-    response = this.extractFrom("--fit-ctx");
-    if (response) return response;
+    const response =
+      this.extractFrom("--ctx-size") ??
+      this.extractFrom("--fit-ctx") ??
+      DEFAULT_CTX;
 
-    return DEFAULT_CTX;
+    return response;
   }
 
   /**

package/src/models/singleModel.ts

@@ -1,31 +1,14 @@
-import { DEFAULT_CTX } from "../constants";
 import { Mode } from "../enums/mode";
 import { Status } from "../enums/status";
-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 {
-  private contextSize?: number;
-
-  constructor(
-    protected readonly model: DataProperty,
-    private readonly extra: ModelProperty,
-  ) {
-    super(model);
-  }
-
   get mode(): Mode {
     return Mode.SINGLE;
   }
 
-  get capabilities(): ["text"] | ["image"] {
-    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");
@@ -33,18 +16,4 @@ export class SingleModel extends BaseModel {
 
     return Status.LOADED;
   }
-
-  async getContextSize(): Promise<number> {
-    // 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 this.contextSize;
-    } catch {
-      return DEFAULT_CTX;
-    }
-  }
 }

package/src/tools/provider.ts

@@ -0,0 +1,28 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PROVIDER_ID, PROVIDER_NAME } from "../constants";
+import type { BaseModel } from "../models/baseModel";
+import { resolveApiKey, resolveUrl } from "./resolver";
+import { listModels } from "./retriever";
+
+/**
+ * Registers the Llama.cpp provider and returns the fetched models.
+ *
+ * @param pi The Pi extension API
+ * @returns The list of models fetched from the server
+ */
+export const registerLlamaCppProvider = async (
+  pi: ExtensionAPI,
+): Promise<BaseModel[]> => {
+  const baseUrl = `${await resolveUrl(process.cwd())}/v1`;
+  const models = await listModels();
+
+  pi.registerProvider(PROVIDER_ID, {
+    name: PROVIDER_NAME,
+    baseUrl,
+    api: "openai-completions",
+    apiKey: await resolveApiKey(),
+    models: await Promise.all(models.map((m) => m.toProviderConfig())),
+  });
+
+  return models;
+};

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 { Auth, AuthFile } from "../interfaces/auth";
+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<AuthFile, Auth | 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/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,289 @@
+import { describe, expect, it, vi } from "vitest";
+import { Mode } from "../src/enums/mode";
+import { DataProperty } from "../src/interfaces/endpoints/models";
+import { RouterModel } from "../src/models/routerModel";
+
+// Mock the retriever module before importing anything that depends on it
+const mockRpc = vi.fn();
+
+vi.mock("../src/tools/retriever", () => ({
+  rpc: (...args: unknown[]) => mockRpc(...args),
+  isServerReady: vi.fn(),
+  listModels: vi.fn(),
+}));
+
+// 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(),
+  status: { value: "loaded", args: [], preset: "default", failed: false },
+  ...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 when loaded", async () => {
+    // First call: getStatus() -> /models
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "loaded", args: ["--model", "gguf", "--ctx-size", "4096", "--fit-ctx", "8192"], preset: "default" },
+        },
+      ],
+    });
+    // Second call: super.getContextSize() -> /models with meta.n_ctx
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          meta: { n_ctx: 4096 },
+        },
+      ],
+    });
+
+    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 and loaded", async () => {
+    // First call: getStatus() -> /models
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "loaded", args: ["--model", "gguf"], preset: "default" },
+        },
+      ],
+    });
+    // Second call: super.getContextSize() -> /models without meta.n_ctx
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+        },
+      ],
+    });
+
+    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 modalities.vision is true", async () => {
+    // getStatus() calls /models first
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "loaded", args: [], preset: "default", failed: false },
+        },
+      ],
+    });
+    // super.getCapabilities() calls /props?model=<id>
+    mockRpc.mockResolvedValueOnce({ modalities: { vision: true } });
+
+    const model = new RouterModel(createModel());
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["image"]);
+    expect(mockRpc).toHaveBeenCalledWith("/props?model=test-model");
+  });
+
+  it("should detect text-only capability when modalities.vision is false", async () => {
+    // getStatus() calls /models first
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "loaded", args: [], preset: "default", failed: false },
+        },
+      ],
+    });
+    // super.getCapabilities() calls /props?model=<id>
+    mockRpc.mockResolvedValueOnce({ modalities: { vision: false } });
+
+    const model = new RouterModel(createModel());
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["text"]);
+  });
+
+  it("should default to text when /props call fails", async () => {
+    // getStatus() calls /models first
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "loaded", args: [], preset: "default", failed: false },
+        },
+      ],
+    });
+    // super.getCapabilities() calls /props?model=<id> which fails
+    mockRpc.mockRejectedValueOnce(new Error("Connection refused"));
+
+    const model = new RouterModel(createModel());
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["text"]);
+  });
+
+  it("should use status.args to detect image capability when not loaded", async () => {
+    // getStatus() calls /models first, returns unloaded
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "unloaded", args: ["--model", "gguf", "--mmproj", "mmproj.gguf"], preset: "default", failed: false },
+        },
+      ],
+    });
+
+    const model = new RouterModel(
+      createModel({
+        status: { value: "unloaded", args: ["--model", "gguf", "--mmproj", "mmproj.gguf"], preset: "default", failed: false },
+      }),
+    );
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["image"]);
+  });
+
+  it("should return text when not loaded and no --mmproj in args", async () => {
+    // getStatus() calls /models first, returns unloaded
+    mockRpc.mockResolvedValueOnce({
+      data: [
+        {
+          id: "test-model",
+          status: { value: "unloaded", args: ["--model", "gguf"], preset: "default", failed: false },
+        },
+      ],
+    });
+
+    const model = new RouterModel(
+      createModel({
+        status: { value: "unloaded", args: ["--model", "gguf"], preset: "default", failed: false },
+      }),
+    );
+    const capabilities = await model.getCapabilities();
+
+    expect(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,140 @@
+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 modalities.vision is true", async () => {
+    mockRpc.mockResolvedValueOnce({ modalities: { vision: true } });
+
+    const model = createModel();
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["image"]);
+    expect(mockRpc).toHaveBeenCalledWith("/props?model=test");
+  });
+
+  it("should detect text-only capability when modalities.vision is false", async () => {
+    mockRpc.mockResolvedValueOnce({ modalities: { vision: false } });
+
+    const model = createModel();
+    const capabilities = await model.getCapabilities();
+
+    expect(capabilities).toEqual(["text"]);
+  });
+
+  it("should return text when /props call fails", async () => {
+    mockRpc.mockRejectedValueOnce(new Error("Connection refused"));
+
+    const model = createModel();
+    const capabilities = await model.getCapabilities();
+
+    expect(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 /models endpoint meta", async () => {
+    mockRpc.mockResolvedValueOnce({
+      data: [{ id: "test", meta: { n_ctx: 8192 } }],
+    });
+
+    const model = createModel();
+    const ctxSize = await model.getContextSize();
+
+    expect(ctxSize).toBe(8192);
+    expect(mockRpc).toHaveBeenCalledWith("/models");
+  });
+
+  it("should return DEFAULT_CTX when model not found in /models", async () => {
+    mockRpc.mockResolvedValueOnce({ data: [] });
+
+    const model = createModel();
+    const ctxSize = await model.getContextSize();
+
+    expect(ctxSize).toBe(DEFAULT_CTX);
+  });
+
+  it("should return DEFAULT_CTX when /models fails", async () => {
+    mockRpc.mockRejectedValueOnce(new Error("Connection refused"));
+
+    const model = createModel();
+    const ctxSize = await model.getContextSize();
+
+    expect(ctxSize).toBe(DEFAULT_CTX);
+  });
+});

package/tsconfig.json

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

package/vitest.config.ts

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

package/src/interfaces/endpoints/slots.ts

@@ -1,15 +0,0 @@
-/**
- * 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>>;
-}