@zhushanwen/pi-smart-context 0.4.1 → 0.4.3

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` 判定后经投递内核追加续跑投递
+- **通知投递路径**：压缩结果 / 阈值提醒 / 模型切换四类通知统一走 nextTurn（custom role 随下次 prompt 注入，不自起 run）——工具压缩掐断的 turn 由 taiji runtime 在 `compaction_end` 判定后经投递内核追加续跑投递
 - **健壮性**：摘要收缩校验、max-tokens 截断 fail-closed、接管失败 3 次熔断（本 session 内停止接管）、transcript 回查指针、压缩后最近文件内容重注入（≤5 文件/50K）、多轮压缩降智提示（累计压缩 ≥2 次后附加）
 - **subagent 进程**自动静默（`TAIJI_AGENT_SUBAGENT` 标记）
 
@@ -32,15 +32,9 @@
 pi install npm:@zhushanwen/pi-smart-context
 ```
 
-## 工具激活（deferred）
+## 工具激活
 
-`compact_context` 工具为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）开启：
-
-```json
-{ "defaultTools": ["+tool_search"] }
-```
-
-`+` 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 `tool_search` 时该工具对模型不可见。
+`compact_context` 工具为 direct 常驻——注册不声明 `exposure` 字段（pi SDK 缺省 `direct`），工具声明随会话常驻、对模型默认可见，无需经 `tool_search` 检索激活，独立 pi 开箱即用。
 
 ## 配置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-smart-context",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -36,7 +36,7 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.23.0",
+    "@zhushanwen/extension-protocol": "0.25.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/pi-llm-shared": "0.12.0"
@@ -72,7 +72,7 @@
     }
   },
   "scripts": {
-    "test": "vitest run",
+    "test": "vitest run --pool=threads",
     "test:watch": "vitest"
   }
 }

package/src/__tests__/tool.test.ts

@@ -12,11 +12,14 @@ vi.mock("../pure.js", async (importOriginal) => {
 import { DEFAULT_SMART_CONTEXT_CONFIG, loadSmartContextConfig } from "../pure.js";
 import { registerCompactContextTool } from "../tool.js";
 import { countCompactions } from "../pure.js";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 
 interface RegisteredTool {
 	name: string;
+	/** pi SDK 的 exposure 缺省值 "direct"（常驻）——不写字段时 SDK 侧默认（pi-semantics PS-91），本视图可缺省。 */
+	exposure?: string;
 	parameters: { type?: string };
+	renderResult?: (result: unknown, options: { expanded: boolean }, theme: Theme) => { render: (width: number) => string[] };
 	execute: (id: string, params: Record<string, unknown>, signal: undefined, onUpdate: undefined, ctx: ExtensionContext) => Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
 }
 
@@ -67,6 +70,17 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(tools[0].name).toBe("compact_context");
 	});
 
+	// exposure 重划终态锚（C-ext-05，2026-10-23 ADR-0136）：direct 常驻 = 注册时不写
+	// exposure 字段（SDK 缺省 direct，pi-semantics PS-91）——误写 "deferred" 会把压缩入口
+	// 从模型默认可见集收走（tool_search 才可激活），此处红。
+	it("exposure 注册终态：direct 常驻——不写 exposure 字段（SDK 缺省 direct）", () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi);
+		expect(tools).toHaveLength(1);
+		expect(tools[0]!.name).toBe("compact_context");
+		expect(tools[0]!.exposure).toBeUndefined();
+	});
+
 	it("门控拒绝（排除命中）→ throw 带原因与恢复指引（D5）", async () => {
 		mockedLoad.mockReturnValue({ ...DEFAULT_SMART_CONTEXT_CONFIG, excludedModels: ["zai/glm"] });
 		const { pi, tools } = makePi();
@@ -95,13 +109,26 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(result.details).toMatchObject({ mode: "same-model", launched: true, fellBack: false, compactionCount: 1 });
 	});
 
+	it("renderResult 接线（C-ext-05）：注册定义携带函数成员 + 折叠态输出 details.summary 一行", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }] });
+		const tool = tools[0];
+		expect(typeof tool.renderResult).toBe("function");
+		const result = await tool.execute("t1", {}, undefined, undefined, makeCtx());
+		const renderTheme = { fg: (_token: string, text: string) => text } as unknown as Theme;
+		const lines = tool.renderResult!(result, { expanded: false }, renderTheme).render(400);
+		// Text.render 按宽度 pad，trim 后断言（折叠态 = details.summary 一行）
+		expect(lines.length).toBe(1);
+		expect(lines[0].trim()).toBe("Context compacted");
+	});
+
 	it("onComplete 兑现后 nextTurn 注入结果（含模式/前后 tokens/成本；降智提示按次数）", async () => {
 		const { pi, tools } = makePi();
 		registerCompactContextTool(pi, { getEntries: () => [{ type: "compaction" }, { type: "compaction" }] });
 		await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
 		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
 		const [message, options] = pi.sendMessage.mock.calls[0];
-		// D4①：nextTurn 化——custom role 消息 + 不自起 run 的投递车道
+		// D4①：nextTurn 化——custom role 消息 + 不自起 run 的投递路径
 		expect(message.customType).toBe("smart-context");
 		expect(message.details).toEqual({ source: "compact-complete" });
 		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
@@ -111,7 +138,7 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(text).toContain("500K");
 		expect(text).toContain("24K");
 		expect(text).toContain("compacted multiple times");
-		// 旧车道（自起 run 的 user 消息）已退役：不再调用 sendUserMessage（mock 挂 spy，被调用即断言红）
+		// 旧投递路径（自起 run 的 user 消息）已退役：不再调用 sendUserMessage（mock 挂 spy，被调用即断言红）
 		expect(pi.sendUserMessage).not.toHaveBeenCalled();
 	});
 
@@ -124,7 +151,7 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(pi.sendMessage.mock.calls[0][0].content).toContain("回退");
 	});
 
-	it("onError → 注入失败消息带重试指引（display:true 失败必须用户可见 + nextTurn 车道不自起 run）", async () => {
+	it("onError → 注入失败消息带重试指引（display:true 失败必须用户可见 + nextTurn 投递路径不自起 run）", async () => {
 		const { pi, tools } = makePi();
 		registerCompactContextTool(pi);
 		const ctx = makeCtx((options) => options.onError(new Error("Nothing to compact")));

package/src/index.ts

@@ -9,7 +9,7 @@
  * - agent_settled：越档检查 + marker 持久化（D15）+ nextTurn 投递一次性提醒（D3/D4①）
  * - model_select：跨界通知 + downshift 提醒（D5/D4①）
  *
- * 通知注入车道（D4①，delivery-ownership-kernel）：四类通知全部经 notices.ts 的
+ * 通知投递路径（D4①，delivery-ownership-kernel）：四类通知全部经 notices.ts 的
  * sendSmartContextNotice 走 nextTurn（随下一次 prompt 注入、不自起 run）——通知 run 不再
  * 抢占用户消息投递跑道；被压缩掐断的 turn 由 runtime 续跑投递兜底（D4②）。
  */

package/src/notices.ts

@@ -33,13 +33,13 @@ export type SmartContextNoticeSource =
 	| "model-downshift";
 
 /**
- * 注入一条 smart-context 通知（nextTurn 车道，不自起 run）。
+ * 注入一条 smart-context 通知（nextTurn 投递路径，不自起 run）。
  *
- * `deliverAs:'nextTurn'` 是投递车道（pi 实装分支序：nextTurn 分支先命中，`triggerTurn`
+ * `deliverAs:'nextTurn'` 是投递路径之一（pi 实装分支序：nextTurn 分支先命中，`triggerTurn`
  * 不再参与判定）；`triggerTurn:false` 是意图的显式声明（双写防未来实现分支序漂移）。
- * `display:true` 使通知在对话流可见——分车道语义（D4①）：compact-result 两条（complete/
+ * `display:true` 使通知在对话流可见——可见性按投递路径区分（D4①）：compact-result 两条（complete/
  * failed）改造前即 display:true 系统消息，可见性保持；阈值提醒/模型跨界/downshift 三条
- * 改造前 display:false 静默（只进 LLM 上下文，不进对话流），随 nextTurn 车道统一转
+ * 改造前 display:false 静默（只进 LLM 上下文，不进对话流），随 nextTurn 投递路径统一转
  * display:true 可见。
  */
 export function sendSmartContextNotice(

package/src/reminder.ts

@@ -2,7 +2,7 @@
  * 提醒与通知文案构造（D3/D4/D5/D13-12）。
  *
  * 全部为纯函数：文案 + 越档判定。注入由 src/index.ts / src/tool.ts 经 notices.ts 的
- * sendSmartContextNotice（nextTurn 车道，D4①）执行。
+ * sendSmartContextNotice（nextTurn 投递路径，D4①）执行。
  * 措辞原则（目标 3）：提醒是数据投递不是指令——给三条件自查清单 + 明确的"可忽略"出口，
  * 避免 agent 见提醒就压缩。
  */

package/src/render-result.ts

@@ -4,32 +4,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { firstContentText } from "@zhushanwen/extension-protocol";
-
-/** content[0] 的 text 纯文本（content 缺失或非 text 类型时兜底空串）。 */
-function contentText(result: unknown): string {
-	const content = fieldValue(result, "content");
-	if (!Array.isArray(content)) return "";
-	return firstContentText({ content });
-}
-
-/** unknown 值按字段名安全取值（index-signature 收窄，替代全可选结构断言）。 */
-function fieldValue(v: unknown, key: string): unknown {
-	if (typeof v !== "object" || v === null) return undefined;
-	return (v as Record<string, unknown>)[key];
-}
-
-/** 从 details 安全读取 summary（容错非对象形态与旧版本 entry）。 */
-function readDetailsSummary(result: unknown): string | undefined {
-	const summary = fieldValue(fieldValue(result, "details"), "summary");
-	return typeof summary === "string" && summary !== "" ? summary : undefined;
-}
-
-/** 折叠态回退：content 文本首行（保持一行摘要形态）。 */
-function firstLine(text: string): string {
-	const idx = text.indexOf("\n");
-	return idx === -1 ? text : text.slice(0, idx);
-}
+import { firstLine, readDetailsSummary, resultContentText } from "@zhushanwen/extension-protocol";
 
 /** 折叠态（expanded=false）= details.summary 一行（dim）；展开态 = content 纯文本。 */
 export function renderCompactContextResult(
@@ -37,7 +12,7 @@ export function renderCompactContextResult(
 	options: { expanded: boolean },
 	theme: Theme,
 ): Text {
-	if (options.expanded) return new Text(contentText(result), 0, 0);
-	const summary = readDetailsSummary(result) ?? firstLine(contentText(result));
+	if (options.expanded) return new Text(resultContentText(result), 0, 0);
+	const summary = readDetailsSummary(result) ?? firstLine(resultContentText(result));
 	return new Text(theme.fg("dim", summary), 0, 0);
 }

package/src/tool.ts

@@ -5,7 +5,7 @@
  * （R2 实测 2026-08-22：tool execute 内 await ctx.compact() 不可行——AgentSession.compact
  * 开头的 abort() 会中止当前 agent 循环，挂起的 Promise 永不兑现、session 无 toolResult。
  * 故走 §3.2 降级态：execute 立即返回"压缩已启动"，onComplete/onError 后经
- * sendSmartContextNotice 注入结果消息（nextTurn 车道，D4①——随下一次 prompt 注入，
+ * sendSmartContextNotice 注入结果消息（nextTurn 投递路径，D4①——随下一次 prompt 注入，
  * 不自起 run；此刻无进行中回合，compact 内部 abort 为 no-op）。
  * 压缩生成由 session_before_compact 接管 handler 完成（工具只触发，不生成）。
  *
@@ -153,9 +153,6 @@ export function registerCompactContextTool(
 	pi.registerTool({
 		name: "compact_context",
 		label: "compact_context",
-		// deferred（tool-declaration-slimming D4）：不常驻声明，tool_search 命中即激活；
-		// 迁移写入的 +tool_search 条目（runtime pi-codemode-settings）承载检索入口
-		exposure: "deferred",
 		description: TOOL_DESCRIPTION,
 		parameters: CompactContextParams,
 		execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {