@zhushanwen/pi-unified-hooks 0.2.4 → 0.2.6

package/README.md

@@ -1,5 +1,17 @@
 # unified-hooks
 
+> **[DEPRECATED] 本包已废弃，被 [`@zhushanwen/pi-base-tool-enhance`](https://www.npmjs.com/package/@zhushanwen/pi-base-tool-enhance) 取代，不再维护。**
+>
+> 能力承接落点：
+>
+> | 原 hook | 承接方式 |
+> |---------|---------|
+> | `test-timeout-guard` | base-tool-enhance 可配置 force-test 白名单：测试类命令**自动转后台执行**并返回 task_id（不再 block 打回补 timeout 参数） |
+> | `network-timeout-guard` | 正则不迁入（这类命令时长不定且结果常被立即需要）；挂死保护由模型显式 timeout + base-tool-enhance 可配置前台默认超时承接 |
+> | `tool-error-handler` | base-tool-enhance 的 tool_error 审计（customType 保持 `unified-hooks:tool-error`，历史 entry 不断链） |
+>
+> 迁移指引：`pi uninstall npm:@zhushanwen/pi-unified-hooks` 后 `pi install npm:@zhushanwen/pi-base-tool-enhance`。两者同时安装会对 bash 产生双重拦截，务必先卸载本包。
+
 统一 hooks 管理器 — 将散落的 hooks 收集到一个扩展中统一维护，每个 hook 可独立启用/禁用。
 
 ## 功能

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.2.4",
-  "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
+  "version": "0.2.6",
+  "description": "[DEPRECATED] Unified hooks extension - collect scattered hooks in one place for easy maintenance",
+  "deprecated": "Superseded by @zhushanwen/pi-base-tool-enhance — install that instead; test-command guarding, tool-error audit and configurable timeouts are all covered.",
   "main": "index.ts",
   "type": "module",
   "xyz-agent": {
@@ -19,7 +20,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.2.2"
+    "@zhushanwen/pi-extension-logger": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.1"

package/src/__tests__/tool-error-handler.test.ts

@@ -3,20 +3,19 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-// Mock 共享 logger，让 logger.warn 可被 spy
+import { setupToolErrorHandler } from "../hooks/tool-error-handler.ts";
+
+// 回归防护：源码已删泛化 logger.warn 双写（D5），若被重新引入测试必须红。
+// mock 掉共享 logger，使 loggerMock.warn 可被断言未被调。
 const { loggerMock } = vi.hoisted(() => ({
-	loggerMock: {
-		debug: vi.fn(),
-		warn: vi.fn(),
-		error: vi.fn(),
-	},
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
 }));
 vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
 }));
 
-import { setupToolErrorHandler } from "../hooks/tool-error-handler.ts";
-
 // --- helper types ---
 interface MockPi {
 	on: ReturnType<typeof vi.fn>;
@@ -40,9 +39,8 @@ describe("setupToolErrorHandler", () => {
 		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
 	});
 
-	it("logs via logger.warn and appendEntry with dedicated customType on isError:true", async () => {
+	it("appendEntry with dedicated customType on isError:true", async () => {
 		const pi = createMockPi();
-		loggerMock.warn.mockClear();
 		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
@@ -50,19 +48,10 @@ describe("setupToolErrorHandler", () => {
 
 		await handler({ isError: true, toolName: "read", toolCallId: "call-42" });
 
-		// logger.warn 被调一次（内部走泛化 appendEntry customType）
-		expect(loggerMock.warn).toHaveBeenCalledTimes(1);
-		expect(loggerMock.warn).toHaveBeenCalledWith(
-			"[unified-hooks] read error (callId=call-42)",
-			expect.objectContaining({
-				toolName: "read",
-				toolCallId: "call-42",
-				errorText: null,
-			}),
-		);
-		// 额外 appendEntry 用专属 customType "unified-hooks:tool-error"，
-		// 保留按 entry type 过滤 tool 错误的埋点契约
+		// 契约载体 = 专属 customType "unified-hooks:tool-error"
 		expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+		// 回归防护（D5）：泛化 logger.warn 双写不得回归
+		expect(loggerMock.warn).not.toHaveBeenCalled();
 		expect(pi.appendEntry).toHaveBeenCalledWith(
 			"unified-hooks:tool-error",
 			expect.objectContaining({
@@ -73,16 +62,16 @@ describe("setupToolErrorHandler", () => {
 		);
 	});
 
-	it("does nothing on isError:false (no logger.warn)", async () => {
+	it("does nothing on isError:false (no appendEntry)", async () => {
 		const pi = createMockPi();
-		loggerMock.warn.mockClear();
+		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
 		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
 		await handler({ isError: false, toolName: "bash", toolCallId: "call-99" });
 
-		expect(loggerMock.warn).not.toHaveBeenCalled();
+		expect(pi.appendEntry).not.toHaveBeenCalled();
 	});
 
 	// --- edge cases ---
@@ -97,7 +86,7 @@ describe("setupToolErrorHandler", () => {
 
 	it("handles concurrent error events independently", async () => {
 		const pi = createMockPi();
-		loggerMock.warn.mockClear();
+		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
 		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
@@ -108,13 +97,13 @@ describe("setupToolErrorHandler", () => {
 			handler({ isError: false, toolName: "edit", toolCallId: "e3" }),
 		]);
 
-		expect(loggerMock.warn).toHaveBeenCalledTimes(2);
-		expect(loggerMock.warn).toHaveBeenCalledWith(
-			"[unified-hooks] read error (callId=e1)",
+		expect(pi.appendEntry).toHaveBeenCalledTimes(2);
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"unified-hooks:tool-error",
 			expect.objectContaining({ toolName: "read", toolCallId: "e1" }),
 		);
-		expect(loggerMock.warn).toHaveBeenCalledWith(
-			"[unified-hooks] bash error (callId=e2)",
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"unified-hooks:tool-error",
 			expect.objectContaining({ toolName: "bash", toolCallId: "e2" }),
 		);
 	});
@@ -123,7 +112,7 @@ describe("setupToolErrorHandler", () => {
 
 	it("从 result.content[0].text 提取错误文本（如 'hub disposed'）", async () => {
 		const pi = createMockPi();
-		loggerMock.warn.mockClear();
+		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
 		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
@@ -135,8 +124,8 @@ describe("setupToolErrorHandler", () => {
 			result: { content: [{ type: "text", text: "hub disposed" }] },
 		});
 
-		expect(loggerMock.warn).toHaveBeenCalledWith(
-			"[unified-hooks] subagent error (callId=call-disposed)",
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"unified-hooks:tool-error",
 			expect.objectContaining({
 				toolName: "subagent",
 				toolCallId: "call-disposed",
@@ -147,7 +136,7 @@ describe("setupToolErrorHandler", () => {
 
 	it("result 缺失或无 content 时降级到无详情（不崩）", async () => {
 		const pi = createMockPi();
-		loggerMock.warn.mockClear();
+		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
 		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
@@ -160,9 +149,9 @@ describe("setupToolErrorHandler", () => {
 		await handler({ isError: true, toolName: "bash", toolCallId: "x3", result: "oops" });
 
 		// 三次都降级为无详情
-		expect(loggerMock.warn.mock.calls[0]![0]).toBe("[unified-hooks] bash error (callId=x1)");
-		expect(loggerMock.warn.mock.calls[0]![1]).toHaveProperty("errorText", null);
-		expect(loggerMock.warn.mock.calls[1]![1]).toHaveProperty("errorText", null);
-		expect(loggerMock.warn.mock.calls[2]![1]).toHaveProperty("errorText", null);
+		expect(pi.appendEntry).toHaveBeenCalledTimes(3);
+		expect(pi.appendEntry.mock.calls[0]![1]).toHaveProperty("errorText", null);
+		expect(pi.appendEntry.mock.calls[1]![1]).toHaveProperty("errorText", null);
+		expect(pi.appendEntry.mock.calls[2]![1]).toHaveProperty("errorText", null);
 	});
 });

package/src/hooks/tool-error-handler.ts

@@ -11,9 +11,6 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("unified-hooks");
 
 /**
  * Subset of `ToolExecutionEndEvent` fields used by this hook.
@@ -86,16 +83,10 @@ export function setupToolErrorHandler(pi: ExtensionAPI): void {
     // SDK 事件无 errorMessage 字段，只能从这里捞；拿不到也不阻断（降级到无详情）。
     const errorText = extractErrorText(e.result);
 
-    // appendEntry 持久化到 session entries，供事后排查（无 UI、不泄漏）。
-    // errorText 一起存上——事后排查能看到真实原因（如 "hub disposed"）。
+    // 契约载体 = 专属 customType `unified-hooks:tool-error`（含 timestamp/toolName/toolCallId/errorText 全量字段）。
+    // 泛化 `unified-hooks:log` 冗余已删（无独有信息，全仓无消费方）。
     // 不调 ctx.ui.notify——tool error 已在对话流里（pi 原生 tool result），
     // notify 会重复显示且措辞（"bash error"）误导。
-    //
-    // 注意：除了 logger.warn（内部走泛化 `unified-hooks:log` customType），
-    // 这里额外调一次 `pi.appendEntry("unified-hooks:tool-error", ...)`。
-    // 原因：logger 内部的 appendEntry 用的是泛化 customType，无法区分 entry
-    // 是否为 tool 错误；保留专属 entry type 让事后按 customType 过滤 tool
-    // 错误的脚本/dashboard 仍可工作（埋点契约）。
     const entry = {
       timestamp: Date.now(),
       toolName: e.toolName,
@@ -103,6 +94,5 @@ export function setupToolErrorHandler(pi: ExtensionAPI): void {
       errorText: errorText ?? null,
     };
     pi.appendEntry("unified-hooks:tool-error", entry);
-    logger.warn(`[unified-hooks] ${e.toolName} error (callId=${e.toolCallId})`, entry);
   });
 }