pi-llama-cpp 0.13.0 → 0.14.0

package/src/ui/editors/override/fields.ts

@@ -0,0 +1,294 @@
+import type { ModelCost, ModelCostRates } from "@earendil-works/pi-ai";
+import type { ModelOverride } from "../../../interfaces/settings";
+import { FIELDS, type Field } from "../../strings";
+import { SettingField } from "../settingField";
+import { OverrideEntry } from "./entry";
+
+/** Type of a field: "input" for free-text, "finite" for fixed options */
+export type FieldType = "input" | "finite";
+
+/** Validation function for input fields */
+export type InputValidator = (raw: string) => string | null;
+
+/**
+ * Abstract base class for one editable field of a model override entry
+ * (Template Method): each subclass owns its display format, validation
+ * and apply logic in a single place, so the parse/format round-trips
+ * can't drift. Extends the shared {@link SettingField} base (id, label,
+ * description, placeholder from the FIELDS registry).
+ */
+export abstract class OverrideField extends SettingField<OverrideEntry> {
+  /** Field type: "input" for free-text, "finite" for fixed options. */
+  abstract readonly type: FieldType;
+
+  /**
+   * Canonical display label for this field — the single source of truth
+   * for both the field rows' `currentValue` and the post-commit refresh
+   * of an open field submenu, so the two can't drift.
+   */
+  abstract displayValue(entry: OverrideEntry): string;
+
+  /** Current value shown in the row — same rendering as the post-commit
+   * refresh of an open field submenu, so the two can't drift. */
+  currentValue(entry: OverrideEntry): string {
+    return this.displayValue(entry);
+  }
+
+  /** For "input" fields: validation function for committed values. */
+  abstract readonly validate: InputValidator;
+
+  /** For "finite" fields: the fixed options (undefined for "input"). */
+  readonly options: readonly string[] | undefined = undefined;
+
+  /** Applies a committed value to the override object. The pattern key
+   * rename is handled separately by the mutator. */
+  abstract apply(override: ModelOverride, value: string): void;
+
+  /** One `term: value` part of the entry-row summary (see
+   * {@link OverrideSummary.of}), or `null` when the field shouldn't
+   * appear (unset/zero values — each field decides). The pattern is the
+   * row label, so it never contributes a part; the default is `null`. */
+  summaryPart(_override: ModelOverride): string | null {
+    return null;
+  }
+
+  /** Parses a non-negative number; blank input means zero (unset fields
+   * default to zero at read time). Returns `null` when invalid. Shared
+   * by the cost and numeric fields so their validation can't drift. */
+  protected static parseNonNegative(raw: string): number | null {
+    const n = Number(raw.trim());
+    return isFinite(n) && n >= 0 ? n : null;
+  }
+}
+
+/**
+ * The entry's pattern key. The rename itself is handled by the mutator
+ * (`OverrideEntryMutator`); {@link apply} is a no-op.
+ */
+class PatternField extends OverrideField {
+  readonly id = "pattern";
+  readonly type = "input";
+  readonly field = FIELDS.pattern;
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.pattern;
+  }
+
+  readonly validate: InputValidator = (raw) => {
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  };
+
+  apply(): void {
+    // The pattern IS the map key — renames go through the mutator.
+  }
+}
+
+/**
+ * One `ModelCostRates` key of the override's `cost` object (absorbs the
+ * former `CostFieldDefFactory` and the standalone `parseCostValue` /
+ * `applyCostFieldValue` helpers): owns the cost parse and immutable
+ * apply in the same place as its display format.
+ */
+class CostField extends OverrideField {
+  readonly type = "input";
+  override readonly field: Field;
+
+  constructor(
+    readonly id: string,
+    private readonly key: keyof ModelCostRates,
+    field: Field,
+    /** Short term used in the entry-row summary (e.g. `cache read`). */
+    private readonly summaryTerm: string,
+  ) {
+    super();
+    this.field = field;
+  }
+
+  displayValue(entry: OverrideEntry): string {
+    return String(entry.override.cost?.[this.key] ?? 0);
+  }
+
+  readonly validate: InputValidator = (raw) => {
+    const parsed = OverrideField.parseNonNegative(raw);
+    return parsed === null ? null : String(parsed);
+  };
+
+  apply(override: ModelOverride, value: string): void {
+    const nextCost = this.applyCost(override.cost, Number(value));
+    if (nextCost) override.cost = nextCost;
+    else delete override.cost;
+  }
+
+  /** Returns a copy of `cost` with this field set to `value`. A `0` (or
+   * non-finite) value removes the field — unset cost fields default to
+   * zero at read time — and when no fields remain, returns `undefined`
+   * so the whole `cost` object can be dropped. Immutable. */
+  private applyCost(
+    cost: ModelOverride["cost"],
+    value: number,
+  ): Partial<ModelCost> | undefined {
+    const next = { ...cost };
+    if (isFinite(value) && value > 0) next[this.key] = value;
+    else delete next[this.key];
+    return Object.keys(next).length > 0 ? next : undefined;
+  }
+
+  /** Appears in the summary only when a non-zero cost is set. */
+  override summaryPart(override: ModelOverride): string | null {
+    const value = override.cost?.[this.key];
+    return value ? `${this.summaryTerm}: $${value}` : null;
+  }
+}
+
+/**
+ * Non-negative numeric field (`contextSize`, `maxTokens`): keeps the
+ * display format, validator and apply logic in a single place so the
+ * three can't drift (e.g. the validator accepting `0` while the apply
+ * drops it — unset fields default to zero at read time, so all render
+ * as `0`).
+ */
+class NumericField extends OverrideField {
+  readonly type = "input";
+  override readonly field: Field;
+
+  constructor(
+    readonly id: "maxTokens" | "contextSize",
+    field: Field,
+  ) {
+    super();
+    this.field = field;
+  }
+
+  displayValue(entry: OverrideEntry): string {
+    return String(entry.override[this.id] ?? 0);
+  }
+
+  /** Accepts finite, non-negative numbers (blank means zero). */
+  readonly validate: InputValidator = (raw) => {
+    const n = OverrideField.parseNonNegative(raw);
+    return n === null ? null : String(n);
+  };
+
+  /** Applies the committed value; non-positive values remove the key. */
+  apply(override: ModelOverride, value: string): void {
+    const n = Number(value);
+    if (isFinite(n) && n > 0) override[this.id] = n;
+    else delete override[this.id];
+  }
+
+  /** Appears in the summary only when set. */
+  override summaryPart(override: ModelOverride): string | null {
+    const value = override[this.id];
+    return value === undefined ? null : `${this.id}: ${value}`;
+  }
+}
+
+/** The override's `capabilities` list (finite: fixed label options). */
+class CapabilitiesField extends OverrideField {
+  readonly id = "capabilities";
+  readonly type = "finite";
+  readonly field = FIELDS.capabilities;
+  override readonly options = ["text", "text | image"];
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.override.capabilities?.join(" | ") ?? "text";
+  }
+
+  readonly validate: InputValidator = (raw) =>
+    this.options?.includes(raw) ? raw : null;
+
+  apply(override: ModelOverride, value: string): void {
+    override.capabilities =
+      value === "text | image"
+        ? ["text", "image"]
+        : value === "text"
+          ? ["text"]
+          : undefined;
+  }
+
+  /** Appears in the summary only when non-empty. */
+  override summaryPart(override: ModelOverride): string | null {
+    return override.capabilities?.length
+      ? `capabilities: ${override.capabilities.join(",")}`
+      : null;
+  }
+}
+
+/** The override's `reasoning` flag (finite: true/false, default true). */
+class ReasoningField extends OverrideField {
+  readonly id = "reasoning";
+  readonly type = "finite";
+  readonly field = FIELDS.reasoning;
+  override readonly options = ["true", "false"];
+
+  displayValue(entry: OverrideEntry): string {
+    return entry.override.reasoning === false ? "false" : "true";
+  }
+
+  readonly validate: InputValidator = (raw) =>
+    this.options?.includes(raw) ? raw : null;
+
+  apply(override: ModelOverride, value: string): void {
+    if (value === "true") override.reasoning = true;
+    else if (value === "false") override.reasoning = false;
+    else delete override.reasoning;
+  }
+
+  /** Appears in the summary only when explicitly set. */
+  override summaryPart(override: ModelOverride): string | null {
+    return override.reasoning === undefined
+      ? null
+      : `reasoning: ${override.reasoning}`;
+  }
+}
+
+/** Cost field specs: [ModelCostRates key, FIELDS entry, summary term] */
+const COST_FIELDS: [keyof ModelCostRates, Field, string][] = [
+  ["input", FIELDS.inputCost, "input"],
+  ["output", FIELDS.outputCost, "output"],
+  ["cacheRead", FIELDS.cacheReadCost, "cache read"],
+  ["cacheWrite", FIELDS.cacheWriteCost, "cache write"],
+];
+
+/**
+ * The field registry for model override entries: the complete list of
+ * editable fields (order defines the row order in the settings list)
+ * plus id-based lookup. Throws on an unknown id — the registry is
+ * static, so a miss is a programming error.
+ */
+export class OverrideFields {
+  static readonly all: OverrideField[] = [
+    new PatternField(),
+    ...COST_FIELDS.map(
+      ([key, field, term]) => new CostField(`cost.${key}`, key, field, term),
+    ),
+    new CapabilitiesField(),
+    new ReasoningField(),
+    new NumericField("contextSize", FIELDS.contextSize),
+    new NumericField("maxTokens", FIELDS.maxTokens),
+  ];
+
+  static byId(id: string): OverrideField {
+    const field = this.all.find((f) => f.id === id);
+    if (!field) throw new Error(`Unknown override field: ${id}`);
+    return field;
+  }
+}
+
+/**
+ * Builds the entry-row summary shown in the override entry list
+ * (`input: $0.2, output: $0.6, cache read: $0.01, …`), composed from the
+ * {@link OverrideFields} registry — adding a field to the registry makes
+ * it show up here too, so the summary can't lag the edit menu. Fields
+ * with unset/zero values are omitted for brevity (each field decides via
+ * {@link OverrideField.summaryPart}); `—` when nothing is set.
+ */
+export class OverrideSummary {
+  static of(override: ModelOverride): string {
+    const parts = OverrideFields.all
+      .map((field) => field.summaryPart(override))
+      .filter((part): part is string => part !== null);
+    return parts.length > 0 ? parts.join(", ") : "—";
+  }
+}

package/src/ui/editors/override/handlers.ts

@@ -0,0 +1,118 @@
+import type { LlamaServer, ModelOverride } from "../../../interfaces/settings";
+import { OverrideEntry } from "./entry";
+import { OverrideFields } from "./fields";
+
+/** Result of applying a field change: the next server list and the
+ * updated override for UI refresh. `null` when the entry doesn't exist
+ * (stale index — a no-op). */
+export interface MutationResult {
+  next: LlamaServer[];
+  updatedOverride: ModelOverride;
+}
+
+/**
+ * Applies edits (field commits, entry adds/renames/removals) to the
+ * override entries of a single server, immutably. Binds the server list
+ * and server index once in the constructor so call sites don't juggle
+ * long positional lists.
+ *
+ * Per-field commit behavior lives in the {@link OverrideFields} registry
+ * (`apply` on each field instance) — this class only resolves the field
+ * and the entry, and handles the pattern rename specially.
+ */
+export class OverrideEntryMutator {
+  constructor(
+    private readonly servers: LlamaServer[],
+    private readonly serverIndex: number,
+  ) {}
+
+  /** The server's override entries, in map iteration order. */
+  entries(): OverrideEntry[] {
+    return OverrideEntry.listFrom(this.servers[this.serverIndex]);
+  }
+
+  /** Handles a field commit from an override entry's submenu. Returns
+   * `null` when the entry doesn't exist (stale index — no-op). */
+  applyFieldChange(
+    entryIndex: number,
+    field: string,
+    value: string,
+  ): MutationResult | null {
+    const entry = this.entries()[entryIndex];
+    if (!entry) return null;
+
+    // Pattern field: rename the pattern key, keep the override object
+    if (field === "pattern") {
+      return {
+        next: this.updateEntry(entryIndex, value, entry.override),
+        updatedOverride: entry.override,
+      };
+    }
+
+    // Other fields: let the field definition apply itself
+    const updatedOverride: ModelOverride = { ...entry.override };
+    OverrideFields.byId(field).apply(updatedOverride, value);
+
+    return {
+      next: this.updateEntry(entryIndex, entry.pattern, updatedOverride),
+      updatedOverride,
+    };
+  }
+
+  /** Adds a new override entry with a uniquified pattern. */
+  addEntry(pattern: string, override: ModelOverride = {}): LlamaServer[] {
+    const server = this.servers[this.serverIndex];
+    if (!server) return this.servers;
+
+    const existing = new Set(Object.keys(server.overrides ?? {}));
+    let uniquePattern = pattern;
+    let n = 2;
+    while (existing.has(uniquePattern)) {
+      uniquePattern = `${pattern}-${n++}`;
+    }
+
+    return this.withServer((s) => ({
+      ...s,
+      overrides: { ...s.overrides, [uniquePattern]: override },
+    }));
+  }
+
+  /** Removes the entry at `entryIndex`. */
+  removeEntry(entryIndex: number): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).filter((_, j) => j !== entryIndex),
+      ),
+    }));
+  }
+
+  // -- internal helpers ------------------------------------------------------
+
+  /** Returns the servers with the target server replaced by
+   * `fn(server)`. Immutable. */
+  private withServer(fn: (server: LlamaServer) => LlamaServer): LlamaServer[] {
+    return this.servers.map((server, i) =>
+      i === this.serverIndex ? fn(server) : server,
+    );
+  }
+
+  /** Replaces the entry at `entryIndex` with `pattern → override` in a
+   * single mutation — used both for renaming the pattern and for editing
+   * its fields. The entry keeps its position in the map's iteration
+   * order. Immutable. */
+  private updateEntry(
+    entryIndex: number,
+    pattern: string,
+    override: ModelOverride,
+  ): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).map(([k, v], j) =>
+          j === entryIndex ? [pattern, override] : [k, v],
+        ),
+      ),
+    }));
+  }
+}

package/src/ui/editors/override/itemBuilder.ts

@@ -0,0 +1,42 @@
+import type { SettingItem } from "@earendil-works/pi-tui";
+import { FieldMessages, TITLES } from "../../strings";
+import { ItemBuilder } from "../itemBuilder";
+import { OverrideEntry } from "./entry";
+import { OverrideFields, type OverrideField } from "./fields";
+
+/**
+ * Builds `SettingItem` objects for override entry field submenus.
+ */
+export class OverrideItemBuilder extends ItemBuilder<
+  OverrideEntry,
+  OverrideField
+> {
+  protected get fields(): readonly OverrideField[] {
+    return OverrideFields.all;
+  }
+
+  /**
+   * Adds field-type-specific columns: fixed `values` for "finite" fields,
+   * an `InputDialog` submenu (validating against the field definition)
+   * for "input" fields.
+   */
+  protected decorate(
+    def: OverrideField,
+    entry: OverrideEntry,
+    base: SettingItem,
+  ): SettingItem {
+    if (def.type === "finite") {
+      return { ...base, values: [...(def.options ?? [])] };
+    }
+
+    return {
+      ...base,
+      submenu: this.dialogs.inputSubmenu(
+        TITLES.edit(def.label),
+        FieldMessages.of(def.field),
+        def.placeholder,
+        def.validate,
+      ),
+    };
+  }
+}

package/src/ui/editors/override/overrideList.ts

@@ -0,0 +1,127 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type {
+  Component,
+  Focusable,
+  SettingItem,
+  SettingsList,
+} from "@earendil-works/pi-tui";
+import type { LlamaServer } from "../../../interfaces/settings";
+import type { LlamaSettingsManager } from "../../../managers/settings";
+import { HINTS } from "../../strings";
+import type { OverrideSettingsListOptions } from "../editorOptions";
+import { SettingsListFactory } from "../settingsListFactory";
+import { OverrideEntryListEditor } from "./entryEditor";
+
+/**
+ * Top-level overrides editor: one row per server, Enter drills into
+ * override entries.
+ *
+ * Unlike `ServerSettingsList`, this has no add/delete — just drill-down.
+ *
+ * Within a server's entry list: Enter drills into the field-edit submenu;
+ * a adds, d deletes (after confirmation). Fields use a mix of finite
+ * (Enter to cycle) and infinite (Enter to type) editing:
+ *
+ * - Pattern / costs (input, output, cacheRead, cacheWrite): infinite —
+ *   Enter opens an Input for typing.
+ * - Capabilities: finite — Enter cycles between `text` and `text | image`.
+ * - Reasoning: finite — Enter cycles between `true` and `false`.
+ *
+ * Servers themselves are not managed here — use `/models servers`.
+ */
+export class OverrideSettingsList implements Component, Focusable {
+  private settingsList: SettingsList | null = null;
+  private isFocused = false;
+
+  constructor(private readonly options: OverrideSettingsListOptions) {
+    this.settingsList = this.buildSettingsList();
+  }
+
+  /**
+   * Opens the editor in a modal `ui.custom` dialog seeded with the
+   * current `llamaSettings.servers` and resolves when the user closes
+   * it (Esc). Writes go through `settings.setLlamaSetting()`; write
+   * errors are notified via `ui` and the editor stays open with the
+   * pre-mutation list.
+   */
+  static async show(
+    ui: ExtensionUIContext,
+    settings: LlamaSettingsManager,
+  ): Promise<void> {
+    const servers = await settings.getLlamaServers();
+
+    await ui.custom<void>(
+      (tui, theme, keybindings, done) =>
+        new OverrideSettingsList({
+          tui,
+          theme,
+          keybindings,
+          servers,
+          persist: (next) => settings.setLlamaSetting("servers", next),
+          done: () => done(undefined),
+          onError: (message) => ui.notify(message, "error"),
+          onChanged: () => {}, // no per-change notification needed
+        }),
+    );
+  }
+
+  // -- Component -------------------------------------------------------------
+
+  invalidate(): void {
+    this.settingsList?.invalidate();
+  }
+
+  handleInput(data: string): void {
+    this.settingsList?.handleInput(data);
+  }
+
+  render(width: number): string[] {
+    if (!this.settingsList) return ["Loading..."];
+    return this.settingsList.render(width);
+  }
+
+  // -- Focusable -------------------------------------------------------------
+
+  get focused(): boolean {
+    return this.isFocused;
+  }
+
+  set focused(value: boolean) {
+    // `SettingsList` has no `focused` flag — the flag is ours alone
+    this.isFocused = value;
+  }
+
+  // -- internal --------------------------------------------------------------
+
+  private buildSettingsList(): SettingsList {
+    const serverItems: SettingItem[] = this.options.servers.map(
+      (server, i) => ({
+        id: `server-${i}`,
+        label: server.url,
+        description: HINTS.overrideServerRow,
+        currentValue: OverrideSettingsList.entriesLabel(server),
+        submenu: (_cv, done) =>
+          new OverrideEntryListEditor(this.options, i, () => {
+            // Entry count may have changed (add/delete/pattern rename)
+            const current = this.options.servers[i];
+            serverList?.updateValue(
+              `server-${i}`,
+              OverrideSettingsList.entriesLabel(current),
+            );
+            done();
+          }),
+      }),
+    );
+
+    let serverList: SettingsList | null = null;
+    serverList = SettingsListFactory.create(serverItems, () => {
+      this.options.done();
+    });
+    return serverList;
+  }
+
+  /** Row summary for a server in the list: its override entry count. */
+  private static entriesLabel(server: LlamaServer | undefined): string {
+    return `${Object.keys(server?.overrides ?? {}).length} entries`;
+  }
+}

package/src/ui/editors/server/builder.ts

@@ -0,0 +1,60 @@
+import type { LlamaServer } from "../../../interfaces/settings";
+
+/**
+ * Builder for `LlamaServer` objects, centralizing the "empty string means
+ * omit the key" rule for the optional `id` and `name` fields — the single
+ * place where that invariant lives, shared by the add-server wizard's
+ * final step and by field commits on existing servers.
+ *
+ * Start from an existing server with {@link from}, chain the setters,
+ * then call {@link build}. Immutable with respect to the input: the
+ * source server is never mutated.
+ */
+export class LlamaServerBuilder {
+  private constructor(private data: LlamaServer) {}
+
+  /** Starts a builder from an existing server (also used to start a
+   * fresh `{ url }` server in the wizard flow). */
+  static from(server: LlamaServer): LlamaServerBuilder {
+    return new LlamaServerBuilder({ ...server });
+  }
+
+  /** Sets the URL (always present, never omitted). */
+  url(url: string): this {
+    this.data = { ...this.data, url };
+    return this;
+  }
+
+  /**
+   * Sets the custom provider ID. An empty value omits the key — when
+   * editing an existing server this removes it, restoring the
+   * URL-based auto-detected ID.
+   */
+  optionalId(id: string): this {
+    this.data = this.withOptional("id", id);
+    return this;
+  }
+
+  /**
+   * Sets the display name. An empty value omits the key — when editing
+   * an existing server this removes it.
+   */
+  optionalName(name: string): this {
+    this.data = this.withOptional("name", name);
+    return this;
+  }
+
+  /** Returns the built server. */
+  build(): LlamaServer {
+    return this.data;
+  }
+
+  /** Copies `data`, setting `key` to `value` when non-empty and
+   * removing the key otherwise. */
+  private withOptional(key: "id" | "name", value: string): LlamaServer {
+    const next = { ...this.data };
+    if (value.length > 0) next[key] = value;
+    else delete next[key];
+    return next;
+  }
+}