@andares/pi-toolkits 0.4.2 → 0.5.0

package/README.md

@@ -8,13 +8,13 @@
 [![npm version](https://img.shields.io/npm/v/@andares/pi-toolkits?label=npm&logo=npm)](https://www.npmjs.com/package/@andares/pi-toolkits)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Package Manager](https://img.shields.io/badge/package%20manager-pnpm-orange?logo=pnpm)](https://pnpm.io)
-[![pi >= 0.87](https://img.shields.io/badge/pi-%3E%3D0.87.0-blueviolet)](https://github.com/earendil-works/pi)
+[![pi >= 0.86](https://img.shields.io/badge/pi-%3E%3D0.86.0%20%3C2.0.0-blueviolet)](https://github.com/earendil-works/pi)
 [![GitHub](https://img.shields.io/badge/github-andares%2Fpi--toolkits-181717?logo=github)](https://github.com/andares/pi-toolkits)
 
 一句话介绍:目前包含五个开箱即用的功能——**只读咨询模式** `ask`、**模型收藏** `favorites`、**提示词暂存** `stash`、**第三方代码评审** `third-review`、**独立压缩模型** `compact-model`,后续持续追加。
 Currently ships five ready-to-use capabilities — **ask mode**, **model favorites**, **prompt stash**, **third-party code review** and a **dedicated compaction model** — with more to come.
 
-**版本要求 · Requirements**:pi ≥ 0.87.0(以 0.87.x 内建压缩行为为基准开发与验证;favorites 的两处运行时 patch 已对齐 0.87 的选择器布局与 `cycleModel` 语义)。
+**版本要求 · Requirements**:pi `>=0.86.0 <2.0.0`(覆盖最近 4 个中版本线 0.86.x / 0.87.x / 0.99.x / 1.0.x —— 0.88–0.98 从未发布。区间内全部 10 个已发布版本逐版本比对宿主 dist:用到的扩展 API 无差异,favorites 两处运行时 patch 目标 `ModelSelectorComponent` / `AgentSession.cycleModel` 字节级一致;并在 0.86.0、0.86.1、0.87.1、0.99.2、1.0.2 上逐一通过 typecheck + 全量测试,在真实 pi 1.0.2 上冒烟加载无警告)。注:pi ≥ 0.99 的宿主要求 `@earendil-works/pi-tui` 声明为 peerDependencies `"*"`(由宿主提供),本包已按要求声明。
 
 ---
 
@@ -191,7 +191,7 @@ pi 的 `/compact` 与 auto-compact 默认**用当前会话模型**做上下文
 | auto-compact 阈值触发 | 压缩模型总结 |
 | context overflow 恢复 | 压缩模型总结,重试行为不变 |
 
-**接管后与 pi 内建行为完全一致的部分**(逐字同步 0.87.1 内建实现,只换执行模型):
+**接管后与 pi 内建行为完全一致的部分**(逐字同步 pi 内建实现,0.87.1 起字节级不变、已核对至 1.0.2,只换执行模型):
 
 - **摘要格式** —— Goal / Progress / Key Decisions 结构化 checkpoint;已有摘要时用迭代更新版 prompt,信息延续不丢
 - **切分行为** —— 保留最近 `keepRecentTokens` 的策略、`firstKeptEntryId` / `tokensBefore` 原样回传,不动

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), model favorites, prompt stash, third-party code review, and a dedicated compaction model",
   "type": "module",
   "license": "MIT",
@@ -27,15 +27,16 @@
     "toolkit"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": ">=0.86.0 <2.0.0",
+    "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
-    "@dreki-gg/pi-command-sandbox": "^0.4.3",
-    "@earendil-works/pi-tui": "^0.87.1"
+    "@dreki-gg/pi-command-sandbox": "^0.4.3"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-ai": "^1.0.2",
+    "@earendil-works/pi-coding-agent": "^1.0.2",
+    "@earendil-works/pi-tui": "^1.0.2",
     "@types/node": "^26.6.2",
     "typescript": "^5.6.0",
     "vitest": "^4.1.10"

package/src/features/compact/index.ts

@@ -10,8 +10,9 @@
  *    emits for ALL three trigger reasons (manual / threshold / overflow)
  *    before running its own compaction
  *  - prompts, message assembly, split-turn handling, output budgets, and the
- *    summary file-list tail are verbatim pi 0.87.1 built-in behavior — only
- *    the executing model differs
+ *    summary file-list tail are verbatim pi built-in behavior (copied from
+ *    0.87.1, verified unchanged through 1.0.2) — only the executing model
+ *    differs
  *  - lossless fallback: unset config, unavailable model, empty/failed
  *    summary, or user abort → return undefined and pi's default compaction
  *    (session model) runs untouched. The extension can never make
@@ -115,8 +116,8 @@ async function completeSummary(
 }
 
 /**
- * pi's output-budget formula (0.87.1 compaction.js): a fraction of
- * reserveTokens clamped by the model's own output cap.
+ * pi's output-budget formula (compaction.js, 0.87.1 → 1.0.2 unchanged): a
+ * fraction of reserveTokens clamped by the model's own output cap.
  */
 function summarizationBudget(
 	fraction: number,
@@ -131,11 +132,12 @@ function summarizationBudget(
 
 /**
  * Run the full compaction summarization with the configured model,
- * replicating pi 0.87.1's compact(): history summary (first-connection or
- * iterative-update prompt, custom focus appended), plus a separate
- * turn-prefix checkpoint when the cut point splits a turn, merged into one
- * summary with the file-list tail. Returns undefined on any failure after
- * notifying (pi default compaction then takes over).
+ * replicating pi's compact() (0.87.1, verified unchanged through 1.0.2):
+ * history summary (first-connection or iterative-update prompt, custom
+ * focus appended), plus a separate turn-prefix checkpoint when the cut point
+ * splits a turn, merged into one summary with the file-list tail. Returns
+ * undefined on any failure after notifying (pi default compaction then takes
+ * over).
  */
 async function runCompactModelCompaction(
 	ctx: ExtensionContext,

package/src/features/compact/prompt.ts

@@ -5,6 +5,9 @@
  * compaction (dist/core/compaction/compaction.js and utils.js) so that
  * summaries produced by the configured compact model are formatted exactly
  * like pi's own compaction output. Only the executing model differs.
+ * Verified byte-identical against pi 1.0.2 (0.88–0.98 were never published;
+ * the only 0.87.1→1.0.2 change there is a combineUsage refactor into a
+ * shared module, no prompt or budget change).
  *
  * Update these strings whenever pi changes its built-in prompts (diff
  * dist/core/compaction/compaction.js between versions).

package/src/features/favorites/favorites.test.ts

@@ -23,7 +23,15 @@ import {
 	ModelSelectorComponent,
 	type Theme,
 } from "@earendil-works/pi-coding-agent";
-import { afterAll, beforeEach, beforeAll, describe, expect, it } from "vitest";
+import {
+	afterAll,
+	beforeEach,
+	beforeAll,
+	describe,
+	expect,
+	it,
+	vi,
+} from "vitest";
 import {
 	FavoritesStore,
 	getFavoritesStore,
@@ -102,14 +110,17 @@ describe("FavoritesStore", () => {
 	it("falls back to empty + defaults on a corrupted file", () => {
 		const file = freshStoreFile();
 		// Intentionally write invalid JSON — the READ side must tolerate it.
+		writeFileSync(file, "{ not json", "utf8");
+		// Suppress the designed degradation log; the spy asserts it fired.
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 		try {
-			writeFileSync(file, "{ not json", "utf8");
-		} catch {
-			// A failed write still leaves the store to hit the read-error path.
+			const store = new FavoritesStore(file);
+			expect(store.count()).toBe(0);
+			expect(store.getConfig().cycleOnlyFavorites).toBe(true);
+			expect(warn).toHaveBeenCalled();
+		} finally {
+			warn.mockRestore();
 		}
-		const store = new FavoritesStore(file);
-		expect(store.count()).toBe(0);
-		expect(store.getConfig().cycleOnlyFavorites).toBe(true);
 	});
 
 	it("loads cycleOnlyFavorites config from disk", () => {

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

@@ -13,8 +13,9 @@
  *    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 pi 0.87's _cycleScopedModel/_cycleAvailableModel
- *    (state swap, session persistence, default-model persistence only when
+ *  - the apply logic mirrors pi's _cycleScopedModel/_cycleAvailableModel
+ *    (byte-identical across every published version in 0.86.0 → 1.0.2:
+ *    state swap, session persistence, default-model persistence only when
  *    `options.persist` is set, thinking-level re-clamp, model_select emit
  *    with source "cycle")
  *
@@ -28,9 +29,10 @@ import {
 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
+ * pi's `Model<any>` — the exact type of `ModelCycleResult.model`
+ * (pi-coding-agent 0.86–1.0; the field is unchanged across that span).
+ * Derived here instead of importing `Model` from @earendil-works/pi-ai,
+ * whose index.d.ts (0.86 through 1.0.2 alike) 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).
  */

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

@@ -19,7 +19,10 @@
  *
  * 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.
+ * keeps loading and ctrl+p falls back to stock behavior. The prototype
+ * shape touched here (handleInput/updateList/filterModels and the instance
+ * fields below) is byte-identical across every published version in
+ * pi 0.86.0 → 1.0.2.
  */
 import {
 	ModelSelectorComponent,
@@ -113,8 +116,9 @@ let patched = false;
 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.
+	// only); the structural view matches pi 0.86–1.0's prototype shape
+	// (byte-identical across that span) and every touched method is
+	// existence-checked below before any patching happens.
 	const proto =
 		ModelSelectorComponent.prototype as unknown as SelectorPatchTarget;
 	if (
@@ -151,7 +155,7 @@ export function applyModelSelectorPatches(): boolean {
 	};
 
 	// ── 2. List rendering: hint row + bold bright yellow favorites ────────
-	// Replicates the built-in updateList layout (pi 0.87: fixed-width cursor
+	// Replicates the built-in updateList layout (pi 0.86–1.0: 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.

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

@@ -204,13 +204,15 @@ describe("ReviewStore", () => {
 
 	it("falls back to unset on a corrupted file", () => {
 		const file = freshStoreFile();
+		writeFileSync(file, "{ not json", "utf8");
+		// Suppress the designed degradation log; the spy asserts it fired.
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
 		try {
-			writeFileSync(file, "{ not json", "utf8");
-		} catch {
-			// A failed write still leaves the store to hit the read-error path.
+			expect(new ReviewStore(file).getModel()).toBeUndefined();
+			expect(warn).toHaveBeenCalled();
+		} finally {
+			warn.mockRestore();
 		}
-		const store = new ReviewStore(file);
-		expect(store.getModel()).toBeUndefined();
 	});
 
 	it("ignores a stored value without a slash", () => {

package/src/lib/model-config.ts

@@ -4,11 +4,12 @@
  * (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.
+ * rather than imported from @earendil-works/pi-ai: pi-ai's index.d.ts (0.87
+ * through 1.0.2 alike) 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,

package/src/lib/model-picker.ts

@@ -9,10 +9,11 @@
  *
  * The component is driven through a small ModelRuntime facade backed by
  * ctx.modelRegistry (pi's extension-facing wrapper). SAFETY: verified
- * against pi 0.87.1 dist (modes/interactive/components/model-selector.js +
- * model-catalog-refresh.js) — the component only calls getAvailableSnapshot,
- * getModel, getError and refresh on modelRuntime, and ModelRegistry provides
- * exactly those (getAvailable/find/getError/refresh).
+ * against pi 0.86–1.0 dist (modes/interactive/components/model-selector.js +
+ * model-catalog-refresh.js — byte-identical across that span) — the
+ * component only calls getAvailableSnapshot, getModel, getError and refresh
+ * on modelRuntime, and ModelRegistry provides exactly those
+ * (getAvailable/find/getError/refresh).
  *
  * `current` is passed as the component's currentModel: the built-in selector
  * preselects, ✓-marks and sorts-first its currentModel, so one Enter accepts
@@ -41,7 +42,7 @@ function modelRuntimeFacade(ctx: ExtensionContext): ModelRuntime {
 		refresh: (options?: { signal?: AbortSignal }) =>
 			ctx.modelRegistry.refresh(options),
 	};
-	// SAFETY: the selector only touches the four members above (pi 0.87.1
+	// SAFETY: the selector only touches the four members above (pi 0.86–1.0
 	// model-selector.js); everything else on ModelRuntime is never reached
 	// from this component.
 	return facade as unknown as ModelRuntime;