@zhushanwen/pi-smart-context 0.1.0

package/src/__tests__/tool.test.ts

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// mock 配置加载（工具测试不落盘）
+vi.mock("../pure.js", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("../pure.js")>();
+	return {
+		...actual,
+		loadSmartContextConfig: vi.fn(),
+	};
+});
+
+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";
+
+interface RegisteredTool {
+	name: string;
+	parameters: { type?: 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> }>;
+}
+
+type CompactOpts = {
+	customInstructions?: string;
+	onComplete: (r: unknown) => void;
+	onError: (e: Error) => void;
+};
+
+function makePi(): { pi: ExtensionAPI & { sendUserMessage: ReturnType<typeof vi.fn> }; tools: RegisteredTool[] } {
+	const tools: RegisteredTool[] = [];
+	const pi = {
+		registerTool: (t: RegisteredTool) => tools.push(t),
+		sendUserMessage: vi.fn(),
+	} as unknown as ExtensionAPI & { sendUserMessage: ReturnType<typeof vi.fn> };
+	return { pi, tools };
+}
+
+function makeCtx(compactImpl?: (options: CompactOpts) => void): ExtensionContext {
+	return {
+		model: { provider: "zai", id: "glm" },
+		getContextUsage: () => ({ tokens: 250_000, contextWindow: 1_000_000 }),
+		sessionManager: { getEntries: () => [] },
+		compact: compactImpl ?? ((options: CompactOpts) => {
+			options.onComplete({
+				tokensBefore: 500_000,
+				estimatedTokensAfter: 24_000,
+				usage: { input: 432_000, output: 1_800, cacheRead: 0 },
+				details: { engine: "smart-context", mode: "same-model" },
+			});
+		}),
+	} as unknown as ExtensionContext;
+}
+
+const mockedLoad = vi.mocked(loadSmartContextConfig);
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mockedLoad.mockReturnValue(DEFAULT_SMART_CONTEXT_CONFIG);
+});
+
+describe("compact_context 工具（R2 降级态：fire-and-forget + 结果注入）", () => {
+	it("parameters 顶层为 Type.Object（OpenAI 兼容红线）", () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi);
+		expect(tools[0].parameters.type).toBe("object");
+		expect(tools[0].name).toBe("compact_context");
+	});
+
+	it("门控拒绝（排除命中）→ throw 带原因与恢复指引（D5）", async () => {
+		mockedLoad.mockReturnValue({ ...DEFAULT_SMART_CONTEXT_CONFIG, excludedModels: ["zai/glm"] });
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { gatingProbe: () => ({ active: false, modelId: "zai/glm" }) });
+		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/已配置为排除/);
+	});
+
+	it("阈值保护：低于最低档 throw 带用量数据（D6）", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { usageProbe: () => ({ tokens: 38_000, contextWindow: 1_000_000 }) });
+		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/38K/);
+	});
+
+	it("阈值保护：tokens null → 用量未知拒绝（D6 null 分支）", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { usageProbe: () => ({ tokens: null, contextWindow: 1_000_000 }) });
+		await expect(tools[0].execute("t1", {}, undefined, undefined, makeCtx())).rejects.toThrow(/用量未知/);
+	});
+
+	it("execute 立即返回「已启动」（不 await 压缩完成，R2 契约）+ details 结构化", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { getEntries: () => [{ type: "message" }] });
+		const result = await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
+		expect(result.content[0].text).toContain("压缩已启动");
+		expect(result.content[0].text).toContain("same-model");
+		expect(result.details).toMatchObject({ mode: "same-model", launched: true, fellBack: false, compactionCount: 1 });
+	});
+
+	it("onComplete 兑现后 sendUserMessage 注入结果（含模式/前后 tokens/成本；降智提示按次数）", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi, { getEntries: () => [{ type: "compaction" }, { type: "compaction" }] });
+		await tools[0].execute("t1", {}, undefined, undefined, makeCtx());
+		expect(pi.sendUserMessage).toHaveBeenCalledTimes(1);
+		const [message, options] = pi.sendUserMessage.mock.calls[0];
+		expect(message).toContain("压缩完成");
+		expect(message).toContain("same-model");
+		expect(message).toContain("500K");
+		expect(message).toContain("24K");
+		expect(message).toContain("compacted multiple times");
+		expect(options).toEqual({ deliverAs: "steer" });
+	});
+
+	it("onComplete 无 engine 标记 → 注入消息含回退说明与修复指引（D7）", async () => {
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi);
+		const ctx = makeCtx((options) => options.onComplete({ tokensBefore: 1, estimatedTokensAfter: 1 }));
+		await tools[0].execute("t1", {}, undefined, undefined, ctx);
+		expect(pi.sendUserMessage).toHaveBeenCalledTimes(1);
+		expect(pi.sendUserMessage.mock.calls[0][0]).toContain("回退");
+	});
+
+	it("onError → 注入失败消息带重试指引", 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.sendUserMessage.mock.calls[0][0]).toContain("压缩失败");
+		expect(pi.sendUserMessage.mock.calls[0][0]).toContain("Nothing to compact");
+	});
+
+	it("custom_instructions 透传给 ctx.compact", async () => {
+		let received: string | undefined;
+		const { pi, tools } = makePi();
+		registerCompactContextTool(pi);
+		const ctx = makeCtx((options) => {
+			received = options.customInstructions;
+			options.onComplete({ details: { engine: "smart-context", mode: "cross-model" } });
+		});
+		await tools[0].execute("t1", { custom_instructions: "保留验证结果" }, undefined, undefined, ctx);
+		expect(received).toBe("保留验证结果");
+	});
+
+	it("countCompactions 只数 compaction entries", () => {
+		expect(countCompactions([{ type: "message" }, { type: "compaction" }, { type: "compaction" }])).toBe(2);
+	});
+});

package/src/compact-handler.ts

@@ -0,0 +1,321 @@
+/**
+ * session_before_compact 接管 handler（D1/D11/D12/D13 核心）。
+ *
+ * 三条压缩路径（agent 工具 / 用户 /compact / 内建 auto）统一经过这里：
+ * - 门控未放行 / 熔断 / 生成失败 → 返回空（pi 原生生成兜底，D2/D7）
+ * - same-model 模式：完整上下文 + 会话原 system prompt + tools + 末尾追加压缩指令（kv-cache 前缀命中）
+ * - cross-model 模式：直接调用包导出的 compact(preparation, 压缩Model, ...)（原生组装零复刻，R4 结论）
+ *
+ * 输出 CompactionResult.details 携带 {engine:"smart-context", mode} 标记（D1 entry 标记）。
+ */
+
+import { buildSessionContext, compact as nativeCompact, convertToLlm } from "@earendil-works/pi-coding-agent";
+import type { CompactionResult } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "@zhushanwen/pi-extension-logger";
+import { resolveModel } from "@zhushanwen/pi-llm-shared";
+import { readFileSync } from "node:fs";
+
+import { callSameModelCompaction, projectTools } from "./llm.js";
+import {
+	buildSameModelInstruction,
+	buildTranscriptPointer,
+	CHECKPOINT_PREAMBLE,
+} from "./prompts.js";
+import {
+	buildReinjectSection,
+	collectKeptReadFiles,
+	computeFileListsLike,
+	estimateShadowedTokens,
+	estimateTextTokens,
+	formatFileOperationsLike,
+	getCurrentModelId,
+	isSummaryInflated,
+	pickMode,
+	pickReinjectFiles,
+	type FileOpsLike,
+	type SmartContextConfig,
+} from "./pure.js";
+
+/** session_before_compact 事件的宽松形状（消费字段收窄，不依赖 pi 事件类型导出）。 */
+export interface BeforeCompactLikeEvent {
+	type: "session_before_compact";
+	preparation: {
+		firstKeptEntryId: string;
+		messagesToSummarize: ReadonlyArray<{ role: string; content?: unknown }>;
+		turnPrefixMessages: ReadonlyArray<{ role: string }>;
+		isSplitTurn: boolean;
+		tokensBefore: number;
+		previousSummary?: string;
+		fileOps: FileOpsLike;
+	};
+	branchEntries: ReadonlyArray<unknown>;
+	customInstructions?: string;
+	reason: "manual" | "threshold" | "overflow";
+	willRetry: boolean;
+	signal?: AbortSignal;
+}
+
+/** handler 返回（SessionBeforeCompactResult 子集）。 */
+export interface BeforeCompactDecision {
+	cancel?: boolean;
+	compaction?: CompactionResult;
+}
+
+/** session 级接管状态（session_start 重建闭包，规范 Session 隔离）。 */
+export interface TakeoverState {
+	/** 接管连续失败计数（D13-3 熔断：≥3 停止接管）。 */
+	failStreak: number;
+	/** 收缩校验失败已记录的段（firstKeptEntryId 集合，D13-1 同段不重试）。 */
+	inflatedSegments: Set<string>;
+}
+
+const TAKEOVER_FAILURE_LIMIT = 3;
+
+export function createTakeoverState(): TakeoverState {
+	return { failStreak: 0, inflatedSegments: new Set() };
+}
+
+/** 统一 logger（@zhushanwen/pi-extension-logger：debug 文件日志 / warn 走 appendEntry 持久化）。 */
+const logger = createLogger("smart-context");
+
+/** 开发调试日志（XYZ_AGENT_DEBUG=1 时写文件，默认 no-op；logging-conventions 统一通道）。 */
+export function debugLog(message: string): void {
+	logger.debug(message);
+}
+
+/** 内部降级/失败（事后排查价值，appendEntry 持久化不进 LLM 上下文）。 */
+function warnLog(message: string, data?: unknown): void {
+	logger.warn(message, data);
+}
+
+/** 压缩引擎标记（D1 entry 标记，details 字段直接落 compaction entry）。 */
+export interface SmartContextDetails {
+	engine: "smart-context";
+	mode: "same-model" | "cross-model";
+}
+
+/**
+ * session 文件路径（transcript 回查指针用，D13-4）：从 sessionManager 推导。
+ * getSessionFile 若不可得则返回空串（指针省略，不失败）。
+ */
+function getSessionFilePath(ctx: ExtensionContext): string {
+	const sm = ctx.sessionManager as unknown as {
+		getSessionFile?: () => string | undefined;
+		sessionFile?: string;
+	};
+	try {
+		return sm.getSessionFile?.() ?? sm.sessionFile ?? "";
+	} catch {
+		return "";
+	}
+}
+
+/** 读文件做重注入（D13-11）：读失败/空内容返回空串（逐文件降级）。 */
+function readFileForReinject(path: string): string {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * 组装 summary 后处理（两模式共用，D13-1/4/9/11 + D11-2）：
+ * preamble + 模型摘要 + fileOps 清单 + 文件重注入节 + transcript 指针。
+ */
+function assembleSummary(
+	summaryText: string,
+	fileOps: FileOpsLike,
+	branchEntries: ReadonlyArray<unknown>,
+	firstKeptEntryId: string,
+	sessionFilePath: string,
+): string {
+	const { readFiles, modifiedFiles } = computeFileListsLike(fileOps);
+	let summary = `${CHECKPOINT_PREAMBLE}\n\n${summaryText}`;
+	summary += formatFileOperationsLike(readFiles, modifiedFiles);
+
+	// D13-11 文件重注入：只读文件取最近 ≤5 个（保留段已有的跳过）
+	const keptReads = collectKeptReadFiles(branchEntries, firstKeptEntryId);
+	const candidates = pickReinjectFiles(readFiles, keptReads);
+	if (candidates.length > 0) {
+		const contents = candidates.map((p) => ({ path: p, content: readFileForReinject(p) }));
+		summary += buildReinjectSection(contents);
+	}
+
+	if (sessionFilePath !== "") {
+		summary += buildTranscriptPointer(sessionFilePath);
+	}
+	return summary;
+}
+
+/**
+ * same-model 生成（D12）：完整上下文 + 会话原 system prompt + tools + 追加压缩指令。
+ * 返回 null = 失败（调用方走 D7 回退）。
+ */
+async function generateSameMode(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	event: BeforeCompactLikeEvent,
+): Promise<CompactionResult | null> {
+	const model = ctx.model;
+	if (!model) {
+		debugLog("same-mode: no current model");
+		return null;
+	}
+	// AgentMessage[]（含 bash/custom 等扩展消息）→ 标准 Message[]（与主会话请求同源转换，
+	// convertToLlm 是 pi host 默认实现——同样的输入产生同样的输出，前缀缓存对齐的前提）
+	const fullMessages = convertToLlm(buildSessionContext(event.branchEntries as never).messages);
+	const instructionMessage = {
+		role: "user" as const,
+		content: [{ type: "text" as const, text: buildSameModelInstruction(event.customInstructions) }],
+		timestamp: Date.now(),
+	};
+	const tools = projectTools(pi.getAllTools());
+	const result = await callSameModelCompaction(ctx, {
+		model,
+		systemPrompt: ctx.getSystemPrompt() ?? "",
+		messages: [...fullMessages, instructionMessage],
+		tools,
+		signal: event.signal,
+		sessionId: ctx.sessionManager.getSessionId(),
+	});
+	if (!result.ok) {
+		warnLog("same-mode call failed", { error: result.error });
+		return null;
+	}
+	// D13-2 max-tokens 截断 fail-closed：不完整 checkpoint 不采用
+	if (result.stopReason === "length") {
+		debugLog("same-mode: summary truncated by max-tokens, rejecting");
+		return null;
+	}
+	if (result.text === "") {
+		debugLog("same-mode: empty summary text");
+		return null;
+	}
+	const sessionFile = getSessionFilePath(ctx);
+	const summary = assembleSummary(
+		result.text,
+		event.preparation.fileOps,
+		event.branchEntries,
+		event.preparation.firstKeptEntryId,
+		sessionFile,
+	);
+	return {
+		summary,
+		firstKeptEntryId: event.preparation.firstKeptEntryId,
+		tokensBefore: event.preparation.tokensBefore,
+		usage: result.usage as CompactionResult["usage"],
+		details: { engine: "smart-context", mode: "same-model" } satisfies SmartContextDetails,
+	};
+}
+
+/**
+ * cross-model 生成（D12）：调用包导出的原生 compact()，仅替换 model + auth。
+ * split-turn 双段合并 / fileOps 追加 / previousSummary 透传全部原生（R4 静态结论，零复刻）。
+ * 返回 null = 失败（调用方走 D7 回退）。
+ */
+async function generateCrossMode(
+	ctx: ExtensionContext,
+	event: BeforeCompactLikeEvent,
+	config: SmartContextConfig,
+): Promise<CompactionResult | null> {
+	const model = resolveModel(ctx, config.compactModel);
+	if (!model) {
+		debugLog("cross-mode: compact model not available, falling back");
+		return null;
+	}
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) {
+		warnLog("cross-mode auth failed", { error: auth.error });
+		return null;
+	}
+	// ProviderHeaders 值可为 null；nativeCompact 的 headers 参数是 Record<string, string>——
+	// 过滤 null 值（运行时清洗而非 cast）
+	const headers = auth.headers
+		? Object.fromEntries(
+			Object.entries(auth.headers).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+		)
+		: undefined;
+	const result = await nativeCompact(
+		event.preparation as never,
+		model as never,
+		auth.apiKey,
+		headers,
+		event.customInstructions,
+		event.signal,
+		undefined,
+		undefined,
+		auth.env,
+	);
+	// D13-2：原生 compact 内部对截断的处理沿用原生语义；此处补 engine 标记
+	return {
+		...result,
+		details: { ...(result.details as object | undefined), engine: "smart-context", mode: "cross-model" } as SmartContextDetails,
+	};
+}
+
+/**
+ * session_before_compact handler 工厂。
+ *
+ * state 为 session 级闭包（由 src/index.ts 在 session_start 重建后传入）。
+ */
+export function createBeforeCompactHandler(
+	pi: ExtensionAPI,
+	getState: () => TakeoverState,
+	loadConfigFn: () => SmartContextConfig,
+): (event: BeforeCompactLikeEvent, ctx: ExtensionContext) => Promise<BeforeCompactDecision> {
+	return async (event, ctx) => {
+		const config = loadConfigFn();
+		const currentModelId = getCurrentModelId(ctx.model);
+
+		// D5 门控：禁用/排除 → 空返回（pi 原生生成）
+		if (config.enabled !== true || currentModelId === "" || config.excludedModels.includes(currentModelId)) {
+			return {};
+		}
+		const state = getState();
+
+		// D13-3 熔断：连续失败 ≥3 → 本 session 停止接管
+		if (state.failStreak >= TAKEOVER_FAILURE_LIMIT) {
+			debugLog("takeover circuit breaker open, falling back to native");
+			return {};
+		}
+		// D13-1 收缩校验失败段不重试
+		if (state.inflatedSegments.has(event.preparation.firstKeptEntryId)) {
+			debugLog("segment previously inflated, skipping takeover");
+			return {};
+		}
+
+		// D12 模式判定（现场热判，切模型/改配置后下次压缩即生效）
+		const mode = pickMode(config, currentModelId);
+
+		try {
+			const result = mode === "same-model"
+				? await generateSameMode(pi, ctx, event)
+				: await generateCrossMode(ctx, event, config);
+
+			if (!result) {
+				state.failStreak += 1;
+				return {}; // D7 回退：pi 原生生成兜底
+			}
+
+			// D13-1 收缩校验：摘要 ≥ 被压段 → 拒绝落盘 + 记录该段
+			const summaryTokens = estimateTextTokens(result.summary);
+			const shadowedTokens = estimateShadowedTokens(event.preparation.messagesToSummarize);
+			if (isSummaryInflated(summaryTokens, shadowedTokens)) {
+				state.inflatedSegments.add(event.preparation.firstKeptEntryId);
+				state.failStreak += 1;
+				warnLog("summary inflated, rejecting takeover", { summaryTokens, shadowedTokens });
+				return {};
+			}
+
+			state.failStreak = 0;
+			debugLog(`takeover ok: mode=${mode} reason=${event.reason} summaryTokens=${summaryTokens}`);
+			return { compaction: result };
+		} catch (error) {
+			state.failStreak += 1;
+			warnLog("takeover error, falling back to native", { error: error instanceof Error ? error.message : String(error) });
+			return {}; // D7 回退
+		}
+	};
+}

package/src/index.ts

@@ -0,0 +1,160 @@
+/**
+ * @zhushanwen/pi-smart-context 入口：事件接线 + 门控。
+ *
+ * 设计文档：docs/extensions/smart-context/design.md
+ * - session_start：session 级闭包状态重建（规范 Session 隔离：fired 档位/熔断计数不跨 session）
+ * - subagent 进程（R6）：不注册工具、不提醒（宁缺勿污）
+ * - session_before_compact：双模式接管（compact-handler）
+ * - session_compact：重置提醒 fired（D3）
+ * - agent_settled：越档检查 + followUp 投递一次性提醒（D3/D4）
+ * - model_select：跨界通知 + downshift 提醒（D5）
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { setPiHandle } from "@zhushanwen/pi-extension-logger";
+
+import {
+	createBeforeCompactHandler,
+	createTakeoverState,
+	debugLog,
+	type BeforeCompactLikeEvent,
+	type TakeoverState,
+} from "./compact-handler.js";
+import { buildDownshiftNotice, buildSwitchNotice, buildThresholdReminder } from "./reminder.js";
+import { registerCompactContextTool } from "./tool.js";
+import {
+	countCompactions,
+	findCrossedThresholds,
+	getCurrentModelId,
+	isGatingActive,
+	isSubagentProcess,
+	loadSmartContextConfig,
+	type EntryLike,
+} from "./pure.js";
+
+/** agent_settled 事件形状（无 payload）。 */
+interface AgentSettledLikeEvent {
+	type: "agent_settled";
+}
+
+/** model_select 事件形状。 */
+interface ModelSelectLikeEvent {
+	type: "model_select";
+	model: { provider?: string; id?: string; contextWindow?: number } | undefined;
+	previousModel: { provider?: string; id?: string; contextWindow?: number } | undefined;
+	source: string;
+}
+
+/** session_compact 事件形状（compactionEntry 只消费 type；interface 无隐式 index signature，
+ * 禁用 `& Record<string, unknown>` 交叉目标——会破坏 on() 重载的参数逆变匹配）。 */
+interface SessionCompactLikeEvent {
+	type: "session_compact";
+	compactionEntry: { type: string };
+	fromExtension: boolean;
+	reason: "manual" | "threshold" | "overflow";
+	willRetry: boolean;
+}
+
+/** session 级闭包状态（规范：模块级仅工厂函数，状态在 session_start 重建）。 */
+interface SessionState {
+	takeover: TakeoverState;
+	/** 已提醒档位（token 值为键；session_compact 清空，D3）。 */
+	firedThresholds: Set<number>;
+}
+
+/** session 级状态唯一构造点（初始态与 session_start 重建同源，新增字段不落两处）。 */
+function createSessionState(): SessionState {
+	return { takeover: createTakeoverState(), firedThresholds: new Set() };
+}
+
+/**
+ * pi-smart-context extension 工厂函数。
+ *
+ * agent 自决上下文压缩：compact_context 工具 + 双模式接管生成（same-model kv-cache /
+ * cross-model 廉价模型）+ 3 档阈值提醒 + 排除模型门控与切换通知。
+ */
+export default function smartContextExtension(pi: ExtensionAPI): void {
+	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle）
+	setPiHandle(pi);
+
+	// R6：subagent 子进程不注册工具、不提醒（PI_SUBAGENT_ROOT_SESSION_ID 标记）
+	if (isSubagentProcess()) {
+		debugLog("subagent process detected, staying inert");
+		return;
+	}
+
+	// session 级状态（session_start 重建闭包；模块级引用仅指向当前 session 的容器）
+	let state: SessionState = createSessionState();
+
+	pi.on("session_start", (_event: unknown, _ctx: ExtensionContext) => {
+		state = createSessionState();
+	});
+
+	// ── 压缩生成接管（D1/D12）──
+	const beforeCompact = createBeforeCompactHandler(
+		pi,
+		() => state.takeover,
+		loadSmartContextConfig,
+	);
+	pi.on("session_before_compact", (event: BeforeCompactLikeEvent, ctx: ExtensionContext) =>
+		beforeCompact(event, ctx));
+
+	// ── 压缩完成：重置提醒档位（D3）──
+	pi.on("session_compact", (_event: SessionCompactLikeEvent, _ctx: ExtensionContext) => {
+		state.firedThresholds.clear();
+	});
+
+	// ── 工具注册（常驻，不可用态由 execute 运行时校验拒绝，D5）──
+	registerCompactContextTool(pi);
+
+	// ── 阈值提醒（D3/D4）：agent_settled 越档检查 + followUp 一次性投递 ──
+	pi.on("agent_settled", (_event: AgentSettledLikeEvent, ctx: ExtensionContext) => {
+		const config = loadSmartContextConfig();
+		const modelId = getCurrentModelId(ctx.model);
+		if (!isGatingActive(config, modelId)) return;
+
+		const usage = ctx.getContextUsage();
+		if (!usage) return; // R7：tokens 可能 null（压缩后首响应前）——findCrossedThresholds 容错
+		const crossed = findCrossedThresholds(config.reminderThresholds, usage.tokens, state.firedThresholds);
+		if (crossed.length === 0) return;
+
+		for (const t of crossed) state.firedThresholds.add(t);
+		const compactionCount = countCompactions(ctx.sessionManager.getEntries() as ReadonlyArray<EntryLike>);
+		const message = buildThresholdReminder(crossed, usage.tokens ?? 0, usage.contextWindow, compactionCount);
+		debugLog(`reminder fired: tiers=${crossed.join(",")} tokens=${usage.tokens}`);
+		// D4：followUp（agent 空闲后投递并触发一个 turn，可立即决定压缩）；
+		// 防循环：crossed 全部已标记 fired，提醒触发的 settled 不会重复发
+		pi.sendUserMessage(message, { deliverAs: "followUp" });
+	});
+
+	// ── 模型切换：跨界通知 + downshift 提醒（D5，仅跨界时注入一次）──
+	pi.on("model_select", (event: ModelSelectLikeEvent, ctx: ExtensionContext) => {
+		const config = loadSmartContextConfig();
+		const modelId = getCurrentModelId(event.model);
+		const previousModelId = getCurrentModelId(event.previousModel);
+		if (modelId === "" || modelId === previousModelId) return;
+
+		const nowExcluded = config.excludedModels.includes(modelId);
+		const wasExcluded = config.excludedModels.includes(previousModelId);
+
+		// 跨越排除边界：注入一条可用性变化通知（同边界内切换静默）
+		if (config.enabled && nowExcluded !== wasExcluded) {
+			const notice = buildSwitchNotice(nowExcluded ? "unavailable" : "available", modelId);
+			debugLog(`switch notice: ${nowExcluded ? "unavailable" : "available"} (${modelId})`);
+			pi.sendUserMessage(notice, { deliverAs: "steer" });
+			return;
+		}
+
+		// downshift 检测：切到更小窗口模型且将触线 → 建议先压缩（不阻止切换）
+		const usage = ctx.getContextUsage();
+		const downshift = buildDownshiftNotice(
+			usage?.tokens ?? null,
+			event.previousModel?.contextWindow,
+			event.model?.contextWindow,
+		);
+		if (downshift && isGatingActive(config, modelId)) {
+			debugLog("downshift notice fired");
+			pi.sendUserMessage(downshift, { deliverAs: "steer" });
+		}
+	});
+}