@andares/pi-toolkits 0.3.1 → 0.4.1

package/src/features/compact/store.ts

@@ -0,0 +1,137 @@
+/**
+ * compact-model feature — persisted compact-model config store.
+ *
+ * State lives in `<agent-dir>/pi-toolkits-compact.json` (agent-dir from
+ * getAgentDir(), same convention as the review store). The file holds a
+ * single model key:
+ *
+ *   { "model": "google/gemini-2.5-flash" }
+ *
+ * Unset = feature disabled: every compaction (manual /compact, auto-compact
+ * threshold, overflow recovery) uses pi's default behavior with the current
+ * session model, zero overhead.
+ *
+ * Robustness mirrors the review store: corrupted/unreadable files fall back
+ * to "no model configured" with a console.warn; writes are atomic
+ * (tmp + rename) and never throw.
+ */
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { COMPACT_FILE } from "./constants.js";
+
+export class CompactStore {
+	private model: string | undefined;
+	private readonly file: string;
+	private loaded = false;
+	private readonly listeners = new Set<() => void>();
+
+	constructor(file: string = join(getAgentDir(), COMPACT_FILE)) {
+		this.file = file;
+	}
+
+	private ensureLoaded(): void {
+		if (this.loaded) return;
+		this.loaded = true;
+		try {
+			if (!existsSync(this.file)) return;
+			const raw = readFileSync(this.file, "utf8");
+			const parsed = JSON.parse(raw) as { model?: unknown };
+			if (
+				parsed &&
+				typeof parsed.model === "string" &&
+				parsed.model.includes("/")
+			) {
+				this.model = parsed.model;
+			}
+		} catch (error) {
+			// pi-lens-ignore: no-console-except-error,console-statement, — deliberate degradation log
+			console.warn(
+				"[pi-toolkits/compact] Failed to load compact-model config, starting unset:",
+				error instanceof Error ? error.message : String(error),
+			);
+			this.model = undefined;
+		}
+	}
+
+	/** 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`;
+			writeFileSync(
+				tmp,
+				`${JSON.stringify({ model: this.model ?? null }, 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/compact] Failed to save compact-model config:",
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+	}
+
+	/** The configured compact model key ("provider/id"), or undefined. */
+	getModel(): string | undefined {
+		this.ensureLoaded();
+		return this.model;
+	}
+
+	/** Set (or clear with undefined) the compact model key and persist. */
+	setModel(key: string | undefined): void {
+		this.ensureLoaded();
+		this.model = key;
+		this.save();
+		this.notify();
+	}
+
+	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 compact config handling.
+			}
+		}
+	}
+}
+
+/**
+ * Process-wide store shared by the session_before_compact handler and the
+ * /compact-model command.
+ *
+ * Accessed via getCompactStore() (lazy) so tests can swap in an isolated
+ * store via setSharedCompactStore().
+ */
+let sharedStore: CompactStore | undefined;
+
+export function getCompactStore(): CompactStore {
+	if (!sharedStore) {
+		sharedStore = new CompactStore();
+	}
+	return sharedStore;
+}
+
+/** Test hook — replace the shared store (e.g. with one backed by a temp file). */
+export function setSharedCompactStore(store: CompactStore): void {
+	sharedStore = store;
+}

package/src/features/favorites/index.ts

@@ -27,6 +27,8 @@
 import type {
 	ExtensionAPI,
 	ExtensionContext,
+	ModelSelectEvent,
+	SessionStartEvent,
 	Theme,
 } from "@earendil-works/pi-coding-agent";
 import { FAVORITES_STATUS_KEY } from "./constants.js";
@@ -68,13 +70,13 @@ export function registerFavorites(pi: ExtensionAPI): void {
 	// selector. setStatus is idempotent and re-synced on every session_start.
 	let latestCtx: ExtensionContext | undefined;
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", (_event: SessionStartEvent, ctx: ExtensionContext) => {
 		latestCtx = ctx;
 		captureTheme(ctx);
 		updateFooterStatus(ctx);
 	});
 
-	pi.on("model_select", (_event, ctx) => {
+	pi.on("model_select", (_event: ModelSelectEvent, ctx: ExtensionContext) => {
 		captureTheme(ctx);
 		updateFooterStatus(ctx);
 	});
@@ -90,7 +92,7 @@ export function registerFavorites(pi: ExtensionAPI): void {
 
 	pi.registerCommand("favorites", {
 		description: "List favorited models (add/remove with ctrl+F in /model)",
-		handler: async (_args, ctx) => {
+		handler: async (_args: string, ctx: ExtensionContext) => {
 			captureTheme(ctx);
 			const list = getFavoritesStore().list();
 			if (list.length === 0) {

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

@@ -7,14 +7,16 @@
  * 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
+ *    models if any — filtered to currently available ones like stock —
+ *    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")
+ *  - the apply logic mirrors pi 0.87's _cycleScopedModel/_cycleAvailableModel
+ *    (state swap, session persistence, default-model persistence only when
+ *    `options.persist` is set, thinking-level re-clamp, model_select emit
+ *    with source "cycle")
  *
  * Version guard: missing cycleModel → warn and skip; the patch is idempotent
  * across /reload.
@@ -23,9 +25,17 @@ import {
 	AgentSession,
 	type ModelCycleResult,
 } from "@earendil-works/pi-coding-agent";
-import type { Model } from "@earendil-works/pi-ai";
 import { getFavoritesStore, modelKey } from "./store.js";
 
+/**
+ * pi's `Model<any>` — the exact type of `ModelCycleResult.model` in
+ * pi-coding-agent 0.87. Derived here instead of importing `Model` from
+ * @earendil-works/pi-ai, whose 0.87 index.d.ts re-exports it via an
+ * extensioned `"./types.ts"` specifier that not every TS resolver substitutes
+ * to `types.d.ts` (tsc 5.9 bundler does; other tsserver builds don't).
+ */
+type AnyModel = NonNullable<ModelCycleResult>["model"];
+
 /**
  * Structural view of the AgentSession internals the patch touches.
  * AgentSession's members are TS-private (compile-time only), so this view is
@@ -33,16 +43,21 @@ import { getFavoritesStore, modelKey } from "./store.js";
  */
 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 }>;
+	_scopedModels: ReadonlyArray<{ model: AnyModel; thinkingLevel?: string }>;
 	// pi-lens-ignore: no-any-type, — same as above
-	_modelRuntime: { getAvailableSnapshot(): Model<any>[] };
+	_modelRuntime: { getAvailableSnapshot(): AnyModel[] };
 	// pi-lens-ignore: no-any-type, — same as above
-	model: Model<any>;
+	model: AnyModel;
 	agent: { state: { model: unknown } };
 	sessionManager: { appendModelChange(provider: string, id: string): void };
 	settingsManager: {
 		setDefaultModelAndProvider(provider: string, id: string): void;
 	};
+	/**
+	 * pi 0.87: keeps a persisted default usable when cycling inside a
+	 * non-empty --models scope.
+	 */
+	_addPersistedDefaultToNonEmptyScope(model: unknown): void;
 	setThinkingLevel(level: unknown): void;
 	_getThinkingLevelForModelSwitch(
 		explicitLevel?: string,
@@ -56,8 +71,7 @@ interface CycleSessionInternals {
 }
 
 interface CycleCandidate {
-	// pi-lens-ignore: no-any-type, — matches pi's Model<any> API
-	model: Model<any>;
+	model: AnyModel;
 	thinkingLevel?: string;
 }
 
@@ -81,15 +95,24 @@ function nextCycleIndex(
 		: (currentIndex - 1 + len) % len;
 }
 
+/** Options accepted by pi 0.87's cycleModel (persist gates default-model persistence). */
+interface CycleOptions {
+	persist?: boolean;
+}
+
 let patched = false;
 
 /** Restrict ctrl+p cycling to favorites. Idempotent; returns false if skipped. */
 export function applyCyclePatch(): boolean {
 	if (patched) return true;
+	// SAFETY: AgentSession's members are TS-private (compile-time only), so a
+	// structural view of the runtime prototype is safe to cast to; guarded by
+	// the typeof check below before any patching happens.
 	const proto = AgentSession.prototype as unknown as {
 		cycleModel(
 			this: CycleSessionInternals,
 			direction?: "forward" | "backward",
+			options?: CycleOptions,
 		): Promise<ModelCycleResult | undefined>;
 	};
 	if (typeof proto.cycleModel !== "function") {
@@ -105,23 +128,34 @@ export function applyCyclePatch(): boolean {
 	proto.cycleModel = async function (
 		this: CycleSessionInternals,
 		direction: "forward" | "backward" = "forward",
+		options: CycleOptions = {},
 	): Promise<ModelCycleResult | undefined> {
 		if (
 			!getFavoritesStore().getConfig().cycleOnlyFavorites ||
 			!getFavoritesStore().hasAny()
 		) {
-			return original.call(this, direction);
+			return original.call(this, direction, options);
 		}
 
+		// Same source and availability filtering as pi 0.87's stock cycling.
 		const scoped = this._scopedModels.length > 0;
-		const candidates: CycleCandidate[] = scoped
-			? this._scopedModels.map((sm) => ({
-					model: sm.model,
-					thinkingLevel: sm.thinkingLevel,
-				}))
-			: this._modelRuntime
+		let candidates: CycleCandidate[];
+		if (scoped) {
+			const availableIds = new Set(
+				this._modelRuntime
 					.getAvailableSnapshot()
-					.map((model) => ({ model, thinkingLevel: undefined }));
+					.map((model) => `${model.provider}\0${model.id}`),
+			);
+			candidates = this._scopedModels.flatMap((sm) =>
+				availableIds.has(`${sm.model.provider}\0${sm.model.id}`)
+					? [{ model: sm.model, thinkingLevel: sm.thinkingLevel }]
+					: [],
+			);
+		} else {
+			candidates = this._modelRuntime
+				.getAvailableSnapshot()
+				.map((model) => ({ model, thinkingLevel: undefined }));
+		}
 		const favorites = candidates.filter((candidate) =>
 			getFavoritesStore().has(candidate.model),
 		);
@@ -148,10 +182,14 @@ export function applyCyclePatch(): boolean {
 				: 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,
-		);
+		// pi 0.87: only persist the default model when the caller asked for it.
+		if (options.persist) {
+			this.settingsManager.setDefaultModelAndProvider(
+				next.model.provider,
+				next.model.id,
+			);
+			this._addPersistedDefaultToNonEmptyScope(next.model);
+		}
 		this.setThinkingLevel(thinkingLevel);
 		await this._emitModelSelect(next.model, current, "cycle");
 		return {

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

@@ -58,6 +58,8 @@ interface SelectorPatchTarget {
 	handleInput(keyData: string): void;
 	updateList(): void;
 	filterModels(query: string): void;
+	/** pi 0.87: default-model badge source. */
+	isDefaultModel(model: ModelRef): boolean;
 	listContainer: ListContainerLike;
 	searchInput: SearchInputLike;
 	filteredModels: ModelItem[];
@@ -110,6 +112,9 @@ let patched = false;
 /** Apply the three selector patches. Idempotent; returns false if skipped. */
 export function applyModelSelectorPatches(): boolean {
 	if (patched) return true;
+	// SAFETY: ModelSelectorComponent's members are TS-private (compile-time
+	// only); the structural view matches pi 0.87's prototype shape and every
+	// touched method is existence-checked below before any patching happens.
 	const proto =
 		ModelSelectorComponent.prototype as unknown as SelectorPatchTarget;
 	if (
@@ -146,9 +151,10 @@ export function applyModelSelectorPatches(): boolean {
 	};
 
 	// ── 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.
+	// Replicates the built-in updateList layout (pi 0.87: fixed-width cursor
+	// and ✓ current-marker columns, provider badge, `· default` badge, scroll
+	// indicator, empty/error states, refresh status, Model Name footer) with
+	// one change: favorited model ids render in the favorite style.
 	proto.updateList = function (this: SelectorPatchTarget): void {
 		const theme = themeProvider();
 		if (!theme) {
@@ -178,24 +184,17 @@ export function applyModelSelectorPatches(): boolean {
 			const isCurrent =
 				this.currentModel !== undefined &&
 				sameModel(item.model, this.currentModel);
+			const isDefault = this.isDefaultModel(item.model);
 			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}`;
-			}
+			const defaultBadge = isDefault
+				? theme.fg("muted", " · default")
+				: "";
+			const cursor = isSelected ? theme.fg("accent", "→ ") : "  ";
+			const currentMarker = isCurrent ? theme.fg("accent", "✓ ") : "  ";
+			const baseText = isSelected ? theme.fg("accent", item.id) : item.id;
+			const modelText = isFavorite ? styleFavorite(item.id) : baseText;
+			const providerBadge = theme.fg("muted", `[${item.provider}]`);
+			const line = `${cursor}${currentMarker}${modelText} ${providerBadge}${defaultBadge}`;
 			list.addChild(new Text(line, 0, 0));
 		}
 		if (startIndex > 0 || endIndex < this.filteredModels.length) {

package/src/features/review/index.ts

@@ -11,11 +11,14 @@
  * model as ordinary text, so an accidental send can never start a review.)
  *
  * Review-model config lives in `<agent-dir>/pi-toolkits-review.json`
- * ("provider/id", see store.ts). When no model is configured, or the
- * configured model is gone/unavailable (e.g. deleted from pi's models.json),
- * the user is told the review model doesn't exist and is shown the available
- * model list (ctx.ui.select, same getAvailable() source as /model); the pick
- * is written back to the config and the review runs immediately.
+ * ("provider/id", see store.ts) and doubles as the picker default. Every
+ * /third-review run opens the model picker (ctx.ui.select, same
+ * getAvailable() source as /model) with the configured model as the FIRST
+ * row — one Enter accepts it and starts the review. Picking a different
+ * model persists it immediately (disk + in-memory) as the new default for
+ * next time; cancelling aborts the review without changing anything. When
+ * the configured model is gone/unavailable (e.g. deleted from pi's
+ * models.json) the user is warned and the picker opens on the plain list.
  *
  * Guards: never fires while the agent is streaming (the review needs the
  * just-finished work as context) and never runs two reviews concurrently.
@@ -23,39 +26,32 @@
 import type {
 	ExtensionAPI,
 	ExtensionContext,
+	SessionStartEvent,
 	Theme,
 } from "@earendil-works/pi-coding-agent";
-import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+	modelKey,
+	resolveConfiguredModel,
+	type AvailableModel,
+} from "../../lib/model-config.js";
 import { REVIEW_STATUS_KEY } from "./constants.js";
 import { REVIEW_PROMPT } from "./prompt.js";
-import { getReviewStore, modelKey, type ReviewStore } from "./store.js";
-
-/** Resolve the configured review model against the available model list. */
-export function resolveConfiguredModel(
-	ctx: ExtensionContext,
-	key: string | undefined,
-): Model<Api> | undefined {
-	if (!key) return undefined;
-	const slash = key.indexOf("/");
-	if (slash <= 0 || slash === key.length - 1) return undefined;
-	const provider = key.slice(0, slash);
-	const id = key.slice(slash + 1);
-	return ctx.modelRegistry
-		.getAvailable()
-		.find((m) => m.provider === provider && m.id === id);
-}
+import { getReviewStore, type ReviewStore } from "./store.js";
 
 /**
  * Let the user pick a review model from the available list and persist the
  * choice. Returns the picked model, or undefined when cancelled/unavailable.
  *
- * The picker title shows the current config so /review-model doubles as a
- * view-and-change entry point; cancelling leaves the config untouched.
+ * The configured model is placed FIRST: the select dialog always highlights
+ * its first row, so one Enter accepts the current default. Picking any other
+ * model persists it (disk + in-memory) as the new default. The title shows
+ * the current config, so /review-model doubles as a view-and-change entry
+ * point; cancelling leaves the config untouched.
  */
 export async function pickReviewModel(
 	ctx: ExtensionContext,
 	store: ReviewStore,
-): Promise<Model<Api> | undefined> {
+): Promise<AvailableModel | undefined> {
 	// Dialog-capable UI exists in TUI and RPC modes (hasUI); json/print and
 	// headless contexts have no dialogs, so fall back to a manual-config hint.
 	if (!ctx.hasUI) {
@@ -74,21 +70,45 @@ export async function pickReviewModel(
 		return undefined;
 	}
 	const configured = store.getModel();
+	const configuredModel = resolveConfiguredModel(ctx, configured);
+	// Configured model first → highlighted by default (Enter accepts it);
+	// the rest keep the registry order.
+	const ordered: AvailableModel[] = configuredModel
+		? [
+				configuredModel,
+				...available.filter(
+					(m) => modelKey(m) !== modelKey(configuredModel),
+				),
+			]
+		: available;
 	// Same display source as the /model selector: name + [provider]/id.
-	const options = available.map((m) => `${m.name} (${m.provider}/${m.id})`);
-	const choice = await ctx.ui.select(
-		configured
-			? `选择评审模型 (当前: ${configured})`
-			: "选择评审模型 (third-review)",
-		options,
+	const options = ordered.map(
+		(m: AvailableModel) => `${m.name} (${m.provider}/${m.id})`,
 	);
+	// Title reflects what Enter actually accepts: the configured model when it
+	// is available, a clear "unavailable" marker otherwise.
+	let title = "选择评审模型 (third-review)";
+	if (configuredModel) {
+		title = `选择评审模型 (当前: ${configured}，回车使用)`;
+	} else if (configured) {
+		title = `选择评审模型 (当前: ${configured} 不可用)`;
+	}
+	const choice = await ctx.ui.select(title, options);
 	if (choice === undefined) {
 		ctx.ui.notify("third-review: 已取消，评审模型配置未变更。", "info");
 		return undefined;
 	}
-	const model = available[options.indexOf(choice)];
+	const model = ordered[options.indexOf(choice)];
 	if (!model) return undefined;
-	store.setModel(modelKey(model));
+	const key = modelKey(model);
+	if (key !== configured) {
+		// Persist immediately (disk + in-memory + footer) — next run defaults here.
+		store.setModel(key);
+		ctx.ui.notify(
+			`third-review: 评审模型已保存为「${model.name}」，下次默认使用。`,
+			"info",
+		);
+	}
 	return model;
 }
 
@@ -128,8 +148,20 @@ export function createReviewRunner(
 						: "third-review: 尚未配置评审模型，请选择。",
 					"warning",
 				);
+			}
+			if (ctx.hasUI) {
+				// Always show the picker: the configured model is the first row
+				// (one Enter accepts it); picking another persists it as default.
 				model = await pickReviewModel(ctx, store);
 				if (!model) return;
+			} else if (!model) {
+				// No dialogs (json/print/headless): the configured-model path keeps
+				// working; without one, point at the config file.
+				ctx.ui.notify(
+					"third-review: 当前环境不支持模型选择对话框，请编辑 <agent-dir>/pi-toolkits-review.json 手动配置。",
+					"error",
+				);
+				return;
 			}
 			const switched = await pi.setModel(model);
 			if (!switched) {
@@ -159,7 +191,7 @@ export function registerReview(pi: ExtensionAPI): void {
 	pi.registerCommand("third-review", {
 		description:
 			"Summon the configured review model to review the just-completed work (check + fix)",
-		handler: async (_args, ctx) => {
+		handler: async (_args: string, ctx: ExtensionContext) => {
 			await runReview(ctx);
 		},
 	});
@@ -170,7 +202,7 @@ export function registerReview(pi: ExtensionAPI): void {
 	pi.registerCommand("review-model", {
 		description:
 			"Set or change the review model used by third-review (picker shows the current one)",
-		handler: async (_args, ctx) => {
+		handler: async (_args: string, ctx: ExtensionContext) => {
 			await pickReviewModel(ctx, getReviewStore());
 		},
 	});
@@ -188,7 +220,7 @@ export function registerReview(pi: ExtensionAPI): void {
 		);
 	};
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", (_event: SessionStartEvent, ctx: ExtensionContext) => {
 		latestCtx = ctx;
 		try {
 			const t = ctx.ui.theme;