@zhushanwen/pi-rename-session 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-rename-session",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.5.1"
+    "@zhushanwen/pi-llm-shared": "0.6.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

package/src/__tests__/commands.test.ts

@@ -28,7 +28,7 @@ describe("executeAutoRenameCommand", () => {
 		if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
 		else process.env.PI_CODING_AGENT_DIR = origEnv;
 		clearConfigCache();
-		fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+		fs.rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	function configPath(): string {

package/src/__tests__/index.test.ts

@@ -10,7 +10,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	setPiHandle: vi.fn(),
 }));
 
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -50,6 +50,8 @@ interface MockSetup {
 	setSessionNameMock: ReturnType<typeof vi.fn>;
 	/** 防覆盖检查读 pi.getSessionName()（D5），非 ctx——默认未命名（undefined）。 */
 	getSessionNameMock: ReturnType<typeof vi.fn>;
+	/** usage 落账入口（设计 §3.3 ③）：index.ts 注入回调体内调 pi.appendEntry，接线断言用。 */
+	appendEntryMock: ReturnType<typeof vi.fn>;
 	turnEndHandler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>;
 }
 
@@ -83,6 +85,7 @@ const DISABLED_CONFIG: RenameSessionConfig = {
 function createMockPi(): MockSetup {
 	const setSessionNameMock = vi.fn();
 	const getSessionNameMock = vi.fn((): string | undefined => undefined);
+	const appendEntryMock = vi.fn();
 	let turnEndHandler!: MockSetup["turnEndHandler"];
 	const pi = {
 		on: vi.fn((event: string, handler: MockSetup["turnEndHandler"]) => {
@@ -91,11 +94,13 @@ function createMockPi(): MockSetup {
 		registerCommand: vi.fn(),
 		getSessionName: getSessionNameMock,
 		setSessionName: setSessionNameMock,
+		appendEntry: appendEntryMock,
 	} as unknown as ExtensionAPI;
 	return {
 		pi,
 		setSessionNameMock,
 		getSessionNameMock,
+		appendEntryMock,
 		get turnEndHandler() {
 			return turnEndHandler;
 		},
@@ -486,3 +491,86 @@ describe("renameSessionExtension", () => {
 		expect(nonA1Calls).toHaveLength(0);
 	});
 });
+
+// ────────────────────────────────────────────────────
+// usage 落账接线（appendUsageEntry 回调注入，设计 §3.3 ③ / §3.6）
+// ────────────────────────────────────────────────────
+
+/** 合法 Usage 夹具（pi-ai Usage 全必填字段，消除 unsafe-cast 强断言）。 */
+const STUB_USAGE: Usage = {
+	input: 10,
+	output: 5,
+	cacheRead: 2,
+	cacheWrite: 1,
+	totalTokens: 18,
+	cost: { input: 0.01, output: 0.02, cacheRead: 0, cacheWrite: 0, total: 0.03 },
+};
+
+describe("usage 落账接线（appendUsageEntry，设计 §3.3 ③）", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		vi.mocked(loadRenameConfig).mockReset();
+		vi.mocked(resolveModel).mockReset();
+		vi.mocked(callLLM).mockReset();
+		vi.mocked(loadRenameConfig).mockReturnValue(ENABLED_CONFIG);
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		setup = createMockPi();
+		renameSessionExtension(setup.pi);
+	});
+
+	it("接线：callLLM ok:true + usage → pi.appendEntry 恰被调一次 ('rename-session', {model, usage})，且先于 setSessionName（标题照常落库）", async () => {
+		vi.mocked(callLLM).mockResolvedValue({
+			ok: true,
+			content: "自动生成的标题",
+			usage: STUB_USAGE,
+		});
+
+		await fire(setup, createMockCtx());
+		await vi.waitFor(() => expect(setup.setSessionNameMock).toHaveBeenCalledWith("自动生成的标题"));
+
+		expect(setup.appendEntryMock).toHaveBeenCalledTimes(1);
+		expect(setup.appendEntryMock).toHaveBeenCalledWith("rename-session", {
+			model: "stub/stub-model",
+			usage: STUB_USAGE,
+		});
+		// 时序：appendEntry 在 callRenameLLM 内（cleanTitle 前）触发，setSessionName 在其后 .then——落账先于落库
+		expect(setup.appendEntryMock.mock.invocationCallOrder[0]).toBeLessThan(
+			setup.setSessionNameMock.mock.invocationCallOrder[0],
+		);
+	});
+
+	it("catch 在回调体内：pi.appendEntry 抛错（session 已切换等）→ logger.error 且后续流程照常（标题照常落库）", async () => {
+		vi.mocked(callLLM).mockResolvedValue({
+			ok: true,
+			content: "自动生成的标题",
+			usage: STUB_USAGE,
+		});
+		setup.appendEntryMock.mockImplementation(() => {
+			throw new Error("session switched");
+		});
+
+		await fire(setup, createMockCtx());
+		// 「标题照常落库」（§3.6）：appendEntry 抛错被回调体内 catch，detached 链继续走 cleanTitle → setSessionName
+		await vi.waitFor(() => expect(setup.setSessionNameMock).toHaveBeenCalledWith("自动生成的标题"));
+
+		expect(loggerMock.error).toHaveBeenCalledWith("failed to append usage entry", {
+			error: "Error: session switched",
+		});
+		// 外层 .catch（rename LLM failed）不应被触发——错误在回调体内已被吞掉
+		const outerCatchCalls = loggerMock.error.mock.calls.filter((c) =>
+			String(c[0]).includes("rename LLM failed"),
+		);
+		expect(outerCatchCalls).toHaveLength(0);
+	});
+
+	it("usage 缺失 → appendEntry 不被调（§3.6 存在性守卫），标题照常落库", async () => {
+		vi.mocked(callLLM).mockResolvedValue({ ok: true, content: "自动生成的标题" });
+
+		await fire(setup, createMockCtx());
+		await vi.waitFor(() => expect(setup.setSessionNameMock).toHaveBeenCalledWith("自动生成的标题"));
+
+		expect(setup.appendEntryMock).not.toHaveBeenCalled();
+	});
+});

package/src/__tests__/llm.test.ts

@@ -10,7 +10,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	setPiHandle: vi.fn(),
 }));
 
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -21,6 +21,13 @@ vi.mock("@zhushanwen/pi-llm-shared", async (importActual) => {
 	return { ...actual, resolveModel: vi.fn(), callLLM: vi.fn() };
 });
 
+// mock pure.js：只把 cleanTitle 包一层 vi.fn（委托真实实现，行为零变化）——
+// 「回调在 cleanTitle 之前」的时序断言需要 cleanTitle 可观测（invocationCallOrder 比较）。
+vi.mock("../pure.js", async (importActual) => {
+	const actual = await importActual<typeof import("../pure.js")>();
+	return { ...actual, cleanTitle: vi.fn(actual.cleanTitle) };
+});
+
 // 被测模块须在 vi.mock 之后 import
 import { callLLM, resolveModel } from "@zhushanwen/pi-llm-shared";
 
@@ -34,7 +41,7 @@ import {
 	isSubagentSession,
 	truncateForTitle,
 } from "../llm.js";
-import { type RenameSessionConfig } from "../pure.js";
+import { cleanTitle, type RenameSessionConfig } from "../pure.js";
 
 // 每用例收尾统一还原：logger mock 恢复 + stub 的 XYZ_AGENT_DEBUG 还原，
 // 防泄漏到后续用例（debug 开关 live 读 process.env，依赖 stubEnv/unstubAllEnvs 成对）
@@ -549,6 +556,106 @@ describe("callRenameLLM", () => {
 	});
 });
 
+// ────────────────────────────────────────────────────
+// usage 落账回调（appendUsageEntry 注入，设计 §3.3 ③ / §3.6）
+// ────────────────────────────────────────────────────
+
+/** 合法 Usage 夹具（pi-ai Usage 全必填字段，消除 unsafe-cast 强断言）。 */
+const STUB_USAGE: Usage = {
+	input: 10,
+	output: 5,
+	cacheRead: 2,
+	cacheWrite: 1,
+	totalTokens: 18,
+	cost: { input: 0.01, output: 0.02, cacheRead: 0, cacheWrite: 0, total: 0.03 },
+};
+
+describe("callRenameLLM usage 落账回调（appendUsageEntry，设计 §3.3 ③）", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("usage 存在 + 注入回调 → 恰被调一次、参数 (provider/id, usage 同一引用)，且在 cleanTitle 之前", async () => {
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		vi.mocked(callLLM).mockResolvedValue({
+			ok: true,
+			content: "  修复登录bug  ",
+			usage: STUB_USAGE,
+		});
+		const appendUsageEntry = vi.fn();
+
+		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE, {
+			appendUsageEntry,
+		});
+
+		expect(result).toBe("修复登录bug");
+		expect(appendUsageEntry).toHaveBeenCalledTimes(1);
+		expect(appendUsageEntry).toHaveBeenCalledWith("stub/stub-model", STUB_USAGE);
+		// 时点契约（§3.3 ③）：ok:true && usage 后立即、cleanTitle 之前
+		expect(appendUsageEntry.mock.invocationCallOrder[0]).toBeLessThan(
+			vi.mocked(cleanTitle).mock.invocationCallOrder[0],
+		);
+	});
+
+	it("计量与标题清洗成败解耦：content 清洗后为空（rename 跳过返回 null）→ 回调仍恰被调一次", async () => {
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		vi.mocked(callLLM).mockResolvedValue({ ok: true, content: "   ", usage: STUB_USAGE });
+		const appendUsageEntry = vi.fn();
+
+		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE, {
+			appendUsageEntry,
+		});
+
+		expect(result).toBeNull();
+		expect(appendUsageEntry).toHaveBeenCalledTimes(1);
+		expect(appendUsageEntry).toHaveBeenCalledWith("stub/stub-model", STUB_USAGE);
+	});
+
+	it("usage 缺失（provider 不回）→ 跳过回调不落账（§3.6 存在性守卫），标题照常返回", async () => {
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		vi.mocked(callLLM).mockResolvedValue({ ok: true, content: "修复登录bug" });
+		const appendUsageEntry = vi.fn();
+
+		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE, {
+			appendUsageEntry,
+		});
+
+		expect(result).toBe("修复登录bug");
+		expect(appendUsageEntry).not.toHaveBeenCalled();
+	});
+
+	it("回调内部抛错被回调实现 catch（§3.6 契约，模拟 index.ts 注入的真实回调）→ 不阻断 cleanTitle 流程，标题照常返回", async () => {
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		vi.mocked(callLLM).mockResolvedValue({ ok: true, content: "修复登录bug", usage: STUB_USAGE });
+		const appendUsageEntry = vi.fn((_model: string, _usage: Usage) => {
+			try {
+				throw new Error("session switched"); // 模拟 pi.appendEntry 抛错（session 已切换等）
+			} catch {
+				// 回调体内 catch（§3.6：catch 必须位于回调实现内部）——index.ts 注入实现同款
+			}
+		});
+
+		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE, {
+			appendUsageEntry,
+		});
+
+		expect(result).toBe("修复登录bug");
+		expect(appendUsageEntry).toHaveBeenCalledTimes(1);
+	});
+
+	it("违约回调（实现未自吞错直接抛出）→ callRenameLLM reject（llm.ts 不吞错——§3.6 catch 归属钉死回调实现内部，防双重 catch 漂移；真实接线的兜底由 index.ts 回调体内 catch + 外层 .catch 覆盖）", async () => {
+		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
+		vi.mocked(callLLM).mockResolvedValue({ ok: true, content: "修复登录bug", usage: STUB_USAGE });
+		const appendUsageEntry = vi.fn(() => {
+			throw new Error("contract violation");
+		});
+
+		await expect(
+			callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE, { appendUsageEntry }),
+		).rejects.toThrow("contract violation");
+	});
+});
+
 // ────────────────────────────────────────────────────
 // A1 日志（失败路径 + 成功路径可排查，契约 C1 文案锁定）
 // ────────────────────────────────────────────────────

package/src/__tests__/pure.test.ts

@@ -302,7 +302,7 @@ describe("环境变量覆盖", () => {
 		else process.env.PI_RENAME_THINKING_LEVEL = origThinkingLevel;
 
 		clearConfigCache();
-		fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+		fs.rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	it("PI_RENAME_ENABLED=true → enabled=true", () => {
@@ -427,7 +427,7 @@ describe("loadRenameConfig / saveRenameConfig", () => {
 		if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
 		else process.env.PI_CODING_AGENT_DIR = origEnv;
 		clearConfigCache();
-		fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+		fs.rmSync(tmpAgentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	it("配置路径 = <agentDir>/config/rename-session-ext-config.json（走 getAgentDir，实例隔离）", () => {

package/src/index.ts

@@ -67,7 +67,21 @@ export default function renameSessionExtension(pi: ExtensionAPI): void {
 			// 5. LLM 生成标题并落库。pi 运行时的事件链是 await 的（runner.emit → await handler），
 			// 若 await callRenameLLM 会阻塞 agent 进入下一次迭代。这里用 detached promise 脱离 await 链，
 			// 真正实现 fire-and-forget：handler 立即 resolve，LLM 调用与 setSessionName 在后台异步完成。
-			void callRenameLLM(ctx, config, event.message)
+			void callRenameLLM(ctx, config, event.message, {
+				// usage 落账回调注入（设计 §3.3 ③）：闭包捕获 pi，把 rename LLM 调用的 usage 以
+				// custom entry 落盘（pi.appendEntry → {type:"custom",customType:"rename-session",
+				// data:{model,usage},timestamp}，不进对话流不进 LLM 上下文）。调用时点
+				// （ok:true && usage 后立即、cleanTitle 前）由 llm.ts 统一规定。
+				appendUsageEntry: (model, usage) => {
+					// §3.6：catch 必须位于回调实现内部——appendEntry 抛错（session 已切换等）只记
+					// 日志，不影响回调返回与后续 cleanTitle/setSessionName（「标题照常落库」）。
+					try {
+						pi.appendEntry("rename-session", { model, usage });
+					} catch (e) {
+						logger.error("failed to append usage entry", { error: String(e) });
+					}
+				},
+			})
 				.then((title) => {
 					if (!title) return;
 					// 防覆盖（D5）：落库前重查——LLM 调用窗口（2-30s）内用户手动命名的竞态由此兜住

package/src/llm.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+import type { AssistantMessage, Message, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { callLLM, resolveModel } from "@zhushanwen/pi-llm-shared";
@@ -195,6 +195,23 @@ function messageText(message: Message): string {
 
 // ──────────────────────── LLM 调用 ────────────────────────
 
+// ──────────────────────── 注入项（usage 落账，设计 §3.3 ③） ────────────────────────
+
+/**
+ * callRenameLLM 可选注入项。llm.ts 不依赖 pi 句柄（ExtensionAPI）——依赖 pi 的副作用由
+ * index.ts 调用处注入回调（闭包捕获 pi），本模块只定义回调形状与调用时点。
+ */
+export interface CallRenameLLMOptions {
+	/**
+	 * usage 落账回调（设计 §3.3 ③）：`callLLM` 返回 `ok:true && usage` 存在后**立即**、
+	 * `cleanTitle` 之前调用——计量「LLM 调用事实」与标题清洗成败解耦（标题清洗为空导致
+	 * rename 跳过时，调用用量照常落账）。`usage` 缺失时不调用（§3.6 存在性守卫）。
+	 * 契约（§3.6）：catch 必须位于回调实现内部（index.ts 侧 try/catch + logger.error），
+	 * 不向调用方抛错；本函数不包裹 try/catch（catch 归属钉死回调体内，防双重 catch 漂移）。
+	 */
+	appendUsageEntry?: (model: string, usage: Usage) => void;
+}
+
 /**
  * 发起 rename LLM 调用，返回提取+清洗后的标题（空串/异常返回 null 表示应跳过 rename）。
  *
@@ -209,6 +226,8 @@ function messageText(message: Message): string {
  * - tools：不传（callLLM 内部显式 tools:[]；旧版 `pi.getAllTools()` 塞全部工具，纯浪费 token）
  * - model 不可用（resolveModel 返回 null）→ 静默跳过返回 null，不报错不阻断
  * - signal：透传 ctx.signal（保留旧版随 session abort 取消的语义）
+ * - options.appendUsageEntry：usage 落账回调注入（§3.3 ③——时点 ok:true && usage 后立即、
+ *   cleanTitle 前；catch 归属回调实现内部，§3.6）
  *
  * 本函数是 async（内部 await callLLM，这是 callRenameLLM 自身流程）；
  * 调用方（turn_end handler）用 fire-and-forget 包裹（`void callRenameLLM(...).then(...).catch(...)`），
@@ -218,6 +237,7 @@ export async function callRenameLLM(
 	ctx: ExtensionContext,
 	config: RenameSessionConfig,
 	finalMessage: unknown,
+	options?: CallRenameLLMOptions,
 ): Promise<string | null> {
 	// 内部顺序不可调换（E2E 竞态断言依赖「内省日志在请求发起前打出」）：
 	// resolveModel → extract prompt → extract finalText → truncate ×2 → build → debug 内省 → callLLM
@@ -273,6 +293,14 @@ export async function callRenameLLM(
 		return null;
 	}
 
+	// usage 落账（设计 §3.3 ③）：ok:true && usage 存在后立即、cleanTitle 之前——「LLM 调用
+	// 事实」的计量与标题清洗成败解耦（cleanTitle 为空跳过 rename 不影响已落账）；usage 缺失
+	// （provider 不回）→ 跳过回调不落账（§3.6 存在性守卫）。回调契约自带 catch（§3.6 归属
+	// 回调实现内部），此处不包裹 try/catch。
+	if (options?.appendUsageEntry && result.usage) {
+		options.appendUsageEntry(`${model.provider}/${model.id}`, result.usage);
+	}
+
 	// A1 成功路径日志（B2+B3 修正）：默认不输出，避免常开 console.warn 污染 Pi 输入框；
 	// 需要排查时设 XYZ_AGENT_DEBUG=1，经 debugLog 输出（带时间戳）。
 	// - B2 位置：原在 callLLM 调用前打出，失败时会误导（日志已落但 rename 未发生）；移到 result.ok 确认后