@andares/pi-toolkits 0.1.0 → 0.3.0

package/src/features/favorites/patch-cycle.ts

@@ -0,0 +1,165 @@
+/**
+ * favorites feature — AgentSession.cycleModel patch.
+ *
+ * ctrl+p / ctrl+shift+p keep their keybindings (they are reserved built-ins
+ * that extensions cannot rebind); instead we change the semantics of the
+ * cycle itself. When `cycleOnlyFavorites` (default true) is set AND at least
+ * one favorite exists, cycling is restricted to favorited models:
+ *
+ *  - candidates come from the same source stock cycling would use (scoped
+ *    models if any, else the available-model snapshot), filtered to favorites
+ *  - if the current model is not a favorite: forward jumps to the first
+ *    favorite, backward to the last (user-confirmed)
+ *  - with exactly one favorite, already on it → undefined (stock "only one
+ *    model available" feedback); otherwise jump to it
+ *  - the apply logic mirrors _cycleAvailableModel (state swap, session +
+ *    settings persistence, thinking-level re-clamp, model_select emit with
+ *    source "cycle")
+ *
+ * Version guard: missing cycleModel → warn and skip; the patch is idempotent
+ * across /reload.
+ */
+import {
+	AgentSession,
+	type ModelCycleResult,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { getFavoritesStore, modelKey } from "./store.js";
+
+/**
+ * Structural view of the AgentSession internals the patch touches.
+ * AgentSession's members are TS-private (compile-time only), so this view is
+ * safe to use as the patched method's `this` type at runtime.
+ */
+interface CycleSessionInternals {
+	// pi-lens-ignore: no-any-type, — pi's Model generic requires `any` (constraint is Api); pi itself uses Model<any> everywhere
+	_scopedModels: ReadonlyArray<{ model: Model<any>; thinkingLevel?: string }>;
+	// pi-lens-ignore: no-any-type, — same as above
+	_modelRuntime: { getAvailableSnapshot(): Model<any>[] };
+	// pi-lens-ignore: no-any-type, — same as above
+	model: Model<any>;
+	agent: { state: { model: unknown } };
+	sessionManager: { appendModelChange(provider: string, id: string): void };
+	settingsManager: {
+		setDefaultModelAndProvider(provider: string, id: string): void;
+	};
+	setThinkingLevel(level: unknown): void;
+	_getThinkingLevelForModelSwitch(
+		explicitLevel?: string,
+	): ModelCycleResult["thinkingLevel"] | undefined;
+	_emitModelSelect(
+		next: unknown,
+		previous: unknown,
+		source: "cycle",
+	): Promise<void>;
+	thinkingLevel: ModelCycleResult["thinkingLevel"];
+}
+
+interface CycleCandidate {
+	// pi-lens-ignore: no-any-type, — matches pi's Model<any> API
+	model: Model<any>;
+	thinkingLevel?: string;
+}
+
+/**
+ * Index of the next favorite to cycle to.
+ *
+ * When the current model is not a favorite (`currentIndex === -1`), forward
+ * jumps to the first favorite and backward to the last (user-confirmed
+ * behavior); otherwise standard wrap-around modulo arithmetic applies.
+ */
+function nextCycleIndex(
+	currentIndex: number,
+	direction: "forward" | "backward",
+	len: number,
+): number {
+	if (currentIndex === -1) {
+		return direction === "forward" ? 0 : len - 1;
+	}
+	return direction === "forward"
+		? (currentIndex + 1) % len
+		: (currentIndex - 1 + len) % len;
+}
+
+let patched = false;
+
+/** Restrict ctrl+p cycling to favorites. Idempotent; returns false if skipped. */
+export function applyCyclePatch(): boolean {
+	if (patched) return true;
+	const proto = AgentSession.prototype as unknown as {
+		cycleModel(
+			this: CycleSessionInternals,
+			direction?: "forward" | "backward",
+		): Promise<ModelCycleResult | undefined>;
+	};
+	if (typeof proto.cycleModel !== "function") {
+		// pi-lens-ignore: no-console-except-error,console-statement, — intentional degradation log
+		console.warn(
+			"[pi-toolkits/favorites] AgentSession.cycleModel missing; cycle patch skipped.",
+		);
+		return false;
+	}
+	patched = true;
+	const original = proto.cycleModel;
+
+	proto.cycleModel = async function (
+		this: CycleSessionInternals,
+		direction: "forward" | "backward" = "forward",
+	): Promise<ModelCycleResult | undefined> {
+		if (
+			!getFavoritesStore().getConfig().cycleOnlyFavorites ||
+			!getFavoritesStore().hasAny()
+		) {
+			return original.call(this, direction);
+		}
+
+		const scoped = this._scopedModels.length > 0;
+		const candidates: CycleCandidate[] = scoped
+			? this._scopedModels.map((sm) => ({
+					model: sm.model,
+					thinkingLevel: sm.thinkingLevel,
+				}))
+			: this._modelRuntime
+					.getAvailableSnapshot()
+					.map((model) => ({ model, thinkingLevel: undefined }));
+		const favorites = candidates.filter((candidate) =>
+			getFavoritesStore().has(candidate.model),
+		);
+		if (favorites.length === 0) {
+			// No favorites among the current source — fall back to stock cycling.
+			return original.call(this, direction);
+		}
+
+		const current = this.model;
+		const currentIndex = favorites.findIndex(
+			(candidate) => modelKey(candidate.model) === modelKey(current),
+		);
+
+		// Already on the only favorite — nothing to cycle to.
+		if (currentIndex !== -1 && favorites.length === 1) {
+			return undefined;
+		}
+		const nextIndex = nextCycleIndex(currentIndex, direction, favorites.length);
+
+		const next = favorites[nextIndex];
+		const thinkingLevel =
+			scoped && next.thinkingLevel !== undefined
+				? this._getThinkingLevelForModelSwitch(next.thinkingLevel)
+				: this._getThinkingLevelForModelSwitch();
+		this.agent.state.model = next.model;
+		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
+		this.settingsManager.setDefaultModelAndProvider(
+			next.model.provider,
+			next.model.id,
+		);
+		this.setThinkingLevel(thinkingLevel);
+		await this._emitModelSelect(next.model, current, "cycle");
+		return {
+			model: next.model,
+			thinkingLevel: this.thinkingLevel,
+			isScoped: scoped,
+		};
+	};
+
+	return true;
+}

package/src/features/favorites/patch-selector.ts

@@ -0,0 +1,300 @@
+/**
+ * favorites feature — ModelSelectorComponent patches.
+ *
+ * pi's extension API has no hook to render inside the built-in model
+ * selector, so we patch the component prototype at runtime. Three hooks:
+ *
+ *  1. handleInput  — intercept ctrl+f (toggle favorite for the selected
+ *                    model) and ctrl+j (toggle "only favorites" filter)
+ *                    BEFORE the original forwards them to the search box.
+ *                    Scoped to the selector: outside it, ctrl+f/ctrl+j keep
+ *                    pi's default editor bindings untouched.
+ *  2. updateList   — inject a hint row at the top of the selector and render
+ *                    favorited model ids in bold bright yellow.
+ *  3. filterModels — when "only favorites" is on, temporarily swap
+ *                    activeModels for the favorites subset so the original
+ *                    fuzzy-filter/selection logic runs on it (zero
+ *                    duplication); every path (search typing, scope toggle,
+ *                    catalog refresh) converges here.
+ *
+ * Version guard: if the prototype no longer has the expected methods (pi
+ * upgraded internals), patches are skipped with a warning — the extension
+ * keeps loading and ctrl+p falls back to stock behavior.
+ */
+import {
+	ModelSelectorComponent,
+	rawKeyHint,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { matchesKey, Spacer, Text } from "@earendil-works/pi-tui";
+import {
+	FAVORITES_ONLY_KEY,
+	FAVORITE_TOGGLE_KEY,
+	styleFavorite,
+} from "./constants.js";
+import { getFavoritesStore } from "./store.js";
+
+/** Minimal structural views of the built-in internals we touch. */
+interface ModelRef {
+	provider: string;
+	id: string;
+	name?: string;
+}
+interface ModelItem {
+	provider: string;
+	id: string;
+	model: ModelRef;
+}
+interface SearchInputLike {
+	getValue(): string;
+}
+interface ListContainerLike {
+	clear(): void;
+	addChild(child: unknown): void;
+}
+
+/** The patched prototype surface (public structural view, no private clash). */
+interface SelectorPatchTarget {
+	handleInput(keyData: string): void;
+	updateList(): void;
+	filterModels(query: string): void;
+	listContainer: ListContainerLike;
+	searchInput: SearchInputLike;
+	filteredModels: ModelItem[];
+	activeModels: ModelItem[];
+	selectedIndex: number;
+	currentModel: ModelRef | undefined;
+	errorMessage?: string;
+	refreshStatusMessage?: string;
+	refreshStatusSuccess?: boolean;
+	tui: { requestRender(): void };
+	children: unknown[];
+	// favorites state injected onto instances
+	__favoritesOnly?: boolean;
+	__favoritesHint?: Text;
+	ensureFavoritesHint(): void;
+	handleFavoriteToggle(): void;
+	toggleFavoritesOnly(): void;
+}
+
+let themeProvider: () => Theme | undefined = () => undefined;
+
+/** Called by registerFavorites once the live theme proxy is available. */
+export function setSelectorThemeProvider(
+	provider: () => Theme | undefined,
+): void {
+	themeProvider = provider;
+}
+
+function sameModel(a: ModelRef, b: ModelRef): boolean {
+	return a.provider === b.provider && a.id === b.id;
+}
+
+function buildHintText(state: SelectorPatchTarget): string {
+	const theme = themeProvider();
+	if (!theme) return "";
+	const keys = `${rawKeyHint(FAVORITE_TOGGLE_KEY, "favorite")} · ${rawKeyHint(FAVORITES_ONLY_KEY, "only-favorites")}`;
+	const mode = state.__favoritesOnly
+		? theme.fg("success", " [ON]")
+		: theme.fg("muted", " [OFF]");
+	const count = getFavoritesStore().count();
+	const countText = theme.fg(
+		"dim",
+		count > 0 ? ` · ${count} favorited` : " · none favorited",
+	);
+	return theme.fg("muted", "Favorites: ") + keys + mode + countText;
+}
+
+let patched = false;
+
+/** Apply the three selector patches. Idempotent; returns false if skipped. */
+export function applyModelSelectorPatches(): boolean {
+	if (patched) return true;
+	const proto =
+		ModelSelectorComponent.prototype as unknown as SelectorPatchTarget;
+	if (
+		typeof proto.handleInput !== "function" ||
+		typeof proto.updateList !== "function" ||
+		typeof proto.filterModels !== "function"
+	) {
+		// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+		console.warn(
+			"[pi-toolkits/favorites] ModelSelectorComponent API changed; model selector patches skipped.",
+		);
+		return false;
+	}
+	patched = true;
+
+	const originalHandleInput = proto.handleInput;
+	const originalUpdateList = proto.updateList;
+	const originalFilterModels = proto.filterModels;
+
+	// ── 1. Key interception (ctrl+f / ctrl+j) ─────────────────────────────
+	proto.handleInput = function (
+		this: SelectorPatchTarget,
+		keyData: string,
+	): void {
+		if (matchesKey(keyData, FAVORITE_TOGGLE_KEY)) {
+			this.handleFavoriteToggle();
+			return;
+		}
+		if (matchesKey(keyData, FAVORITES_ONLY_KEY)) {
+			this.toggleFavoritesOnly();
+			return;
+		}
+		originalHandleInput.call(this, keyData);
+	};
+
+	// ── 2. List rendering: hint row + bold bright yellow favorites ────────
+	// Replicates the built-in updateList layout (current-model check, selected
+	// row, scroll indicator, empty/error states, refresh status) with one
+	// change: favorited model ids render in the favorite style.
+	proto.updateList = function (this: SelectorPatchTarget): void {
+		const theme = themeProvider();
+		if (!theme) {
+			// Degraded path (theme not captured yet / non-TUI): stock rendering.
+			originalUpdateList.call(this);
+			return;
+		}
+		this.ensureFavoritesHint();
+		const list = this.listContainer;
+		list.clear();
+		const maxVisible = 10;
+		const startIndex = Math.max(
+			0,
+			Math.min(
+				this.selectedIndex - Math.floor(maxVisible / 2),
+				this.filteredModels.length - maxVisible,
+			),
+		);
+		const endIndex = Math.min(
+			startIndex + maxVisible,
+			this.filteredModels.length,
+		);
+		for (let i = startIndex; i < endIndex; i++) {
+			const item = this.filteredModels[i];
+			if (!item) continue;
+			const isSelected = i === this.selectedIndex;
+			const isCurrent =
+				this.currentModel !== undefined &&
+				sameModel(item.model, this.currentModel);
+			const isFavorite = getFavoritesStore().has(item.model);
+			let line: string;
+			if (isSelected) {
+				const prefix = theme.fg("accent", "→ ");
+				const modelText = isFavorite
+					? styleFavorite(item.id)
+					: theme.fg("accent", item.id);
+				const providerBadge = theme.fg("muted", `[${item.provider}]`);
+				const checkmark = isCurrent ? theme.fg("success", " ✓") : "";
+				line = `${prefix + modelText} ${providerBadge}${checkmark}`;
+			} else {
+				const modelText = isFavorite
+					? `  ${styleFavorite(item.id)}`
+					: `  ${item.id}`;
+				const providerBadge = theme.fg("muted", `[${item.provider}]`);
+				const checkmark = isCurrent ? theme.fg("success", " ✓") : "";
+				line = `${modelText} ${providerBadge}${checkmark}`;
+			}
+			list.addChild(new Text(line, 0, 0));
+		}
+		if (startIndex > 0 || endIndex < this.filteredModels.length) {
+			const scrollInfo = theme.fg(
+				"muted",
+				`  (${this.selectedIndex + 1}/${this.filteredModels.length})`,
+			);
+			list.addChild(new Text(scrollInfo, 0, 0));
+		}
+		if (this.errorMessage) {
+			for (const line of this.errorMessage.split("\n")) {
+				list.addChild(new Text(theme.fg("error", line), 0, 0));
+			}
+		} else if (this.filteredModels.length === 0) {
+			list.addChild(new Text(theme.fg("muted", "  No matching models"), 0, 0));
+		} else {
+			const selected = this.filteredModels[this.selectedIndex];
+			list.addChild(new Spacer(1));
+			list.addChild(
+				new Text(
+					theme.fg("muted", `  Model Name: ${selected.model.name}`),
+					0,
+					0,
+				),
+			);
+		}
+		if (this.refreshStatusMessage) {
+			list.addChild(new Spacer(1));
+			list.addChild(
+				new Text(
+					theme.fg(
+						this.refreshStatusSuccess ? "success" : "muted",
+						`  ${this.refreshStatusMessage}`,
+					),
+					0,
+					0,
+				),
+			);
+		}
+	};
+
+	// ── 3. "Only favorites" filter ────────────────────────────────────────
+	// Swap activeModels for the favorites subset around the original call so
+	// the built-in fuzzy-filter + selection-index logic runs on the subset.
+	proto.filterModels = function (
+		this: SelectorPatchTarget,
+		query: string,
+	): void {
+		if (this.__favoritesOnly) {
+			const saved = this.activeModels;
+			this.activeModels = saved.filter((item) =>
+				getFavoritesStore().has(item.model),
+			);
+			try {
+				originalFilterModels.call(this, query);
+			} finally {
+				this.activeModels = saved;
+			}
+		} else {
+			originalFilterModels.call(this, query);
+		}
+	};
+
+	// ── helpers injected onto the prototype ───────────────────────────────
+	proto.ensureFavoritesHint = function (this: SelectorPatchTarget): void {
+		if (this.__favoritesHint) return;
+		const theme = themeProvider();
+		if (!theme) return;
+		const hint = new Text(buildHintText(this), 0, 0);
+		// children: [0]=top border, [1]=spacer, then provider/scope hint rows…
+		this.children.splice(2, 0, hint);
+		this.__favoritesHint = hint;
+	};
+
+	proto.handleFavoriteToggle = function (this: SelectorPatchTarget): void {
+		const selected = this.filteredModels[this.selectedIndex];
+		if (!selected) return;
+		const nowFavorite = getFavoritesStore().toggle(selected.model);
+		if (this.__favoritesHint) {
+			this.__favoritesHint.setText(buildHintText(this));
+		}
+		if (this.__favoritesOnly && !nowFavorite) {
+			// Un-favorited while the favorites-only filter is on: drop it from
+			// the list immediately.
+			this.filterModels(this.searchInput.getValue());
+		} else {
+			this.updateList();
+		}
+		this.tui.requestRender();
+	};
+
+	proto.toggleFavoritesOnly = function (this: SelectorPatchTarget): void {
+		this.__favoritesOnly = !this.__favoritesOnly;
+		if (this.__favoritesHint) {
+			this.__favoritesHint.setText(buildHintText(this));
+		}
+		this.filterModels(this.searchInput.getValue());
+		this.tui.requestRender();
+	};
+
+	return true;
+}

package/src/features/favorites/store.ts

@@ -0,0 +1,197 @@
+/**
+ * favorites feature — persisted favorites store.
+ *
+ * State lives in `<agent-dir>/pi-toolkits-favorites.json` (agent-dir from
+ * getAgentDir(), same convention as @cnife/pi-auto-naming-session's config
+ * file). Favorites are global across projects and sessions.
+ *
+ * File shape:
+ *   {
+ *     "favorites": ["anthropic/claude-sonnet-4", "openrouter/openai/gpt-5"],
+ *     "config": { "cycleOnlyFavorites": true }
+ *   }
+ *
+ * `cycleOnlyFavorites` (default true) gates the ctrl+p favorites-only
+ * cycling behavior — set it to false in the JSON to restore full cycling.
+ *
+ * Robustness: corrupted/unreadable files fall back to an empty set + default
+ * config with a console.warn; writes are atomic (tmp file + rename) and
+ * failures are logged, never thrown.
+ */
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { FAVORITES_FILE } from "./constants.js";
+
+export interface FavoritesConfig {
+	/** When true (default), ctrl+p / ctrl+shift+p cycle only favorited models. */
+	cycleOnlyFavorites: boolean;
+}
+
+export interface FavoritesSnapshot {
+	favorites: string[];
+	config: FavoritesConfig;
+}
+
+const DEFAULT_CONFIG: FavoritesConfig = { cycleOnlyFavorites: true };
+
+/** Model identity used as the favorites key: "provider/id". */
+export function modelKey(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export class FavoritesStore {
+	private favorites = new Set<string>();
+	private config: FavoritesConfig = { ...DEFAULT_CONFIG };
+	private readonly file: string;
+	private loaded = false;
+	private readonly listeners = new Set<() => void>();
+
+	constructor(file: string = join(getAgentDir(), FAVORITES_FILE)) {
+		this.file = file;
+	}
+
+	private ensureLoaded(): void {
+		if (this.loaded) return;
+		this.loaded = true;
+		try {
+			if (!existsSync(this.file)) {
+				this.save();
+				return;
+			}
+			const raw = readFileSync(this.file, "utf8");
+			const parsed = JSON.parse(raw) as Partial<FavoritesSnapshot>;
+			if (parsed && Array.isArray(parsed.favorites)) {
+				for (const id of parsed.favorites) {
+					if (typeof id === "string" && id.includes("/")) {
+						this.favorites.add(id);
+					}
+				}
+			}
+			if (parsed && parsed.config && typeof parsed.config === "object") {
+				const cfg = parsed.config as Partial<FavoritesConfig>;
+				if (typeof cfg.cycleOnlyFavorites === "boolean") {
+					this.config.cycleOnlyFavorites = cfg.cycleOnlyFavorites;
+				}
+			}
+		} catch (error) {
+			// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+			console.warn(
+				"[pi-toolkits/favorites] Failed to load favorites file, starting empty:",
+				error instanceof Error ? error.message : String(error),
+			);
+			this.favorites.clear();
+			this.config = { ...DEFAULT_CONFIG };
+		}
+	}
+
+	/** Atomically persist (tmp + rename). Never throws. */
+	save(): void {
+		try {
+			const dir = dirname(this.file);
+			if (!existsSync(dir)) {
+				mkdirSync(dir, { recursive: true });
+			}
+			const tmp = `${this.file}.tmp`;
+			const data: FavoritesSnapshot = {
+				// Explicit comparator: keys are "provider/id" strings, sorted
+				// lexicographically for a deterministic state file.
+				favorites: [...this.favorites].sort((a, b) => a.localeCompare(b)),
+				config: this.config,
+			};
+			writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+			renameSync(tmp, this.file);
+		} catch (error) {
+			// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+			console.warn(
+				"[pi-toolkits/favorites] Failed to save favorites file:",
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+	}
+
+	has(model: { provider: string; id: string }): boolean {
+		this.ensureLoaded();
+		return this.favorites.has(modelKey(model));
+	}
+
+	hasAny(): boolean {
+		this.ensureLoaded();
+		return this.favorites.size > 0;
+	}
+
+	count(): number {
+		this.ensureLoaded();
+		return this.favorites.size;
+	}
+
+	list(): string[] {
+		this.ensureLoaded();
+		return [...this.favorites].sort((a, b) => a.localeCompare(b));
+	}
+
+	/** Toggle favorite for a model. Returns true if it is now favorited. */
+	toggle(model: { provider: string; id: string }): boolean {
+		this.ensureLoaded();
+		const key = modelKey(model);
+		let nowFavorite: boolean;
+		if (this.favorites.has(key)) {
+			this.favorites.delete(key);
+			nowFavorite = false;
+		} else {
+			this.favorites.add(key);
+			nowFavorite = true;
+		}
+		this.save();
+		this.notify();
+		return nowFavorite;
+	}
+
+	getConfig(): FavoritesConfig {
+		this.ensureLoaded();
+		return { ...this.config };
+	}
+
+	subscribe(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+
+	private notify(): void {
+		for (const listener of [...this.listeners]) {
+			try {
+				listener();
+			} catch {
+				// A broken listener must not break favorites handling.
+			}
+		}
+	}
+}
+
+/**
+ * Process-wide store shared by the selector/cycle patches and commands.
+ *
+ * Accessed via getFavoritesStore() (lazy) so tests can swap in an isolated
+ * store via setSharedFavoritesStore().
+ */
+let sharedStore: FavoritesStore | undefined;
+
+export function getFavoritesStore(): FavoritesStore {
+	if (!sharedStore) {
+		sharedStore = new FavoritesStore();
+	}
+	return sharedStore;
+}
+
+/** Test hook — replace the shared store (e.g. with one backed by a temp file). */
+export function setSharedFavoritesStore(store: FavoritesStore): void {
+	sharedStore = store;
+}

package/src/features/review/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * review feature — constants.
+ *
+ * The review-model config lives in `<agent-dir>/pi-toolkits-review.json`
+ * (same agent-dir convention as the favorites store) and holds a single
+ * model key `"provider/id"` — see store.ts.
+ */
+
+/** Config file name inside the pi agent dir. */
+export const REVIEW_FILE = "pi-toolkits-review.json";
+
+/** Footer status key shown while a review model is configured. */
+export const REVIEW_STATUS_KEY = "review";