pi-llama-cpp 0.10.0 → 0.12.0

package/README.md

@@ -61,6 +61,18 @@ The recommended way to configure the extension is using the `llamaSettings` key.
 
 Add this to your `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (global):
 
+#### Minimal configuration
+
+```json
+{
+  "llamaSettings": {
+    "servers": [{ "url": "http://127.0.0.1:8080" }]
+  }
+}
+```
+
+#### Full configuration
+
 ```json
 {
   "llamaSettings": {
@@ -68,7 +80,8 @@ Add this to your `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (g
       {
         "url": "http://127.0.0.1:8080",
         "id": "local",
-        "name": "Local Server"
+        "name": "Local Server",
+        "overrides": {}
       },
       {
         "url": "http://10.0.0.5:8080",
@@ -77,6 +90,7 @@ Add this to your `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (g
     ],
     "reactToModelSelect": true,
     "autoloadOnMessage": false,
+    "sortBy": "asc",
     "pollingTimeout": 60000,
     "serverTimeout": 1000
   }
@@ -91,7 +105,7 @@ With this config, the servers will appear in Pi as **Llama.cpp (Local Server)**
 | ------ | ------ | -------- | ---------------------------------------------------------------------------- |
 | `url`  | string | Yes      | The URL of the llama.cpp server                                              |
 | `id`   | string | No       | Custom provider ID (used for API key auth). Defaults to `llama-server=<url>` |
-| `name` | string | No       | Display name for the server in the UI (shown as `Llama.cpp — <name>`)        |
+| `name` | string | No       | Display name for the server in the UI (shown as `Llama.cpp (<name>)`)        |
 
 > **Note:** If you set a custom `id`, you can use it in `~/.pi/agent/auth.json`. The extension will also fall back to the URL-based ID if no key is found for the custom `id`.
 
@@ -101,11 +115,32 @@ With this config, the servers will appear in Pi as **Llama.cpp (Local Server)**
 | -------------------- | ------- | ------- | ------------------------------------------------------------- |
 | `reactToModelSelect` | boolean | `true`  | Load the model when you switch via Pi's model picker.         |
 | `autoloadOnMessage`  | boolean | `false` | Automatically load an unloaded model before sending a message |
+| `sortBy`             | string  | `"asc"` | Sort order for models (see below)                             |
 | `pollingTimeout`     | number  | `60000` | Max time (ms) to wait for model loading before giving up      |
 | `serverTimeout`      | number  | `1000`  | Timeout (ms) for server health checks and SSE probes          |
 
 > **Note:** `serverTimeout` controls individual HTTP request timeouts (health checks, SSE probe). `pollingTimeout` controls the total wait time for a model to finish loading. Increase `serverTimeout` for slow/high-latency servers, and `pollingTimeout` for large models or slow hardware.
 
+#### In-session settings menu
+
+Run `/models settings` to edit the scalar settings above without hand-editing JSON. Changes are written to the **project** `.pi/settings.json` if it exists, otherwise to **global** `~/.pi/agent/settings.json`. Boolean and sort changes apply immediately; timeout changes apply on the next model load. The `servers` list is edited with `/models servers` (see below), and per-server model overrides with `/models overrides` (see [Model Overrides](#model-overrides)).
+
+#### Server list editor
+
+Run `/models servers` to add, edit or remove entries of `llamaSettings.servers`
+without hand-editing JSON. Each change is written immediately to the **project**
+`.pi/settings.json` if it exists, otherwise to **global**
+`~/.pi/agent/settings.json`.
+
+Changes take effect immediately after closing the editor: new servers
+register their providers, removed ones leave pi's registry right away,
+and edited ones are re-registered with the fresh config — no restart or
+`/models` needed.
+
+Limitation: a model already loading in the background on a removed or
+edited server finishes loading, but its progress notifications stop;
+re-select it from the (new) provider afterwards.
+
 #### Environment variable
 
 For a quick setup, you can use the `LLAMA_SERVER_URL` environment variable instead of the JSON config:
@@ -200,6 +235,7 @@ llama-server --model path/to/model.gguf ...
 
 The extension determines the context size as follows:
 
+- A per-model `contextSize` override (see [Model Overrides](#model-overrides)) takes precedence over everything below
 - **Router mode**
   - When loaded, reads `meta.n_ctx` from the `/v1/models` endpoint
   - When not loaded, reads `--ctx-size` and/or `--fit-ctx` from the server arguments (which can also originate from the **presets.ini** file the llama.cpp server uses to load its models).
@@ -209,11 +245,14 @@ The extension determines the context size as follows:
 
 ### Commands
 
-| Command          | Description                                                                        |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| `/models`        | Browse your models with live status. Select a model to load, switch, or unload it. |
-| `/models info`   | Show detailed information for all available models at once.                        |
-| `/models unload` | Unload all loaded models at once.                                                  |
+| Command             | Description                                                                             |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| `/models`           | Browse your models with live status. Select a model to load, switch, or unload it.      |
+| `/models info`      | Show detailed information for all available models at once.                             |
+| `/models unload`    | Unload all loaded models at once.                                                       |
+| `/models settings`  | Open a menu to edit the scalar `llamaSettings` fields.                                  |
+| `/models servers`   | Add, edit or remove llama.cpp server URLs via a TUI editor.                             |
+| `/models overrides` | Edit per-server model overrides (`llamaSettings.servers[].overrides`) via a TUI editor. |
 
 > **Note:** When a llama.cpp server is slow to respond, it will be skipped at startup with a warning. Run `/models` to retry without timeout and see all models.
 
@@ -221,6 +260,19 @@ The extension determines the context size as follows:
 
 > **Note:** The `/models unload` command only makes sense in router mode.
 
+#### Model sorting
+
+The order of models in the `/models` menu is controlled by the `sortBy` setting.
+Servers maintain their order from `llamaSettings`; sorting applies **within each server**:
+
+| Value         | Description                                                                                                               |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `"asc"`       | Sort by model ID ascending (default)                                                                                      |
+| `"desc"`      | Sort by model ID descending                                                                                               |
+| `"asc-name"`  | Sort by model name ascending (ties broken by ID)                                                                          |
+| `"desc-name"` | Sort by model name descending (ties broken by ID)                                                                         |
+| `"api"`       | No sorting — models appear in the order returned by each server's `/v1/models` endpoint, servers in `llamaSettings` order |
+
 ### Model Actions
 
 When browsing models via the `/models` command, you can:
@@ -266,6 +318,129 @@ User-defined budgets can override the defaults by adding a `thinkingBudgets` obj
 Only `minimal`, `low`, `medium`, `high` and `xhigh` are configurable — `off` (0) and `max` (-1, unlimited) are fixed.
 The extension automatically injects the appropriate `thinking_budget_tokens` into each request payload based on the selected level.
 
+### Model Overrides
+
+A locally-run `llama.cpp` server is free, but you can simulate costs for budgeting, experimentation, or comparison purposes — and fine-tune what the extension reports about each model.
+
+This extension supports **per-model, per-server configuration** via the `overrides` key inside each server entry of `llamaSettings.servers`. Each entry can override the model's `cost`, `capabilities`, `reasoning`, `contextSize`, `maxTokens`, and `compat`, regardless of what the server reports.
+
+Add overrides to your server configuration:
+
+```json
+{
+  "llamaSettings": {
+    "servers": [
+      {
+        "url": "http://127.0.0.1:8080",
+        "overrides": {
+          "qwen-3.8-27b": {
+            "cost": { "input": 0.42, "output": 3.0, "cacheRead": 0.085 }
+          },
+          "glm-5.3-flash": {
+            "cost": { "input": 0.15, "output": 0.5, "cacheRead": 0.03 },
+            "capabilities": ["text"],
+            "reasoning": false,
+            "contextSize": 32768,
+            "maxTokens": 4096
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+Every field of an override is optional — absent fields fall back to what the extension detects (`capabilities`) or to its defaults (`reasoning: true`, zeroed cost).
+
+#### Override editor
+
+Run `/models overrides` to edit a server's override entries without hand-editing
+JSON. It opens a settings menu (same UX as `/models settings`).
+
+Each change is written immediately to the **project**
+`.pi/settings.json` if it exists, otherwise to **global**
+`~/.pi/agent/settings.json`.
+
+Overrides take effect on the next provider request after closing the editor —
+no `/reload` needed.
+
+#### Cost Fields
+
+Inside an override, the `cost` object accepts:
+
+| Field        | Type   | Description                         |
+| ------------ | ------ | ----------------------------------- |
+| `input`      | number | Cost per million input tokens       |
+| `output`     | number | Cost per million output tokens      |
+| `cacheRead`  | number | Cost per million cache read tokens  |
+| `cacheWrite` | number | Cost per million cache write tokens |
+
+All four fields are optional — unspecified fields default to zero.
+In the override editor, entering `0` (or leaving a field empty) removes the field from the settings — and the `cost` object itself once no fields remain — with the same effect as leaving it unset.
+
+#### Other Fields
+
+| Field          | Type             | Description                                                                                    |
+| -------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
+| `capabilities` | array of strings | Pi capabilities for the model (`"text"`, `"image"`). Fully replaces the detected capabilities. |
+| `reasoning`    | boolean          | Whether the model is a reasoning model. Defaults to `true` when absent.                        |
+| `contextSize`  | number           | Override the model's context size in tokens. Falls back to autodetection when absent or `0`.   |
+| `maxTokens`    | number           | Override max generation tokens. Falls back to context size when absent or `0`.                 |
+| `compat`       | object           | OpenAI-compatible provider compatibility settings (see below).                                 |
+
+#### Compatibility (`compat`)
+
+The `compat` field accepts any subset of [OpenAI-compatible provider compatibility settings](https://github.com/earendil-works/pi/blob/main/packages/ai/src/types.ts) used by the `openai-completions` API. These control how the extension talks to your server — for example, disabling `developer` role support, choosing the thinking format, enabling Anthropic-style cache control, or setting thinking token budgets.
+
+Example:
+
+```json
+{
+  "llamaSettings": {
+    "servers": [
+      {
+        "url": "http://127.0.0.1:8080",
+        "overrides": {
+          "llama-3": {
+            "compat": {
+              "supportsDeveloperRole": false,
+              "thinkingFormat": "openai",
+              "thinkingTokenBudgetField": "thinking_budget_tokens"
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Prefix matching
+
+Override keys are treated as **prefix filters** — a model ID matches if it starts with the key. When multiple patterns match, the **longest (most specific) match wins**. This lets you define broad patterns at the top of your overrides and override them with more specific ones below.
+
+Example:
+
+```json
+{
+  "llama": { "cost": { "input": 0.01, "output": 0.02 } },
+  "llama-3": { "reasoning": false },
+  "llama-3-8b": { "cost": { "input": 0.2, "output": 0.6 } }
+}
+```
+
+| Model ID      | Matching keys                    | Winner (longest) | Effective override                                     |
+| ------------- | -------------------------------- | ---------------- | ------------------------------------------------------ |
+| `llama-3-8b`  | `llama`, `llama-3`, `llama-3-8b` | `llama-3-8b`     | `{ cost: { input: 0.2, output: 0.6 } }`                |
+| `llama-3-70b` | `llama`, `llama-3`               | `llama-3`        | `{ reasoning: false }`                                 |
+| `mistral-7b`  | `llama` (no)                     | none             | defaults (zero cost, detected caps, `reasoning: true`) |
+
+> **Note:** Exact model IDs still work — they are simply the longest possible prefix for themselves. Empty keys are silently ignored.
+
+Model matching uses this prefix system — the model ID must start with the override key for a match.
+
+> **Note:** Overrides are resolved through the same settings merge logic (project overrides global), so they follow the same precedence chain as other server settings. If the same URL appears multiple times with different `overrides`, only the first one's overrides will be used (consistent with existing dedup behavior).
+
 ### Model Selection Event
 
 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.
@@ -288,9 +463,11 @@ If loading takes longer than **60 seconds** (configurable via `pollingTimeout`),
 
 Each model exposed to Pi includes the following defaults:
 
-- **`maxTokens`** — dynamically set to the model's context window (detected from llama-server)
-- **`reasoning`** — `true` (assumed, as llama.cpp's `/v1/models` endpoint does not expose it)
-- **`cost`** — all zero (local models)
+- **`contextWindow`** — detected from llama-server (see how the extension determines the context size above); can be overridden per-model via `llamaSettings.servers[].overrides` (see [Model Overrides](#model-overrides))
+- **`maxTokens`** — dynamically set to the model's context window (detected from llama-server); can be overridden per-model via `llamaSettings.servers[].overrides` (see [Model Overrides](#model-overrides))
+- **`reasoning`** — `true` by default (llama.cpp's `/v1/models` endpoint does not expose it); can be overridden per-model via `llamaSettings.servers[].overrides` (see [Model Overrides](#model-overrides))
+- **`cost`** — all zero by default; can be customized per-model via `llamaSettings.servers[].overrides` (see [Model Overrides](#model-overrides))
+- **`compat`** — OpenAI-compatible provider compatibility settings; can be set per-model via `llamaSettings.servers[].overrides` (see [Model Overrides](#model-overrides))
 
 ## Dependencies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-llama-cpp",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Pi extension for llama.cpp integration. Supports router, single and legacy models. Supports multiple servers.",
   "keywords": [
     "pi",
@@ -32,14 +32,14 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.0",
-    "@earendil-works/pi-coding-agent": ">=0.84.0",
-    "@earendil-works/pi-tui": ">=0.84.0"
+    "@earendil-works/pi-ai": ">=0.85.1",
+    "@earendil-works/pi-coding-agent": ">=0.85.1",
+    "@earendil-works/pi-tui": ">=0.85.1"
   },
   "type": "module",
   "devDependencies": {
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   }
 }

package/src/api/client.ts

@@ -1,13 +1,29 @@
 import { POLLING_INTERVAL } from "../constants";
-import { Cache } from "../utils/cache";
-import { Mutex } from "../utils/mutex";
 
 /**
- * HTTP client for llama-server with caching and deduplication.
+ * How long GET responses stay cached: half the polling interval, so a poll
+ * tick always reaches the server while multiple reads within one tick
+ * (fan-outs like `toProviderConfig`, concurrent model polls) do not.
+ */
+const CACHE_TTL = POLLING_INTERVAL / 2;
+
+/**
+ * HTTP client for llama-server with GET caching and request deduplication.
+ *
+ * Two complementary mechanisms keep repeated reads from reaching the server:
+ * - the TTL cache absorbs time-spaced repeats (poll loops, sequential reads);
+ * - the in-flight map absorbs simultaneous bursts: concurrent callers for the
+ *   same key share one request's promise.
+ *
+ * POST requests are deduplicated but never cached — they are not idempotent
+ * reads, and the only caller (`Server.postRequest()`) clears the cache around
+ * them. The dedup matters: independent load triggers (command, auto-load,
+ * model-select) can race, and merging their duplicate `POST /models/load`
+ * into one server call avoids load-state glitches.
  */
 export class ApiClient {
-  private cache = new Cache(POLLING_INTERVAL / 2);
-  private mutex = new Mutex();
+  private cache = new Map<string, { data: unknown; timestamp: number }>();
+  private inflight = new Map<string, Promise<unknown>>();
 
   /**
    * Creates a new ApiClient.
@@ -22,40 +38,34 @@ export class ApiClient {
 
   /**
    * Makes a cached, deduplicated GET request to the llama-server.
-   * Results are cached for half the polling interval and in-flight requests are deduplicated.
    *
    * @param endpoint The endpoint path to fetch (e.g. "/health")
    * @returns The parsed JSON response from the server
    */
   async get<T>(endpoint: string): Promise<T> {
-    const cached = this.cache.get<T>(endpoint);
+    const cached = this.cacheGet<T>(endpoint);
     if (cached !== undefined) return cached;
 
-    return this.mutex.getOrCreate(endpoint, async () => {
-      const data = (await this.do_get<T>(endpoint)) as T;
-      this.cache.set(endpoint, data);
+    return this.dedupe(endpoint, async () => {
+      const data = await this.do_get<T>(endpoint);
+      this.cacheSet(endpoint, data);
       return data;
     });
   }
 
   /**
-   * Makes a cached, deduplicated POST request to the llama-server.
-   * Results are cached for half the polling interval and in-flight requests are deduplicated.
+   * Makes a deduplicated POST request to the llama-server.
+   * Concurrent duplicate requests share one server call; responses are
+   * never cached.
    *
    * @param endpoint The endpoint path to post to
    * @param body The optional request body
    * @returns The parsed JSON response from the server
    */
   async post<T>(endpoint: string, body?: Record<string, unknown>): Promise<T> {
-    const key = this.cacheKey(endpoint, body);
-    const cached = this.cache.get<T>(key);
-    if (cached !== undefined) return cached;
-
-    return this.mutex.getOrCreate(key, async () => {
-      const data = (await this.do_post<T>(endpoint, body)) as T;
-      this.cache.set(key, data);
-      return data;
-    });
+    return this.dedupe(this.cacheKey(endpoint, body), async () =>
+      this.do_post<T>(endpoint, body),
+    );
   }
 
   /**
@@ -65,6 +75,51 @@ export class ApiClient {
     this.cache.clear();
   }
 
+  /**
+   * Runs `fn` for the given key, or returns an existing in-flight promise.
+   * Concurrent callers for the same key share the same promise.
+   */
+  private dedupe<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const existing = this.inflight.get(key);
+    if (existing) return existing as Promise<T>;
+
+    const promise = fn().finally(() => {
+      this.inflight.delete(key);
+    });
+    this.inflight.set(key, promise);
+    return promise;
+  }
+
+  /**
+   * Gets a cached GET response. Returns `undefined` if missing or expired.
+   */
+  private cacheGet<T>(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+    if (Date.now() - entry.timestamp > CACHE_TTL) {
+      this.cache.delete(key);
+      return undefined;
+    }
+    return entry.data as T;
+  }
+
+  /**
+   * Stores a GET response in the cache with the current timestamp.
+   */
+  private cacheSet(key: string, data: unknown): void {
+    this.cache.set(key, { data, timestamp: Date.now() });
+  }
+
+  /**
+   * Builds the dedup key for a POST request.
+   *
+   * @param endpoint The endpoint path to post to
+   * @param body The optional request body
+   */
+  private cacheKey(endpoint: string, body?: Record<string, unknown>): string {
+    return body ? `${endpoint}:${JSON.stringify(body)}` : endpoint;
+  }
+
   /**
    * Makes a raw GET request to the llama-server.
    * This bypasses caching and deduplication.
@@ -107,15 +162,4 @@ export class ApiClient {
 
     return res.json();
   }
-
-  /**
-   * Sets a cache key
-   *
-   * @param endpoint The endpoint path to post to
-   * @param body The optional request body
-   * @returns The cache key
-   */
-  private cacheKey(endpoint: string, body?: Record<string, unknown>): string {
-    return body ? `${endpoint}:${JSON.stringify(body)}` : endpoint;
-  }
 }

package/src/constants.ts

@@ -3,6 +3,11 @@
  */
 export const PROVIDER_PREFIX = "llama-server";
 
+/**
+ * The settings key used in project/global settings.
+ */
+export const SETTINGS_KEY = "llamaSettings";
+
 /**
  * This provider's name
  */
@@ -58,6 +63,16 @@ export const REACT_TO_MODEL_SELECT = true;
  */
 export const AUTOLOAD_ON_MESSAGE = false;
 
+/**
+ * Default sort order for model lists.
+ */
+export const SORT_BY = "asc";
+
+/**
+ * Sort order options for model lists.
+ */
+export type SortBy = "asc" | "desc" | "asc-name" | "desc-name" | "api";
+
 /**
  * Thinking budgets to send to the server, depending on user-selected level in Pi.
  */

package/src/index.ts

@@ -14,11 +14,9 @@ import { ServerManager } from "./managers/server";
 import { settings } from "./managers/settings";
 
 export default async function (pi: ExtensionAPI) {
-  const servers = await settings.resolveServers();
-
-  const eventManager = new EventManager(servers);
-  const serverManager = new ServerManager(servers);
-  const commandManager = new CommandManager(serverManager);
+  const serverManager = new ServerManager(settings);
+  const eventManager = new EventManager(serverManager, settings);
+  const commandManager = new CommandManager(serverManager, settings);
 
   // Register providers once at startup
   await serverManager.initialize(pi);

package/src/interfaces/events.ts

@@ -1,3 +1,14 @@
-export interface ModelSelectEvent {
-  model: { id: string; provider: string };
-}
+import type { ExtensionEvent } from "@earendil-works/pi-coding-agent";
+
+/**
+ * pi-coding-agent does not re-export its `ModelSelectEvent` from the public
+ * API (it exists in the internal extensions/index but is omitted from the
+ * root re-export list, and the package's `exports` map blocks deep imports).
+ * It is therefore derived from the exported `ExtensionEvent` union, which
+ * yields pi's real event shape (`model: Model<any>`, `previousModel`,
+ * `source`) and tracks the API automatically.
+ */
+export type ModelSelectEvent = Extract<
+  ExtensionEvent,
+  { type: "model_select" }
+>;

package/src/interfaces/server.ts

@@ -0,0 +1,27 @@
+import type { ModelOverride } from "./settings";
+
+/**
+ * Identity of a llama.cpp server endpoint.
+ *
+ * Persisted counterpart: {@link LlamaServer} (`llamaSettings.servers`),
+ * whose `url`/`id`/`name` map onto these fields.
+ */
+export interface ServerOptions {
+  /**
+   * Base URL of the llama.cpp server (e.g. "http://127.0.0.1:8080").
+   */
+  baseUrl: string;
+  /**
+   * Custom provider ID; falls back to a URL-based one.
+   */
+  customId?: string;
+  /**
+   * Custom provider name suffix; falls back to the base URL.
+   */
+  customName?: string;
+  /**
+   * Per-model overrides resolved from `llamaSettings.servers`. See
+   * {@link ModelOverride} for the fallback semantics of each field.
+   */
+  overrides?: Record<string, ModelOverride>;
+}

package/src/interfaces/settings.ts

@@ -1,7 +1,47 @@
+import type { ModelCost, OpenAICompletionsCompat } from "@earendil-works/pi-ai";
+import type { SortBy } from "../constants";
+
+/**
+ * Per-model overrides applied on top of what llama-server reports.
+ * Every field is optional — absent fields fall back to detection/defaults.
+ */
+export interface ModelOverride {
+  /**
+   * Per-model token pricing. All four cost fields are optional —
+   * unspecified fields default to zero.
+   */
+  cost?: Partial<ModelCost>;
+  /**
+   * Pi capabilities for the model. When present, **fully replaces** the
+   * capabilities detected from the server (no merging).
+   */
+  capabilities?: ("text" | "image")[];
+  /**
+   * Whether the model is a reasoning model. When absent, defaults to `true`.
+   */
+  reasoning?: boolean;
+  /**
+   * Override the model's context size (in tokens), replacing the value
+   * autodetected from the server. When absent or `0`, falls back to
+   * detection (then `FALLBACK_CTX`).
+   */
+  contextSize?: number;
+  /**
+   * Override the maximum number of tokens the model can generate. When
+   * absent, falls back to the context size detected from the server.
+   */
+  maxTokens?: number;
+  /**
+   * OpenAI-compatible provider compatibility settings. Merged with any
+   * provider-level compat when the model is registered with Pi.
+   */
+  compat?: Partial<OpenAICompletionsCompat>;
+}
+
 /**
  * A description of a server in the "llamaSettings" key
  */
-interface LlamaServer {
+export interface LlamaServer {
   /**
    * The URL of the llama.cpp server.
    */
@@ -14,6 +54,33 @@ interface LlamaServer {
    * Custom display name for this server.
    */
   name?: string;
+  /**
+   * Per-model overrides for this server. Keys are **prefix filters** —
+   * a model ID matches if it starts with the key. When multiple patterns
+   * match, the **longest (most specific) match wins**.
+   *
+   * All fields of an override are optional — absent fields fall back to
+   * detection (`capabilities`) or defaults (`reasoning: true`, zero costs).
+   *
+   * Example:
+   * ```json
+   * {
+   *   "llama": { "cost": { "input": 0.01, "output": 0.02 } },
+   *   "llama-3": { "reasoning": false },
+   *   "llama-3-8b": {
+   *     "cost": { "input": 0.2, "output": 0.6, "cacheRead": 0.01 },
+   *     "capabilities": ["text", "image"]
+   *   }
+   * }
+   * ```
+   *
+   * For model `"llama-3-8b"`:
+   * - `"llama"` matches → cost `{ input: 0.01, output: 0.02 }`
+   * - `"llama-3"` matches → reasoning `false`
+   * - `"llama-3-8b"` matches → cost + capabilities fully replaced
+   * - **Winner**: `"llama-3-8b"` (longest match)
+   */
+  overrides?: Record<string, ModelOverride>;
 }
 
 /**
@@ -29,14 +96,16 @@ interface LlamaServer {
  *   }],
  *   "reactToModelSelect": true
  *   "autoloadOnMessage": false
+ *   "sortBy": "asc"
  * }
 }
  */
 export interface LlamaSettings {
   /**
    * List of servers to connect to.
+   * @default []
    */
-  servers: LlamaServer[];
+  servers?: LlamaServer[];
   /**
    * Whether to react to model selection events by loading the model.
    * @default true
@@ -57,4 +126,9 @@ export interface LlamaSettings {
    * @default 1000
    */
   serverTimeout?: number;
+  /**
+   * How to sort models in the /models command.
+   * @default "asc"
+   */
+  sortBy?: SortBy;
 }