@zhushanwen/pi-smart-context 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @zhushanwen/pi-smart-context
+
+智能上下文压缩 pi extension：把 compact 时机交给 agent 自决，压缩生成用双模式接管（same-model KV 缓存命中 / cross-model 廉价模型），3 档阈值提醒不强制。
+
+## 功能
+
+- **`compact_context` 工具**：agent 在「任务阶段性完成 && 压缩不影响后续 && 上下文超阈值」三条件同时满足时自决调用；带最低档阈值保护
+- **双模式生成接管**（`session_before_compact`，覆盖工具 / `/compact` / 内建 auto 三条路径）：
+  - same-model：完整原始上下文 + 会话原 system prompt + tools + 末尾追加压缩指令——前缀缓存全命中，成本≈增量指令+输出，且模型看全量上下文（质量上限最高）
+  - cross-model：调用 pi 原生 `compact()` 仅换模型与凭证——split-turn / fileOps / previousSummary 原生组装
+- **3 档阈值提醒**（默认 200K/400K/600K）：`agent_settled` 越档检查，每档一次、多档合并、压缩后重置，followUp 投递；措辞是数据投递不是指令
+- **排除模型**（精准 `provider/modelId` 匹配）：工具拒绝 + 不提醒 + 回落 pi 原生生成；切换跨界时注入一条可用性通知，downshift（切小窗模型将触线）时建议先压缩
+- **健壮性**：摘要收缩校验、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 桌面端在设置页（系统 → 智能上下文压缩）可视化配置。
+
+## 设计文档
+
+`docs/extensions/smart-context/design.md`（xyz-agent 仓库）——决策依据、探针记录、验收场景。

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zhushanwen/pi-smart-context",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.ts",
+  "xyz-agent": {
+    "role": "universal"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.2.2",
+    "@zhushanwen/pi-llm-shared": "0.4.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/",
+    "vitest.config.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

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

@@ -0,0 +1,56 @@
+---
+name: smart-context-ext-config
+description: "配置 @zhushanwen/pi-smart-context（智能上下文压缩：agent 自决 compact_context 工具 + 双模式摘要生成 + 3 档阈值提醒）时加载。含配置文件路径、schema、默认值、双模式说明、排障。触发词：smart-context 配置、压缩配置、compact 配置、上下文压缩、压缩模型、提醒阈值、排除模型。"
+---
+
+# smart-context 配置指南
+
+## 功能概览
+
+- `compact_context` 工具：agent 在「任务阶段性完成 && 压缩不影响后续 && 上下文超阈值」时自决调用
+- 双模式摘要生成：压缩模型 = 当前模型 → same-model 模式（KV 缓存命中，成本最低质量最高）；不同 → cross-model 模式（廉价模型 + 最小输入）
+- 3 档阈值提醒：越过档位时 agent 收到一次性提示（自行判断，不强制）
+- 排除模型：命中列表的会话模型整体关闭本功能（回落 pi 原生压缩）
+- pi 内建自动压缩的触发线保留为最后防线，其压缩执行也走本扩展逻辑
+
+## 配置文件
+
+路径：`<agentDir>/config/smart-context-ext-config.json`（`<agentDir>` = `getAgentDir()`，默认 `~/.pi/agent`，xyz-agent 环境 `~/.xyz-agent/pi/agent`；`PI_CODING_AGENT_DIR` 可覆盖）。
+
+### Schema
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 总开关 |
+| `compactModel` | `{type:"ref", ref:string}` | `{type:"ref", ref:""}` | 压缩模型（完整 `provider/modelId`）。`ref` 为空 = 跟随当前会话模型（same-model 模式）；等于当前模型同样进 same-model 模式 |
+| `reminderThresholds` | `number[]` | `[200000, 400000, 600000]` | 3 档提醒阈值（token 绝对数，升序） |
+| `excludedModels` | `string[]` | `[]` | 排除模型列表，完整 `provider/modelId` 精准等值匹配（如 `"deepseek/deepseek-chat"`），不做前缀匹配 |
+
+### 配置示例
+
+```json
+{
+  "enabled": true,
+  "compactModel": { "type": "ref", "ref": "xiaomi-token-plan-cn/mimo-v2.5" },
+  "reminderThresholds": [200000, 400000, 600000],
+  "excludedModels": ["deepseek/deepseek-chat"]
+}
+```
+
+## 生效时机
+
+配置为读时热加载（mtime 检测）：修改保存后**下一次事件（压缩/提醒/工具调用）即生效**，无需重启会话。
+
+## 模式选择建议
+
+- 当前模型缓存便宜（如 DeepSeek）→ 加入 `excludedModels`，压缩反而更贵
+- 当前模型缓存贵 + 有廉价可用模型 → `compactModel` 配廉价模型（cross-model）
+- 想要最高摘要质量 + 最低成本 → `compactModel` 留空或配成当前模型（same-model，KV 缓存命中）
+
+## 排障
+
+- 压缩回退当前模型：`compactModel.ref` 指向的模型不可用（无凭证/已删）——换可用模型或留空
+- 工具调用被拒「已禁用」/「已排除」：检查 `enabled` 与 `excludedModels`
+- 提醒未出现：`getContextUsage().tokens` 在压缩后首个响应前为 null，属正常（下轮恢复）
+- 连续接管失败 3 次后不再接管：本会话熔断保护，查看 `XYZ_AGENT_DEBUG=1` 日志定位失败原因
+- 调试：`XYZ_AGENT_DEBUG=1` 后看 `[smart-context]` 前缀日志（`~/.pi/agent/logs/`）

package/src/__tests__/compact-handler.test.ts

@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// mock pi SDK：接管路径的单测不触网（same-mode 输入链 + cross-mode 原生组装都替换）
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+	buildSessionContext: (entries: unknown[]) => ({ messages: [{ role: "user", content: "history" }] }),
+	convertToLlm: (messages: unknown[]) => messages,
+	compact: vi.fn(),
+}));
+vi.mock("../llm.js", () => ({
+	callSameModelCompaction: vi.fn(),
+	projectTools: (tools: unknown[]) => tools.map((t) => ({ name: (t as { name: string }).name })),
+}));
+
+import { compact as nativeCompact } from "@earendil-works/pi-coding-agent";
+import { callSameModelCompaction } from "../llm.js";
+import {
+	createBeforeCompactHandler,
+	createTakeoverState,
+	type BeforeCompactLikeEvent,
+} from "../compact-handler.js";
+import { normalizeSmartContextConfig, type SmartContextConfig } from "../pure.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+function makeEvent(overrides?: Partial<BeforeCompactLikeEvent["preparation"]>): BeforeCompactLikeEvent {
+	return {
+		type: "session_before_compact",
+		preparation: {
+			firstKeptEntryId: "kept-1",
+			messagesToSummarize: [
+				{ role: "user", content: "x".repeat(4_000) },
+				{ role: "assistant", content: "y".repeat(4_000) },
+			],
+			turnPrefixMessages: [],
+			isSplitTurn: false,
+			tokensBefore: 500_000,
+			fileOps: { read: new Set(["/a.ts"]), written: new Set(), edited: new Set() },
+			...overrides,
+		},
+		branchEntries: [],
+		customInstructions: undefined,
+		reason: "manual",
+		willRetry: false,
+	};
+}
+
+function makeCtx(): ExtensionContext {
+	return {
+		model: { provider: "zai", id: "glm" },
+		getSystemPrompt: () => "sys",
+		sessionManager: { getSessionId: () => "s1", getSessionFile: () => "/tmp/s1.jsonl" },
+		modelRegistry: {
+			getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "k" }),
+			find: () => null,
+		},
+	} as unknown as ExtensionContext;
+}
+
+function makePi(): ExtensionAPI {
+	return { getAllTools: () => [] } as unknown as ExtensionAPI;
+}
+
+const mockedCall = vi.mocked(callSameModelCompaction);
+const mockedNative = vi.mocked(nativeCompact);
+
+function makeHandler(config: SmartContextConfig) {
+	const state = createTakeoverState();
+	const handler = createBeforeCompactHandler(makePi(), () => state, () => config);
+	return { handler, state };
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe("session_before_compact 接管 handler", () => {
+	it("门控未放行（disabled / 排除命中）→ 空返回（pi 原生生成）", async () => {
+		const disabled = makeHandler(normalizeSmartContextConfig({ enabled: false }));
+		await expect(disabled.handler(makeEvent(), makeCtx())).resolves.toEqual({});
+
+		const excluded = makeHandler(
+			normalizeSmartContextConfig({ excludedModels: ["zai/glm"] }),
+		);
+		await expect(excluded.handler(makeEvent(), makeCtx())).resolves.toEqual({});
+		expect(mockedCall).not.toHaveBeenCalled();
+	});
+
+	it("same-model 成功 → compaction 带 engine/mode 标记 + preamble + fileOps 清单 + transcript 指针", async () => {
+		mockedCall.mockResolvedValue({ ok: true, text: "summary body", usage: { input: 1, output: 2 } });
+		const { handler } = makeHandler(normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "" } }));
+		const decision = await handler(makeEvent(), makeCtx());
+		expect(decision.compaction?.details).toEqual({ engine: "smart-context", mode: "same-model" });
+		expect(decision.compaction?.summary).toContain("summary body");
+		// D13-9 preamble 在最前；D11-2 fileOps；D13-4 transcript
+		expect(decision.compaction?.summary.startsWith("This is an automatically generated checkpoint")).toBe(true);
+		expect(decision.compaction?.summary).toContain("<read-files>");
+		expect(decision.compaction?.summary).toContain("/tmp/s1.jsonl");
+		// cache-key 一致性：调用参数含 systemPrompt + tools（mock 收到的 options）
+		expect(mockedCall.mock.calls[0][1].systemPrompt).toBe("sys");
+	});
+
+	it("max-tokens 截断 fail-closed（D13-2）→ 空返回 + failStreak +1", async () => {
+		mockedCall.mockResolvedValue({ ok: true, text: "half...", stopReason: "length" });
+		const { handler, state } = makeHandler(normalizeSmartContextConfig({}));
+		await expect(handler(makeEvent(), makeCtx())).resolves.toEqual({});
+		expect(state.failStreak).toBe(1);
+	});
+
+	it("cross-model：resolveModel 不可用 → 空返回（D7 回退）", async () => {
+		const { handler } = makeHandler(
+			normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "xiaomi/mimo" } }),
+		);
+		// modelRegistry.find 未命中 mimo → resolveModel 返回 null → generateCrossMode D7 静默回退
+		const ctx = makeCtx();
+		await expect(handler(makeEvent(), ctx)).resolves.toEqual({});
+		expect(mockedNative).not.toHaveBeenCalled();
+	});
+
+	it("收缩校验失败（摘要 ≥ 被压段）→ 拒绝 + 同段记录不重试（D13-1）", async () => {
+		mockedCall.mockResolvedValue({ ok: true, text: "z".repeat(10_000) });
+		const { handler, state } = makeHandler(normalizeSmartContextConfig({}));
+		const event = makeEvent({ messagesToSummarize: [{ role: "user", content: "x".repeat(400) }] });
+		await expect(handler(event, makeCtx())).resolves.toEqual({});
+		expect(state.inflatedSegments.has("kept-1")).toBe(true);
+		// 同段第二次直接跳过（不再调 LLM）
+		mockedCall.mockClear();
+		await expect(handler(event, makeCtx())).resolves.toEqual({});
+		expect(mockedCall).not.toHaveBeenCalled();
+	});
+
+	it("连续失败 3 次熔断（D13-3）→ 第 4 次起直接空返回", async () => {
+		mockedCall.mockResolvedValue({ ok: false, text: "", error: "boom" });
+		const { handler, state } = makeHandler(normalizeSmartContextConfig({}));
+		for (let i = 0; i < 3; i++) {
+			await expect(handler(makeEvent(), makeCtx())).resolves.toEqual({});
+		}
+		expect(state.failStreak).toBe(3);
+		mockedCall.mockClear();
+		await expect(handler(makeEvent(), makeCtx())).resolves.toEqual({});
+		expect(mockedCall).not.toHaveBeenCalled(); // 熔断后不再尝试
+	});
+});

package/src/__tests__/pure.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	DEFAULT_SMART_CONTEXT_CONFIG,
+	buildReinjectSection,
+	checkToolThresholdGuard,
+	computeFileListsLike,
+	estimateTextTokens,
+	findCrossedThresholds,
+	formatFileOperationsLike,
+	formatK,
+	getCurrentModelId,
+	isGatingActive,
+	isSubagentProcess,
+	isSummaryInflated,
+	normalizeSmartContextConfig,
+	pickMode,
+	pickReinjectFiles,
+} from "../pure.js";
+
+describe("normalizeSmartContextConfig", () => {
+	it("非对象输入回退默认值", () => {
+		const c = normalizeSmartContextConfig(null);
+		expect(c).toEqual(DEFAULT_SMART_CONTEXT_CONFIG);
+		expect(c.reminderThresholds).toEqual([200_000, 400_000, 600_000]);
+	});
+
+	it("阈值过滤非正数并升序、截 3 档；空数组回退默认", () => {
+		const c = normalizeSmartContextConfig({ reminderThresholds: [300_000, 100_000, -5, "x", 200_000, 999_000] });
+		expect(c.reminderThresholds).toEqual([100_000, 200_000, 300_000]);
+
+		const c2 = normalizeSmartContextConfig({ reminderThresholds: [] });
+		expect(c2.reminderThresholds).toEqual([200_000, 400_000, 600_000]);
+	});
+
+	it("excludedModels 只留含 / 的字符串条目并去重（精准匹配要求完整 provider/modelId）", () => {
+		const c = normalizeSmartContextConfig({
+			excludedModels: ["deepseek/deepseek-chat", "deepseek", "deepseek/deepseek-chat", 42],
+		});
+		expect(c.excludedModels).toEqual(["deepseek/deepseek-chat"]);
+	});
+
+	it("compactModel 非法形态回退空 ref", () => {
+		const c = normalizeSmartContextConfig({ compactModel: { type: "regex", pattern: "x" } });
+		expect(c.compactModel).toEqual({ type: "ref", ref: "" });
+	});
+});
+
+describe("门控与模式判定（D5/D12）", () => {
+	it("getCurrentModelId 拼接 provider/modelId，缺失返回空串", () => {
+		expect(getCurrentModelId({ provider: "zai", id: "glm" })).toBe("zai/glm");
+		expect(getCurrentModelId(undefined)).toBe("");
+	});
+
+	it("isGatingActive：enabled 且未命中排除才放行", () => {
+		const config = normalizeSmartContextConfig({ enabled: true, excludedModels: ["deepseek/deepseek-chat"] });
+		expect(isGatingActive(config, "zai/glm")).toBe(true);
+		expect(isGatingActive(config, "deepseek/deepseek-chat")).toBe(false);
+		// provider 前缀不算命中（精准匹配）
+		expect(isGatingActive(config, "deepseek/other-model")).toBe(true);
+		const disabled = normalizeSmartContextConfig({ enabled: false });
+		expect(isGatingActive(disabled, "zai/glm")).toBe(false);
+		expect(isGatingActive(config, "")).toBe(false);
+	});
+
+	it("pickMode：ref 等于当前模型或未配置 → same-model", () => {
+		const unset = normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "" } });
+		expect(pickMode(unset, "zai/glm")).toBe("same-model");
+
+		const same = normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "zai/glm" } });
+		expect(pickMode(same, "zai/glm")).toBe("same-model");
+
+		const cross = normalizeSmartContextConfig({ compactModel: { type: "ref", ref: "xiaomi/mimo" } });
+		expect(pickMode(cross, "zai/glm")).toBe("cross-model");
+	});
+});
+
+describe("阈值检查（D3/D6）", () => {
+	it("findCrossedThresholds：null tokens 容错为空（R7）；已 fired 排除", () => {
+		const tiers = [5_000, 10_000, 15_000];
+		expect(findCrossedThresholds(tiers, null, new Set())).toEqual([]);
+		expect(findCrossedThresholds(tiers, 11_000, new Set([5_000]))).toEqual([10_000]);
+		expect(findCrossedThresholds(tiers, 99_000, new Set())).toEqual(tiers);
+	});
+
+	it("checkToolThresholdGuard：低于最低档拒绝并带用量数据；null 拒绝", () => {
+		const tiers = [200_000, 400_000, 600_000];
+		const guardMessage = checkToolThresholdGuard(tiers, 38_000);
+		expect(guardMessage).toMatch(/38K/);
+		expect(guardMessage).toMatch(/200K/);
+		expect(checkToolThresholdGuard(tiers, 250_000)).toBeNull();
+		expect(checkToolThresholdGuard(tiers, null)).toMatch(/用量未知/);
+	});
+});
+
+describe("摘要后处理纯函数（D11/D13）", () => {
+	it("formatK 整数/小数", () => {
+		expect(formatK(200_000)).toBe("200K");
+		expect(formatK(215_000)).toBe("215K");
+	});
+
+	it("isSummaryInflated + estimateTextTokens（chars/4）", () => {
+		expect(estimateTextTokens("abcd")).toBe(1);
+		expect(isSummaryInflated(500, 400)).toBe(true);
+		expect(isSummaryInflated(300, 400)).toBe(false);
+	});
+
+	it("computeFileListsLike：只读 = read − modified；排序", () => {
+		const { readFiles, modifiedFiles } = computeFileListsLike({
+			read: new Set(["b.ts", "a.ts", "c.ts"]),
+			written: new Set(["c.ts"]),
+			edited: new Set(["d.ts"]),
+		});
+		expect(readFiles).toEqual(["a.ts", "b.ts"]);
+		expect(modifiedFiles).toEqual(["c.ts", "d.ts"]);
+	});
+
+	it("formatFileOperationsLike 对齐 pi XML tags 格式", () => {
+		expect(formatFileOperationsLike(["a.ts"], ["b.ts"])).toBe(
+			"\n\n<read-files>\na.ts\n</read-files>\n\n<modified-files>\nb.ts\n</modified-files>",
+		);
+		expect(formatFileOperationsLike([], [])).toBe("");
+	});
+
+	it("pickReinjectFiles：跳过保留段已读，取最近 ≤5（尾部）", () => {
+		const reads = ["f1", "f2", "f3", "f4", "f5", "f6", "f7"];
+		expect(pickReinjectFiles(reads, new Set(["f2"]))).toEqual(["f3", "f4", "f5", "f6", "f7"]);
+	});
+
+	it("buildReinjectSection：空内容跳过、超预算截停", () => {
+		expect(buildReinjectSection([{ path: "a", content: "" }])).toBe("");
+		const long = "x".repeat(6_000);
+		const section = buildReinjectSection([{ path: "a", content: long }]);
+		expect(section).toContain("### a");
+		expect(section).toContain("[... truncated]");
+	});
+});
+
+describe("subagent 识别（R6）", () => {
+	it("PI_SUBAGENT_ROOT_SESSION_ID 存在即 subagent", () => {
+		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(true);
+		expect(isSubagentProcess({})).toBe(false);
+	});
+});

package/src/__tests__/reminder.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	buildDegradationHintLine,
+	buildDownshiftNotice,
+	buildSwitchNotice,
+	buildThresholdReminder,
+} from "../reminder.js";
+import { buildSameModelInstruction, buildTranscriptPointer, CHECKPOINT_PREAMBLE } from "../prompts.js";
+
+describe("buildThresholdReminder（D3/D4：数据投递不强制）", () => {
+	it("含用量数据、档位、三条件自查清单、可忽略出口", () => {
+		const msg = buildThresholdReminder([200_000], 215_000, 1_000_000, 0);
+		expect(msg).toContain("215K / 1000K");
+		expect(msg).toContain("21.5%");
+		expect(msg).toContain("200K");
+		expect(msg).toContain("compact_context");
+		expect(msg).toContain("1. 当前任务的一个阶段已完成");
+		expect(msg).toContain("忽略本提示继续工作");
+	});
+
+	it("多档合并为一条消息", () => {
+		const msg = buildThresholdReminder([200_000, 400_000], 430_000, 1_000_000, 0);
+		expect(msg).toContain("200K（第 1 档）、400K（第 2 档）");
+	});
+
+	it("累计压缩 ≥2 次附降智提示（D13-12）", () => {
+		const without = buildThresholdReminder([200_000], 215_000, 1_000_000, 1);
+		const with_ = buildThresholdReminder([200_000], 215_000, 1_000_000, 2);
+		expect(without).not.toContain("compacted multiple times");
+		expect(with_).toContain("compacted multiple times");
+	});
+});
+
+describe("buildSwitchNotice（D5 跨界通知）", () => {
+	it("不可用/恢复两态文案含模型 ID 与原因", () => {
+		const unavailableNotice = buildSwitchNotice("unavailable", "deepseek/deepseek-chat");
+		expect(unavailableNotice).toContain("deepseek/deepseek-chat");
+		expect(unavailableNotice).toContain("暂时不可用");
+		expect(buildSwitchNotice("available", "zai/glm")).toContain("恢复可用");
+	});
+});
+
+describe("buildDownshiftNotice（D5 窗口收缩）", () => {
+	it("窗口变大或未触线返回 null", () => {
+		expect(buildDownshiftNotice(100_000, 200_000, 1_000_000)).toBeNull();
+		expect(buildDownshiftNotice(100_000, 1_000_000, 500_000)).toBeNull();
+		expect(buildDownshiftNotice(null, 1_000_000, 200_000)).toBeNull();
+	});
+
+	it("切小窗且 tokens 超内建触发线 → 建议压缩", () => {
+		const notice = buildDownshiftNotice(190_000, 1_000_000, 200_000);
+		expect(notice).toContain("190K");
+		expect(notice).toContain("200K");
+		expect(notice).toContain("建议尽快压缩");
+	});
+});
+
+describe("prompts（D13-6/7/8/9 + D12）", () => {
+	it("same-model 指令：首尾 TEXT ONLY 双保险 + 结构化模板 + 先验合并规则", () => {
+		const instruction = buildSameModelInstruction();
+		expect(instruction.startsWith("CRITICAL: Respond with TEXT ONLY")).toBe(true);
+		expect(instruction.endsWith("REMINDER: Respond with TEXT ONLY. Do NOT call any tools. Output only the checkpoint text.")).toBe(true);
+		expect(instruction).toContain("## Goal");
+		expect(instruction).toContain("## Files and Code");
+		expect(instruction).toContain("## Errors and Fixes");
+		expect(instruction).toContain("do NOT copy it forward verbatim");
+	});
+
+	it("custom_instructions 追加 focus 段", () => {
+		const instruction = buildSameModelInstruction("保留验证结果");
+		expect(instruction).toContain('Additional focus from the calling agent');
+		expect(instruction).toContain("保留验证结果");
+	});
+
+	it("transcript 指针含路径", () => {
+		expect(buildTranscriptPointer("/tmp/s.jsonl")).toContain("/tmp/s.jsonl");
+	});
+
+	it("落回包裹语存在（D13-9）", () => {
+		expect(CHECKPOINT_PREAMBLE).toContain("without acknowledging this checkpoint");
+	});
+});

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

@@ -0,0 +1,66 @@
+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）。
+ */
+
+import {
+	buildSessionContext,
+	compact,
+	convertToLlm,
+	DEFAULT_COMPACTION_SETTINGS,
+} from "@earendil-works/pi-coding-agent";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+
+describe("pi SDK 契约（compact 接管路径依赖的导出形状）", () => {
+	it("compact / buildSessionContext / convertToLlm / DEFAULT_COMPACTION_SETTINGS 为函数/对象导出", () => {
+		expect(typeof compact).toBe("function");
+		expect(typeof buildSessionContext).toBe("function");
+		expect(typeof convertToLlm).toBe("function");
+		expect(typeof DEFAULT_COMPACTION_SETTINGS).toBe("object");
+	});
+
+	it("buildSessionContext(branchEntries) 返回 { messages, entries }（R9 完整上下文数据源）", () => {
+		const entries = [
+			{ id: "m1", parentId: null, type: "message", timestamp: 1, message: { role: "user", content: "hi", timestamp: 1 } },
+			{ id: "c1", parentId: "m1", type: "compaction", timestamp: 2, summary: "s", firstKeptEntryId: "m2", tokensBefore: 10 },
+			{ id: "m2", parentId: "c1", type: "message", timestamp: 3, message: { role: "user", content: "kept", timestamp: 3 } },
+		];
+		const ctx = buildSessionContext(entries as never);
+		expect(Array.isArray(ctx.messages)).toBe(true);
+		// compaction entry 投影为一条消息 + 保留段消息（旧摘要在前缀中，D12 same-mode 前提）
+		expect(ctx.messages.length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("convertToLlm 把 user text message 原样保留（same-mode 输入链不变形）", () => {
+		const out = convertToLlm([{ role: "user", content: "hello", timestamp: 1 } as never]);
+		expect(out.length).toBe(1);
+		expect(out[0].role).toBe("user");
+	});
+
+	it("completeSimple 为函数导出（same-mode LLM 调用通道）", () => {
+		expect(typeof completeSimple).toBe("function");
+	});
+
+	it("compact() 的 preparation 参数运行时消费字段（messagesToSummarize/previousSummary/fileOps）在函数体内可达——静态签名核对", async () => {
+		// 不真正调网：用立即 abort 的 signal 让 compact 提前拒绝，验证参数形状被接受不抛 TypeError
+		const controller = new AbortController();
+		controller.abort();
+		const preparation = {
+			firstKeptEntryId: "x",
+			messagesToSummarize: [{ role: "user", content: "m", timestamp: 1 }],
+			turnPrefixMessages: [],
+			isSplitTurn: false,
+			tokensBefore: 10,
+			previousSummary: undefined,
+			fileOps: { read: new Set(), written: new Set(), edited: new Set() },
+			settings: DEFAULT_COMPACTION_SETTINGS,
+		};
+		const model = { id: "m", provider: "p", contextWindow: 1000, maxTokens: 100 } as never;
+		await expect(
+			compact(preparation as never, model, "key", undefined, undefined, controller.signal),
+		).rejects.toThrow();
+	});
+});