@zhushanwen/pi-rename-session 0.2.0

package/README.md

@@ -0,0 +1,56 @@
+# @zhushanwen/pi-rename-session
+
+Pi rename-session 扩展 — 新 session 首 turn 完成后，自动生成会话标题并落库（`setSessionName`），让 session 列表摆脱默认的日期/序号占位，一眼可辨。
+
+## 功能
+
+- 新 session 的**首个 turn** 完成后自动生成简短标题（3-8 个词，跟随对话语言）
+- 复用主 turn 完整上下文发起独立 LLM 调用，命中 kvcache，几乎不产生额外成本
+- 标题直接 `setSessionName` 落库，不进 session history（不污染对话记录）
+- fire-and-forget：任何失败（LLM 调用 / 提取 / auth / 读取）都静默跳过，保留原 label，绝不阻断 agent 循环
+- **子 session 自动排除**：subagent 子进程 session 不触发 rename（避免给临时产物起名）
+
+## 安装
+
+```bash
+pi install npm:@zhushanwen/pi-rename-session
+```
+
+## 开关
+
+文件存在 = 开启。默认**关闭**，需显式开启。
+
+- **原生 pi 用户**：手动创建开关文件
+  ```bash
+  touch ~/.pi/agent/auto-rename-enabled
+  ```
+- **xyz-agent 用户**：通过 settings 的开关控制（由 xyz-agent 桥接到同一个开关文件）
+
+开关文件路径可通过 `PI_CODING_AGENT_DIR` 环境变量覆盖基础目录（默认 `~/.pi/agent`）。
+
+## 工作原理
+
+1. **监听 `turn_end`**：每个 turn 完成时触发。
+2. **开关 + subagent 过滤**：开关关闭则直接返回；session 路径含 `subagents` 段则视为子进程 session，跳过。
+3. **首 turn 判定**：统计 session entries 中 `assistant` 回复数，===1 才是首 turn（后续 turn 不重复 rename）。
+4. **LLM 生成标题**：复用主 turn 的完整上下文（system prompt + tools + messages），追加一条 rename 指令的 user message，发起一次独立 LLM 调用。由于前缀与主 turn 字节级一致，能命中 kvcache，显著省成本。
+5. **落库**：调 `setSessionName` 写入标题。**不**写入 session history（不调用 `appendEntry`），对话记录不受影响。
+
+## 子 session 自动排除
+
+subagent 子进程的 session 目录形如 `.../subagents/...`，是临时产物。本扩展通过检测路径中的 `subagents` 段判定子 session，自动跳过 rename，避免给这些临时 session 生成噪音标题。
+
+## 文件结构
+
+```
+rename-session/
+├── index.ts              # 工厂入口（re-export src/index.ts）
+├── package.json
+├── vitest.config.ts
+├── README.md
+└── src/
+    ├── index.ts          # 工厂入口（注册 turn_end handler）
+    ├── pure.ts           # 纯函数（countAssistantReplies / extractTitle / isEnabled / CONFIG）
+    ├── llm.ts            # callRenameLLM（动态 import completeSimple，复用主 turn 上下文）
+    └── __tests__/        # 单测（pure 纯函数 + llm mock + index 集成）
+```

package/index.ts

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zhushanwen/pi-rename-session",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": []
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "vitest.config.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@sinclair/typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@sinclair/typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/__tests__/commands.test.ts

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { executeAutoRenameCommand } from "../commands.js";
+
+/**
+ * executeAutoRenameCommand 依赖模块级 CONFIG.switchFilePath，用 vi.mock("./pure.js")
+ * 注入可控路径，避免读写真实 ~/.pi/agent 目录。
+ */
+vi.mock("../pure.js", async (importActual) => {
+	const actual = await importActual<typeof import("../pure.js")>();
+	const tmpFile = path.join(os.tmpdir(), `rename-cmd-${Date.now()}-enabled`);
+	return {
+		...actual,
+		CONFIG: { ...actual.CONFIG, switchFilePath: tmpFile },
+		isEnabled: (p: string) => fs.existsSync(p),
+		setSwitch: actual.setSwitch,
+	};
+});
+
+// 被测模块须在 vi.mock 之后 import（vitest 提升 vi.mock）
+import { CONFIG as MOCKED_CONFIG } from "../pure.js";
+
+describe("executeAutoRenameCommand", () => {
+	afterEach(() => {
+		try { fs.unlinkSync(MOCKED_CONFIG.switchFilePath); } catch (e) { console.debug("cleanup skip:", e); }
+	});
+
+	it("无参数 → 显示当前状态 + 用法", () => {
+		const msg = executeAutoRenameCommand("");
+		expect(msg).toContain("自动重命名会话");
+		expect(msg).toContain("用法");
+	});
+
+	it("status → 同无参数", () => {
+		const msg = executeAutoRenameCommand("status");
+		expect(msg).toContain("自动重命名会话");
+	});
+
+	it("on → 开启并创建文件", () => {
+		const msg = executeAutoRenameCommand("on");
+		expect(msg).toContain("已开启");
+		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
+	});
+
+	it("off → 关闭并删除文件", () => {
+		fs.writeFileSync(MOCKED_CONFIG.switchFilePath, "");
+		const msg = executeAutoRenameCommand("off");
+		expect(msg).toContain("已关闭");
+		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(false);
+	});
+
+	it("enable/disable 作为 on/off 别名", () => {
+		expect(executeAutoRenameCommand("enable")).toContain("已开启");
+		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
+		expect(executeAutoRenameCommand("disable")).toContain("已关闭");
+	});
+
+	it("大小写不敏感（ON / Off）", () => {
+		expect(executeAutoRenameCommand("ON")).toContain("已开启");
+		expect(executeAutoRenameCommand("Off")).toContain("已关闭");
+	});
+
+	it("未知参数 → 提示用法", () => {
+		const msg = executeAutoRenameCommand("xyz");
+		expect(msg).toContain("未知参数");
+		expect(msg).toContain("用法");
+	});
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,233 @@
+/* eslint-disable taste/no-unsafe-cast */
+
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// 默认 isEnabled 返回 falsy（开关关闭），符合测试环境无 auto-rename-enabled 文件的语义，
+// 也避免依赖开发者机器上真实文件是否存在而 flaky。个别 TC 按需 mockReturnValue。
+vi.mock("../pure.js", async (importActual) => {
+	const actual = await importActual<typeof import("../pure.js")>();
+	return { ...actual, isEnabled: vi.fn() };
+});
+
+// mock completeSimple：callRenameLLM 内部动态 import("@earendil-works/pi-ai/compat")，
+// vitest 会把该 mock 注入到动态 import 的解析结果。LTC8/10/11/12 通过 vi.mocked 控制其行为。
+// vi.mock 被提升到文件顶部执行，故此处 import 拿到的是 mock 后的 completeSimple，与 import 位置无关。
+vi.mock("@earendil-works/pi-ai/compat", () => ({
+	completeSimple: vi.fn(),
+}));
+
+// 被测模块须在 vi.mock 之后 import：vi.mock 被 vitest 提升到文件顶部，被测模块才能拿到 mock 后的依赖。
+import renameSessionExtension from "../index";
+import { isEnabled } from "../pure.js";
+
+// ── Mock 工具 ───────────────────────────────────────
+
+interface MockSetup {
+	pi: ExtensionAPI;
+	setSessionNameMock: ReturnType<typeof vi.fn>;
+	getAllToolsMock: ReturnType<typeof vi.fn>;
+	turnEndHandler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>;
+}
+
+/** getAllTools 返回的固定非空 ToolInfo[]（callRenameLLM 不读工具内容，占位即可） */
+const STUB_TOOLS = [
+	{ name: "read", description: "read file", parameters: { type: "object" } },
+];
+
+function createMockPi(): MockSetup {
+	const setSessionNameMock = vi.fn();
+	const getAllToolsMock = vi.fn(() => STUB_TOOLS);
+	let turnEndHandler!: MockSetup["turnEndHandler"];
+	const pi = {
+		on: vi.fn((event: string, handler: MockSetup["turnEndHandler"]) => {
+			if (event === "turn_end") turnEndHandler = handler;
+		}),
+		registerCommand: vi.fn(),
+		setSessionName: setSessionNameMock,
+		getAllTools: getAllToolsMock,
+	} as unknown as ExtensionAPI;
+	return { pi, setSessionNameMock, getAllToolsMock, get turnEndHandler() { return turnEndHandler; } };
+}
+
+/** 扩展 ctx 的可选字段：未传则用主 session 默认值（getSessionDir 返回非 subagents 路径、model/auth 均就绪） */
+interface MockCtxOptions {
+	entries?: unknown[];
+	sessionDir?: string;
+	model?: unknown;
+	auth?: { ok: true; apiKey?: string } | { ok: false; error: string };
+}
+
+function createMockCtx(opts: MockCtxOptions = {}): ExtensionContext {
+	const entries = opts.entries ?? [];
+	const sessionDir = opts.sessionDir ?? "/home/u/.pi/agent/sessions";
+	// 用 in 判断区分「未传字段」（用默认 stub）与「显式传 undefined」（保留 undefined，LTC9 依赖此语义）。
+	const model = "model" in opts ? opts.model : { id: "stub-model" };
+	const auth = opts.auth ?? { ok: true, apiKey: "stub-key" };
+	return {
+		sessionManager: {
+			getEntries: () => entries,
+			getSessionId: () => "test-session-id",
+			getSessionDir: () => sessionDir,
+		},
+		model,
+		modelRegistry: {
+			getApiKeyAndHeaders: async () => auth,
+		},
+		getSystemPrompt: () => "stub system prompt",
+		signal: new AbortController().signal,
+	} as unknown as ExtensionContext;
+}
+
+const ONE_ASSISTANT = [
+	{ type: "message", message: { role: "user" } },
+	{ type: "message", message: { role: "assistant" } },
+];
+
+/** 触发 turn_end handler 的便捷封装（事件载荷在测试中不被读取，固定即可） */
+function fire(setup: MockSetup, ctx: ExtensionContext): Promise<void> {
+	return setup.turnEndHandler(
+		{ type: "turn_end", turnIndex: 0, message: null, toolResults: [] },
+		ctx,
+	) as Promise<void>;
+}
+
+// ────────────────────────────────────────────────────
+// renameSessionExtension 工厂 + hook 注册
+// ────────────────────────────────────────────────────
+
+describe("renameSessionExtension", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		vi.mocked(isEnabled).mockReset();
+		vi.mocked(completeSimple).mockReset();
+		setup = createMockPi();
+		renameSessionExtension(setup.pi);
+	});
+
+	it("TC13: 注册后 pi.on 以 'turn_end' 调用一次", () => {
+		expect(setup.pi.on).toHaveBeenCalledTimes(1);
+		expect(setup.pi.on).toHaveBeenCalledWith("turn_end", expect.any(Function));
+		expect(setup.turnEndHandler).toBeTypeOf("function");
+	});
+
+	it("TC14: 开关关闭时 handler 触发后不调 setSessionName", async () => {
+		vi.mocked(isEnabled).mockReturnValue(false);
+
+		await fire(setup, createMockCtx({ entries: ONE_ASSISTANT }));
+
+		expect(isEnabled).toHaveBeenCalled();
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+	});
+
+	it("TC15: getEntries 抛错时 handler 不抛（catch console.error）", async () => {
+		// 开关打开，让 handler 走到 getEntries
+		vi.mocked(isEnabled).mockReturnValue(true);
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+		const ctx = {
+			sessionManager: {
+				getEntries: () => { throw new Error("boom"); },
+				getSessionId: () => "test-session-id",
+				getSessionDir: () => "/home/u/.pi/agent/sessions",
+			},
+			model: { id: "stub-model" },
+			modelRegistry: { getApiKeyAndHeaders: async () => ({ ok: true }) },
+			getSystemPrompt: () => "stub system prompt",
+			signal: new AbortController().signal,
+		} as unknown as ExtensionContext;
+
+		await expect(fire(setup, ctx)).resolves.toBeUndefined();
+
+		expect(errorSpy).toHaveBeenCalled();
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+
+	// ────────────────────────────────────────────────────
+	// rename-llm wave：callRenameLLM 集成覆盖（LTC7-LTC12）
+	// ────────────────────────────────────────────────────
+
+	it("LTC7: subagents 子 session 路径 → isSubagentSession 早退，不调 setSessionName", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+
+		await fire(setup, createMockCtx({
+			entries: ONE_ASSISTANT,
+			sessionDir: "/home/u/.pi/agent/subagents/--proj--/sessions",
+		}));
+
+		// isSubagentSession 在首 turn 判定之前早退，不应触达 LLM
+		expect(completeSimple).not.toHaveBeenCalled();
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+	});
+
+	it("LTC8: getApiKeyAndHeaders resolve {ok:false} → callRenameLLM 返回 null，不调 setSessionName", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+
+		await fire(setup, createMockCtx({
+			entries: ONE_ASSISTANT,
+			auth: { ok: false, error: "no api key" },
+		}));
+
+		// auth 未通过，不应发起 LLM 调用
+		expect(completeSimple).not.toHaveBeenCalled();
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+	});
+
+	it("LTC9: ctx.model = undefined → callRenameLLM 早退返回 null，不调 setSessionName", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+
+		await fire(setup, createMockCtx({ entries: ONE_ASSISTANT, model: undefined }));
+
+		expect(completeSimple).not.toHaveBeenCalled();
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+	});
+
+	it("LTC10: completeSimple 返回 text → extractTitle 去空白后 setSessionName 落库", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+		vi.mocked(completeSimple).mockResolvedValue({
+			content: [{ type: "text", text: "  修复登录bug  " }],
+		});
+
+		await fire(setup, createMockCtx({ entries: ONE_ASSISTANT }));
+		// handler 内 callRenameLLM 是 detached promise（fire-and-forget），fire 立即 resolve；
+		// 需等 detached promise settle 后再断言落库结果。
+		await vi.waitFor(() => expect(setup.setSessionNameMock).toHaveBeenCalledWith("修复登录bug"));
+
+		expect(completeSimple).toHaveBeenCalledTimes(1);
+		expect(setup.setSessionNameMock).toHaveBeenCalledWith("修复登录bug");
+	});
+
+	it("LTC11: completeSimple 返回无 text（仅 toolCall）→ extractTitle 空串 → 不调 setSessionName", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+		vi.mocked(completeSimple).mockResolvedValue({
+			content: [{ type: "toolCall", name: "x", arguments: {} }],
+		});
+
+		await fire(setup, createMockCtx({ entries: ONE_ASSISTANT }));
+		// handler 内 callRenameLLM 是 detached promise（fire-and-forget），fire 立即 resolve；
+		// 需等 detached promise settle（completeSimple 被调用）后再断言不落库。
+		await vi.waitFor(() => expect(completeSimple).toHaveBeenCalledTimes(1));
+
+		expect(completeSimple).toHaveBeenCalledTimes(1);
+		// extractTitle 返回空串 → callRenameLLM 返回 null → 不落库
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+	});
+
+	it("LTC12: completeSimple reject → handler 不抛，setSessionName 未调用", async () => {
+		vi.mocked(isEnabled).mockReturnValue(true);
+		vi.mocked(completeSimple).mockRejectedValue(new Error("llm down"));
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+		await expect(fire(setup, createMockCtx({ entries: ONE_ASSISTANT }))).resolves.toBeUndefined();
+		// handler 内 callRenameLLM 是 detached promise（fire-and-forget），fire 立即 resolve；
+		// reject 由 detached promise 的 catch 兜底，需等其 settle 后再断言。
+		await vi.waitFor(() => expect(completeSimple).toHaveBeenCalledTimes(1));
+
+		expect(completeSimple).toHaveBeenCalledTimes(1);
+		expect(setup.setSessionNameMock).not.toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+});

package/src/__tests__/llm.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import { buildMessages, isSubagentSession, mapToolsToAiFormat } from "../llm.js";
+
+describe("buildMessages", () => {
+	it("LTC1: 从 entries 构造前缀 + 追加 rename 指令", () => {
+		const entries = [
+			{ type: "message", message: { role: "user", content: [{ type: "text", text: "hi" }] } },
+			{ type: "message", message: { role: "assistant", content: [{ type: "text", text: "hello" }] } },
+		];
+		const result = buildMessages(entries, "生成标题");
+		expect(result).toHaveLength(3);
+		expect(result[0]).toEqual({ role: "user", content: [{ type: "text", text: "hi" }] });
+		expect(result[2]).toEqual({ role: "user", content: [{ type: "text", text: "生成标题" }] });
+	});
+
+	it("LTC2: 过滤非 message entry", () => {
+		const entries = [
+			{ type: "thinkingLevelChange", data: {} },
+			{ type: "message", message: { role: "user", content: [] } },
+			{ type: "message", message: { role: "assistant", content: [] } },
+			{ type: "modelChange", data: {} },
+		];
+		const result = buildMessages(entries, "生成标题");
+		// user + assistant + rename 指令
+		expect(result).toHaveLength(3);
+	});
+
+	it("LTC3: toolResult message 保留（kvcache 前缀完整性）", () => {
+		const entries = [
+			{ type: "message", message: { role: "user", content: [] } },
+			{ type: "message", message: { role: "assistant", content: [] } },
+			{ type: "message", message: { role: "toolResult", content: [] } },
+			{ type: "message", message: { role: "assistant", content: [] } },
+		];
+		const result = buildMessages(entries, "生成标题");
+		// 4 条前缀 + rename 指令
+		expect(result).toHaveLength(5);
+		expect((result[2] as { role: string }).role).toBe("toolResult");
+	});
+});
+
+describe("isSubagentSession", () => {
+	it("LTC4: subagents 路径返回 true", () => {
+		expect(isSubagentSession("/home/u/.pi/agent/subagents/--proj--/sessions")).toBe(true);
+	});
+
+	it("LTC5: 主 session 路径返回 false", () => {
+		expect(isSubagentSession("/home/u/.pi/agent/sessions")).toBe(false);
+	});
+});
+
+describe("mapToolsToAiFormat", () => {
+	it("LTC6: ToolInfo[] 转 pi-ai Tool[]（只留 name/description/parameters）", () => {
+		const tools = [
+			{
+				name: "read",
+				description: "read file",
+				parameters: { type: "object" },
+				promptGuidelines: ["x"],
+				sourceInfo: {},
+			},
+		];
+		const result = mapToolsToAiFormat(tools);
+		expect(result).toEqual([{ name: "read", description: "read file", parameters: { type: "object" } }]);
+		// 确认多余字段已去掉（toEqual 已校验结构无多余键，此处再显式断言 sourceInfo/promptGuidelines 不存在）
+		expect("sourceInfo" in result[0]).toBe(false);
+		expect("promptGuidelines" in result[0]).toBe(false);
+	});
+});

package/src/__tests__/pure.test.ts

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { CONFIG, countAssistantReplies, extractTitle, isEnabled, setSwitch } from "../pure.js";
+
+// ────────────────────────────────────────────────────
+// countAssistantReplies
+// ────────────────────────────────────────────────────
+
+describe("countAssistantReplies", () => {
+	it("[user, assistant] → 1", () => {
+		const entries = [
+			{ type: "message", message: { role: "user" } },
+			{ type: "message", message: { role: "assistant" } },
+		];
+		expect(countAssistantReplies(entries)).toBe(1);
+	});
+
+	it("[user, assistant, user, assistant] → 2", () => {
+		const entries = [
+			{ type: "message", message: { role: "user" } },
+			{ type: "message", message: { role: "assistant" } },
+			{ type: "message", message: { role: "user" } },
+			{ type: "message", message: { role: "assistant" } },
+		];
+		expect(countAssistantReplies(entries)).toBe(2);
+	});
+
+	it("过滤非 message（thinkingLevelChange / modelChange）→ 1", () => {
+		const entries = [
+			{ type: "thinkingLevelChange" },
+			{ type: "message", message: { role: "user" } },
+			{ type: "message", message: { role: "assistant" } },
+			{ type: "modelChange" },
+		];
+		expect(countAssistantReplies(entries)).toBe(1);
+	});
+
+	it("[user, assistant, toolResult] → 1（toolResult 不计入）", () => {
+		const entries = [
+			{ type: "message", message: { role: "user" } },
+			{ type: "message", message: { role: "assistant" } },
+			{ type: "toolResult" },
+		];
+		expect(countAssistantReplies(entries)).toBe(1);
+	});
+});
+
+// ────────────────────────────────────────────────────
+// extractTitle
+// ────────────────────────────────────────────────────
+
+describe("extractTitle", () => {
+	it("trim 首尾空白 → '修复登录 bug'", () => {
+		const resp = { content: [{ type: "text", text: "  修复登录 bug  \n" }] };
+		expect(extractTitle(resp, 50)).toBe("修复登录 bug");
+	});
+
+	it("去引号 + markdown 强调 → '重构 API 层'", () => {
+		const resp = { content: [{ type: "text", text: "\"**重构 API 层**\"" }] };
+		expect(extractTitle(resp, 50)).toBe("重构 API 层");
+	});
+
+	it("超长文本截断到 <=50 字符", () => {
+		const long = "这是一个非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常长的标题".repeat(3);
+		const resp = { content: [{ type: "text", text: long }] };
+		const result = extractTitle(resp, 50);
+		expect(Array.from(result).length).toBe(50);
+	});
+
+	it("仅 toolCall 块（无 text）→ ''", () => {
+		const resp = { content: [{ type: "toolCall", name: "x", arguments: {} }] };
+		expect(extractTitle(resp, 50)).toBe("");
+	});
+
+	it("空 content → ''", () => {
+		const resp = { content: [] };
+		expect(extractTitle(resp, 50)).toBe("");
+	});
+});
+
+// ────────────────────────────────────────────────────
+// isEnabled
+// ────────────────────────────────────────────────────
+
+describe("isEnabled", () => {
+	let tmpDir: string;
+
+	afterEach(() => {
+		if (tmpDir) {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+
+	it("文件存在 → true", () => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-test-"));
+		const switchFile = path.join(tmpDir, "auto-rename-enabled");
+		fs.writeFileSync(switchFile, "");
+		expect(isEnabled(switchFile)).toBe(true);
+	});
+
+	it("文件不存在 → false", () => {
+		expect(isEnabled(path.join(os.tmpdir(), "rename-not-exist-" + Date.now()))).toBe(false);
+	});
+
+	it("fs.existsSync 抛错 → false（当作关闭）", () => {
+		const spy = vi.spyOn(fs, "existsSync").mockImplementation(() => {
+			throw new Error("EACCES");
+		});
+		try {
+			expect(isEnabled("/whatever")).toBe(false);
+		} finally {
+			spy.mockRestore();
+		}
+	});
+});
+
+// ────────────────────────────────────────────────────
+// setSwitch
+// ────────────────────────────────────────────────────
+
+describe("setSwitch", () => {
+	let tmpDir: string;
+
+	afterEach(() => {
+		if (tmpDir) {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+
+	it("enabled=true 创建文件（含父目录）", () => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-set-"));
+		const switchFile = path.join(tmpDir, "sub", "auto-rename-enabled");
+		const msg = setSwitch(switchFile, true);
+		expect(msg).toContain("已开启");
+		expect(fs.existsSync(switchFile)).toBe(true);
+	});
+
+	it("enabled=false 删除已存在的文件", () => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-set-"));
+		const switchFile = path.join(tmpDir, "auto-rename-enabled");
+		fs.writeFileSync(switchFile, "");
+		const msg = setSwitch(switchFile, false);
+		expect(msg).toContain("已关闭");
+		expect(fs.existsSync(switchFile)).toBe(false);
+	});
+
+	it("enabled=false 文件不存在 → 提示已是关闭状态", () => {
+		const switchFile = path.join(os.tmpdir(), "rename-not-exist-" + Date.now());
+		const msg = setSwitch(switchFile, false);
+		expect(msg).toContain("已是关闭状态");
+	});
+
+	it("enabled=true 文件已存在 → 幂等，仍提示已开启", () => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-set-"));
+		const switchFile = path.join(tmpDir, "auto-rename-enabled");
+		fs.writeFileSync(switchFile, "");
+		const msg = setSwitch(switchFile, true);
+		expect(msg).toContain("已开启");
+	});
+});
+
+// ────────────────────────────────────────────────────
+// CONFIG smoke
+// ────────────────────────────────────────────────────
+
+describe("CONFIG", () => {
+	it("包含 switchFilePath / maxTitleLength / renameInstruction", () => {
+		expect(typeof CONFIG.switchFilePath).toBe("string");
+		expect(CONFIG.switchFilePath.length).toBeGreaterThan(0);
+		expect(CONFIG.maxTitleLength).toBe(50);
+		expect(typeof CONFIG.renameInstruction).toBe("string");
+	});
+});

package/src/commands.ts

@@ -0,0 +1,49 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { CONFIG, isEnabled, setSwitch } from "./pure.js";
+
+/**
+ * 解析 /auto-rename 参数并执行开关操作。纯函数，返回反馈文本（供 handler notify）。
+ *
+ * 用法：
+ *   /auto-rename         — 查看当前状态
+ *   /auto-rename on      — 开启
+ *   /auto-rename off     — 关闭
+ */
+export function executeAutoRenameCommand(args: string): string {
+	const trimmed = args.trim().toLowerCase();
+
+	if (trimmed === "" || trimmed === "status") {
+		const state = isEnabled(CONFIG.switchFilePath) ? "已开启 ✓" : "已关闭 ✗";
+		return `自动重命名会话：${state}\n用法：/auto-rename on | off | status`;
+	}
+
+	if (trimmed === "on" || trimmed === "enable") {
+		return setSwitch(CONFIG.switchFilePath, true);
+	}
+
+	if (trimmed === "off" || trimmed === "disable") {
+		return setSwitch(CONFIG.switchFilePath, false);
+	}
+
+	return `未知参数 "${args.trim()}"。\n用法：/auto-rename on | off | status`;
+}
+
+/** 注册 /auto-rename 命令。 */
+export function registerAutoRenameCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("auto-rename", {
+		description: "控制自动重命名会话功能。/auto-rename [on|off|status]",
+		getArgumentCompletions(prefix: string) {
+			const trimmed = prefix.trimStart().toLowerCase();
+			const opts = [
+				{ label: "on", value: "on", description: "开启自动重命名" },
+				{ label: "off", value: "off", description: "关闭自动重命名" },
+				{ label: "status", value: "status", description: "查看当前状态" },
+			];
+			return trimmed === "" ? opts : opts.filter((o) => o.label.startsWith(trimmed));
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			ctx.ui.notify(executeAutoRenameCommand(args), "info");
+		},
+	});
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { registerAutoRenameCommand } from "./commands.js";
+import { callRenameLLM, isSubagentSession } from "./llm.js";
+import { CONFIG, countAssistantReplies, isEnabled } from "./pure.js";
+
+/** turn_end 事件的宽松类型（参考 pi extensions/types.ts:704-710 的 TurnEndEvent） */
+interface TurnEndLikeEvent {
+	type: "turn_end";
+	turnIndex: number;
+	message: unknown;
+	toolResults: unknown[];
+}
+
+/** ToolInfo 的宽松类型（pi 的 ToolInfo = Pick<ToolDefinition,...> & {sourceInfo}，用宽松类型避免强耦合）。 */
+interface ToolInfoLike {
+	name: string;
+	description: string;
+	parameters: object;
+}
+
+/**
+ * pi-rename-session extension 工厂函数。
+ * 新 session 首 turn 完成后，自动生成会话标题并 setSessionName 落库。
+ */
+export default function renameSessionExtension(pi: ExtensionAPI): void {
+	registerAutoRenameCommand(pi);
+
+	pi.on("turn_end", async (_event: TurnEndLikeEvent, ctx: ExtensionContext) => {
+		try {
+			// 1. 开关检查
+			if (!isEnabled(CONFIG.switchFilePath)) return;
+
+			// 2. 排除 subagent 子进程 session（子 session 是临时产物，rename 产生噪音）
+			if (isSubagentSession(ctx.sessionManager.getSessionDir())) return;
+
+			// 3. 首 turn 判定（assistant 回复数 === 1）
+			const entries = ctx.sessionManager.getEntries();
+			const assistantCount = countAssistantReplies(entries);
+			if (assistantCount !== 1) return;
+
+			// 4. LLM 生成标题并落库。pi 运行时的事件链是 await 的（runner.emit → await handler），
+			// 若 await callRenameLLM 会阻塞 agent 进入下一次迭代。这里用 detached promise 脱离 await 链，
+			// 真正实现 fire-and-forget：handler 立即 resolve，LLM 调用与 setSessionName 在后台异步完成。
+			// pi.getAllTools() 的 .d.ts 因 pi-ai 泛型未完全解析而被降级，经 unknown 收窄到宽松 ToolInfoLike。
+			void callRenameLLM(ctx, pi.getAllTools() as unknown as ReadonlyArray<ToolInfoLike>)
+				.then((title) => {
+					if (title) pi.setSessionName(title);
+				})
+				.catch((e) => console.error("[pi-rename-session] rename LLM failed:", e));
+			// rename 是 best-effort，任何 LLM 失败（网络/提取/auth）都静默跳过保留原 label，不进 session history。
+			// 同步部分（开关/子 session/首 turn 判定）的错误兜底：绝不阻断 agent 循环。
+			// eslint-disable-next-line taste/no-silent-catch
+		} catch (e) {
+			console.error("[pi-rename-session] failed:", e);
+		}
+	});
+}

package/src/llm.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+import type {
+	AssistantMessage,
+	Context as LlmContext,
+	SimpleStreamOptions,
+} from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { CONFIG, extractTitle } from "./pure.js";
+
+/** sessionDir 路径含 subagents 段 → 是 subagent 子进程 session，跳过 rename。 */
+export function isSubagentSession(sessionDir: string): boolean {
+	return sessionDir.includes(path.sep + "subagents" + path.sep);
+}
+
+/** entry 的宽松类型（structural typing，兼容 pi 的 SessionEntry[] 但不依赖 pi 类型） */
+interface EntryLike {
+	type: string;
+	message?: unknown;
+}
+
+/**
+ * 从 session entries 构造 messages 前缀，末尾追加 rename 指令 user message。
+ * 取 type==='message' 的 entry.message，按原顺序保留（前缀与主 turn 字节级一致，命中 kvcache）。
+ */
+export function buildMessages(entries: ReadonlyArray<EntryLike>, instruction: string): unknown[] {
+	const prefix = entries
+		.filter((e) => e.type === "message" && e.message !== undefined)
+		.map((e) => e.message as object);
+	return [
+		...prefix,
+		{ role: "user", content: [{ type: "text", text: instruction }] },
+	];
+}
+
+/** ToolInfo 的宽松类型（pi 的 ToolInfo 是 Pick<ToolDefinition,...> & {sourceInfo}） */
+interface ToolInfoLike {
+	name: string;
+	description: string;
+	parameters: object;
+}
+
+/** pi.getAllTools() 的 ToolInfo[] 转 pi-ai 的 Tool[]（只留 name/description/parameters，丢弃 sourceInfo 等扩展字段）。 */
+export function mapToolsToAiFormat(tools: ReadonlyArray<ToolInfoLike>): ToolInfoLike[] {
+	return tools.map((t) => ({
+		name: t.name,
+		description: t.description,
+		parameters: t.parameters,
+	}));
+}
+
+/**
+ * 发起 rename LLM 调用，返回提取的标题（空串/异常时返回 null 表示应跳过 rename）。
+ *
+ * 动态 import completeSimple：加载阶段 pi-ai/compat 是 throwing stub（loader.ts 尚未 bindCore），
+ * 必须延迟到 turn_end 处理时（bindCore 完成）才能 import 成功，故不能用顶层 import。
+ */
+export async function callRenameLLM(
+	ctx: ExtensionContext,
+	tools: ReadonlyArray<ToolInfoLike>,
+): Promise<string | null> {
+	const model = ctx.model;
+	if (!model) return null;
+
+	// getApiKeyAndHeaders 返回判别联合，必须显式检查 .ok 才能取 apiKey/headers
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) return null;
+
+	const sessionId = ctx.sessionManager.getSessionId();
+	const systemPrompt = ctx.getSystemPrompt();
+	const messages = buildMessages(
+		ctx.sessionManager.getEntries() as ReadonlyArray<EntryLike>,
+		CONFIG.renameInstruction,
+	);
+	const mappedTools = mapToolsToAiFormat(tools);
+
+	const { completeSimple } = await import("@earendil-works/pi-ai/compat");
+
+	const options: SimpleStreamOptions = {
+		apiKey: auth.apiKey,
+		headers: auth.headers,
+		env: auth.env,
+		sessionId,
+		signal: ctx.signal,
+		// 标题只需几个词，64 token 足够且省 quota
+		maxTokens: 64,
+	};
+	const context: LlmContext = { systemPrompt, messages, tools: mappedTools };
+	const resp: AssistantMessage = await completeSimple(model, context, options);
+
+	const title = extractTitle(resp, CONFIG.maxTitleLength);
+	return title || null;
+}

package/src/pure.ts

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** 配置：开关文件路径、标题最大长度、rename 指令。readonly，集中管理便于测试注入。 */
+export interface RenameConfig {
+	readonly switchFilePath: string;
+	readonly maxTitleLength: number;
+	readonly renameInstruction: string;
+}
+
+/** pi 实际使用的根数据目录（与 pi 的 getAgentDir 同源，读 PI_CODING_AGENT_DIR env） */
+const ROOT = process.env.PI_CODING_AGENT_DIR
+	?? path.join(os.homedir(), ".pi", "agent");
+
+export const CONFIG: RenameConfig = {
+	switchFilePath: path.join(ROOT, "auto-rename-enabled"),
+	maxTitleLength: 50,
+	renameInstruction: "根据以上对话，为这个会话生成一个简短标题（3-8 个词）。用对话所用的语言。只输出标题文本，不要解释，不要 emoji，不要引号或 markdown 标记。",
+};
+
+/** entry 的宽松类型（structural typing，兼容 pi 的 SessionEntry[] 但不依赖 pi 类型） */
+interface EntryLike {
+	type: string;
+	message?: { role?: string };
+}
+
+/**
+ * 数 session 中 assistant 回复数。用于判定首 turn（===1）。
+ * 判定条件：entry.type === "message" && entry.message.role === "assistant"
+ * （pi 内部 session-manager.ts:367/937/1392 同款模式）
+ */
+export function countAssistantReplies(entries: ReadonlyArray<EntryLike>): number {
+	let count = 0;
+	for (const entry of entries) {
+		if (entry.type === "message" && entry.message?.role === "assistant") {
+			count++;
+		}
+	}
+	return count;
+}
+
+/** AssistantMessage.content 的宽松元素类型 */
+interface ContentBlockLike {
+	type: string;
+	text?: string;
+}
+
+/**
+ * 从 completeSimple 返回的 AssistantMessage.content 提取标题文本。
+ * 遍历 content 取 type==='text' 的 .text 拼接，trim，去首尾引号/markdown 包装，截断。
+ * 仅 toolCall 块（无 text）或空 content → 返回空串。
+ */
+export function extractTitle(resp: { content: ReadonlyArray<ContentBlockLike> }, maxLength: number): string {
+	const rawText = resp.content
+		.filter((block) => block.type === "text" && block.text)
+		.map((block) => block.text as string)
+		.join("");
+
+	const trimmed = rawText.trim();
+	if (!trimmed) return "";
+
+	// 去首尾成对引号（单/双/中文）和 markdown 强调标记（* ** ` _）
+	const cleaned = trimmed
+		.replace(/^["“”'`*_]+|["“”'`*_]+$/g, "")
+		.trim();
+
+	if (!cleaned) return "";
+
+	// 按 Unicode 码点截断（避免截断多字节字符）
+	const chars = Array.from(cleaned);
+	if (chars.length <= maxLength) return cleaned;
+	return chars.slice(0, maxLength).join("");
+}
+
+/**
+ * 检查开关文件是否存在。文件存在=开启。
+ * try/catch 包裹，读失败（权限/IO）返回 false（当作关闭）。
+ */
+export function isEnabled(switchFilePath: string): boolean {
+	try {
+		return fs.existsSync(switchFilePath);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * 设置开关状态。enabled=true 创建文件（含父目录），false 删除文件。
+ * 返回操作结果描述（供 command 反馈）。IO 失败时返回错误信息，不抛。
+ */
+export function setSwitch(switchFilePath: string, enabled: boolean): string {
+	try {
+		if (enabled) {
+			fs.mkdirSync(path.dirname(switchFilePath), { recursive: true });
+			fs.writeFileSync(switchFilePath, "", { flag: "a" });
+			return `已开启：自动重命名会话（${switchFilePath}）`;
+		}
+		if (fs.existsSync(switchFilePath)) {
+			fs.unlinkSync(switchFilePath);
+			return "已关闭：自动重命名会话";
+		}
+		return "已是关闭状态，无需操作";
+	} catch (e) {
+		return `设置失败：${e instanceof Error ? e.message : String(e)}`;
+	}
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});