@zhushanwen/pi-smart-context 0.4.0 → 0.4.1

package/README.md

@@ -10,7 +10,7 @@
   - cross-model：调用 pi 原生 `compact()` 仅换模型与凭证——split-turn / fileOps / previousSummary 原生组装
 - **3 档阈值提醒**（默认 400K/500K/600K）：`agent_settled` 越档检查，每档一次、多档合并、压缩后重置，nextTurn 投递（随下一次 prompt 注入，不自起 run）；已提醒档位经 `pi.appendEntry` 落在 session entries（`smart-context:fired`），reload / 进程重启后从 entries 重建，同一档不会重复提醒；措辞是数据投递不是指令
 - **排除模型**（精准 `provider/modelId` 匹配）：工具拒绝 + 不提醒 + 回落 pi 原生生成；切换跨界时注入一条可用性通知，downshift（切小窗模型将触线）时建议先压缩
-- **通知车道**：压缩结果 / 阈值提醒 / 模型切换四类通知统一走 nextTurn（custom role 随下次 prompt 注入，不自起 run）——工具压缩掐断的 turn 由 taiji runtime 在 `compaction_end` 判定后经投递内核追加续跑投递（详情见仓库设计文档 delivery-ownership-kernel）
+- **通知车道**：压缩结果 / 阈值提醒 / 模型切换四类通知统一走 nextTurn（custom role 随下次 prompt 注入，不自起 run）——工具压缩掐断的 turn 由 taiji runtime 在 `compaction_end` 判定后经投递内核追加续跑投递
 - **健壮性**：摘要收缩校验、max-tokens 截断 fail-closed、接管失败 3 次熔断（本 session 内停止接管）、transcript 回查指针、压缩后最近文件内容重注入（≤5 文件/50K）、多轮压缩降智提示（累计压缩 ≥2 次后附加）
 - **subagent 进程**自动静默（`TAIJI_AGENT_SUBAGENT` 标记）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -36,10 +36,10 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.23.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-llm-shared": "0.11.3"
+    "@zhushanwen/pi-llm-shared": "0.12.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/src/__tests__/index-generation.test.ts

@@ -5,7 +5,7 @@
 // wrapper（() => isCtxStale()）——registerCompactContextTool 在 factory 体同步执行，简写
 // 属性 { isCtxStale } 会把该行时刻的初始 () => false 快照进 deps 对象，session_start
 // handler 内的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
-// 守卫的前置代际检查恒不生效，stale 分诊 100% 退化为 PS-30 文案兜底。
+// 检查的前置代际检查恒不生效，stale 分诊 100% 退化为 PS-30 文案兜底。
 //
 // 可区分快照 vs live 的唯一拓扑是 factory 重跑（生产主路径：pi 每次 session 替换
 // newSession/fork/switchSession 都重跑 factory 函数体，loader.ts extensionCache 只缓存

package/src/__tests__/sdk-contract.test.ts

@@ -31,7 +31,7 @@ describe("pi SDK 契约（compact 接管路径依赖的导出形状）", () => {
 		];
 		const ctx = buildSessionContext(entries as never);
 		expect(Array.isArray(ctx.messages)).toBe(true);
-		// compaction entry 投影为一条消息 + 保留段消息（旧摘要在前缀中，D12 same-mode 前提）
+		// compaction entry 派生为一条消息 + 保留段消息（旧摘要在前缀中，D12 same-mode 前提）
 		expect(ctx.messages.length).toBeGreaterThanOrEqual(2);
 	});
 

package/src/compact-handler.ts

@@ -83,7 +83,7 @@ interface SessionManagerSessionFileLike {
 }
 
 /**
- * sessionManager 会话文件访问形状的运行时守卫（D13-4）：
+ * sessionManager 会话文件访问形状的运行时检查（D13-4）：
  * 只收窄到对象（字段存在性/类型由消费侧可选链 + ?? 兜底，与原语义一致）。
  */
 function isSessionManagerSessionFileLike(sm: unknown): sm is SessionManagerSessionFileLike {
@@ -95,7 +95,7 @@ function isSessionManagerSessionFileLike(sm: unknown): sm is SessionManagerSessi
  * getSessionFile 若不可得则返回空串（指针省略，不失败）。
  */
 function getSessionFilePath(ctx: ExtensionContext): string {
-	// 经 unknown 再守卫：sessionFile 是 sessionManager 的类型未暴露字段（宽于其声明）
+	// 经 unknown 再检查：sessionFile 是 sessionManager 的类型未暴露字段（宽于其声明）
 	const sm: unknown = ctx.sessionManager;
 	const accessor = isSessionManagerSessionFileLike(sm) ? sm : undefined;
 	try {

package/src/index.ts

@@ -150,7 +150,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// isCtxStale 必须传 live 绑定 wrapper 而非简写属性：本行在 factory 体同步执行，简写
 	// { isCtxStale } 会把此刻的初始 () => false 快照进 deps 对象，上方 session_start
 	// handler 的重新赋值不回写已构造对象 → compact onComplete/onError（E1 实锤崩溃点）
-	// 守卫的前置代际检查恒不生效。wrapper 每次调用读闭包当前绑定。
+	// 检查的前置代际检查恒不生效。wrapper 每次调用读闭包当前绑定。
 	registerCompactContextTool(pi, { isCtxStale: () => isCtxStale() });
 
 	// ── 阈值提醒（D3/D4）：agent_settled 越档检查 + marker 持久化 + nextTurn 一次性投递 ──
@@ -184,7 +184,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		// 会在 agent 空闲后自起一个提醒 run，与用户消息同抢 prompt 跑道（故事 C 的三重放大器之一）。
 		// 防循环：crossed 全部已标记 fired，marker 与提醒触发的 settled 不会重复发。
 		// 事件回调内直接调用捕获的 pi——session 替换窗口可能 stale（crash-resilience D1
-		// 普查接入点），守卫 stale 静默降级（不杀 pi 进程），非 stale 错误原样上抛。
+		// 普查接入点），检查 stale 静默降级（不杀 pi 进程），非 stale 错误原样上抛。
 		guardStaleCtx(() => {
 			sendSmartContextNotice(pi, message, "threshold-reminder");
 		}, {
@@ -211,7 +211,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 			debugLog(`switch notice: ${nowExcluded ? "unavailable" : "available"} (${modelId})`);
 			// 状态通知（非紧急）：triggerTurn:false 不唤醒轮次——LLM 在下一轮自然看到并自行
 			// 调整（compact 工具 execute 有运行时门控校验兜底），不为通知烧一整轮全量上下文。
-			// session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
+			// session 替换窗口可能 stale（D1 普查接入点）——检查 stale 静默降级
 			guardStaleCtx(() => {
 				sendSmartContextNotice(pi, notice, "model-switch");
 			}, {
@@ -232,7 +232,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 		if (downshift && isGatingActive(config, modelId)) {
 			debugLog("downshift notice fired");
 			// "建议"非紧急（同 S1 裁决）：triggerTurn:false 不唤醒轮次，用户继续对话时
-			// LLM 自行决策是否先压缩。session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
+			// LLM 自行决策是否先压缩。session 替换窗口可能 stale（D1 普查接入点）——检查 stale 静默降级
 			guardStaleCtx(() => {
 				sendSmartContextNotice(pi, downshift, "model-downshift");
 			}, {

package/src/llm.ts

@@ -17,7 +17,7 @@ import type { ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 /**
- * ToolInfo → pi-ai Tool 投影：三字段直取。parameters 是 typebox schema（主会话同源对象，
+ * ToolInfo → pi-ai Tool 派生视图：三字段直取。parameters 是 typebox schema（主会话同源对象，
  * 序列化后与主请求一致——缓存对齐的关键是不改造、原样透传）。
  */
 export function projectTools(toolInfos: readonly ToolInfo[]): LlmTool[] {
@@ -67,11 +67,11 @@ export interface SameModelCallOptions {
 	systemPrompt: string;
 	/** 完整上下文 messages + 末尾已追加的压缩指令 message。 */
 	messages: Message[];
-	/** 主会话工具投影（缓存对齐）。 */
+	/** 主会话工具派生视图（缓存对齐）。 */
 	tools: LlmTool[];
 	signal?: AbortSignal;
 	sessionId?: string;
-	/** 工具投影与 LLM 调用的依赖注入（单测 mock 点）。 */
+	/** 工具派生视图与 LLM 调用的依赖注入（单测 mock 点）。 */
 	deps?: {
 		getApiKeyAndHeaders?: (model: Model<never> | Model<string>) => Promise<{ ok: true; apiKey?: string; headers?: Record<string, string>; env?: Record<string, string> } | { ok: false; error: string }>;
 		call?: (model: Model<never> | Model<string>, context: LlmContext, options: SimpleStreamOptions) => Promise<SimpleResponseLike>;

package/src/notices.ts

@@ -9,12 +9,12 @@
  * `Agent is already processing` 拒绝。
  *
  * 语义定性（设计 D4「C-ext-19 合规定性」四类两分）：
- * - 阈值提醒 / model_select 两条 = **提醒语义**（与 scheduler 2026-09-15 销账先例同类：
+ * - 阈值提醒 / model_select 两条 = **提醒语义**（与 scheduler 2026-09-15 逐条处理完毕先例同类：
  *   提醒不承载必须必达的结果）；
  * - 压缩结果 onComplete / onError = **结果语义**，本改造是**存量域内改判而非新建
  *   at-most-once 通道**：原 steer 通道即 at-most-once 且自起 run，nextTurn 化后必达性
- *   （常驻至被消费）与运行面（不自起 run）同时持平或改善；账本化正向要求的完整迁移维持
- *   pi-boundary-reliability 附录 B 挂账不变（设计 §1.3 Out）。
+ *   （常驻至被消费）与运行侧（不自起 run）同时持平或改善；账本化正向要求的完整迁移维持
+ *   pi-boundary-reliability 附录 B 挂着不处理不变（设计 §1.3 Out）。
  *
  * 已接受代价（设计 D4 四要素）：阈值提醒不再于 agent 空闲时立即生效，改为随用户下一条消息
  * 注入——pi 内建 overflow/threshold 自动压缩兜底在场，无人在场时上下文可能持续增长。

package/src/tool.ts

@@ -125,7 +125,7 @@ export function registerCompactContextTool(
 		 * G1 代际检测（crash-resilience D1）：compact 是 fire-and-forget——onComplete/onError
 		 * 回调在压缩 LLM 调用期间异步触发，用户此间切换/重载 session 后回调持有的 pi 已
 		 * stale（E1 实锤崩溃点）。index.ts 注入模块级代数比对闭包，前置检查 + 错误分诊
-		 * 双保险；缺省时守卫退化为纯文案兜底分诊（PS-30 门禁守文案）。
+		 * 双保险；缺省时检查退化为纯文案兜底分诊（PS-30 门禁守文案）。
 		 */
 		isCtxStale?: () => boolean;
 	},
@@ -192,8 +192,8 @@ export function registerCompactContextTool(
 				// session/新建/重载高频触发）下 sendMessage 命中 stale ctx 同步抛错即
 				// 杀死 pi 进程（pi 1.0.0 实装：dist/core/extensions/loader.js 的 assertActive
 				// wrapper 对 stale 即 throw "no longer active"，在 runtime 调用前同步 throw）。
-				// 守卫 stale 静默降级（结果不投递，用户可重试 /compact），非
-				// stale 错误原样上抛（守卫不吞真实 bug）。
+				// 检查 stale 静默降级（结果不投递，用户可重试 /compact），非
+				// stale 错误原样上抛（检查不吞真实 bug）。
 				onComplete: (r: unknown) => {
 					guardStaleCtx(() => {
 						const result = toCompactionResultLike(r);
@@ -218,7 +218,7 @@ export function registerCompactContextTool(
 					});
 				},
 				onError: (err: Error) => {
-					// 压缩本身的失败信息先落日志（守卫体外——stale 降级时该观测保留）
+					// 压缩本身的失败信息先落日志（检查体外——stale 降级时该观测保留）
 					debugLog(`compact_context error: ${err.message}`);
 					guardStaleCtx(() => {
 						sendSmartContextNotice(