@zhushanwen/pi-smart-context 0.3.0 → 0.3.1

package/README.md

@@ -13,10 +13,20 @@
 - **健壮性**：摘要收缩校验、max-tokens 截断 fail-closed、接管失败 3 次熔断、transcript 回查指针、压缩后最近文件内容重注入（≤5 文件/50K）、多轮压缩降智提示
 - **subagent 进程**自动静默（`PI_SUBAGENT_ROOT_SESSION_ID` 标记）
 
-## 配置
+## 行为门控
 
-`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。xyz-agent 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。
+| 状态 | 工具 execute | 阈值提醒 | 压缩生成接管 |
+|---|---|---|---|
+| enabled，模型未排除 | 放行（低于最低档阈值时拒绝并返回用量建议） | 生效 | 生效（按双模式判定） |
+| enabled，模型命中排除列表 | 拒绝（返回原因） | 跳过 | 跳过（回落 pi 原生生成） |
+| enabled=false | 拒绝（"可在设置页开启"） | 跳过 | 跳过（回落 pi 原生） |
+| compactModel 未配置/无效 | 放行（same-model 不依赖该配置） | 生效 | same-model 生效；cross-model 回退当前模型，压缩不失败 |
+| 模型切换跨界（model_select） | 常驻不变 | 注入一条可用性变化通知（仅跨界时） | 按新模型即时重判 |
+
+行为正确性由 execute / handler 现场校验兜底，每次事件回调重新读配置（热加载，改完下一 turn 生效，无需重启）。
 
-## 设计文档
+> 设计层 why 与业界调研记录见原设计文档（已随 2026-09 docs 清理退役，git 历史可查 `docs/extensions/smart-context/design.md`）。
 
-`docs/extensions/smart-context/design.md`（xyz-agent 仓库）——决策依据、探针记录、验收场景。
+## 配置
+
+`<agentDir>/config/smart-context-ext-config.json`（读时热加载）。schema 与示例见 `skills/smart-context-ext-config/SKILL.md`。xyz-agent 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -36,9 +36,9 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.3.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0",
-    "@zhushanwen/pi-llm-shared": "0.7.0"
+    "@zhushanwen/pi-llm-shared": "0.8.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/src/__tests__/pure.test.ts

@@ -12,7 +12,6 @@ import {
 	formatK,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	isSummaryInflated,
 	normalizeSmartContextConfig,
 	pickMode,
@@ -173,9 +172,6 @@ describe("estimateShadowedTokens 口径契约（D2：与 pi estimateTokens 同
 	});
 });
 
-describe("subagent 识别（R6）", () => {
-	it("PI_SUBAGENT_ROOT_SESSION_ID 存在即 subagent", () => {
-		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(true);
-		expect(isSubagentProcess({})).toBe(false);
-	});
-});
+// [HISTORICAL] subagent 识别（R6）用例已随本地实现删除移除——现行谓词收敛于
+// ext-guards isSubagentProcess（ext-simplify-17 D4），三态与「宁缺勿污」钉值见
+// extensions/shared/ext-guards/src/__tests__/predicates.test.ts。

package/src/compact-handler.ts

@@ -14,6 +14,7 @@
 import { buildSessionContext, compact as nativeCompact, convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { CompactionResult, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { createLogger } from "@zhushanwen/pi-extension-logger";
 import { resolveModel } from "@zhushanwen/pi-llm-shared";
 import { readFileSync } from "node:fs";
@@ -319,7 +320,7 @@ export function createBeforeCompactHandler(
 			return { compaction: result };
 		} catch (error) {
 			state.failStreak += 1;
-			warnLog("takeover error, falling back to native", { error: error instanceof Error ? error.message : String(error) });
+			warnLog("takeover error, falling back to native", { error: toErrorMessage(error) });
 			return {}; // D7 回退
 		}
 	};

package/src/index.ts

@@ -11,7 +11,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { guardStaleCtx, isSubagentProcess, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import {
@@ -27,7 +27,6 @@ import {
 	findCrossedThresholds,
 	getCurrentModelId,
 	isGatingActive,
-	isSubagentProcess,
 	loadSmartContextConfig,
 	type EntryLike,
 } from "./pure.js";
@@ -63,7 +62,8 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）
 	setPiHandle(pi);
 
-	// R6：subagent 子进程不注册工具、不提醒（PI_SUBAGENT_ROOT_SESSION_ID 标记）
+	// R6：subagent 子进程不注册工具、不提醒（宁缺勿污；XYZ_AGENT_SUBAGENT 标记——
+	// ext-guards isSubagentProcess，ext-simplify-17 D4 重锚）
 	if (isSubagentProcess()) {
 		debugLog("subagent process detected, staying inert");
 		return;

package/src/llm.ts

@@ -14,6 +14,7 @@ import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { Context as LlmContext, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
 import type { Tool as LlmTool, Message, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /**
  * ToolInfo → pi-ai Tool 投影：三字段直取。parameters 是 typebox schema（主会话同源对象，
@@ -127,6 +128,6 @@ export async function callSameModelCompaction(
 		const text = resp.content.map(blockText).join("\n").trim();
 		return { ok: true, text, usage: resp.usage, stopReason: resp.stopReason };
 	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+		return { ok: false, error: toErrorMessage(error) };
 	}
 }

package/src/pure.ts

@@ -6,8 +6,9 @@
  */
 
 import { estimateTokens } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 import type { ModelSelector } from "@zhushanwen/pi-llm-shared";
-import { loadConfig } from "@zhushanwen/pi-llm-shared";
+import { loadConfig, normalizeModelSelector } from "@zhushanwen/pi-llm-shared";
 
 // ──────────────────────── 配置 schema（D8） ────────────────────────
 
@@ -59,13 +60,8 @@ export function normalizeSmartContextConfig(raw: unknown): SmartContextConfig {
 
 	const enabled = typeof r.enabled === "boolean" ? r.enabled : base.enabled;
 
-	const rawModel = typeof r.compactModel === "object" && r.compactModel !== null
-		? (r.compactModel as Record<string, unknown>)
-		: null;
 	const compactModel: ModelSelector =
-		rawModel?.type === "ref" && typeof rawModel.ref === "string"
-			? { type: "ref", ref: rawModel.ref }
-			: { type: "ref", ref: "" };
+		normalizeModelSelector(r.compactModel) ?? { type: "ref", ref: "" };
 
 	const rawThresholds = Array.isArray(r.reminderThresholds)
 		? r.reminderThresholds
@@ -249,16 +245,6 @@ export function buildReinjectSection(contents: ReadonlyArray<{ path: string; con
 	return `\n\n<recently-read-files>\n${parts.join("\n\n")}\n</recently-read-files>`;
 }
 
-// ──────────────────────── subagent 识别（R6） ────────────────────────
-
-/**
- * subagent 子进程检测（D9/R6）：subagent-core session-runner 无条件注入 PI_SUBAGENT_ROOT_SESSION_ID。
- * 命中 → 本进程不注册工具、不提醒（宁缺勿污）。
- */
-export function isSubagentProcess(env: NodeJS.ProcessEnv = process.env): boolean {
-	return env.PI_SUBAGENT_ROOT_SESSION_ID !== undefined;
-}
-
 // ──────────────────────── session entries 统计（D13 纯函数） ────────────────────────
 
 /** sessionManager entries 的宽松形状（降智计数）。 */
@@ -271,11 +257,6 @@ export function countCompactions(entries: ReadonlyArray<EntryLike>): number {
 	return entries.filter((e) => e.type === "compaction").length;
 }
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof / Array.isArray 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /**
  * 保留段已 Read 的文件集合（D13-11 去重：重注入跳过保留段已有的 Read 结果）。
  * 保留段 = branchEntries 中 firstKeptEntryId 之后的 message entries；从其 toolCall 参数提取 path。

package/src/tool.ts

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { guardStaleCtx, toErrorMessage } from "@zhushanwen/pi-ext-guards";
+import { guardStaleCtx, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { debugLog } from "./compact-handler.js";
@@ -66,11 +66,6 @@ const TOOL_DESCRIPTION =
 	"2) 后续工作不再依赖将被压缩的早期细节；3) 上下文已超过提醒阈值（你会收到 [smart-context 提示]）。" +
 	"若任一条件不满足，不要调用。";
 
-/** unknown 的对象收窄（Record 视图；字段消费再经 typeof 收窄）。 */
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
 /** CompactionResult → 宽松形状的 guard 转换（onComplete 回调参数消费，避免 cast）。 */
 function toCompactionResultLike(result: unknown): CompactionResultLike {
 	const r: Record<string, unknown> = isRecord(result) ? result : {};