pi-better-model-select 0.1.3

package/extensions/lib/picker.ts

@@ -0,0 +1,261 @@
+// The /bms picker: a filter Input stacked on a SelectList.
+//
+// Typing always goes to the search box, so plain letters can never be stolen
+// as action shortcuts. Actions are therefore ctrl-chords, which stay reachable
+// while the cursor sits in the search field.
+
+import {
+  Container,
+  fuzzyFilter,
+  Input,
+  matchesKey,
+  SelectList,
+  type Focusable,
+  type SelectItem,
+  type SelectListTheme,
+  Text,
+} from "@earendil-works/pi-tui";
+import { loadUsage, usageKey, type ModelsConfig } from "./store.ts";
+
+export type PickerAction =
+  | { kind: "load"; provider: string; modelId: string }
+  | { kind: "add" }
+  | { kind: "update"; provider?: string; modelId?: string }
+  | { kind: "delete"; provider?: string; modelId?: string }
+  | { kind: "reset" }
+  | { kind: "close" };
+
+export interface RankedModel {
+  provider: string;
+  modelId: string;
+  label: string;
+  count: number;
+  lastUsed: number;
+  contextWindow?: number;
+  reasoning: boolean;
+}
+
+/**
+ * Rank models by usage: most-selected first, ties broken by most-recent, then
+ * alphabetically so the order is stable for never-used models.
+ */
+export function rankModels(config: ModelsConfig): RankedModel[] {
+  const stats = loadUsage();
+  const rows: RankedModel[] = [];
+  for (const [provider, entry] of Object.entries(config.providers ?? {})) {
+    for (const m of entry.models ?? []) {
+      const key = usageKey(provider, m.id);
+      rows.push({
+        provider,
+        modelId: m.id,
+        label: m.name ?? m.id,
+        count: stats.counts[key] ?? 0,
+        lastUsed: stats.lastUsed[key] ?? 0,
+        contextWindow: m.contextWindow,
+        reasoning: Boolean(m.reasoning),
+      });
+    }
+  }
+  rows.sort((a, b) => {
+    if (b.count !== a.count) return b.count - a.count;
+    if (b.lastUsed !== a.lastUsed) return b.lastUsed - a.lastUsed;
+    return a.label.localeCompare(b.label);
+  });
+  return rows;
+}
+
+function formatContext(n?: number): string {
+  if (!n) return "";
+  return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+
+export function toSelectItem(row: RankedModel): SelectItem {
+  const bits: string[] = [row.modelId, `[${row.provider}]`];
+  const ctxLabel = formatContext(row.contextWindow);
+  if (ctxLabel) bits.push(`ctx ${ctxLabel}`);
+  if (row.reasoning) bits.push("reasoning");
+  if (row.count > 0) bits.push(`used ${row.count}x`);
+  return {
+    value: `${row.provider}\u0000${row.modelId}`,
+    label: row.label,
+    description: bits.join("  •  "),
+  };
+}
+
+export function decodeValue(value: string): { provider: string; modelId: string } | null {
+  const idx = value.indexOf("\u0000");
+  if (idx < 0) return null;
+  return { provider: value.slice(0, idx), modelId: value.slice(idx + 1) };
+}
+
+export function selectListTheme(theme: any): SelectListTheme {
+  const fg =
+    typeof theme?.fg === "function"
+      ? (role: string, t: string) => theme.fg(role, t)
+      : (_role: string, t: string) => t;
+  return {
+    selectedPrefix: (t: string) => fg("accent", t),
+    selectedText: (t: string) => fg("accent", t),
+    description: (t: string) => fg("muted", t),
+    scrollInfo: (t: string) => fg("dim", t),
+    noMatch: (t: string) => fg("warning", t),
+  };
+}
+
+const HINT =
+  "↑↓ move  •  enter load  •  ctrl+a add  •  ctrl+u update  •  ctrl+x delete  •  ctrl+r reset stats  •  esc close";
+
+export class ModelPicker extends Container implements Focusable {
+  private search: Input;
+  private list: SelectList;
+  private rows: RankedModel[];
+  private filtered: RankedModel[];
+  private hintText: Text;
+  private countText: Text;
+  // Plain fields rather than constructor parameter properties, so the source
+  // also loads under type-stripping runtimes that reject that syntax.
+  private theme: any;
+  private onChange: () => void;
+  private done: (action: PickerAction) => void;
+
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  // Propagate focus to the Input so the hardware cursor lands correctly for IME.
+  set focused(value: boolean) {
+    this._focused = value;
+    this.search.focused = value;
+  }
+
+  constructor(
+    rows: RankedModel[],
+    theme: any,
+    onChange: () => void,
+    done: (action: PickerAction) => void,
+  ) {
+    super();
+    this.theme = theme;
+    this.onChange = onChange;
+    this.done = done;
+    this.rows = rows;
+    this.filtered = rows;
+
+    const fg =
+      typeof theme?.fg === "function"
+        ? (role: string, t: string) => theme.fg(role, t)
+        : (_role: string, t: string) => t;
+
+    this.search = new Input({
+      prompt: "  search ",
+      placeholder: "type to filter by name, id or provider…",
+      placeholderStyle: (t: string) => fg("dim", t),
+    });
+    this.search.onEscape = () => this.done({ kind: "close" });
+    this.search.onSubmit = () => this.loadSelected();
+
+    this.list = this.buildList(rows);
+
+    this.countText = new Text(fg("dim", this.countLabel()), 1, 0);
+    this.hintText = new Text(fg("dim", HINT), 1, 0);
+
+    this.addChild(this.search);
+    this.addChild(this.list);
+    this.addChild(this.countText);
+    this.addChild(this.hintText);
+  }
+
+  /** SelectList has no public API to replace its items, so rebuild it. */
+  private buildList(rows: RankedModel[]): SelectList {
+    const list = new SelectList(
+      rows.map(toSelectItem),
+      Math.min(Math.max(rows.length, 1), 12),
+      selectListTheme(this.theme),
+    );
+    list.onSelect = () => this.loadSelected();
+    list.onCancel = () => this.done({ kind: "close" });
+    return list;
+  }
+
+  private countLabel(): string {
+    const total = this.rows.length;
+    const shown = this.filtered.length;
+    return shown === total ? `${total} models` : `${shown} of ${total} models`;
+  }
+
+  private currentRow(): RankedModel | null {
+    const item = this.list.getSelectedItem();
+    if (!item) return null;
+    const decoded = decodeValue(item.value);
+    if (!decoded) return null;
+    return (
+      this.filtered.find(
+        (r) => r.provider === decoded.provider && r.modelId === decoded.modelId,
+      ) ?? null
+    );
+  }
+
+  private loadSelected(): void {
+    const row = this.currentRow();
+    if (!row) return;
+    this.done({ kind: "load", provider: row.provider, modelId: row.modelId });
+  }
+
+  /**
+   * Re-filter with fuzzyFilter rather than SelectList.setFilter, which only does
+   * a prefix match on item.value and would ignore the display name. Ranking is
+   * preserved because fuzzyFilter is stable over the already-sorted rows for
+   * equal scores, and exact-prefix hits still surface first.
+   */
+  private applyFilter(): void {
+    const query = this.search.getValue().trim();
+    this.filtered = query
+      ? fuzzyFilter(this.rows, query, (r) => `${r.label} ${r.modelId} ${r.provider}`)
+      : this.rows;
+
+    // Swap the list child in place; index 1 is the SelectList.
+    const next = this.buildList(this.filtered);
+    const idx = this.children.indexOf(this.list);
+    if (idx >= 0) this.children[idx] = next;
+    this.list = next;
+
+    const fg =
+      typeof this.theme?.fg === "function"
+        ? (role: string, t: string) => this.theme.fg(role, t)
+        : (_role: string, t: string) => t;
+    this.countText.setText(fg("dim", this.countLabel()));
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) return this.done({ kind: "close" });
+    if (matchesKey(data, "ctrl+a")) return this.done({ kind: "add" });
+    if (matchesKey(data, "ctrl+r")) return this.done({ kind: "reset" });
+
+    if (matchesKey(data, "ctrl+u")) {
+      const row = this.currentRow();
+      return this.done({ kind: "update", provider: row?.provider, modelId: row?.modelId });
+    }
+    if (matchesKey(data, "ctrl+x")) {
+      const row = this.currentRow();
+      return this.done({ kind: "delete", provider: row?.provider, modelId: row?.modelId });
+    }
+
+    // Navigation and submit belong to the list; everything else is search text.
+    if (
+      matchesKey(data, "up") ||
+      matchesKey(data, "down") ||
+      matchesKey(data, "pageUp") ||
+      matchesKey(data, "pageDown") ||
+      matchesKey(data, "enter")
+    ) {
+      this.list.handleInput(data);
+      this.onChange();
+      return;
+    }
+
+    const before = this.search.getValue();
+    this.search.handleInput(data);
+    if (this.search.getValue() !== before) this.applyFilter();
+    this.onChange();
+  }
+}

package/extensions/lib/store.ts

@@ -0,0 +1,205 @@
+// Model configuration access + usage statistics store.
+//
+// Pi reads models.json itself. Better Model Select also supports an optional
+// models.local.json overlay for personal edits. The extension merges and
+// registers that overlay at runtime, so the local file remains private to BMS.
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type ConfigTarget = "models.json" | "models.local.json";
+
+export const MODELS_PATH = (): string => join(getAgentDir(), "models.json");
+export const LOCAL_MODELS_PATH = (): string => join(getAgentDir(), "models.local.json");
+export const USAGE_PATH = (): string => join(getAgentDir(), "bms-usage.json");
+
+export interface ModelEntry {
+  id: string;
+  /** BMS overlay tombstone. Hides an inherited model without editing models.json. */
+  bmsDeleted?: boolean;
+  name?: string;
+  reasoning?: boolean;
+  input?: string[];
+  contextWindow?: number;
+  maxTokens?: number;
+  [k: string]: unknown;
+}
+
+export interface ProviderEntry {
+  name?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  api?: string;
+  models?: ModelEntry[];
+  [k: string]: unknown;
+}
+
+export interface ModelsConfig {
+  providers?: Record<string, ProviderEntry>;
+  [k: string]: unknown;
+}
+
+export function configPath(target: ConfigTarget): string {
+  return target === "models.local.json" ? LOCAL_MODELS_PATH() : MODELS_PATH();
+}
+
+/** Write JSON atomically so a crash mid-write cannot truncate the target file. */
+function writeJsonAtomic(path: string, data: unknown): void {
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  renameSync(tmp, path);
+}
+
+function readConfig(path: string): ModelsConfig {
+  return JSON.parse(readFileSync(path, "utf8")) as ModelsConfig;
+}
+
+export function loadConfigFile(
+  ctx: { ui: { notify: (m: string, l: string) => void } },
+  target: ConfigTarget,
+  missingIsEmpty = false,
+): ModelsConfig | null {
+  const path = configPath(target);
+  if (missingIsEmpty && !existsSync(path)) return { providers: {} };
+  try {
+    return readConfig(path);
+  } catch (e) {
+    ctx.ui.notify(`Cannot read/parse ${path}: ${e}`, "error");
+    return null;
+  }
+}
+
+/** Merge models.local.json over models.json. Model entries merge by id. */
+export function mergeConfigs(base: ModelsConfig, local: ModelsConfig): ModelsConfig {
+  const merged = structuredClone(base);
+  merged.providers = merged.providers ?? {};
+
+  for (const [providerName, localProvider] of Object.entries(local.providers ?? {})) {
+    const baseProvider = merged.providers[providerName] ?? {};
+    const localModels = localProvider.models;
+    const provider = { ...baseProvider, ...structuredClone(localProvider) };
+
+    if (localModels) {
+      const models = new Map<string, ModelEntry>();
+      for (const model of baseProvider.models ?? []) models.set(model.id, structuredClone(model));
+      for (const model of localModels) {
+        if (model.bmsDeleted === true) models.delete(model.id);
+        else models.set(model.id, { ...(models.get(model.id) ?? {}), ...structuredClone(model) });
+      }
+      provider.models = [...models.values()];
+    }
+
+    merged.providers[providerName] = provider;
+  }
+
+  return merged;
+}
+
+/** Load the effective config used by the picker and BMS provider overlay. */
+export function loadConfig(ctx: {
+  ui: { notify: (m: string, l: string) => void };
+}): ModelsConfig | null {
+  const base = loadConfigFile(ctx, "models.json");
+  if (!base) return null;
+  if (!existsSync(LOCAL_MODELS_PATH())) return base;
+  const local = loadConfigFile(ctx, "models.local.json");
+  return local ? mergeConfigs(base, local) : null;
+}
+
+export function saveConfig(config: ModelsConfig, target: ConfigTarget): void {
+  writeJsonAtomic(configPath(target), config);
+}
+
+export function configContainsModel(
+  config: ModelsConfig,
+  provider: string,
+  modelId: string,
+): boolean {
+  return Boolean(config.providers?.[provider]?.models?.some((model) => model.id === modelId));
+}
+
+/** Hide an inherited model through the BMS local overlay. */
+export function tombstoneModel(config: ModelsConfig, provider: string, modelId: string): void {
+  upsertModel(config, provider, { id: modelId, bmsDeleted: true });
+}
+
+/** Upsert a complete model entry into one config file. */
+export function upsertModel(
+  config: ModelsConfig,
+  provider: string,
+  model: ModelEntry,
+): void {
+  config.providers = config.providers ?? {};
+  const target = (config.providers[provider] = config.providers[provider] ?? {});
+  target.models = target.models ?? [];
+  const index = target.models.findIndex((entry) => entry.id === model.id);
+  if (index >= 0) target.models[index] = model;
+  else target.models.push(model);
+}
+
+// ----- usage statistics ----------------------------------------------------
+
+export interface UsageStats {
+  version: 1;
+  /** "provider/modelId" -> number of times selected */
+  counts: Record<string, number>;
+  /** "provider/modelId" -> epoch millis of the last selection */
+  lastUsed: Record<string, number>;
+}
+
+const EMPTY_USAGE: UsageStats = { version: 1, counts: {}, lastUsed: {} };
+
+export function usageKey(provider: string, modelId: string): string {
+  return `${provider}/${modelId}`;
+}
+
+export function loadUsage(): UsageStats {
+  try {
+    const raw = JSON.parse(readFileSync(USAGE_PATH(), "utf8")) as Partial<UsageStats>;
+    return {
+      version: 1,
+      counts: raw.counts ?? {},
+      lastUsed: raw.lastUsed ?? {},
+    };
+  } catch {
+    // Missing or corrupt stats must never block the picker. Usage data is not
+    // a source of truth, so alphabetical ranking is a safe fallback.
+    return { ...EMPTY_USAGE, counts: {}, lastUsed: {} };
+  }
+}
+
+export function saveUsage(stats: UsageStats): void {
+  try {
+    writeJsonAtomic(USAGE_PATH(), stats);
+  } catch {
+    // Non-fatal: ranking degrades to alphabetical, the picker still works.
+  }
+}
+
+/** Record one selection of provider/modelId. */
+export function recordUsage(provider: string, modelId: string): void {
+  const stats = loadUsage();
+  const key = usageKey(provider, modelId);
+  stats.counts[key] = (stats.counts[key] ?? 0) + 1;
+  stats.lastUsed[key] = Date.now();
+  saveUsage(stats);
+}
+
+/** Drop stats for models that no longer exist in the effective config. */
+export function pruneUsage(config: ModelsConfig): void {
+  const live = new Set<string>();
+  for (const [p, provider] of Object.entries(config.providers ?? {})) {
+    for (const m of provider.models ?? []) live.add(usageKey(p, m.id));
+  }
+  const stats = loadUsage();
+  let changed = false;
+  for (const key of Object.keys(stats.counts)) {
+    if (!live.has(key)) {
+      delete stats.counts[key];
+      delete stats.lastUsed[key];
+      changed = true;
+    }
+  }
+  if (changed) saveUsage(stats);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-better-model-select",
+  "version": "0.1.3",
+  "type": "module",
+  "description": "Better model select for pi — /bms opens a searchable model picker sorted by how often you actually use each model, with inline add, update and delete.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "bms",
+    "model-select",
+    "model-manager",
+    "model-picker",
+    "search",
+    "fuzzy",
+    "mru",
+    "usage-ranking",
+    "litellm",
+    "openai-compatible"
+  ],
+  "license": "MIT",
+  "files": [
+    "extensions/",
+    "!extensions/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/bms.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test extensions/lib/*.test.ts",
+    "check:pack": "npm pack --dry-run --ignore-scripts >/dev/null",
+    "gate": "npm run typecheck && npm test && npm run check:pack"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  }
+}