@zhushanwen/pi-unified-hooks 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
   "main": "index.ts",
   "type": "module",
@@ -19,11 +19,16 @@
     "typebox": "*",
     "@mariozechner/pi-coding-agent": "*"
   },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
   "files": [
     "src/",
     "index.ts"
   ],
   "scripts": {
-    "typecheck": "npx tsc --noEmit"
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/__tests__/session-start-handler.test.ts

@@ -0,0 +1,155 @@
+// src/__tests__/session-start-handler.test.ts
+import { describe, expect, it, vi } from "vitest";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import type { HookContext } from "../hooks/tool-error-handler.ts";
+
+// --- mocks for hook setup modules ---
+vi.mock("../hooks/tool-error-handler.ts", () => ({
+	setupToolErrorHandler: vi.fn(),
+}));
+
+vi.mock("../hooks/network-timeout-guard.ts", () => ({
+	setupNetworkTimeoutGuard: vi.fn(),
+}));
+
+vi.mock("../hooks/test-timeout-guard.ts", () => ({
+	setupTestTimeoutGuard: vi.fn(),
+}));
+
+vi.mock("../hooks/subagent-list-injector.ts", () => ({
+	setupSubagentListInjector: vi.fn(),
+}));
+
+// Re-import after mocking so the mocked versions are used
+import { setupToolErrorHandler } from "../hooks/tool-error-handler.ts";
+import { setupNetworkTimeoutGuard } from "../hooks/network-timeout-guard.ts";
+import { setupTestTimeoutGuard } from "../hooks/test-timeout-guard.ts";
+import { setupSubagentListInjector } from "../hooks/subagent-list-injector.ts";
+
+import unifiedHooksExtension from "../index.ts";
+
+// --- helpers ---
+function createMockPi(): {
+	on: ReturnType<typeof vi.fn>;
+	appendEntry: ReturnType<typeof vi.fn>;
+} {
+	return {
+		on: vi.fn(),
+		appendEntry: vi.fn(),
+	};
+}
+
+function createMockCtx(): { ctx: HookContext; notify: ReturnType<typeof vi.fn> } {
+	const notify = vi.fn();
+	const ctx = { ui: { notify } } as unknown as HookContext;
+	return { ctx, notify };
+}
+
+function getSessionStartHandler(pi: ReturnType<typeof createMockPi>): (event: unknown, ctx: HookContext) => void {
+	return pi.on.mock.calls.find(
+		(c: unknown[]) => c[0] === "session_start",
+	)![1] as (event: unknown, ctx: HookContext) => void;
+}
+
+// --- tests ---
+describe("session_start handler", () => {
+	it("notifies 'info' when all hooks are enabled", () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		// All hooks succeed
+		(setupToolErrorHandler as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+		(setupNetworkTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+
+		unifiedHooksExtension(pi as unknown as ExtensionAPI);
+
+		const handler = getSessionStartHandler(pi);
+		handler({}, ctx);
+
+		expect(notify).toHaveBeenCalledTimes(1);
+		expect(notify.mock.calls[0]![1]).toBe("info");
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
+			enabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard", "subagent-list-injector"],
+			disabled: [],
+		});
+	});
+
+	it("notifies 'warning' and lists disabled hooks when some hooks fail", () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		// Two hooks fail
+		(setupToolErrorHandler as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+		(setupNetworkTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("setup failed");
+		});
+		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("timeout");
+		});
+		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {});
+
+		unifiedHooksExtension(pi as unknown as ExtensionAPI);
+
+		const handler = getSessionStartHandler(pi);
+		handler({}, ctx);
+
+		expect(notify).toHaveBeenCalledTimes(1);
+		const [msg, level] = notify.mock.calls[0]!;
+		expect(level).toBe("warning");
+		expect(msg).toContain("Failed: network-timeout-guard, test-timeout-guard");
+		expect(msg).toContain("Loaded: tool-error-handler, subagent-list-injector");
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
+			enabled: ["tool-error-handler", "subagent-list-injector"],
+			disabled: ["network-timeout-guard", "test-timeout-guard"],
+		});
+	});
+
+	it("notifies 'warning' when all hooks are disabled", () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		// All hooks fail
+		(setupToolErrorHandler as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("a");
+		});
+		(setupNetworkTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("b");
+		});
+		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("c");
+		});
+		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {
+			throw new Error("d");
+		});
+
+		unifiedHooksExtension(pi as unknown as ExtensionAPI);
+
+		const handler = getSessionStartHandler(pi);
+		handler({}, ctx);
+
+		expect(notify.mock.calls[0]![1]).toBe("warning");
+		const msg = notify.mock.calls[0]![0] as string;
+		expect(msg).toContain("(none)");
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
+			enabled: [],
+			disabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard", "subagent-list-injector"],
+		});
+	});
+
+	it("does not throw when ctx.ui is undefined (headless / RPC session)", () => {
+		// [HISTORICAL] headless 会话 ctx.ui 为 undefined，旧实现直接 ctx.ui.notify 会 NPE。
+		const pi = createMockPi();
+		const ctx = { ui: undefined } as unknown as HookContext;
+
+		unifiedHooksExtension(pi as unknown as ExtensionAPI);
+
+		const handler = getSessionStartHandler(pi);
+		expect(() => handler({}, ctx)).not.toThrow();
+		// appendEntry 仍应记录（无 UI 也不丢日志）
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", expect.any(Object));
+	});
+});

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

@@ -0,0 +1,244 @@
+// src/__tests__/tool-error-handler.test.ts
+import { describe, expect, it, vi } from "vitest";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { setupToolErrorHandler, type HookContext } from "../hooks/tool-error-handler.ts";
+
+// --- helper types ---
+interface MockPi {
+	on: ReturnType<typeof vi.fn>;
+	appendEntry: ReturnType<typeof vi.fn>;
+}
+
+function createMockPi(overrides?: Partial<MockPi>): MockPi {
+	return {
+		on: vi.fn(),
+		appendEntry: vi.fn(),
+		...overrides,
+	};
+}
+
+function createMockCtx(): { ctx: HookContext; notify: ReturnType<typeof vi.fn> } {
+	const notify = vi.fn();
+	const ctx = { ui: { notify } };
+	return { ctx, notify };
+}
+
+describe("setupToolErrorHandler", () => {
+	it("registers a handler on the tool_execution_end event", () => {
+		const pi = createMockPi();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+
+		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
+	});
+
+	it("notifies via ctx.ui.notify and persists via appendEntry on isError:true", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await handler(
+			{ isError: true, toolName: "read", toolCallId: "call-42" },
+			ctx,
+		);
+
+		expect(notify).toHaveBeenCalledTimes(1);
+		expect(notify).toHaveBeenCalledWith(
+			"[unified-hooks] read error (callId=call-42)",
+			"warning",
+		);
+		expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
+			toolName: "read",
+			toolCallId: "call-42",
+			errorText: null,
+		});
+	});
+
+	it("does nothing on isError:false (no notify, no appendEntry)", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await handler(
+			{ isError: false, toolName: "bash", toolCallId: "call-99" },
+			ctx,
+		);
+
+		expect(notify).not.toHaveBeenCalled();
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+
+	it("uses the warn notification type for errors", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await handler(
+			{ isError: true, toolName: "edit", toolCallId: "c1" },
+			ctx,
+		);
+
+		// Second arg of notify is the type — must be "warning" (matches SDK literal union, not info/error).
+		expect(notify.mock.calls[0]![1]).toBe("warning");
+	});
+
+	// --- edge cases ---
+
+	it("propagates if pi.on throws during registration", () => {
+		const pi = createMockPi({
+		on: vi.fn(() => { throw new Error("registration failed"); }),
+		});
+
+		expect(() => setupToolErrorHandler(pi as unknown as ExtensionAPI)).toThrow("registration failed");
+	});
+
+	it("does not crash if handler callback throws (notify throws)", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+		notify.mockImplementation(() => { throw new Error("notify broke"); });
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await expect(
+			handler({ isError: true, toolName: "bash", toolCallId: "c2" }, ctx),
+		).rejects.toThrow("notify broke");
+
+		// appendEntry should NOT have been called since notify threw first
+		expect(pi.appendEntry).not.toHaveBeenCalled();
+	});
+
+	it("does not crash if handler callback throws (appendEntry throws)", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+		pi.appendEntry.mockImplementation(() => { throw new Error("append broke"); });
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await expect(
+			handler({ isError: true, toolName: "grep", toolCallId: "c3" }, ctx),
+		).rejects.toThrow("append broke");
+
+		// notify was called before appendEntry threw
+		expect(notify).toHaveBeenCalledTimes(1);
+	});
+
+	it("handles concurrent error events independently", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await Promise.all([
+			handler({ isError: true, toolName: "read", toolCallId: "e1" }, ctx),
+			handler({ isError: true, toolName: "bash", toolCallId: "e2" }, ctx),
+			handler({ isError: false, toolName: "edit", toolCallId: "e3" }, ctx),
+		]);
+
+		expect(notify).toHaveBeenCalledTimes(2);
+		expect(pi.appendEntry).toHaveBeenCalledTimes(2);
+
+		// verify both calls persisted independently
+		const calls = pi.appendEntry.mock.calls.map((c) => c[1]);
+		expect(calls).toEqual(
+			expect.arrayContaining([
+				{ toolName: "read", toolCallId: "e1", errorText: null },
+				{ toolName: "bash", toolCallId: "e2", errorText: null },
+			]),
+		);
+	});
+
+	it("falls back to console.warn when ctx.ui is undefined (headless session)", async () => {
+		// [HISTORICAL] headless / RPC 会话 ctx.ui 为 undefined，旧实现直接 ctx.ui.notify 会 NPE。
+		const pi = createMockPi();
+		const ctx = { ui: undefined } as unknown as HookContext;
+		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await handler({ isError: true, toolName: "bash", toolCallId: "h1" }, ctx);
+
+		expect(warnSpy).toHaveBeenCalledTimes(1);
+		expect(warnSpy.mock.calls[0]![0]).toContain("bash error");
+		// appendEntry 仍持久化
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
+			toolName: "bash",
+			toolCallId: "h1",
+			errorText: null,
+		});
+		warnSpy.mockRestore();
+	});
+
+	// --- errorText 提取（核心新增能力）---
+
+	it("从 result.content[0].text 提取错误文本并拼到 warning（如 'hub disposed'）", async () => {
+		// [HISTORICAL] subagent execute throw 时 Pi 把 error.message 塞进 result.content[0].text。
+		// 旧实现只打 "(callId=xxx)" 无详情，AI 看不到真实原因（如 hub disposed）只能盲猜。
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		await handler(
+			{
+				isError: true,
+				toolName: "subagent",
+				toolCallId: "call-disposed",
+				result: { content: [{ type: "text", text: "hub disposed" }] },
+			},
+			ctx,
+		);
+
+		expect(notify).toHaveBeenCalledWith(
+			"[unified-hooks] subagent error (callId=call-disposed): hub disposed",
+			"warning",
+		);
+		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
+			toolName: "subagent",
+			toolCallId: "call-disposed",
+			errorText: "hub disposed",
+		});
+	});
+
+	it("result 缺失或无 content 时降级到无详情（不崩）", async () => {
+		const pi = createMockPi();
+		const { ctx, notify } = createMockCtx();
+
+		setupToolErrorHandler(pi as unknown as ExtensionAPI);
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+
+		// result 为 undefined（某些 headless 路径）
+		await handler({ isError: true, toolName: "bash", toolCallId: "x1" }, ctx);
+		// result.content 为空数组
+		await handler(
+			{ isError: true, toolName: "bash", toolCallId: "x2", result: { content: [] } },
+			ctx,
+		);
+		// result 不是对象
+		await handler(
+			{ isError: true, toolName: "bash", toolCallId: "x3", result: "oops" },
+			ctx,
+		);
+
+		// 三次都降级为无详情后缀
+		expect(notify.mock.calls[0]![0]).toBe("[unified-hooks] bash error (callId=x1)");
+		expect(notify.mock.calls[1]![0]).toBe("[unified-hooks] bash error (callId=x2)");
+		expect(notify.mock.calls[2]![0]).toBe("[unified-hooks] bash error (callId=x3)");
+		pi.appendEntry.mock.calls.forEach((c) => {
+			expect(c[1]).toHaveProperty("errorText", null);
+		});
+	});
+});

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

@@ -11,20 +11,87 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
  * Subset of `ToolExecutionEndEvent` fields used by this hook.
  * Local interface because the SDK's full event type is not re-exported
  * by the CI ambient type stubs in `shared/types/mariozechner/index.d.ts`.
+ *
+ * `result` 形如 `{ content: Array<{ type: "text", text: string }>, isError: boolean }`
+ * （Pi 框架在 tool execute throw 时塞入 error content）。SDK 事件结构里没有独立
+ * errorMessage 字段——错误文本只能从 result.content 里取。
  */
 interface ToolExecutionEndLikeEvent {
   isError: boolean;
   toolName: string;
   toolCallId: string;
+  result?: unknown;
+}
+
+/** ExtensionContext 的最小子集，仅声明 unified-hooks 内部用到的 ui 字段。 */
+export interface HookContext {
+  // headless / RPC 会话 ctx.ui 可能为 undefined（TUI 未初始化）。
+  ui?: {
+    // type 必须用 SDK 字面量联合，否则非法值（如 "warn"）会被 Pi 降级为 info 静默丢失。
+    notify(msg: string, type?: "info" | "warning" | "error"): void;
+  };
+}
+
+/**
+ * 从 tool 执行结果里提取错误文本。
+ *
+ * Pi 框架在 tool execute 抛错时，构造 `{ content: [{ type: "text", text }] }`
+ * 塞进 result.content[0].text。不同 tool / 框架版本可能格式略有差异，这里防御性
+ * 取多种结构，取不到就返回 undefined（调用方降级，不阻断）。
+ */
+function extractErrorText(result: unknown): string | undefined {
+  // 常见结构：{ content: [{ type: "text", text: "..." }] }
+  const contentArr = getContentArray(result);
+  if (contentArr) {
+    for (const item of contentArr) {
+      const text = getStringProperty(item, "text");
+      if (text) return text;
+    }
+  }
+
+  // 兜底：某些工具直接塞 { error: "..." }
+  return getStringProperty(result, "error");
+}
+
+/** 若 result.content 是数组则返回它，否则 undefined。 */
+function getContentArray(result: unknown): unknown[] | undefined {
+  if (typeof result !== "object" || result === null) return undefined;
+  const content = (result as Record<string, unknown>).content;
+  return Array.isArray(content) ? content : undefined;
+}
+
+/** 类型守卫：返回 obj[key] 当它是非空 string，否则 undefined。 */
+function getStringProperty(obj: unknown, key: string): string | undefined {
+  if (typeof obj !== "object" || obj === null) return undefined;
+  const val = (obj as Record<string, unknown>)[key];
+  return typeof val === "string" && val.length > 0 ? val : undefined;
 }
 
 export function setupToolErrorHandler(pi: ExtensionAPI): void {
-  pi.on("tool_execution_end", async (event: unknown) => {
+  pi.on("tool_execution_end", async (event: unknown, ctx: HookContext) => {
     const e = event as ToolExecutionEndLikeEvent;
     if (!e.isError) return;
-    // Tool error diagnostics are internal — surfacing to the terminal
-    // would leak to the input area. ctx.ui.notify is unnecessary because
-    // tool errors are already surfaced by Pi's own error rendering.
-    console.warn(`[unified-hooks] ${e.toolName} error (callId=${e.toolCallId})`);
+
+    // 提取错误文本：tool execute throw 时 Pi 把 error.message 塞进 result.content。
+    // SDK 事件无 errorMessage 字段，只能从这里捞；拿不到也不阻断（降级到无详情）。
+    const errorText = extractErrorText(e.result);
+    const detail = errorText ? `: ${errorText}` : "";
+    const msg = `[unified-hooks] ${e.toolName} error (callId=${e.toolCallId})${detail}`;
+
+    // ctx.ui.notify 走 TUI 通知区，不越过 alternate screen 污染 input。
+    // console.warn 会写 raw stderr，在 TUI 下泄漏到 input 区。
+    // headless / RPC 会话 ctx.ui 可能为 undefined——降级到 console.warn 保证不 NPE。
+    if (ctx.ui?.notify) {
+      ctx.ui.notify(msg, "warning");
+    } else {
+      console.warn(msg);
+    }
+    // appendEntry 持久化到 session entries，供事后排查（无 UI、不泄漏）。
+    // errorText 一起存上——事后排查能看到真实原因（如 "hub disposed"）。
+    pi.appendEntry("unified-hooks:tool-error", {
+      toolName: e.toolName,
+      toolCallId: e.toolCallId,
+      errorText: errorText ?? null,
+    });
   });
 }

package/src/index.ts

@@ -8,15 +8,11 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 // Re-export hook modules for easy access
-export { setupNetworkTimeoutGuard } from "./hooks/network-timeout-guard";
-export { setupSubagentListInjector } from "./hooks/subagent-list-injector";
-export { setupTestTimeoutGuard } from "./hooks/test-timeout-guard";
-export { setupToolErrorHandler } from "./hooks/tool-error-handler";
 
 import { setupNetworkTimeoutGuard } from "./hooks/network-timeout-guard";
 import { setupSubagentListInjector } from "./hooks/subagent-list-injector";
 import { setupTestTimeoutGuard } from "./hooks/test-timeout-guard";
-import { setupToolErrorHandler } from "./hooks/tool-error-handler";
+import { type HookContext, setupToolErrorHandler } from "./hooks/tool-error-handler";
 
 /**
  * Extension factory - registers all unified hooks
@@ -44,16 +40,16 @@ export default function unifiedHooksExtension(pi: ExtensionAPI): void {
     }
   }
 
-  // Hook status is an internal diagnostic — surfacing to the terminal
-  // would leak to the input area. Use console.warn (stderr) for
-  // development debugging; production should be silent.
-  pi.on("session_start", () => {
+  // Hook status surfaced via TUI notify (走通知区，不泄漏到 input area）
+  // + appendEntry 持久化供事后排查。禁止用 console.warn（raw stderr 在 TUI
+  // alternate screen 下会越过渲染层污染 input 区）。
+  pi.on("session_start", (_event: unknown, ctx: HookContext) => {
     const enabled = hooks.filter((h) => h.enabled).map((h) => h.name);
     const disabled = hooks.filter((h) => !h.enabled).map((h) => h.name);
-    console.warn(
-      `[unified-hooks] Loaded: ${enabled.join(", ") || "(none)"}${
-        disabled.length ? ` | Failed: ${disabled.join(", ")}` : ""
-      }`
-    );
+    const msg = `[unified-hooks] Loaded: ${enabled.join(", ") || "(none)"}${
+      disabled.length ? ` | Failed: ${disabled.join(", ")}` : ""
+    }`;
+    ctx.ui?.notify(msg, disabled.length ? "warning" : "info");
+    pi.appendEntry("unified-hooks:loaded", { enabled, disabled });
   });
-}
+}