pi-model-sort 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# 🔄 pi-model-sort
+
+**Sort models by last usage in [pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_Your most-used models appear first — no more scrolling past providers you never touch._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+## The Problem
+
+Pi's `/model` selector sorts models alphabetically by provider. If you have Anthropic + OpenAI + Google + Ollama all configured, your most-used model might be buried behind twenty other models. Every time you open the picker, you scroll past providers you haven't touched in weeks. There's no built-in way to say *"show me what I actually use."*
+
+## The Solution
+
+`pi-model-sort` tracks every model selection and reorders the `/model` picker so your most recently used models appear at the top.
+
+- **Automatic tracking** — every `/model` switch, `Ctrl+P` cycle, and session restore is recorded with a Unix timestamp
+- **Sort order** — current model first → most recently used descending → provider/id alphabetical fallback
+- **Persistent** — usage data lives in `~/.pi/agent/extensions/pi-model-sort.json`, survives restarts
+- **No config needed** — install and forget; the extension starts tracking on first use
+- **Zero setup** — with no recorded usage, models fall back to the default alphabetical order
+- **Everywhere** — the sort applies to `/model` (`Ctrl+L`), both "Scope: all" and "Scope: scoped" views, `--list-models` CLI, and the `/scoped-models` config selector
+
+No `settings.json` modifications. No manual maintenance. No database.
+
+## Usage
+
+The extension works automatically — there are no commands to learn.
+
+```bash
+# Install, then just use pi normally
+/model                    # Most recently used models now appear at the top
+pi --list-models          # CLI output is also sorted by last usage
+```
+
+Open `/model` and press `Tab` to switch between "Scope: all" and "Scope: scoped" — both views are sorted by recency.
+
+### Config File
+
+The extension creates `~/.pi/agent/extensions/pi-model-sort.json` automatically on first model switch:
+
+```json
+{
+  "lastUsed": {
+    "anthropic/claude-sonnet-4-20250514": 1717000000000,
+    "openai/gpt-4o": 1716995000000,
+    "google/gemini-2.5-pro": 1716000000000
+  }
+}
+```
+
+No manual editing needed. To clear usage history, delete the file and `/reload`.
+
+## Install
+
+**With `pi install`** (recommended):
+
+```bash
+pi install https://github.com/monotykamary/pi-model-sort
+```
+
+**With npm**:
+
+```bash
+npm install pi-model-sort
+```
+
+Or in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    "git:github.com/monotykamary/pi-model-sort"
+  ]
+}
+```
+
+Then `/reload` or restart pi.
+
+For quick one-off tests:
+
+```bash
+pi -e ./model-sort.ts
+```
+
+## How It Works
+
+```
+model_select event fires
+  → Extension records timestamp
+  → Writes to pi-model-sort.json
+  → Next /model opens with updated sort
+
+Session starts
+  → Extension reads pi-model-sort.json
+  → Monkey-patches ModelSelectorComponent.prototype:
+      sortModels — sorts "Scope: all" view
+      loadModels — sorts "Scope: scoped" scopedModelItems after load
+  → Monkey-patches ModelRegistry.prototype.getAvailable/getAll
+  → Sort order: current model first → most recent → provider/id alphabetical
+  → Patches survive modelRegistry.refresh()
+```
+
+**Four patches, full coverage:**
+
+| Patch | What it affects |
+|-------|----------------|
+| `ModelSelectorComponent.prototype.sortModels` | `/model` TUI picker — "Scope: all" view |
+| `ModelSelectorComponent.prototype.loadModels` | `/model` TUI picker — "Scope: scoped" view (configured cycling models) |
+| `ModelRegistry.prototype.getAvailable()` | `/scoped-models` config selector, model resolution |
+| `ModelRegistry.prototype.getAll()` | `--list-models` CLI output |
+
+The SDK doesn't expose a sort order for model lists. Monkey-patching the component and registry methods is the only way to control ordering without rebuilding the entire picker UI.
+
+The patches survive `modelRegistry.refresh()` because they wrap the original methods. On reload, the extension detects the prototypes are already patched and just updates the last-used data source.
+
+## Comparison with Alternatives
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **pi-model-sort** (this) | Automatic, zero-config, persistent, applies everywhere | Monkey-patches internal prototypes |
+| `enabledModels` in `settings.json` (manual) | Built-in, no extension needed | Allowlist — must list models manually; doesn't sort, just scopes |
+| Custom `/model` replacement extension | Full control over UI | Rebuilds the entire picker component from scratch (~400 lines of TUI code) |
+| Manually ordering `models.json` | Controls `--list-models` output | Static, doesn't react to actual usage; doesn't affect `/model` picker |
+
+## Development
+
+```bash
+npm install
+npm test          # Vitest unit tests
+npm run typecheck # TypeScript validation
+npm run lint:dead # Dead code detection (knip)
+```
+
+### Structure
+
+```
+.
+├── model-sort.ts       # Main extension
+├── src/
+│   └── index.ts        # Sort logic, types, and utilities
+├── __tests__/
+│   └── sort.test.ts    # Unit tests for sortByLastUsed
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── knip.json
+```
+
+## License
+
+MIT

package/model-sort.ts

@@ -0,0 +1,227 @@
+/**
+ * pi-model-sort — sort models in pi by last usage (descending).
+ *
+ * Strategy: monkey-patches ModelSelectorComponent.prototype.sortModels and
+ * loadModels so the /model picker sorts by recency instead of alphabetically
+ * by provider — including the "Scope: scoped" view for Ctrl+P cycling.
+ * Also patches ModelRegistry.getAvailable() and getAll() so --list-models
+ * and the scoped-models config selector benefit from the same ordering.
+ *
+ * Usage tracking is automatic — every model selection (manual, Ctrl+P cycle,
+ * or session restore) updates the last-used timestamp. Data persists to
+ * ~/.pi/agent/extensions/pi-model-sort.json.
+ *
+ * With no recorded usage, the sort degrades gracefully to the default
+ * provider/model-id alphabetical order.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ModelRegistry, ModelSelectorComponent } from "@earendil-works/pi-coding-agent";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  buildModelKey,
+  CONFIG_FILENAME,
+  type ModelSortConfig,
+  sortByLastUsed,
+} from "./src/index.js";
+
+const HOME = homedir();
+const CONFIG_PATH = join(HOME, ".pi", "agent", "extensions", CONFIG_FILENAME);
+
+// Config I/O
+
+function readConfig(): ModelSortConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return { lastUsed: {} };
+  }
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as ModelSortConfig;
+    return { lastUsed: parsed.lastUsed ?? {} };
+  } catch {
+    return { lastUsed: {} };
+  }
+}
+
+function writeConfig(config: ModelSortConfig): void {
+  const dir = join(HOME, ".pi", "agent", "extensions");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+// ModelSelectorComponent sortModels patch
+
+let origSortModels: ((models: Array<{ provider: string; id: string; model: unknown }>) => Array<{ provider: string; id: string; model: unknown }>) | null = null;
+
+function buildCurrentModelKey(instance: Record<string, unknown>): string | null {
+  const cm = instance.currentModel as { provider?: string; id?: string } | undefined;
+  if (cm?.provider && cm?.id) {
+    return buildModelKey(cm.provider, cm.id);
+  }
+  return null;
+}
+
+function patchSortModels(getLastUsed: () => Record<string, number>): void {
+  if (origSortModels !== null) return;
+
+  const proto = ModelSelectorComponent.prototype as unknown as Record<string, unknown>;
+  origSortModels = proto.sortModels as typeof origSortModels;
+
+  proto.sortModels = function (
+    this: Record<string, unknown>,
+    models: Array<{ provider: string; id: string; model: unknown }>,
+  ) {
+    const lastUsed = getLastUsed();
+    return sortByLastUsed(models, lastUsed, buildCurrentModelKey(this));
+  };
+}
+
+function unpatchSortModels(): void {
+  if (origSortModels === null) return;
+  (ModelSelectorComponent.prototype as unknown as Record<string, unknown>).sortModels = origSortModels;
+  origSortModels = null;
+}
+
+// ModelSelectorComponent loadModels patch — sorts scopedModelItems for the
+// "Scope: scoped" toggle in the /model picker.
+
+let origLoadModels: (() => Promise<void>) | null = null;
+
+function patchLoadModels(getLastUsed: () => Record<string, number>): void {
+  if (origLoadModels !== null) return;
+
+  const proto = ModelSelectorComponent.prototype as unknown as Record<string, unknown>;
+  origLoadModels = proto.loadModels as () => Promise<void>;
+
+  proto.loadModels = async function (this: Record<string, unknown>) {
+    await origLoadModels!.call(this);
+
+    const scopedItems = this.scopedModelItems as Array<{ provider: string; id: string; model: unknown }> | undefined;
+    if (!scopedItems || scopedItems.length === 0) return;
+
+    const lastUsed = getLastUsed();
+    this.scopedModelItems = sortByLastUsed(scopedItems, lastUsed, buildCurrentModelKey(this));
+
+    if (this.scope === "scoped") {
+      this.activeModels = this.scopedModelItems;
+      // Sync filteredModels — the original loadModels set it to the
+      // unsorted scopedModelItems before our patch had a chance to sort.
+      this.filteredModels = this.scopedModelItems;
+
+      // Recalculate selectedIndex — the original loadModels computed it
+      // from the unsorted array, so the cursor is at the old position.
+      const currentKey = buildCurrentModelKey(this);
+      if (currentKey) {
+        const filtered = this.filteredModels as Array<{ provider: string; id: string }>;
+        const newIndex = filtered.findIndex(
+          (item) => buildModelKey(item.provider, item.id) === currentKey,
+        );
+        if (newIndex >= 0) {
+          this.selectedIndex = newIndex;
+        }
+      }
+    }
+  };
+}
+
+function unpatchLoadModels(): void {
+  if (origLoadModels === null) return;
+  (ModelSelectorComponent.prototype as unknown as Record<string, unknown>).loadModels = origLoadModels;
+  origLoadModels = null;
+}
+
+// ModelRegistry getAvailable / getAll patch
+
+const REGISTRY_PATCH_KEY = "__model_sort_registry_patched";
+
+interface PatchedRegistry {
+  [REGISTRY_PATCH_KEY]: boolean;
+  getAvailable(): unknown[];
+  getAll(): unknown[];
+  __model_sort_get_last_used: () => Record<string, number>;
+  __model_sort_orig_getAvailable: () => unknown[];
+  __model_sort_orig_getAll: () => unknown[];
+}
+
+function patchRegistry(
+  registry: PatchedRegistry,
+  getLastUsed: () => Record<string, number>,
+): void {
+  if (registry[REGISTRY_PATCH_KEY]) {
+    registry.__model_sort_get_last_used = getLastUsed;
+    return;
+  }
+
+  registry[REGISTRY_PATCH_KEY] = true;
+  registry.__model_sort_get_last_used = getLastUsed;
+
+  registry.__model_sort_orig_getAvailable = registry.getAvailable.bind(registry);
+  registry.__model_sort_orig_getAll = registry.getAll.bind(registry);
+
+  registry.getAvailable = function (this: PatchedRegistry) {
+    const lastUsed = this.__model_sort_get_last_used();
+    const all = this.__model_sort_orig_getAvailable() as Array<{ provider: string; id: string }>;
+    return sortByLastUsed(all, lastUsed, null);
+  };
+
+  registry.getAll = function (this: PatchedRegistry) {
+    const lastUsed = this.__model_sort_get_last_used();
+    const all = this.__model_sort_orig_getAll() as Array<{ provider: string; id: string }>;
+    return sortByLastUsed(all, lastUsed, null);
+  };
+}
+
+function unpatchRegistry(registry: PatchedRegistry): void {
+  if (!registry[REGISTRY_PATCH_KEY]) return;
+
+  registry.getAvailable = registry.__model_sort_orig_getAvailable;
+  registry.getAll = registry.__model_sort_orig_getAll;
+
+  const raw = registry as unknown as Record<string, unknown>;
+  delete raw[REGISTRY_PATCH_KEY];
+  delete raw.__model_sort_get_last_used;
+  delete raw.__model_sort_orig_getAvailable;
+  delete raw.__model_sort_orig_getAll;
+}
+
+// Extension
+
+export default function (pi: ExtensionAPI) {
+  let lastUsed: Record<string, number> = {};
+
+  pi.on("session_start", async (_event, ctx) => {
+    const config = readConfig();
+    lastUsed = config.lastUsed;
+
+    patchRegistry(ctx.modelRegistry as unknown as PatchedRegistry, () => lastUsed);
+    patchSortModels(() => lastUsed);
+    patchLoadModels(() => lastUsed);
+
+    if (ctx.hasUI) {
+      const count = Object.keys(lastUsed).length;
+      ctx.ui.notify(
+        count > 0
+          ? `pi-model-sort: ${count} model(s) tracked — sorting by last usage`
+          : "pi-model-sort: tracking started — models will sort by recency after first use",
+        "info",
+      );
+    }
+  });
+
+  // Track every model selection (manual, Ctrl+P cycle, session restore)
+  pi.on("model_select", async (event, _ctx) => {
+    const key = buildModelKey(event.model.provider, event.model.id);
+    lastUsed[key] = Date.now();
+    writeConfig({ lastUsed });
+  });
+
+  // Cleanup on shutdown / reload
+  pi.on("session_shutdown", () => {
+    unpatchSortModels();
+    unpatchLoadModels();
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pi-model-sort",
+  "version": "0.1.0",
+  "description": "Sort models in pi's /model selector by last usage — most recently used models appear first",
+  "type": "module",
+  "author": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-model-sort.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-model-sort#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-model-sort/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "model",
+    "sort",
+    "recent",
+    "last-used",
+    "model-selector"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "pi": {
+    "extensions": [
+      "./model-sort.ts"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared constants, types, and utilities for pi-model-sort.
+ */
+
+/** Default config file name (placed in ~/.pi/agent/extensions/). */
+export const CONFIG_FILENAME = "pi-model-sort.json";
+
+export interface ModelSortConfig {
+  /** Map of "provider/modelId" → last-used Unix timestamp (ms). */
+  lastUsed: Record<string, number>;
+}
+
+/** Build a stable model key from provider and model id. */
+export function buildModelKey(provider: string, modelId: string): string {
+  return `${provider}/${modelId}`;
+}
+
+/**
+ * Sort an array of models (or model-like objects) by last-usage recency.
+ *
+ * Sort order:
+ *   1. Current model first (if currentModelKey is provided)
+ *   2. Most recently used (highest timestamp) first
+ *   3. Provider name alphabetically
+ *   4. Model id alphabetically
+ *
+ * Models with no recorded usage get timestamp 0 (sorted last).
+ */
+export function sortByLastUsed<T extends { provider: string; id: string }>(
+  items: T[],
+  lastUsed: Record<string, number>,
+  currentModelKey: string | null,
+): T[] {
+  const sorted = [...items];
+  sorted.sort((a, b) => {
+    const aKey = buildModelKey(a.provider, a.id);
+    const bKey = buildModelKey(b.provider, b.id);
+
+    if (currentModelKey !== null) {
+      const aIsCurrent = aKey === currentModelKey;
+      const bIsCurrent = bKey === currentModelKey;
+      if (aIsCurrent && !bIsCurrent) return -1;
+      if (!aIsCurrent && bIsCurrent) return 1;
+    }
+
+    const aLast = lastUsed[aKey] ?? 0;
+    const bLast = lastUsed[bKey] ?? 0;
+    if (aLast !== bLast) return bLast - aLast;
+
+    return a.provider.localeCompare(b.provider) || a.id.localeCompare(b.id);
+  });
+  return sorted;
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["__tests__/**/*.test.ts"],
+    exclude: ["node_modules", "dist", ".idea", ".git", ".cache"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: ["node_modules/", "**/*.d.ts", "**/*.test.ts"],
+    },
+  },
+});