@zhushanwen/pi-unified-hooks 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
   "main": "index.ts",
   "type": "module",

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

@@ -55,6 +55,7 @@ describe("setupToolErrorHandler", () => {
 		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
 			toolName: "read",
 			toolCallId: "call-42",
+			errorText: null,
 		});
 	});
 
@@ -152,8 +153,8 @@ describe("setupToolErrorHandler", () => {
 		const calls = pi.appendEntry.mock.calls.map((c) => c[1]);
 		expect(calls).toEqual(
 			expect.arrayContaining([
-				{ toolName: "read", toolCallId: "e1" },
-				{ toolName: "bash", toolCallId: "e2" },
+				{ toolName: "read", toolCallId: "e1", errorText: null },
+				{ toolName: "bash", toolCallId: "e2", errorText: null },
 			]),
 		);
 	});
@@ -175,7 +176,69 @@ describe("setupToolErrorHandler", () => {
 		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,11 +11,16 @@ 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 字段。 */
@@ -27,11 +32,52 @@ export interface HookContext {
   };
 }
 
+/**
+ * 从 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, ctx: HookContext) => {
     const e = event as ToolExecutionEndLikeEvent;
     if (!e.isError) return;
-    const msg = `[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。
@@ -41,9 +87,11 @@ export function setupToolErrorHandler(pi: ExtensionAPI): void {
       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,
     });
   });
 }