@andares/pi-toolkits 0.3.1 → 0.4.0

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,37 @@ 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) => ({
+		let candidates: CycleCandidate[];
+		if (scoped) {
+			const availableIds = new Set(
+				this._modelRuntime
+					.getAvailableSnapshot()
+					.map((model) => `${model.provider}\0${model.id}`),
+			);
+			candidates = this._scopedModels
+				.filter(
+					(sm) => availableIds.has(`${sm.model.provider}\0${sm.model.id}`),
+			)
+				.map((sm) => ({
 					model: sm.model,
 					thinkingLevel: sm.thinkingLevel,
-				}))
-			: this._modelRuntime
-					.getAvailableSnapshot()
-					.map((model) => ({ model, thinkingLevel: undefined }));
+				}));
+		} else {
+			candidates = this._modelRuntime
+				.getAvailableSnapshot()
+				.map((model) => ({ model, thinkingLevel: undefined }));
+		}
 		const favorites = candidates.filter((candidate) =>
 			getFavoritesStore().has(candidate.model),
 		);
@@ -148,10 +185,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,20 @@ 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 modelText = isFavorite
+				? styleFavorite(item.id)
+				: isSelected
+					? theme.fg("accent", item.id)
+					: item.id;
+			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

@@ -23,27 +23,17 @@
 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
@@ -55,7 +45,7 @@ export function resolveConfiguredModel(
 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) {
@@ -75,7 +65,7 @@ export async function pickReviewModel(
 	}
 	const configured = store.getModel();
 	// Same display source as the /model selector: name + [provider]/id.
-	const options = available.map((m) => `${m.name} (${m.provider}/${m.id})`);
+	const options = available.map((m: AvailableModel) => `${m.name} (${m.provider}/${m.id})`);
 	const choice = await ctx.ui.select(
 		configured
 			? `选择评审模型 (当前: ${configured})`
@@ -159,7 +149,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 +160,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 +178,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;

package/src/features/review/review.test.ts

@@ -34,13 +34,15 @@ import {
 import {
 	createReviewRunner,
 	pickReviewModel,
-	resolveConfiguredModel,
 } from "./index.js";
+import {
+	modelKey,
+	resolveConfiguredModel,
+} from "../../lib/model-config.js";
 import { REVIEW_PROMPT } from "./prompt.js";
 import {
 	ReviewStore,
 	getReviewStore,
-	modelKey,
 	setSharedReviewStore,
 } from "./store.js";
 

package/src/features/review/store.ts

@@ -22,11 +22,6 @@ import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { REVIEW_FILE } from "./constants.js";
 
-/** Model identity used as the review-model key: "provider/id". */
-export function modelKey(model: { provider: string; id: string }): string {
-	return `${model.provider}/${model.id}`;
-}
-
 export class ReviewStore {
 	private model: string | undefined;
 	private readonly file: string;

package/src/index.ts

@@ -9,15 +9,18 @@
  *  - favorites — model favorites (ctrl+F/ctrl+J in /model, favorites-only cycling)
  *  - stash — prompt stash (ctrl+alt+y swap / double-press stash-and-clear)
  *  - review — third-party code review with a configured review model (third-review)
+ *  - compact — dedicated compact model for /compact + auto-compact summaries
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAsk } from "./features/ask/index.js";
+import { registerCompact } from "./features/compact/index.js";
 import { registerFavorites } from "./features/favorites/index.js";
 import { registerReview } from "./features/review/index.js";
 import { registerStash } from "./features/stash/index.js";
 
 export default function piToolkits(pi: ExtensionAPI): void {
 	registerAsk(pi);
+	registerCompact(pi);
 	registerFavorites(pi);
 	registerReview(pi);
 	registerStash(pi);

package/src/lib/model-config.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared model-config helpers for features that persist a "provider/id"
+ * model key and resolve it against the currently available model list
+ * (review, compact-model — favorites keeps its own store-local key logic).
+ *
+ * Types are derived from pi-coding-agent's own exports (ModelRegistry)
+ * rather than imported from @earendil-works/pi-ai: pi-ai 0.87's index.d.ts
+ * re-exports `Model`/`Api` via extensioned `./types.ts` specifiers, which
+ * tsc 5.9 bundler resolution substitutes to `.d.ts` but some tsserver
+ * builds do not. Deriving from ModelRegistry keeps every resolver in
+ * agreement with the exact type `ctx.modelRegistry.getAvailable()` returns.
+ */
+import type {
+	ExtensionContext,
+	ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+
+/** The model type pi's ModelRegistry exposes (`Model<Api>`). */
+export type AvailableModel = ReturnType<ModelRegistry["getAvailable"]>[number];
+
+/** Model identity used as a persisted config key: "provider/id". */
+export function modelKey(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+/**
+ * Resolve a persisted "provider/id" key against the available model list.
+ * Ids may themselves contain slashes (e.g. openrouter/openai/gpt-5), so only
+ * the first slash splits provider from id. Returns undefined for missing,
+ * malformed, or currently-unavailable keys.
+ */
+export function resolveConfiguredModel(
+	ctx: ExtensionContext,
+	key: string | undefined,
+): AvailableModel | 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);
+}