@benvargas/pi-model-sort 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-08-28
+
+### Added
+- Initial `@benvargas/pi-model-sort` package, forked from
+  [monotykamary/pi-model-sort](https://github.com/monotykamary/pi-model-sort)
+  v0.3.2 (MIT): last-usage sorting for the `/model` picker (all and scoped
+  views, fuzzy-search results) and scoped Ctrl+P cycling; MRU model selection
+  on fresh starts; per-model thinking level memory; persistent usage history
+  in `~/.pi/agent/extensions/pi-model-sort.json`.
+- Continued sessions (`pi -c`, `--session`, `/resume`, context-bearing
+  forks) record their restored model as last-used — pi 0.84.3 restores without
+  emitting `model_select`, so the extension timestamps it at `session_start`
+  (fresh `new` sessions and `reload` are excluded).
+- Unit tests for continuation detection (including pi's new-session entry
+  seeding, context-only summarized branches, and compaction-only branches),
+  MRU auth fallback, restore-timestamp gating, and config sanitization.
+
+### Changed
+- Fork change from upstream: the MRU startup override skips continued
+  sessions. Upstream applies the override on every `startup` session start,
+  which replaces the model restored by `pi -c` (or `--session`) with the
+  global most-recently-used model. Continuation is detected by projecting
+  the branch through pi's context-message rules (`message`, `custom_message`,
+  non-empty `branch_summary`, `compaction` — the same predicate
+  `buildSessionContext()` uses) — pi seeds every new session with
+  `model_change` + `thinking_level_change` entries before `session_start`
+  fires, so raw branch length would disable the override everywhere, and
+  literal-message-only detection would miss context-only summarized
+  branches.
+- Registry cleanup on `session_shutdown` (`unpatchRegistry` is defined but
+  never called upstream).
+- Documentation narrowed to the surfaces actually affected on pi 0.84.x:
+  `--list-models`, `/scoped-models`, and unscoped Ctrl+P cycling read
+  `ModelRuntime` directly and are not re-sorted (upstream README claims
+  otherwise for older pi versions).
+- Peer dependency floor set to the tested-with release
+  (`@earendil-works/pi-coding-agent >=0.84.0`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Vargas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @benvargas/pi-model-sort
+
+Sorts pi's model picker by last usage and starts fresh sessions on your most recently used model.
+
+- `/model` picker — both "Scope: all" and "Scope: scoped" views, including fuzzy-search results — is sorted by recency: current model first → most recently used → provider/id alphabetical
+- Ctrl+P / Ctrl+Shift+P **scoped** cycling follows last-used order (scoped models come from `enabledModels` or `--models`)
+- Fresh starts and `/new` begin on your most recently used model instead of `enabledModels[0]` or the hardcoded provider default
+- Continued sessions (`pi -c`, `--session`, `/resume`, forks) keep the model saved in the session file, and that restored model is recorded as last-used (fresh `/new` sessions and `/reload` are excluded from that recording)
+- Remembers the thinking level you last used on each model and restores it on every switch, clamped to what each model supports
+- No configuration needed — tracking starts on first use and degrades to the default alphabetical order with no history
+
+> Forked from [monotykamary/pi-model-sort](https://github.com/monotykamary/pi-model-sort) (MIT, v0.3.2). See `THIRD_PARTY_NOTICES.md` for the full list of fork changes and attribution.
+
+## Install
+
+```bash
+pi install npm:@benvargas/pi-model-sort
+```
+
+Or try without installing:
+
+```bash
+pi -e npm:@benvargas/pi-model-sort
+```
+
+## Usage
+
+The extension works automatically — there are no commands to learn.
+
+```
+/model                    # Most recently used models appear at the top
+Ctrl+P / Ctrl+Shift+P     # Cycle through scoped models in last-used order
+pi                        # Fresh starts use MRU
+pi -c                     # Continuations keep the session's model
+```
+
+## How It Works
+
+- Tracking uses pi's documented extension events: `/model` switches (`model_select`) and thinking-level changes (`thinking_level_select`) are timestamped into `~/.pi/agent/extensions/pi-model-sort.json`. Continued sessions restore their model during construction without emitting `model_select` (pi 0.84.3), so the extension records the restored model at `session_start` itself.
+- Sorting has no SDK hook, so the extension wraps (monkey-patches) internal methods: `ModelSelectorComponent.sortModels`, its scoped loader and `filterModels`, and `AgentSession._cycleScopedModel` for scoped cycling. All original methods are preserved and restored on shutdown/reload; the patches survive `modelRegistry.refresh()`.
+- The MRU startup override calls `pi.setModel()` on `session_start` for fresh starts and `/new` only. A continued session is detected by projecting its branch through pi's own context-message rules (`message`, `custom_message`, non-empty `branch_summary`, and `compaction` entries — exactly what `buildSessionContext()` counts) — pi seeds every new session with `model_change` + `thinking_level_change` entries before `session_start` fires, so raw branch length cannot distinguish fresh from continued.
+
+### Known limitations on pi 0.84.x
+
+- `--list-models` output is **not** sorted: the CLI lists models before extensions load and re-sorts by provider/id internally.
+- `/scoped-models` and unscoped Ctrl+P cycling are **not** re-sorted: they read `ModelRuntime` snapshots directly, not the extension-facing `ModelRegistry` facade this extension wraps. (Scoped cycling — the common case with `enabledModels` set — is sorted via the `_cycleScopedModel` wrapper.)
+
+## Configuration
+
+Usage history lives in `~/.pi/agent/extensions/pi-model-sort.json`:
+
+```json
+{
+  "lastUsed": {
+    "provider/modelId": 1717000000000
+  },
+  "thinking": {
+    "provider/modelId": "high"
+  }
+}
+```
+
+No manual editing is needed. To clear usage history, delete the file and `/reload`.
+
+## Notes
+
+- Ctrl+P cycling does not update last-used timestamps — doing so would create a sort feedback loop (each cycle step re-sorts the selected model to the top, making the cycle toggle forever between the top two). Manual selections and session restores still update it.
+- Patches are coupled to pi internals; this package is maintained against current pi releases (peer requirement `>=0.84.0`, the version it is tested with).
+
+## Uninstall
+
+```bash
+pi remove npm:@benvargas/pi-model-sort
+```

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,50 @@
+# Third-Party Notices
+
+## pi-model-sort
+
+This package is adapted from [monotykamary/pi-model-sort](https://github.com/monotykamary/pi-model-sort),
+version 0.3.2, by Tom X Nguyen. The upstream project is MIT-licensed (see its
+`package.json`); it did not ship a standalone `LICENSE` file at the time of
+forking.
+
+Modifications in this fork:
+
+- The MRU startup override skips continued sessions (`pi -c`, `--session`)
+  so the model restored from the session file is preserved; continuation is
+  detected by projecting the branch through pi's context-message rules
+  (message, custom_message, non-empty branch_summary, compaction entries)
+  because pi seeds new sessions with model/thinking entries before
+  `session_start`.
+- Continued sessions record their restored model as last-used (pi 0.84.3
+  does not emit `model_select` for construction-time restoration).
+- `unpatchRegistry()` (defined but never called upstream) is invoked on
+  `session_shutdown` so registry cleanup is symmetric with the other patches.
+- Upstream non-null assertions in the scoped-loader, filter, and cycle
+  wrappers were replaced with runtime null guards.
+- `findMruModel` moved into the shared helpers module and is exported for
+  testing.
+- Code reformatted to this repository's Biome configuration and restructured
+  to the `extensions/` package layout; documentation corrected for the
+  surfaces actually affected on pi 0.84.x.
+
+MIT License
+
+Copyright (c) 2026 Tom X Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/index.ts

@@ -0,0 +1,469 @@
+/**
+ * pi-model-sort — sort models in pi by last usage (descending) and start
+ * fresh sessions on the most recently used model.
+ *
+ * Adapted from monotykamary/pi-model-sort (MIT). See THIRD_PARTY_NOTICES.md.
+ * Fork change: the MRU startup override skips continued sessions (`pi -c`,
+ * `--session`) so the model restored from the session file is preserved.
+ *
+ * Strategy: monkey-patches three areas:
+ *   ModelSelectorComponent.prototype.sortModels, filterModels, and the scoped
+ *   loader (loadModelsFromSnapshot on pi 0.80.8+, loadModels on older pi) —
+ *   sorts both "Scope: all" and "Scope: scoped" views in the /model TUI
+ *   picker, including fuzzy-search results.
+ *   AgentSession.prototype._cycleScopedModel — sorts the Ctrl+P / Ctrl+Shift+P
+ *   scoped cycling order (non-destructively — the configured order is
+ *   preserved).
+ *   ModelRegistry getAvailable/getAll — sorts the extension-facing registry
+ *   facade for any extension consumer. NOT affected on pi 0.84.x:
+ *   --list-models (the CLI lists before extensions load), /scoped-models, and
+ *   unscoped Ctrl+P cycling, which read ModelRuntime snapshots directly.
+ *
+ * Usage tracking: manual /model selections and switches via pi's model_select
+ * event (Ctrl+P cycles are deliberately excluded to avoid a sort feedback
+ * loop); continued-session restores are timestamped at session_start because
+ * pi 0.84.3 restores them without emitting model_select. Data persists to
+ * ~/.pi/agent/extensions/pi-model-sort.json.
+ *
+ * It also remembers the thinking level last used on each model and restores
+ * it on every switch (including Ctrl+P cycling), clamped to what the model
+ * supports — deepseek stays on max, claude on high, without manual
+ * re-adjustment after every switch.
+ *
+ * With no recorded usage, the sort degrades gracefully to the default
+ * provider/model-id alphabetical order.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { AgentSession, getAgentDir, ModelSelectorComponent } from "@earendil-works/pi-coding-agent";
+import {
+	buildModelKey,
+	CONFIG_FILENAME,
+	createThinkingTracker,
+	findMruModel,
+	handleModelSelect,
+	hasContextMessages,
+	type ModelSortConfig,
+	parseConfig,
+	recordThinkingSelect,
+	shouldApplyMruOverride,
+	shouldTimestampRestoredModel,
+	sortByLastUsed,
+} from "./sort.js";
+
+const CONFIG_PATH = join(getAgentDir(), "extensions", CONFIG_FILENAME);
+
+// Config I/O
+
+function readConfig(): ModelSortConfig {
+	if (!existsSync(CONFIG_PATH)) {
+		return { lastUsed: {}, thinking: {} };
+	}
+	try {
+		const raw = readFileSync(CONFIG_PATH, "utf-8");
+		return parseConfig(JSON.parse(raw));
+	} catch {
+		return { lastUsed: {}, thinking: {} };
+	}
+}
+
+function writeConfig(config: ModelSortConfig): void {
+	const dir = join(getAgentDir(), "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 scoped-loader patch — sorts scopedModelItems for
+// the "Scope: scoped" toggle in the /model picker.
+//
+// pi 0.80.8 split the old loadModels() into a synchronous
+// loadModelsFromSnapshot() (used for both the initial render and after each
+// catalog refresh) plus a new async refreshModels(). The scoped items are built
+// directly inside the snapshot loader and never pass through sortModels, so
+// this patch re-sorts them there. We hook whichever method the running pi
+// exposes — new (loadModelsFromSnapshot, sync) or old (loadModels, async) — so
+// the sort applies on initial render, after a refresh, and (because
+// scopedModelItems is re-sorted even when the active scope is "all") survives
+// the Tab toggle to "scoped".
+
+let origScopedLoader: ((this: unknown) => unknown) | null = null;
+let scopedLoaderName: string | null = null;
+
+function sortScopedItems(instance: Record<string, unknown>, getLastUsed: () => Record<string, number>): void {
+	const scopedItems = instance.scopedModelItems as Array<{ provider: string; id: string; model: unknown }> | undefined;
+	if (!scopedItems || scopedItems.length === 0) return;
+
+	const lastUsed = getLastUsed();
+	instance.scopedModelItems = sortByLastUsed(scopedItems, lastUsed, buildCurrentModelKey(instance));
+
+	if (instance.scope === "scoped") {
+		// Sync activeModels/filteredModels — the loader set them to the unsorted
+		// scopedModelItems before our patch had a chance to sort.
+		instance.activeModels = instance.scopedModelItems;
+		instance.filteredModels = instance.scopedModelItems;
+
+		// Recalculate selectedIndex — the loader computed it from the unsorted
+		// array, so the cursor is at the old position.
+		const currentKey = buildCurrentModelKey(instance);
+		if (currentKey) {
+			const filtered = instance.filteredModels as Array<{ provider: string; id: string }>;
+			const newIndex = filtered.findIndex((item) => buildModelKey(item.provider, item.id) === currentKey);
+			if (newIndex >= 0) {
+				instance.selectedIndex = newIndex;
+			}
+		}
+	}
+}
+
+function patchScopedLoader(getLastUsed: () => Record<string, number>): void {
+	if (origScopedLoader !== null) return;
+
+	const proto = ModelSelectorComponent.prototype as unknown as Record<string, unknown>;
+
+	// pi 0.80.8+ — synchronous snapshot loader (initial render + after refresh).
+	if (typeof proto.loadModelsFromSnapshot === "function") {
+		origScopedLoader = proto.loadModelsFromSnapshot as (this: unknown) => unknown;
+		scopedLoaderName = "loadModelsFromSnapshot";
+		proto.loadModelsFromSnapshot = function (this: Record<string, unknown>) {
+			const orig = origScopedLoader;
+			if (!orig) return;
+			orig.call(this);
+			sortScopedItems(this, getLastUsed);
+		};
+		return;
+	}
+
+	// pi <= 0.80.3 — async loadModels.
+	if (typeof proto.loadModels === "function") {
+		origScopedLoader = proto.loadModels as (this: unknown) => unknown;
+		scopedLoaderName = "loadModels";
+		proto.loadModels = async function (this: Record<string, unknown>) {
+			const orig = origScopedLoader;
+			if (!orig) return;
+			await orig.call(this);
+			sortScopedItems(this, getLastUsed);
+		};
+	}
+}
+
+function unpatchScopedLoader(): void {
+	if (origScopedLoader === null || scopedLoaderName === null) return;
+	(ModelSelectorComponent.prototype as unknown as Record<string, unknown>)[scopedLoaderName] = origScopedLoader;
+	origScopedLoader = null;
+	scopedLoaderName = null;
+}
+
+// ModelSelectorComponent filterModels patch — re-applies last-used sort after
+// fuzzyFilter re-orders results by match quality. Without this, typing in the
+// /model picker search box discards the last-used order.
+
+let origFilterModels: ((query: string) => void) | null = null;
+
+function patchFilterModels(getLastUsed: () => Record<string, number>): void {
+	if (origFilterModels !== null) return;
+
+	const proto = ModelSelectorComponent.prototype as unknown as Record<string, unknown>;
+	origFilterModels = proto.filterModels as (query: string) => void;
+
+	proto.filterModels = function (this: Record<string, unknown>, query: string) {
+		const orig = origFilterModels;
+		if (!orig) return;
+
+		// Suppress the original's updateList() call — we'll call it once after
+		// re-sorting to avoid a double-render.
+		const origUpdateList = this.updateList as () => void;
+		this.updateList = () => {};
+
+		try {
+			orig.call(this, query);
+		} finally {
+			this.updateList = origUpdateList;
+		}
+
+		// Empty query: nothing to re-sort (activeModels is already sorted by our
+		// sortModels/scoped-loader patches), just render the original result.
+		if (!query) {
+			origUpdateList.call(this);
+			return;
+		}
+
+		const filtered = this.filteredModels as Array<{ provider: string; id: string; model: unknown }> | undefined;
+		if (!filtered || filtered.length <= 1) {
+			origUpdateList.call(this);
+			return;
+		}
+
+		const lastUsed = getLastUsed();
+		this.filteredModels = sortByLastUsed(filtered, lastUsed, buildCurrentModelKey(this));
+
+		// Re-sync selectedIndex — fuzzyFilter may have moved the current model.
+		const currentKey = buildCurrentModelKey(this);
+		if (currentKey) {
+			const newFiltered = this.filteredModels as Array<{ provider: string; id: string }>;
+			const newIndex = newFiltered.findIndex((item) => buildModelKey(item.provider, item.id) === currentKey);
+			if (newIndex >= 0) {
+				this.selectedIndex = newIndex;
+			}
+		}
+
+		// Render once with the final sorted list.
+		origUpdateList.call(this);
+	};
+}
+
+function unpatchFilterModels(): void {
+	if (origFilterModels === null) return;
+	(ModelSelectorComponent.prototype as unknown as Record<string, unknown>).filterModels = origFilterModels;
+	origFilterModels = 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;
+}
+
+// AgentSession _cycleScopedModel patch — sorts the scoped models list
+// before cycling so Ctrl+P / Ctrl+Shift+P follows last-used order instead
+// of the configured order. Non-destructive: the session's stored order is
+// temporarily swapped and restored after the cycle lookup.
+
+type ScopedModelEntry = { model: { provider: string; id: string }; thinkingLevel?: string };
+
+let origCycleScopedModel: ((direction: string) => Promise<unknown>) | null = null;
+
+function patchCycleScopedModel(getLastUsed: () => Record<string, number>): void {
+	if (origCycleScopedModel !== null) return;
+
+	const proto = AgentSession.prototype as unknown as Record<string, unknown>;
+	origCycleScopedModel = proto._cycleScopedModel as (direction: string) => Promise<unknown>;
+
+	proto._cycleScopedModel = async function (this: Record<string, unknown>, direction: string) {
+		const orig = origCycleScopedModel;
+		if (!orig) return undefined;
+
+		const lastUsed = getLastUsed();
+		const origScoped = this._scopedModels as ScopedModelEntry[] | undefined;
+
+		if (!origScoped || origScoped.length <= 1) {
+			return orig.call(this, direction);
+		}
+
+		// Sort by last-used without mutating the session's stored order.
+		const sorted = [...origScoped].sort((a, b) => {
+			const aKey = buildModelKey(a.model.provider, a.model.id);
+			const bKey = buildModelKey(b.model.provider, b.model.id);
+			const aLast = lastUsed[aKey] ?? 0;
+			const bLast = lastUsed[bKey] ?? 0;
+			if (aLast !== bLast) return bLast - aLast;
+			return a.model.provider.localeCompare(b.model.provider) || a.model.id.localeCompare(b.model.id);
+		});
+
+		// Temporarily swap for the cycle lookup, restore afterward.
+		this._scopedModels = sorted;
+		try {
+			return await orig.call(this, direction);
+		} finally {
+			this._scopedModels = origScoped;
+		}
+	};
+}
+
+function unpatchCycleScopedModel(): void {
+	if (origCycleScopedModel === null) return;
+	(AgentSession.prototype as unknown as Record<string, unknown>)._cycleScopedModel = origCycleScopedModel;
+	origCycleScopedModel = null;
+}
+
+// Extension
+
+export default function (pi: ExtensionAPI) {
+	let lastUsed: Record<string, number> = {};
+	const tracker = createThinkingTracker();
+
+	pi.on("session_start", async (event, ctx) => {
+		const config = readConfig();
+		lastUsed = config.lastUsed;
+		tracker.thinking = config.thinking;
+		tracker.activeKey = ctx.model ? buildModelKey(ctx.model.provider, ctx.model.id) : null;
+		tracker.sawSwitchClamp = false;
+
+		patchRegistry(ctx.modelRegistry as unknown as PatchedRegistry, () => lastUsed);
+		patchSortModels(() => lastUsed);
+		patchScopedLoader(() => lastUsed);
+		patchFilterModels(() => lastUsed);
+		patchCycleScopedModel(() => lastUsed);
+
+		// Override the initial model to MRU on fresh starts.
+		// Pi core picks the saved default if in scope, otherwise scopedModels[0].
+		// This override switches to the most recently used model instead, so your
+		// actual usage history determines the default — not scope order.
+		//
+		// Continued sessions (pi -c, --session, /resume, forks) are skipped: pi
+		// has already restored the model saved in the session file, and global
+		// MRU should not clobber it.
+		//
+		// NOTE: pi seeds every new session with model_change +
+		// thinking_level_change entries before session_start fires, so
+		// continuation is derived by projecting the branch through pi's own
+		// context-message rules (message, custom_message, non-empty
+		// branch_summary, compaction entries) — the same predicate pi core uses
+		// for its continuation check, not raw branch length and not literal
+		// message entries alone.
+		const hasSessionMessages = hasContextMessages(ctx.sessionManager.buildContextEntries());
+		if (shouldApplyMruOverride(event.reason, hasSessionMessages) && Object.keys(lastUsed).length > 0) {
+			const mruModel = findMruModel(lastUsed, ctx.modelRegistry);
+			const currentModel = ctx.model as { provider: string; id: string } | undefined;
+			if (
+				mruModel &&
+				(!currentModel ||
+					currentModel.provider !== (mruModel as { provider: string }).provider ||
+					currentModel.id !== (mruModel as { id: string }).id)
+			) {
+				await pi.setModel(mruModel as Parameters<typeof pi.setModel>[0]);
+			}
+		} else if (shouldTimestampRestoredModel(event.reason, hasSessionMessages) && ctx.model) {
+			// Continued session (continued startup, resume, or context-bearing
+			// fork): pi 0.84.3 restores the session's model during construction
+			// without emitting model_select, so recency would never update for
+			// continuations. Record the restored model here so "last used"
+			// stays accurate. Fresh "new" sessions and "reload" are excluded —
+			// they perform no construction-time restore worth recording.
+			lastUsed[buildModelKey(ctx.model.provider, ctx.model.id)] = Date.now();
+			writeConfig({ lastUsed, thinking: tracker.thinking });
+		}
+	});
+
+	// Record thinking levels per model. Pi emits this only when the effective
+	// level changes — for manual changes (Ctrl+T, /thinking) and for the
+	// re-clamp inside setModel/cycle, which runs before model_select fires.
+	pi.on("thinking_level_select", (event, ctx) => {
+		const currentKey = ctx.model ? buildModelKey(ctx.model.provider, ctx.model.id) : null;
+		if (recordThinkingSelect(tracker, currentKey, event.level, event.previousLevel)) {
+			writeConfig({ lastUsed, thinking: tracker.thinking });
+		}
+	});
+
+	// Track model selections (manual, session restore).
+	// Skip lastUsed updates for "cycle" events — updating lastUsed during
+	// Ctrl+P cycling creates a feedback loop: each cycle step makes the
+	// selected model most-recent, re-sorts it to position 0, then
+	// (currentIndex + 1) % len always hits position 1 — toggling forever
+	// between the top 2. Thinking restore still applies to cycle selections.
+	pi.on("model_select", async (event, _ctx) => {
+		const newKey = buildModelKey(event.model.provider, event.model.id);
+		if (event.source !== "cycle") {
+			lastUsed[newKey] = Date.now();
+		}
+
+		const previousKey = event.previousModel
+			? buildModelKey(event.previousModel.provider, event.previousModel.id)
+			: null;
+		const restoreLevel = handleModelSelect(tracker, newKey, previousKey, pi.getThinkingLevel());
+		writeConfig({ lastUsed, thinking: tracker.thinking });
+
+		// Restore the model's remembered thinking level. setThinkingLevel clamps
+		// to the model's capabilities; if clamping changes the level, the
+		// resulting thinking_level_select records the effective level instead.
+		if (restoreLevel !== null) {
+			pi.setThinkingLevel(restoreLevel);
+		}
+	});
+
+	// Cleanup on shutdown / reload
+	pi.on("session_shutdown", (_event, ctx) => {
+		unpatchSortModels();
+		unpatchScopedLoader();
+		unpatchFilterModels();
+		unpatchCycleScopedModel();
+		unpatchRegistry(ctx.modelRegistry as unknown as PatchedRegistry);
+	});
+}

package/extensions/sort.ts

@@ -0,0 +1,263 @@
+/**
+ * Shared constants, types, and utilities for pi-model-sort.
+ */
+
+import { type SessionEntry, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+
+/** Default config file name (placed in ~/.pi/agent/extensions/). */
+export const CONFIG_FILENAME = "pi-model-sort.json";
+
+/** Thinking levels supported by pi. Mirrors ThinkingLevel from pi-agent-core. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/** All valid thinking levels, ascending. */
+export const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+/** Type guard for ThinkingLevel. */
+export function isThinkingLevel(value: unknown): value is ThinkingLevel {
+	return typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export interface ModelSortConfig {
+	/** Map of "provider/modelId" → last-used Unix timestamp (ms). */
+	lastUsed: Record<string, number>;
+	/** Map of "provider/modelId" → last-used thinking level. */
+	thinking: Record<string, ThinkingLevel>;
+}
+
+/**
+ * Parse a raw config file payload into a ModelSortConfig, dropping malformed
+ * entries. Unknown fields are ignored; missing fields default to empty maps.
+ */
+export function parseConfig(raw: unknown): ModelSortConfig {
+	const config: ModelSortConfig = { lastUsed: {}, thinking: {} };
+	if (typeof raw !== "object" || raw === null) return config;
+
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.lastUsed === "object" && obj.lastUsed !== null) {
+		for (const [key, value] of Object.entries(obj.lastUsed)) {
+			if (typeof value === "number" && Number.isFinite(value)) {
+				config.lastUsed[key] = value;
+			}
+		}
+	}
+	if (typeof obj.thinking === "object" && obj.thinking !== null) {
+		for (const [key, value] of Object.entries(obj.thinking)) {
+			if (isThinkingLevel(value)) {
+				config.thinking[key] = value;
+			}
+		}
+	}
+	return config;
+}
+
+/** Parse a model key into [provider, modelId]. Returns undefined if malformed. */
+export function parseModelKey(key: string): [provider: string, modelId: string] | undefined {
+	const idx = key.indexOf("/");
+	if (idx === -1) return undefined;
+	return [key.substring(0, idx), key.substring(idx + 1)];
+}
+
+/** Build a stable model key from provider and model id. */
+export function buildModelKey(provider: string, modelId: string): string {
+	return `${provider}/${modelId}`;
+}
+
+/** Reasons pi reports for session_start events. */
+export type SessionStartReason = "startup" | "reload" | "new" | "resume" | "fork";
+
+/**
+ * Whether the session branch produces context messages — pi core's own
+ * continuation predicate (`buildSessionContext().messages.length > 0`).
+ *
+ * pi seeds every NEW session with `model_change` and `thinking_level_change`
+ * entries during `createAgentSession` — BEFORE extensions are bound and
+ * `session_start` fires (installed pi 0.84.3, dist/core/sdk.js:241-252) — so
+ * raw branch length is always > 0 by the time extensions observe it. Context
+ * messages come from more than literal `message` entries: pi's
+ * `sessionEntryToContextMessages` also projects `custom_message`, non-empty
+ * `branch_summary`, and `compaction` entries (dist/core/session-manager.js:
+ * 162-188), so a summarized branch with no literal message still counts as
+ * continued for core — and must for us too.
+ */
+export function hasContextMessages(entries: readonly SessionEntry[]): boolean {
+	return entries.flatMap(sessionEntryToContextMessages).length > 0;
+}
+
+/**
+ * Whether the MRU (most recently used) startup override should apply for a
+ * session start.
+ *
+ * Fresh starts and `/new` switch to the most recently used model. A continued
+ * session (`pi -c`, `--session`) has already restored the model saved in its
+ * session file — the override is skipped so global MRU does not clobber it.
+ * `/resume` and forked sessions keep the session's own model as well.
+ *
+ * @param reason session_start reason reported by pi
+ * @param hasSessionMessages whether the session branch produces context messages
+ */
+export function shouldApplyMruOverride(reason: SessionStartReason, hasSessionMessages: boolean): boolean {
+	if (reason === "startup" && hasSessionMessages) return false;
+	return reason === "startup" || reason === "new";
+}
+
+/**
+ * Whether the model pi restored for this session start should be recorded as
+ * last-used. Pi 0.84.3 restores a continued session's model during
+ * construction without emitting `model_select`, so recency would otherwise
+ * never update for continuations.
+ *
+ * Only starts of a session that already carries context count (continued
+ * `startup`, `resume`, `fork`). "new" is excluded — a fresh session has no
+ * restored model even when a `setup` hook appended messages before
+ * `session_start`. "reload" is excluded — it rebuilds the extension runner
+ * around the same live session without a construction-time restore, and the
+ * active model was already recorded when it became active.
+ *
+ * @param reason session_start reason reported by pi
+ * @param hasSessionMessages whether the session branch produces context messages
+ */
+export function shouldTimestampRestoredModel(reason: SessionStartReason, hasSessionMessages: boolean): boolean {
+	if (!hasSessionMessages) return false;
+	return reason === "startup" || reason === "resume" || reason === "fork";
+}
+
+/**
+ * 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;
+}
+
+/**
+ * MRU model lookup — finds the most recently used model that exists in the
+ * registry and has auth configured. Returns undefined if no usable model is
+ * found. `find`/`hasConfiguredAuth` match the pi 0.84.3 ModelRegistry
+ * extension facade surface.
+ */
+export function findMruModel(
+	lastUsed: Record<string, number>,
+	registry: { find(provider: string, modelId: string): unknown; hasConfiguredAuth(model: unknown): boolean },
+): unknown | undefined {
+	const sorted = Object.entries(lastUsed).sort(([, a], [, b]) => b - a);
+	for (const [key] of sorted) {
+		const parsed = parseModelKey(key);
+		if (!parsed) continue;
+		const [provider, modelId] = parsed;
+		const model = registry.find(provider, modelId);
+		if (model && registry.hasConfiguredAuth(model)) {
+			return model;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Per-model thinking-level memory.
+ *
+ * Pi keeps one global thinking level: on every model switch it carries the
+ * current level over and clamps it to the new model's capabilities, so each
+ * model needs manual re-adjustment. This tracker records the last level used
+ * per model and computes which level to restore on switch.
+ *
+ * Attribution relies on pi's event ordering: setModel/cycle swap the model
+ * and re-clamp the level (emitting thinking_level_select) *before* emitting
+ * model_select. So when a thinking_level_select arrives whose current model
+ * no longer matches the tracked active model, the change belongs to a switch:
+ * previousLevel is the final level of the model being left (recorded), while
+ * the new level is inherited rather than chosen (not recorded).
+ */
+export interface ThinkingTrackerState {
+	/** Persisted map of "provider/modelId" → last-used thinking level. */
+	thinking: Record<string, ThinkingLevel>;
+	/** Key of the model last accounted for (session start or last model_select). */
+	activeKey: string | null;
+	/** Whether a switch-time re-clamp fired since the last model_select. */
+	sawSwitchClamp: boolean;
+}
+
+export function createThinkingTracker(): ThinkingTrackerState {
+	return { thinking: {}, activeKey: null, sawSwitchClamp: false };
+}
+
+function recordLevel(state: ThinkingTrackerState, key: string, level: ThinkingLevel): boolean {
+	if (state.thinking[key] === level) return false;
+	state.thinking[key] = level;
+	return true;
+}
+
+/**
+ * Record a thinking_level_select event. currentKey is the model pi reports as
+ * active at event time. Returns true when the thinking map changed.
+ */
+export function recordThinkingSelect(
+	state: ThinkingTrackerState,
+	currentKey: string | null,
+	level: ThinkingLevel,
+	previousLevel: ThinkingLevel,
+): boolean {
+	if (currentKey !== null && state.activeKey !== null && currentKey !== state.activeKey) {
+		state.sawSwitchClamp = true;
+		return recordLevel(state, state.activeKey, previousLevel);
+	}
+	const key = currentKey ?? state.activeKey;
+	if (key === null) return false;
+	return recordLevel(state, key, level);
+}
+
+/**
+ * Account for a model_select event and decide which level to restore, if any.
+ * currentLevel is the session's thinking level after pi's switch-time clamp.
+ * Sets activeKey to newKey — callers must apply the returned level afterwards
+ * (via pi.setThinkingLevel) so the emitted thinking_level_select attributes
+ * the effective, possibly further-clamped level to the new model.
+ */
+export function handleModelSelect(
+	state: ThinkingTrackerState,
+	newKey: string,
+	previousKey: string | null,
+	currentLevel: ThinkingLevel,
+): ThinkingLevel | null {
+	// No re-clamp during the switch means the level carried over unchanged, so
+	// currentLevel is also the previous model's final level. When a re-clamp did
+	// fire, recordThinkingSelect already stored the previous model's level.
+	if (previousKey !== null && !state.sawSwitchClamp) {
+		recordLevel(state, previousKey, currentLevel);
+	}
+	state.sawSwitchClamp = false;
+	state.activeKey = newKey;
+
+	const remembered = state.thinking[newKey];
+	if (remembered === undefined || remembered === currentLevel) return null;
+	return remembered;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@benvargas/pi-model-sort",
+  "version": "1.0.0",
+  "description": "Sort models in pi by last usage and start fresh sessions on the most recently used model",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "model",
+    "sort",
+    "mru",
+    "last-used",
+    "model-selector",
+    "thinking-level"
+  ],
+  "type": "module",
+  "files": [
+    "extensions/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ben-vargas/pi-packages.git",
+    "directory": "packages/pi-model-sort"
+  },
+  "author": "Ben Vargas",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ben-vargas/pi-packages/issues"
+  },
+  "homepage": "https://github.com/ben-vargas/pi-packages/tree/main/packages/pi-model-sort#readme"
+}