@zhushanwen/pi-base-tool-enhance 0.8.3 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design decisions documented in source comments)",
   "type": "module",
   "main": "src/index.ts",
@@ -28,11 +28,11 @@
     "skills/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.20.0",
-    "@zhushanwen/pi-ext-guards": "0.4.4",
+    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/pi-file-lock": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.11.2"
+    "@zhushanwen/pi-llm-shared": "0.11.3"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -40,10 +40,14 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-pending-notifications": "0.8.5"
+    "@zhushanwen/pi-pending-notifications": "0.9.0"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "@zhushanwen/pi-pending-notifications": {
       "optional": true
     }

package/src/__tests__/render-result.test.ts

@@ -0,0 +1,176 @@
+// bash_output / bash_kill 收起态摘要测试：summary 纯函数文案 + details 形态 +
+// renderResult 折叠/展开。summary 从自产 JSON 文本防御性取数。
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+	buildBashKillSummary,
+	buildBashOutputSummary,
+	renderBashToolResult,
+} from "../render-result";
+import { createBashKillToolDefinition } from "../bash-kill-tool";
+import { createBashOutputToolDefinition } from "../bash-output-tool";
+import { clearTaskStoreForTest, registerSpawnedTask } from "../background/task-store";
+import type { BackgroundTask } from "../background/types";
+
+function resultOf(text: string): { content: Array<{ type: string; text?: string }>; details?: unknown } {
+	return { content: [{ type: "text", text }] };
+}
+
+// ── buildBashOutputSummary ───────────────────────────
+
+describe("buildBashOutputSummary", () => {
+	it("指定 task_id → Output of task <id> · N lines", () => {
+		const text = JSON.stringify({ task_id: "t1", state: "exited", output: "line1\nline2\nline3", truncated: false });
+		expect(buildBashOutputSummary({ task_id: "t1" }, resultOf(text))).toBe("Output of task t1 · 3 lines");
+	});
+
+	it("output 丢失（<lost>）→ 省略行数后缀", () => {
+		const text = JSON.stringify({ task_id: "t1", state: "running", output: "<lost>" });
+		expect(buildBashOutputSummary({ task_id: "t1" }, resultOf(text))).toBe("Output of task t1");
+	});
+
+	it("output 空串 → 省略行数后缀", () => {
+		const text = JSON.stringify({ task_id: "t1", state: "running", output: "" });
+		expect(buildBashOutputSummary({ task_id: "t1" }, resultOf(text))).toBe("Output of task t1");
+	});
+
+	it("省略 task_id（列表视图）→ N background tasks / No background tasks", () => {
+		const text = JSON.stringify({ tasks: [{ task_id: "a" }, { task_id: "b" }] });
+		expect(buildBashOutputSummary({}, resultOf(text))).toBe("2 background tasks");
+		const empty = JSON.stringify({ tasks: [] });
+		expect(buildBashOutputSummary({}, resultOf(empty))).toBe("No background tasks");
+	});
+
+	it("content 非 JSON（防御）→ 兜底 Done", () => {
+		expect(buildBashOutputSummary({ task_id: "t1" }, resultOf("not json"))).toBe("Done");
+	});
+});
+
+// ── buildBashKillSummary ─────────────────────────────
+
+describe("buildBashKillSummary", () => {
+	it("killed=true → Killed task <id>", () => {
+		const text = JSON.stringify({ killed: true, reason: "kill signal sent; poll bash_output for the final state" });
+		expect(buildBashKillSummary({ task_id: "t1" }, resultOf(text))).toBe("Killed task t1");
+	});
+
+	it("killed=false → Kill failed: <reason>", () => {
+		const text = JSON.stringify({ killed: false, reason: "no such task", hint: "use bash_output to list" });
+		expect(buildBashKillSummary({ task_id: "t1" }, resultOf(text))).toBe("Kill failed: no such task");
+	});
+
+	it("reason 超长截 80 加省略号", () => {
+		const text = JSON.stringify({ killed: false, reason: "x".repeat(100) });
+		expect(buildBashKillSummary({ task_id: "t1" }, resultOf(text))).toBe(`Kill failed: ${"x".repeat(80)}…`);
+	});
+
+	it("content 非 JSON（防御）→ 兜底 Done", () => {
+		expect(buildBashKillSummary({ task_id: "t1" }, resultOf(""))).toBe("Done");
+	});
+});
+
+// ── details 形态（definition.execute 层）────────────
+
+function makeTask(taskId: string, outputFile: string): BackgroundTask {
+	return {
+		taskId,
+		pid: 1,
+		command: "echo hi",
+		outputFile,
+		registryPath: "/tmp/registry.json",
+		startedAt: 0,
+		state: "running",
+		ownerPiPid: 1,
+		sessionId: "s",
+	} as BackgroundTask;
+}
+
+describe("bash tools details.summary wiring", () => {
+	afterEach(() => {
+		clearTaskStoreForTest();
+	});
+
+	it("bash_output 列表视图 details = { summary }", async () => {
+		const def = createBashOutputToolDefinition() as {
+			execute: (id: string, args: { task_id?: string }, s: undefined, u: unknown, ctx: { sessionManager: { getSessionId: () => string } }) => Promise<{ details: unknown }>;
+		};
+		const res = await def.execute("id", {}, undefined, undefined, { sessionManager: { getSessionId: () => "s" } });
+		expect(res.details).toMatchObject({ summary: "No background tasks" });
+	});
+
+	it("bash_output 详情视图 → summary 带行数（单例表注册任务）", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "bte-output-"));
+		try {
+			const outputFile = join(dir, "out.log");
+			writeFileSync(outputFile, "line1\nline2\nline3", "utf8");
+			registerSpawnedTask(makeTask("t-detail", outputFile));
+			const def = createBashOutputToolDefinition() as {
+				execute: (id: string, args: { task_id?: string }, s: undefined, u: unknown, ctx: { sessionManager: { getSessionId: () => string } }) => Promise<{ details: unknown }>;
+			};
+			const res = await def.execute("id", { task_id: "t-detail" }, undefined, undefined, {
+				sessionManager: { getSessionId: () => "s" },
+			});
+			expect(res.details).toMatchObject({ summary: "Output of task t-detail · 3 lines" });
+		} finally {
+			rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+		}
+	});
+
+	it("bash_kill definition 挂 renderResult", () => {
+		const def = createBashKillToolDefinition() as { renderResult?: unknown };
+		expect(typeof def.renderResult).toBe("function");
+	});
+
+	it("bash_output definition 挂 renderResult", () => {
+		const def = createBashOutputToolDefinition() as { renderResult?: unknown };
+		expect(typeof def.renderResult).toBe("function");
+	});
+});
+
+// ── renderBashToolResult（TUI renderResult）──────────
+
+const mockTheme = {
+	fg: (_color: string, text: string) => text,
+	bg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+	italic: (text: string) => text,
+	underline: (text: string) => text,
+	inverse: (text: string) => text,
+	strikethrough: (text: string) => text,
+	getFgAnsi: (_color: string) => "",
+	getBgAnsi: (_color: string) => "",
+	getColorMode: () => "truecolor" as const,
+	getThinkingBorderColor: () => (text: string) => text,
+	getBashModeBorderColor: () => (text: string) => text,
+} as unknown as Theme;
+
+function renderedText(result: unknown, expanded: boolean): string {
+	return renderBashToolResult(result, { expanded }, mockTheme)
+		.render(400)
+		.map((line) => line.trimEnd())
+		.join("\n");
+}
+
+describe("renderBashToolResult", () => {
+	it("折叠态 → details.summary 一行", () => {
+		const r = { content: [{ type: "text", text: '{"killed":true}' }], details: { summary: "Killed task t1" } };
+		expect(renderedText(r, false)).toBe("Killed task t1");
+	});
+
+	it("展开态 → content 纯文本（JSON 原文）", () => {
+		const json = JSON.stringify({ killed: true }, null, 2);
+		const r = { content: [{ type: "text", text: json }], details: { summary: "Killed task t1" } };
+		expect(renderedText(r, true)).toBe(json);
+	});
+
+	it("无 summary（旧 entry）→ 折叠态回退 content 首行", () => {
+		const r = { content: [{ type: "text", text: '{"killed":true}' }], details: undefined };
+		expect(renderedText(r, false)).toBe('{"killed":true}');
+	});
+});

package/src/bash-kill-tool.ts

@@ -16,7 +16,7 @@
  * 宁不杀勿误杀，§3.6 收殓侧同原则）。
  */
 
-import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
@@ -27,6 +27,7 @@ import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { getRegistryPath, readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./background/registry.ts";
 import { getAllTasks, markKillingIntent } from "./background/task-store.ts";
 import { isActiveState, isTerminalState, type RegistryEntry } from "./background/types.ts";
+import { buildBashKillSummary, renderBashToolResult } from "./render-result.ts";
 
 const bashKillSchema = Type.Object({
 	task_id: Type.String({ description: "Task id returned by the background bash tool." }),
@@ -42,12 +43,17 @@ const JSON_INDENT = 2;
 
 const logger = getLogger("base-tool-enhance");
 
-function textResult(text: string): AgentToolResult<unknown> {
-	return { content: [{ type: "text", text }], details: undefined };
+/** 文本 + 收起态摘要（原 details 为 undefined → 统一 { summary }）。 */
+function textResultWithSummary(text: string, summary: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details: { summary } };
 }
 
-function killedFalse(reason: string, hint?: string): AgentToolResult<unknown> {
-	return textResult(JSON.stringify({ killed: false, reason, ...(hint !== undefined ? { hint } : {}) }, null, JSON_INDENT));
+function killedFalse(taskId: string, reason: string, hint?: string): AgentToolResult<unknown> {
+	const text = JSON.stringify({ killed: false, reason, ...(hint !== undefined ? { hint } : {}) }, null, JSON_INDENT);
+	return textResultWithSummary(
+		text,
+		buildBashKillSummary({ task_id: taskId }, { content: [{ type: "text", text }] }),
+	);
 }
 
 export function createBashKillToolDefinition() {
@@ -74,10 +80,11 @@ export function createBashKillToolDefinition() {
 					args.task_id,
 				);
 				if (entry === undefined) {
-					return killedFalse("no such task", "use bash_output to list");
+					return killedFalse(args.task_id, "no such task", "use bash_output to list");
 				}
 				if (isTerminalState(entry.state)) {
 					return killedFalse(
+						args.task_id,
 						`already exited${entry.exitCode !== undefined && entry.exitCode !== null ? ` (code ${entry.exitCode})` : ""}`,
 					);
 				}
@@ -87,6 +94,7 @@ export function createBashKillToolDefinition() {
 				// 纯 CLI 独立安装无 runtime 收殓兜底，孤儿自然退出或手动杀——E11 已
 				// 接受边界，hint 按形态分流，不写死 runtime 承诺）
 				return killedFalse(
+					args.task_id,
 					"cross-process running task owned by another pi process",
 					"the task is managed by the pi process that started it (bash_kill from that session); " +
 						"if that process is gone, the orphan keeps running until it exits on its own; " +
@@ -96,6 +104,7 @@ export function createBashKillToolDefinition() {
 			}
 			if (isTerminalState(fromStore.state)) {
 				return killedFalse(
+					args.task_id,
 					`already exited${fromStore.exitCode !== undefined && fromStore.exitCode !== null ? ` (code ${fromStore.exitCode})` : ""}`,
 				);
 			}
@@ -107,12 +116,13 @@ export function createBashKillToolDefinition() {
 			//  - 无字段（spawn 时 ps 不可用平台）→ 放行：登记原进程在 spawn 时刻存活，
 			//    复用窗口毫秒级；registry 终态条目不会走到这里（上面 already exited）
 			if (!isPidAlive(fromStore.pid)) {
-				return killedFalse("already exited (process no longer alive; final state will be written on task exit)");
+				return killedFalse(args.task_id, "already exited (process no longer alive; final state will be written on task exit)");
 			}
 			if (fromStore.pidStartTime !== undefined) {
 				const actualStartSec = getProcessStartTimeSec(fromStore.pid);
 				if (actualStartSec === undefined) {
 					return killedFalse(
+						args.task_id,
 						"cannot verify process start time; refusing to kill (better safe than sorry)",
 						`pid ${fromStore.pid} is alive but its start time is unreadable, so pid reuse cannot be ruled out; ` +
 							"poll bash_output for the final state, or kill the process group manually if certain",
@@ -120,6 +130,7 @@ export function createBashKillToolDefinition() {
 				}
 				if (actualStartSec !== fromStore.pidStartTime) {
 					return killedFalse(
+						args.task_id,
 						`pid reuse suspected: recorded start time ${fromStore.pidStartTime} but actual ${actualStartSec}; refusing to kill`,
 						`pid ${fromStore.pid} likely belongs to an unrelated recycled process now; ` +
 							"if you are certain, kill the process group manually (kill -- -<pgid>)",
@@ -143,18 +154,25 @@ export function createBashKillToolDefinition() {
 				}),
 			);
 			// 终态由 exit 事件边沿收尾（exit-collector，事件驱动；无轮询器）
-			return textResult(
-				JSON.stringify(
-					{
-						killed: true,
-						reason: isActiveState(fromStore.state)
-							? "kill signal sent; poll bash_output for the final state"
-							: "kill signal re-sent; poll bash_output for the final state",
-					},
-					null,
-					JSON_INDENT,
-				),
+			const text = JSON.stringify(
+				{
+					killed: true,
+					reason: isActiveState(fromStore.state)
+						? "kill signal sent; poll bash_output for the final state"
+						: "kill signal re-sent; poll bash_output for the final state",
+				},
+				null,
+				JSON_INDENT,
+			);
+			// 收起态一行摘要：details 由 undefined 改为 { summary }，GUI 收起态与 TUI 折叠态共用
+			return textResultWithSummary(
+				text,
+				buildBashKillSummary(args, { content: [{ type: "text", text }] }),
 			);
 		},
+
+		renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+			return renderBashToolResult(result, options, theme);
+		},
 	};
 }

package/src/bash-output-tool.ts

@@ -12,7 +12,7 @@
  * 前发起的）；registry 侧只读当前 sessionId 目录。他进程任务查不到（回发起 session）。
  */
 
-import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { readOutputTail } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
@@ -22,6 +22,7 @@ import { TAIL_MAX_BYTES, TAIL_MAX_LINES } from "./background/output-tail.ts";
 import { getRegistryPath, readRegistry } from "./background/registry.ts";
 import { getAllTasks } from "./background/task-store.ts";
 import { isTerminalState, type BackgroundTask, type RegistryEntry } from "./background/types.ts";
+import { buildBashOutputSummary, renderBashToolResult } from "./render-result.ts";
 
 const bashOutputSchema = Type.Object({
 	task_id: Type.Optional(Type.String({ description: "Task id returned by the background bash tool. Omit to list all background tasks." })),
@@ -52,8 +53,9 @@ function toListRow(source: BackgroundTask | RegistryEntry) {
 	};
 }
 
-function textResult(text: string): AgentToolResult<unknown> {
-	return { content: [{ type: "text", text }], details: undefined };
+/** 文本 + 收起态摘要（原 details 为 undefined → 统一 { summary }）。 */
+function textResultWithSummary(text: string, summary: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details: { summary } };
 }
 
 /**
@@ -128,7 +130,11 @@ export function createBashOutputToolDefinition() {
 			const sessionId = ctx.sessionManager.getSessionId();
 			const registry = readRegistry(getRegistryPath(getAgentDir(), sessionId));
 
-			if (args.task_id === undefined) return textResult(listTasksText(registry));
+			if (args.task_id === undefined) {
+				const text = listTasksText(registry);
+				// 收起态一行摘要：details 由 undefined 改为 { summary }，GUI 收起态与 TUI 折叠态共用
+				return textResultWithSummary(text, buildBashOutputSummary(args, { content: [{ type: "text", text }] }));
+			}
 
 			const task = findTask(args.task_id, registry);
 			if (task === undefined) {
@@ -136,7 +142,12 @@ export function createBashOutputToolDefinition() {
 					`No such task: ${args.task_id}. Use bash_output without task_id to list known background tasks.`,
 				);
 			}
-			return textResult(taskDetailText(task));
+			const text = taskDetailText(task);
+			return textResultWithSummary(text, buildBashOutputSummary(args, { content: [{ type: "text", text }] }));
+		},
+
+		renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+			return renderBashToolResult(result, options, theme);
 		},
 	};
 }

package/src/render-result.ts

@@ -0,0 +1,106 @@
+/**
+ * bash_output / bash_kill 的收起态一行摘要 + TUI renderResult。
+ *
+ * summary 来源：两个工具的成功/失败产出都是自产 JSON 文本（content[0].text），
+ * summary 纯函数对它做防御性 JSON.parse 取数（自家 stringify 产物，解析失败走兜底）。
+ * 原 details 为 undefined → 统一改为 { summary }。
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { firstContentText } from "@zhushanwen/extension-protocol";
+
+// ── summary 纯函数 ───────────────────────────────────
+
+interface ToolResultLike { // oe-exempt:20261017:framework:details 数据形状窄 view（单实现消费，非抽象接口）
+	content: Array<{ type: string; text?: string }>;
+	details?: unknown;
+}
+
+/** 自产 JSON 文本的安全解析（解析失败/非对象 → undefined）。 */
+function parseOwnJson(result: ToolResultLike): Record<string, unknown> | undefined {
+	const text = firstContentText(result);
+	if (text === "") return undefined;
+	try {
+		const parsed: unknown = JSON.parse(text);
+		return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** 文本行数（去末尾换行后按 \n 切分；空文本 = 0 行）。 */
+function countLines(text: string): number {
+	if (text === "") return 0;
+	return text.replace(/\n$/, "").split("\n").length;
+}
+
+/** bash_output 摘要：详情 → `Output of task <id> · N lines`；列表 → `N background tasks`。 */
+export function buildBashOutputSummary(
+	args: { task_id?: string },
+	result: ToolResultLike,
+): string {
+	const parsed = parseOwnJson(result);
+	if (parsed === undefined) return "Done";
+	if (args.task_id === undefined) {
+		const tasks = Array.isArray(parsed.tasks) ? parsed.tasks.length : 0;
+		return tasks === 0 ? "No background tasks" : `${tasks} background tasks`;
+	}
+	if (parsed.output === "<lost>") return `Output of task ${args.task_id}`;
+	const lines = countLines(typeof parsed.output === "string" ? parsed.output : "");
+	return lines === 0 ? `Output of task ${args.task_id}` : `Output of task ${args.task_id} · ${lines} lines`;
+}
+
+/** 收起态摘要中失败 reason 的保留长度（超长截断加省略号）。 */
+const KILL_REASON_SUMMARY_CHARS = 80;
+
+/** bash_kill 摘要：killed=true → `Killed task <id>`；killed=false（正常返回的失败形态）
+ *  → `Kill failed: <reason>`。 */
+export function buildBashKillSummary(args: { task_id: string }, result: ToolResultLike): string {
+	const parsed = parseOwnJson(result);
+	if (parsed === undefined) return "Done";
+	if (parsed.killed === true) return `Killed task ${args.task_id}`;
+	const reason = typeof parsed.reason === "string" ? parsed.reason : "unknown";
+	const clipped = reason.length > KILL_REASON_SUMMARY_CHARS
+		? `${reason.slice(0, KILL_REASON_SUMMARY_CHARS)}…`
+		: reason;
+	return `Kill failed: ${clipped}`;
+}
+
+// ── TUI renderResult ─────────────────────────────────
+
+/** unknown 值按字段名安全取值（index-signature 收窄，替代全可选结构断言）。 */
+function fieldValue(v: unknown, key: string): unknown {
+	if (typeof v !== "object" || v === null) return undefined;
+	return (v as Record<string, unknown>)[key];
+}
+
+/** 从 details 安全读取 summary（容错非对象形态与旧版本 entry）。 */
+function readDetailsSummary(result: unknown): string | undefined {
+	const summary = fieldValue(fieldValue(result, "details"), "summary");
+	return typeof summary === "string" && summary !== "" ? summary : undefined;
+}
+
+/** content[0] 的 text 纯文本（content 缺失或非 text 类型时兜底空串）。 */
+function contentText(result: unknown): string {
+	const content = fieldValue(result, "content");
+	if (!Array.isArray(content)) return "";
+	return firstContentText({ content });
+}
+
+/** 折叠态回退：JSON 文本取首行（保持一行摘要形态）。 */
+function firstLine(text: string): string {
+	const idx = text.indexOf("\n");
+	return idx === -1 ? text : text.slice(0, idx);
+}
+
+/** 折叠态（expanded=false）= details.summary 一行（dim）；展开态 = content 纯文本。 */
+export function renderBashToolResult(
+	result: unknown,
+	options: { expanded: boolean },
+	theme: Theme,
+): Text {
+	if (options.expanded) return new Text(contentText(result), 0, 0);
+	const summary = readDetailsSummary(result) ?? firstLine(contentText(result));
+	return new Text(theme.fg("dim", summary), 0, 0);
+}