@zhushanwen/pi-smart-context 0.3.3 → 0.3.5

package/README.md

@@ -8,8 +8,9 @@
 - **双模式生成接管**（`session_before_compact`，覆盖工具 / `/compact` / 内建 auto 三条路径）：
   - same-model：完整原始上下文 + 会话原 system prompt + tools + 末尾追加压缩指令——前缀缓存全命中，成本≈增量指令+输出，且模型看全量上下文（质量上限最高）
   - cross-model：调用 pi 原生 `compact()` 仅换模型与凭证——split-turn / fileOps / previousSummary 原生组装
-- **3 档阈值提醒**（默认 400K/500K/600K）：`agent_settled` 越档检查，每档一次、多档合并、压缩后重置。投递是**静默注入**（`pi.sendMessage` custom message + `triggerTurn:false` + `display:false`）——只进 LLM 上下文，不触发新 turn、不进对话流，用户继续对话时模型在下一轮自然看到；已提醒档位经 `pi.appendEntry` 落在 session entries（`smart-context:fired`），reload / 进程重启后从 entries 重建，同一档不会重复提醒。提醒文案两行以内，措辞是数据投递不是指令
+- **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）
 - **健壮性**：摘要收缩校验、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.3.3",
+  "version": "0.3.5",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -36,9 +36,9 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-llm-shared": "0.9.0"
+    "@zhushanwen/pi-llm-shared": "0.11.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/skills/smart-context-ext-config/SKILL.md

@@ -31,7 +31,7 @@ description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agen
 ```json
 {
   "enabled": true,
-  "compactModel": { "type": "ref", "ref": "xiaomi-token-plan-cn/mimo-v2.5" },
+  "compactModel": { "type": "ref", "ref": "xiaomi-token-plan-cn/mimo-v2.6-flash" },
   "reminderThresholds": [400000, 500000, 600000],
   "excludedModels": ["deepseek/deepseek-chat"]
 }

package/src/__tests__/index-reminder-delivery.test.ts

@@ -1,6 +1,6 @@
 // src/__tests__/index-reminder-delivery.test.ts
 //
-// D4' + D15 装配回归：越档提醒的「静默注入 + 档位持久化」两条语义在 index.ts 装配点成立。
+// D4① + D15 装配回归：越档提醒的「nextTurn 投递 + 档位持久化」两条语义在 index.ts 装配点成立。
 //
 // 现场（2026-09-19 会话 01a0b8b3）：taiji skill-reload 发 `/__taiji_reload__` → pi ctx.reload()
 // 重跑 extension factory（jiti moduleCache:false 重新 import）→ firedThresholds 归零，且 reload
@@ -8,7 +8,9 @@
 // sendUserMessage(followUp) 恒触发一轮（pi 语义），用户收工后仍被唤醒烧掉一整轮全量上下文。
 //
 // 本文件锁两件事：
-//   ① 投递形态 = sendMessage({customType, display:false}, {triggerTurn:false})，且不再用 sendUserMessage；
+//   ① 投递形态 = notices.ts 的 sendSmartContextNotice（customType "smart-context" + display:true，
+//      {triggerTurn:false, deliverAs:"nextTurn"}——随下一次 prompt 注入，不自起 run），且不再用
+//      sendUserMessage；
 //   ② fired 档位写入 session entries（appendEntry marker），工厂重跑（reload 等价拓扑）后
 //      从 entries 重建 → 同档不重复、跨档照常提醒。
 
@@ -37,12 +39,15 @@ const TEST_CONFIG = {
 	reminderThresholds: [200_000, 400_000, 600_000],
 	excludedModels: [] as string[],
 };
+/** 当前生效配置（事件回调热读——用例按需改写，beforeEach 复位）。 */
+let activeConfig = structuredClone(TEST_CONFIG);
 vi.mock("../pure.js", async (importOriginal) => ({
 	...(await importOriginal<typeof import("../pure.js")>()),
-	loadSmartContextConfig: () => structuredClone(TEST_CONFIG),
+	loadSmartContextConfig: () => structuredClone(activeConfig),
 }));
 
-import { FIRED_ENTRY_CUSTOM_TYPE, THRESHOLD_REMINDER_CUSTOM_TYPE } from "../pure.js";
+import { FIRED_ENTRY_CUSTOM_TYPE } from "../pure.js";
+import { SMART_CONTEXT_NOTICE_CUSTOM_TYPE } from "../notices.js";
 import smartContextExtension from "../index.js";
 
 interface MockPi {
@@ -93,8 +98,8 @@ function fireSessionStart(pi: MockPi, ctx: ExtensionContext): void {
 	pi.events.get("session_start")!({ type: "session_start", reason: "startup" }, ctx);
 }
 
-describe("D4': 越档提醒静默注入（不触发 turn、不进对话流）", () => {
-	it("命中档位 → sendMessage(customType, display:false) + {triggerTurn:false}；不再 sendUserMessage", () => {
+describe("D4①: 越档提醒 nextTurn 投递（不自起 run，随下次 prompt 注入）", () => {
+	it("命中档位 → sendMessage(customType smart-context + display:true + source) + {triggerTurn:false, deliverAs:'nextTurn'}；不再 sendUserMessage", () => {
 		const mock = createMockPi();
 		smartContextExtension(mock.pi);
 		fireSessionStart(mock, makeCtx(0));
@@ -103,9 +108,13 @@ describe("D4': 越档提醒静默注入（不触发 turn、不进对话流）",
 		expect(mock.sendUserMessage).not.toHaveBeenCalled();
 		expect(mock.sendMessage).toHaveBeenCalledTimes(1);
 		const [message, options] = mock.sendMessage.mock.calls[0]!;
-		expect(message).toMatchObject({ customType: THRESHOLD_REMINDER_CUSTOM_TYPE, display: false });
+		expect(message).toMatchObject({
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			display: true,
+			details: { source: "threshold-reminder" },
+		});
 		expect(String(message.content)).toContain("[smart-context]");
-		expect(options).toEqual({ triggerTurn: false });
+		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
 	});
 
 	it("命中档位 → 先写 fired marker（session entries 持久化）", () => {
@@ -201,6 +210,75 @@ describe("D15: 档位持久化跨 factory 重跑（reload 等价拓扑）", () =
 	});
 });
 
+describe("D5/D4①: 模型切换通知 nextTurn 投递（跨界 switch + downshift 两形态）", () => {
+	beforeEach(() => {
+		activeConfig = structuredClone(TEST_CONFIG);
+	});
+
+	/** 触发 model_select。 */
+	const fireModelSelect = (
+		mock: MockPi,
+		model: { provider: string; id: string; contextWindow?: number },
+		previousModel: { provider: string; id: string; contextWindow?: number },
+		tokens: number,
+	): void => {
+		mock.events.get("model_select")!({ type: "model_select", model, previousModel }, makeCtx(tokens));
+	};
+
+	it("跨越排除边界（切到 excludedModels 内模型）→ switch notice『不可用』经 nextTurn 投递", () => {
+		activeConfig.excludedModels = ["prov/small"];
+		const mock = createMockPi();
+		smartContextExtension(mock.pi);
+		fireModelSelect(mock, { provider: "prov", id: "small" }, { provider: "prov", id: "big" }, 0);
+
+		expect(mock.sendUserMessage).not.toHaveBeenCalled();
+		expect(mock.sendMessage).toHaveBeenCalledTimes(1);
+		const [message, options] = mock.sendMessage.mock.calls[0]!;
+		expect(message).toMatchObject({
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			display: true,
+			details: { source: "model-switch" },
+		});
+		expect(String(message.content)).toContain("暂时不可用");
+		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
+	});
+
+	it("同边界内切换（双方都未排除）且未触线 → 静默不投递", () => {
+		const mock = createMockPi();
+		smartContextExtension(mock.pi);
+		fireModelSelect(
+			mock,
+			{ provider: "prov", id: "a", contextWindow: 1_000_000 },
+			{ provider: "prov", id: "b", contextWindow: 1_000_000 },
+			100,
+		);
+
+		expect(mock.sendMessage).not.toHaveBeenCalled();
+	});
+
+	it("切到更小窗口且 tokens 将触线 → downshift notice 经 nextTurn 投递", () => {
+		const mock = createMockPi();
+		smartContextExtension(mock.pi);
+		// 旧窗口 1M → 新窗口 200K；触线 = 200K − pi 内建 reserve 16_384 = 183_616，tokens 190K 已过线
+		fireModelSelect(
+			mock,
+			{ provider: "prov", id: "small", contextWindow: 200_000 },
+			{ provider: "prov", id: "big", contextWindow: 1_000_000 },
+			190_000,
+		);
+
+		expect(mock.sendMessage).toHaveBeenCalledTimes(1);
+		const [message, options] = mock.sendMessage.mock.calls[0]!;
+		expect(message).toMatchObject({
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			display: true,
+			details: { source: "model-downshift" },
+		});
+		expect(String(message.content)).toContain("接近新模型窗口上限");
+		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
+	});
+});
+
 describe("D15: entries 读取异常降级（不阻断提醒链路）", () => {
 	beforeEach(() => {
 		loggerMock.debug.mockClear();

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

@@ -3,9 +3,10 @@ import { describe, expect, it } from "vitest";
 /**
  * SDK 契约测试（规范：凡调用 pi.on / pi.registerTool / 读 ctx.* 的代码必须有契约测试覆盖）。
  * 兜底 compact-handler.ts / llm.ts 中跨 SDK 泛型边界的 `as never` 断言——
- * 断言的运行时形状在这里实测（node_modules 实装 @earendil-works/pi-coding-agent@0.84.1）。
+ * 断言的运行时形状在这里实测（node_modules 实装 @earendil-works/pi-coding-agent@0.84.4）。
  */
 
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	buildSessionContext,
 	compact,
@@ -44,6 +45,25 @@ describe("pi SDK 契约（compact 接管路径依赖的导出形状）", () => {
 		expect(typeof completeSimple).toBe("function");
 	});
 
+	/**
+	 * D4① 通知注入通道契约：notices.ts 的 sendSmartContextNotice 形态必须与 SDK
+	 * ExtensionAPI.sendMessage 参数类型完全对齐（customType/content/display/details +
+	 * {triggerTurn, deliverAs:'nextTurn'}）——SDK 形状漂移时本用例编译期红。
+	 */
+	it("sendMessage(nextTurn) 通知形态符合 SDK 参数契约", () => {
+		type SendMessageParams = Parameters<ExtensionAPI["sendMessage"]>;
+		const message: SendMessageParams[0] = {
+			customType: "smart-context",
+			content: "[smart-context] 压缩完成。",
+			display: true,
+			details: { source: "compact-complete" },
+		};
+		const options: SendMessageParams[1] = { triggerTurn: false, deliverAs: "nextTurn" };
+		expect(message.customType).toBe("smart-context");
+		expect(options?.deliverAs).toBe("nextTurn");
+		expect(options?.triggerTurn).toBe(false);
+	});
+
 	it("compact() 的 preparation 参数运行时消费字段（messagesToSummarize/previousSummary/fileOps）在函数体内可达——静态签名核对", async () => {
 		// 不真正调网：用立即 abort 的 signal 让 compact 提前拒绝，验证参数形状被接受不抛 TypeError
 		const controller = new AbortController();

package/src/__tests__/tool.test.ts

@@ -9,7 +9,7 @@ vi.mock("../pure.js", async (importOriginal) => {
 	};
 });
 
-import { DEFAULT_SMART_CONTEXT_CONFIG, COMPACT_RESULT_CUSTOM_TYPE, loadSmartContextConfig } from "../pure.js";
+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";
@@ -26,12 +26,13 @@ type CompactOpts = {
 	onError: (e: Error) => void;
 };
 
-function makePi(): { pi: ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn> }; tools: RegisteredTool[] } {
+function makePi(): { pi: ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn>; sendUserMessage: ReturnType<typeof vi.fn> }; tools: RegisteredTool[] } {
 	const tools: RegisteredTool[] = [];
 	const pi = {
 		registerTool: (t: RegisteredTool) => tools.push(t),
 		sendMessage: vi.fn(),
-	} as unknown as ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn> };
+		sendUserMessage: vi.fn(),
+	} as unknown as ExtensionAPI & { sendMessage: ReturnType<typeof vi.fn>; sendUserMessage: ReturnType<typeof vi.fn> };
 	return { pi, tools };
 }
 
@@ -94,20 +95,24 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		expect(result.details).toMatchObject({ mode: "same-model", launched: true, fellBack: false, compactionCount: 1 });
 	});
 
-	it("onComplete 兑现后 sendMessage custom message 注入结果（customType/display/triggerTurn 三要素；模式/前后 tokens/成本；降智提示按次数）", async () => {
+	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]!;
-		expect(message).toMatchObject({ customType: COMPACT_RESULT_CUSTOM_TYPE, display: true });
-		expect(String(message.content)).toContain("压缩完成");
-		expect(String(message.content)).toContain("same-model");
-		expect(String(message.content)).toContain("500K");
-		expect(String(message.content)).toContain("24K");
-		expect(String(message.content)).toContain("compacted multiple times");
-		// A6 投递时机：triggerTurn:true 唤醒轮次消费压缩结果（streaming 时 pi 缺省走 steer 队列）
-		expect(options).toEqual({ triggerTurn: true });
+		const [message, options] = pi.sendMessage.mock.calls[0];
+		// 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" });
+		const text = message.content as string;
+		expect(text).toContain("压缩完成");
+		expect(text).toContain("same-model");
+		expect(text).toContain("500K");
+		expect(text).toContain("24K");
+		expect(text).toContain("compacted multiple times");
+		// 旧车道（自起 run 的 user 消息）已退役：不再调用 sendUserMessage（mock 挂 spy，被调用即断言红）
+		expect(pi.sendUserMessage).not.toHaveBeenCalled();
 	});
 
 	it("onComplete 无 engine 标记 → 注入消息含回退说明与修复指引（D7）", async () => {
@@ -116,20 +121,19 @@ describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入
 		const ctx = makeCtx((options) => options.onComplete({ tokensBefore: 1, estimatedTokensAfter: 1 }));
 		await tools[0].execute("t1", {}, undefined, undefined, ctx);
 		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
-		expect(String(pi.sendMessage.mock.calls[0]![0].content)).toContain("回退");
+		expect(pi.sendMessage.mock.calls[0][0].content).toContain("回退");
 	});
 
-	it("onError → 注入失败消息带重试指引（display:true 失败必须用户可见 + triggerTurn:true）", 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")));
 		await tools[0].execute("t1", {}, undefined, undefined, ctx);
-		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
-		const [message, options] = pi.sendMessage.mock.calls[0]!;
-		expect(message).toMatchObject({ customType: COMPACT_RESULT_CUSTOM_TYPE, display: true });
-		expect(String(message.content)).toContain("压缩失败");
-		expect(String(message.content)).toContain("Nothing to compact");
-		expect(options).toEqual({ triggerTurn: true });
+		const [message, options] = pi.sendMessage.mock.calls[0];
+		expect(message.content).toContain("压缩失败");
+		expect(message.content).toContain("Nothing to compact");
+		expect(message.details).toEqual({ source: "compact-failed" });
+		expect(options).toEqual({ triggerTurn: false, deliverAs: "nextTurn" });
 	});
 
 	it("custom_instructions 透传给 ctx.compact", async () => {

package/src/index.ts

@@ -6,8 +6,12 @@
  * - subagent 进程（R6）：不注册工具、不提醒（宁缺勿污）
  * - session_before_compact：双模式接管（compact-handler）
  * - session_compact：重置提醒 fired（D3）
- * - agent_settled：越档检查 + marker 持久化 + 静默注入（D3/D4/D15）
- * - model_select：跨界通知 + downshift 提醒（D5）
+ * - agent_settled：越档检查 + marker 持久化（D15）+ nextTurn 投递一次性提醒（D3/D4①）
+ * - model_select：跨界通知 + downshift 提醒（D5/D4①）
+ *
+ * 通知注入车道（D4①，delivery-ownership-kernel）：四类通知全部经 notices.ts 的
+ * sendSmartContextNotice 走 nextTurn（随下一次 prompt 注入、不自起 run）——通知 run 不再
+ * 抢占用户消息投递跑道；被压缩掐断的 turn 由 runtime 续跑投递兜底（D4②）。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -20,6 +24,7 @@ import {
 	debugLog,
 	type TakeoverState,
 } from "./compact-handler.js";
+import { sendSmartContextNotice } from "./notices.js";
 import { buildDownshiftNotice, buildSwitchNotice, buildThresholdReminder } from "./reminder.js";
 import { registerCompactContextTool } from "./tool.js";
 import {
@@ -30,9 +35,6 @@ import {
 	getCurrentModelId,
 	isGatingActive,
 	loadSmartContextConfig,
-	SWITCH_NOTICE_CUSTOM_TYPE,
-	DOWNSHIFT_NOTICE_CUSTOM_TYPE,
-	THRESHOLD_REMINDER_CUSTOM_TYPE,
 	type EntryLike,
 } from "./pure.js";
 
@@ -151,7 +153,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 	// 守卫的前置代际检查恒不生效。wrapper 每次调用读闭包当前绑定。
 	registerCompactContextTool(pi, { isCtxStale: () => isCtxStale() });
 
-	// ── 阈值提醒（D3/D4/D4'）：agent_settled 越档检查 + 静默注入（不触发 turn） ──
+	// ── 阈值提醒（D3/D4）：agent_settled 越档检查 + marker 持久化 + nextTurn 一次性投递 ──
 	pi.on("agent_settled", (_event, ctx) => {
 		const config = loadSmartContextConfig();
 		const modelId = getCurrentModelId(ctx.model);
@@ -178,18 +180,13 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 			label: "smart-context:fired-marker",
 			onStale: (error) => debugLog(`fired marker skipped (stale ctx): ${toErrorMessage(error)}`),
 		});
-		// D4'：静默注入——custom message + triggerTurn:false = 只进 LLM 上下文，不触发新 turn、
-		// 不进对话流（display:false）。不再用 sendUserMessage（pi 语义：user message 恒触发
-		// 一轮），避免用户已收工时被提醒强行唤醒烧一整轮全量上下文。
-		// 用户继续对话时，模型在下一轮自然看到本提醒并自行决定是否 compact。
-		// 防循环：crossed 全部已标记 fired，marker 也不会产生新 turn。
+		// D4①：nextTurn（随下一次 prompt 作为 custom role 上下文注入，不自起 run）——原 followUp
+		// 会在 agent 空闲后自起一个提醒 run，与用户消息同抢 prompt 跑道（故事 C 的三重放大器之一）。
+		// 防循环：crossed 全部已标记 fired，marker 与提醒触发的 settled 不会重复发。
 		// 事件回调内直接调用捕获的 pi——session 替换窗口可能 stale（crash-resilience D1
 		// 普查接入点），守卫 stale 静默降级（不杀 pi 进程），非 stale 错误原样上抛。
 		guardStaleCtx(() => {
-			pi.sendMessage(
-				{ customType: THRESHOLD_REMINDER_CUSTOM_TYPE, content: message, display: false },
-				{ triggerTurn: false },
-			);
+			sendSmartContextNotice(pi, message, "threshold-reminder");
 		}, {
 			isCtxStale,
 			label: "smart-context:threshold-reminder",
@@ -216,10 +213,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 			// 调整（compact 工具 execute 有运行时门控校验兜底），不为通知烧一整轮全量上下文。
 			// session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
 			guardStaleCtx(() => {
-				pi.sendMessage(
-					{ customType: SWITCH_NOTICE_CUSTOM_TYPE, content: notice, display: false },
-					{ triggerTurn: false },
-				);
+				sendSmartContextNotice(pi, notice, "model-switch");
 			}, {
 				isCtxStale,
 				label: "smart-context:switch-notice",
@@ -240,10 +234,7 @@ export default function smartContextExtension(pi: ExtensionAPI): void {
 			// "建议"非紧急（同 S1 裁决）：triggerTurn:false 不唤醒轮次，用户继续对话时
 			// LLM 自行决策是否先压缩。session 替换窗口可能 stale（D1 普查接入点）——守卫 stale 静默降级
 			guardStaleCtx(() => {
-				pi.sendMessage(
-					{ customType: DOWNSHIFT_NOTICE_CUSTOM_TYPE, content: downshift, display: false },
-					{ triggerTurn: false },
-				);
+				sendSmartContextNotice(pi, downshift, "model-downshift");
 			}, {
 				isCtxStale,
 				label: "smart-context:downshift-notice",

package/src/notices.ts

@@ -0,0 +1,59 @@
+/**
+ * 通知注入唯一出口（D4①：四类通知 nextTurn 化）。
+ *
+ * 四类通知（压缩结果 onComplete / onError、阈值提醒、model_select 跨界与降档两条）从
+ * `sendUserMessage(deliverAs:'steer'|'followUp')` 改为 `sendMessage(deliverAs:'nextTurn',
+ * triggerTurn:false)`——通知作为 custom role 上下文随下一次 prompt 注入（pi 0.84.4 实证，登记
+ * docs/pi-semantics.json#PS-06：`_pendingNextTurnMessages` 常驻至被消费、不自起 run），结构上消除「通知自起 run 抢占用户
+ * 消息投递跑道」——故事 C 根因：压缩完成后通知 run 与用户消息同时 prompt()，后到者被 pi 以
+ * `Agent is already processing` 拒绝。
+ *
+ * 语义定性（设计 D4「C-ext-19 合规定性」四类两分）：
+ * - 阈值提醒 / 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）。
+ *
+ * 已接受代价（设计 D4 四要素）：阈值提醒不再于 agent 空闲时立即生效，改为随用户下一条消息
+ * 注入——pi 内建 overflow/threshold 自动压缩兜底在场，无人在场时上下文可能持续增长。
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** 通知的 customType（taiji 侧按此识别 system 消息来源；pi TUI display 恒 true）。 */
+export const SMART_CONTEXT_NOTICE_CUSTOM_TYPE = "smart-context";
+
+/** 通知来源（进 details.source，排障定位用）。 */
+export type SmartContextNoticeSource =
+	| "compact-complete"
+	| "compact-failed"
+	| "threshold-reminder"
+	| "model-switch"
+	| "model-downshift";
+
+/**
+ * 注入一条 smart-context 通知（nextTurn 车道，不自起 run）。
+ *
+ * `deliverAs:'nextTurn'` 是投递车道（pi 实装分支序：nextTurn 分支先命中，`triggerTurn`
+ * 不再参与判定）；`triggerTurn:false` 是意图的显式声明（双写防未来实现分支序漂移）。
+ * `display:true` 使通知在对话流可见——分车道语义（D4①）：compact-result 两条（complete/
+ * failed）改造前即 display:true 系统消息，可见性保持；阈值提醒/模型跨界/downshift 三条
+ * 改造前 display:false 静默（只进 LLM 上下文，不进对话流），随 nextTurn 车道统一转
+ * display:true 可见。
+ */
+export function sendSmartContextNotice(
+	pi: Pick<ExtensionAPI, "sendMessage">,
+	text: string,
+	source: SmartContextNoticeSource,
+): void {
+	pi.sendMessage(
+		{
+			customType: SMART_CONTEXT_NOTICE_CUSTOM_TYPE,
+			content: text,
+			display: true,
+			details: { source },
+		},
+		{ triggerTurn: false, deliverAs: "nextTurn" },
+	);
+}

package/src/pure.ts

@@ -272,18 +272,6 @@ export function countCompactions(entries: ReadonlyArray<EntryLike>): number {
  */
 export const FIRED_ENTRY_CUSTOM_TYPE = "smart-context:fired";
 
-/** 越档提醒注入的 custom message 类型（静默通道：只进 LLM 上下文，不进对话流）。 */
-export const THRESHOLD_REMINDER_CUSTOM_TYPE = "smart-context:threshold-reminder";
-
-/** 模型跨界通知注入的 custom message 类型（静默通道：不触发 turn，LLM 下轮自然可见）。 */
-export const SWITCH_NOTICE_CUSTOM_TYPE = "smart-context:switch-notice";
-
-/** downshift 建议压缩注入的 custom message 类型（静默通道：不触发 turn，用户继续对话时 LLM 自行决策）。 */
-export const DOWNSHIFT_NOTICE_CUSTOM_TYPE = "smart-context:downshift-notice";
-
-/** compact 完成/失败注入的 custom message 类型（用户可见系统消息 + 唤醒一轮消费压缩结果）。 */
-export const COMPACT_RESULT_CUSTOM_TYPE = "smart-context:compact-result";
-
 /** fired marker 的载荷形状（写入方 index.ts 与本文件推导函数共用的唯一定义点）。 */
 export interface FiredMarkerData {
 	/** 本次标记已提醒的档位（token 值）。 */

package/src/reminder.ts

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

package/src/tool.ts

@@ -5,8 +5,13 @@
  * （R2 实测 2026-08-22：tool execute 内 await ctx.compact() 不可行——AgentSession.compact
  * 开头的 abort() 会中止当前 agent 循环，挂起的 Promise 永不兑现、session 无 toolResult。
  * 故走 §3.2 降级态：execute 立即返回"压缩已启动"，onComplete/onError 后经
- * pi.sendMessage custom message 注入结果——此时无进行中回合，abort 为 no-op）。
+ * sendSmartContextNotice 注入结果消息（nextTurn 车道，D4①——随下一次 prompt 注入，
+ * 不自起 run；此刻无进行中回合，compact 内部 abort 为 no-op）。
  * 压缩生成由 session_before_compact 接管 handler 完成（工具只触发，不生成）。
+ *
+ * 掐断的 turn 由 runtime 兜底续跑（设计 D4②）：本工具触发的 manual compact 会 abort 进行中
+ * 的 agent turn（pi F5：manual compact 明文不续跑），runtime 在 compaction_end 判定
+ * 「manual + 非 runtime 发起 + compaction_start 前 turn 被掐断」后经投递内核追加续跑投递。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -14,11 +19,11 @@ import { guardStaleCtx, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guar
 import { Type } from "typebox";
 
 import { debugLog } from "./compact-handler.js";
+import { sendSmartContextNotice } from "./notices.js";
 import { buildDegradationHintLine } from "./reminder.js";
 import {
 	DEGRADATION_HINT_MIN_COMPACTIONS,
 	checkToolThresholdGuard,
-	COMPACT_RESULT_CUSTOM_TYPE,
 	countCompactions,
 	formatK,
 	getCurrentModelId,
@@ -161,9 +166,8 @@ export function registerCompactContextTool(
 			const compactionCount = countCompactions(getEntries(ctx));
 
 			// R2 降级态：fire-and-forget。工具立即返回"已启动"；压缩完成后（此时无进行中
-			// 回合，compact 内部的 abort 为 no-op）经 sendMessage custom message 注入结果
-			// （triggerTurn:true 唤醒一轮让 agent 立即消费结果——工具已承诺"完成后你会收到
-			// 结果消息"；若此刻仍在 streaming，pi 缺省走 steer 队列，下一 LLM 调用前投递）
+			// 回合，compact 内部的 abort 为 no-op）经 sendSmartContextNotice 注入结果
+			// （nextTurn：随下一次 prompt 作为 custom role 上下文注入，不自起 run——D4①）
 			const mode = pickMode(config, gating.modelId);
 			ctx.compact({
 				customInstructions:
@@ -172,7 +176,7 @@ export function registerCompactContextTool(
 						: undefined,
 				// E1 实锤崩溃点（9/3 pi-crash log）：两个回调由 compact 的内部 Promise 链异步
 				// 调用，不在 pi runner emit() 的 try/catch 内——session 替换窗口（GUI 切
-				// session/新建/重载高频触发）下 pi.sendMessage 命中 stale ctx 同步抛错即
+				// session/新建/重载高频触发）下 sendMessage 命中 stale ctx 同步抛错即
 				// 杀死 pi 进程（pi 0.84.4 实装：dist/core/extensions/loader.js 的 assertActive
 				// 214-219 wrapper → 142-146 staleMessage throw，在 runtime 调用前同步 throw）。
 				// 守卫 stale 静默降级（结果不投递，用户可重试 /compact），非
@@ -193,12 +197,7 @@ export function registerCompactContextTool(
 							`压缩前 ${formatK(result.tokensBefore ?? 0)} tokens → 压缩后约 ${formatK(result.estimatedTokensAfter ?? 0)} tokens；摘要生成成本：${cost}。`,
 							showHint ? buildDegradationHintLine() : "",
 						].filter((l) => l !== "");
-						// display:true 进对话流（系统消息形态，非用户气泡）；对齐
-						// base-tool-enhance 完成通知先例（失败必须用户可见，不压 display:false）
-						pi.sendMessage(
-							{ customType: COMPACT_RESULT_CUSTOM_TYPE, content: lines.join("\n"), display: true },
-							{ triggerTurn: true },
-						);
+						sendSmartContextNotice(pi, lines.join("\n"), "compact-complete");
 					}, {
 						isCtxStale: deps?.isCtxStale,
 						label: "smart-context:compact-onComplete",
@@ -209,13 +208,10 @@ export function registerCompactContextTool(
 					// 压缩本身的失败信息先落日志（守卫体外——stale 降级时该观测保留）
 					debugLog(`compact_context error: ${err.message}`);
 					guardStaleCtx(() => {
-						pi.sendMessage(
-							{
-								customType: COMPACT_RESULT_CUSTOM_TYPE,
-								content: `[smart-context] 压缩失败：${err.message}。上下文未变化，可稍后重试（若反复失败，检查 smart-context 配置或使用 /compact）。`,
-								display: true,
-							},
-							{ triggerTurn: true },
+						sendSmartContextNotice(
+							pi,
+							`[smart-context] 压缩失败：${err.message}。上下文未变化，可稍后重试（若反复失败，检查 smart-context 配置或使用 /compact）。`,
+							"compact-failed",
 						);
 					}, {
 						isCtxStale: deps?.isCtxStale,