@zhushanwen/pi-session-manager 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-manager",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Pi extension for managing agent-managed sessions — create, send, read history, list, status, abort via ctx.ui.select channel.",
   "type": "module",
   "main": "index.ts",
@@ -30,11 +30,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@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-notify-ledger-host": "0.3.3",
-    "@zhushanwen/subagent-core": "1.5.1",
-    "@zhushanwen/extension-protocol": "0.20.0"
+    "@zhushanwen/pi-notify-ledger-host": "0.3.5",
+    "@zhushanwen/subagent-core": "1.5.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -43,12 +43,16 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "typebox": {
       "optional": true
     }

package/src/__tests__/tool-summary.test.ts

@@ -0,0 +1,169 @@
+// tool-summary.test.ts — details.summary 产出（六工具文案断言，走 execute 骨架）+
+// renderSessionManagerResult 两态（折叠态一行摘要 / 展开态原始 content 文本）。
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import registerExtension from "../index.ts";
+import { renderSessionManagerResult } from "../render.ts";
+
+/** Capture registered tools and provide a mock ctx.ui.select. */
+function createHarness() {
+	const registered: Array<{ name: string; execute: Function; renderResult?: Function }> = [];
+	const selectMock = vi.fn().mockResolvedValue('{"ok":true}');
+	const pi = {
+		registerTool: (tool: { name: string; execute: Function; renderResult?: Function }) => registered.push(tool),
+		on: vi.fn(),
+		getAllTools: vi.fn(() => []),
+		setActiveTools: vi.fn(),
+	};
+	const ctx = {
+		mode: "rpc" as const,
+		hasUI: true,
+		ui: { select: selectMock },
+	};
+	registerExtension(pi as never);
+	return { registered, selectMock, ctx };
+}
+
+// mock theme（fg 直通，便于断言纯文本；todo render.test.ts 同款）
+const mockTheme = {
+	fg: (_color: string, text: string) => text,
+	bg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+} as unknown as Theme;
+
+function renderedText(result: unknown, expanded: boolean): string {
+	return renderSessionManagerResult(result, { expanded }, mockTheme).render(400).join("\n");
+}
+
+describe("execute 组装 details.summary（六工具文案）", () => {
+	let harness: ReturnType<typeof createHarness>;
+
+	beforeEach(() => {
+		harness = createHarness();
+	});
+
+	async function summaryOf(toolName: string, params: Record<string, unknown>, reply: unknown): Promise<string> {
+		harness.selectMock.mockResolvedValue(JSON.stringify(reply));
+		const tool = harness.registered.find((t) => t.name === toolName)!;
+		const result = (await tool.execute("call-1", params, undefined, undefined, harness.ctx)) as {
+			details: { summary: string };
+		};
+		return result.details.summary;
+	}
+
+	it("create_managed_session：带 label → 引号 label；无 label → 回退 sessionId", async () => {
+		expect(
+			await summaryOf("create_managed_session", { cwd: "/work", label: "worker" }, { sessionId: "s1", status: "created" }),
+		).toBe('Created session "worker"');
+		expect(
+			await summaryOf("create_managed_session", { cwd: "/work" }, { sessionId: "s1", status: "created" }),
+		).toBe("Created session s1");
+	});
+
+	it("send_to_session：Sent message to <sessionId>", async () => {
+		expect(await summaryOf("send_to_session", { sessionId: "s1", prompt: "hi" }, { queued: true, willNotify: true })).toBe(
+			"Sent message to s1",
+		);
+	});
+
+	it("read_session_history：messages 计数后缀", async () => {
+		expect(
+			await summaryOf("read_session_history", { sessionId: "s1" }, { messages: [{}, {}, {}], truncated: false }),
+		).toBe("Read history of s1 · 3 entries");
+	});
+
+	it("list_my_sessions：sessions 计数", async () => {
+		expect(await summaryOf("list_my_sessions", {}, { sessions: [{ id: "s1" }, { id: "s2" }] })).toBe(
+			"Listed 2 managed sessions",
+		);
+	});
+
+	it("get_session_status：<sessionId> · <status>", async () => {
+		expect(await summaryOf("get_session_status", { sessionId: "s1" }, { status: "idle", undeliveredResults: 0 })).toBe(
+			"s1 · idle",
+		);
+	});
+
+	it("abort_session：Aborted <sessionId>", async () => {
+		expect(await summaryOf("abort_session", { sessionId: "s1" }, { success: true })).toBe("Aborted s1");
+	});
+});
+
+describe("toSummary 数据缺失分支（形状漂移退化为短文案，不抛错）", () => {
+	let harness: ReturnType<typeof createHarness>;
+
+	beforeEach(() => {
+		harness = createHarness();
+	});
+
+	async function summaryOf(toolName: string, params: Record<string, unknown>, reply: unknown): Promise<string> {
+		harness.selectMock.mockResolvedValue(JSON.stringify(reply));
+		const tool = harness.registered.find((t) => t.name === toolName)!;
+		const result = (await tool.execute("call-1", params, undefined, undefined, harness.ctx)) as {
+			details: { summary: string };
+		};
+		return result.details.summary;
+	}
+
+	it("create_managed_session：label 与 sessionId 均缺 → 裸文案", async () => {
+		expect(await summaryOf("create_managed_session", { cwd: "/work" }, {})).toBe("Created session");
+	});
+
+	it("read_session_history：messages 缺失/非数组 → 无计数后缀", async () => {
+		expect(await summaryOf("read_session_history", { sessionId: "s1" }, { truncated: false })).toBe("Read history of s1");
+	});
+
+	it("list_my_sessions：sessions 非数组 → 无计数", async () => {
+		expect(await summaryOf("list_my_sessions", {}, { sessions: "bad" })).toBe("Listed managed sessions");
+	});
+
+	it("get_session_status：status 缺失 → Status of <sessionId>", async () => {
+		expect(await summaryOf("get_session_status", { sessionId: "s1" }, {})).toBe("Status of s1");
+	});
+});
+
+describe("renderSessionManagerResult 两态", () => {
+	it("折叠态（expanded=false）：渲染 details.summary 一行摘要，不含原始 JSON", () => {
+		const result = {
+			content: [{ type: "text", text: '{"messages":[{}]}' }],
+			details: { summary: "Read history of s1 · 1 entries" },
+		};
+		const out = renderedText(result, false);
+		expect(out).toContain("Read history of s1 · 1 entries");
+		expect(out).not.toContain("messages");
+	});
+
+	it("展开态（expanded=true）：渲染 content[0] 原始文本，不含摘要", () => {
+		const result = {
+			content: [{ type: "text", text: '{"messages":[{}]}' }],
+			details: { summary: "Read history of s1 · 1 entries" },
+		};
+		const out = renderedText(result, true);
+		expect(out).toContain('{"messages":[{}]}');
+		expect(out).not.toContain("Read history of s1");
+	});
+
+	it("折叠态但 details 缺失 / summary 非字符串 → 回退 content 文本", () => {
+		expect(renderedText({ content: [{ type: "text", text: "raw" }] }, false)).toContain("raw");
+		expect(renderedText({ content: [{ type: "text", text: "raw" }], details: { summary: 7 } }, false)).toContain("raw");
+	});
+
+	it("六工具注册的 renderResult 均存在且折叠态行为一致（共用渲染内核）", () => {
+		const harness = createHarness();
+		const renderFns = harness.registered.map((t) => t.renderResult);
+		expect(renderFns).toHaveLength(6);
+		for (const fn of renderFns) expect(typeof fn).toBe("function");
+		// 抽查一个 handler：折叠态出摘要、不出原始 JSON（handler 是各 registerTool
+		// 的方法包装，内核同为 renderSessionManagerResult）
+		const out = (renderFns[0] as (r: unknown, o: { expanded: boolean }, t: unknown) => { render: (w: number) => string[] })(
+			{ content: [{ type: "text", text: "raw" }], details: { summary: "Aborted s1" } },
+			{ expanded: false },
+			mockTheme,
+		)
+			.render(400)
+			.join("\n");
+		expect(out).toContain("Aborted s1");
+		expect(out).not.toContain("raw");
+	});
+});

package/src/index.ts

@@ -7,6 +7,7 @@ import type {
 	ExtensionToolContext,
 	SessionCompactEvent,
 	SessionStartEvent,
+	Theme,
 } from "@earendil-works/pi-coding-agent";
 import {
 	SESSION_MANAGER_MARKER,
@@ -19,6 +20,7 @@ import {
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 import { Type, type Static, type TObject } from "typebox";
 
+import { renderSessionManagerResult } from "./render.ts";
 import { ensureLedgerBound, runLedgerCompactionCheck } from "./notify-ledger.ts";
 import { createWatchCoordinator } from "./watch-coordinator.ts";
 
@@ -106,6 +108,18 @@ function asResultRecord(v: unknown): Record<string, unknown> | undefined {
 			: undefined;
 }
 
+/** toSummary 的字段守卫：非空 string 才采信（缺字段 = 摘要省略对应段，不抛错——
+ * 摘要只是展示辅助，不得反过来影响工具成功路径）。 */
+function stringField(rec: Record<string, unknown> | undefined, key: string): string | undefined {
+	const v = rec?.[key];
+	return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+function arrayField(rec: Record<string, unknown> | undefined, key: string): unknown[] | undefined {
+	const v = rec?.[key];
+	return Array.isArray(v) ? v : undefined;
+}
+
 /**
  * 统一的 execute 包装：调用 select 通道并解析结果。
  * 返回标准 AgentToolResult 形状；select 取消/超时/异常/非 JSON 回包是错误路径，
@@ -122,7 +136,8 @@ async function executeTool(
 	action: SessionManagerAction,
 	params: Record<string, unknown>,
 	onResult?: (ctx: ExtensionContext, params: Record<string, unknown>, result: unknown) => void,
-): Promise<{ content: Array<{ type: "text"; text: string }>; details: undefined }> {
+	toSummary?: (params: Record<string, unknown>, result: unknown) => string,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: { summary: string } | undefined }> {
 	const result = await callSessionManager(ctx, action, params);
 	if (!result.ok) {
 		// 行为微变①（D8，有意）：非 JSON 回包从「catch 后
@@ -147,9 +162,11 @@ async function executeTool(
 	// 成功路径副作用编排（notify-once U4）：send/create 的 willNotify arm（register + 开表）、
 	// label 缓存回填（list）——错误路径已 throw，天然不触发。
 	onResult?.(ctx, params, parsed);
+	// details.summary 一行摘要（工具收起态展示）：六工具共用本骨架统一组装，
+	// 文案由各工具 cfg.toSummary 从协议 params + 回包产出（未配置 = details 缺省）。
 	return {
 		content: [{ type: "text" as const, text: raw }],
-		details: undefined,
+		details: toSummary ? { summary: toSummary(params, parsed) } : undefined,
 	};
 }
 
@@ -166,6 +183,13 @@ interface SessionToolConfig<S extends TObject> {
 	toParams: (params: Static<S>) => Record<string, unknown>
 	/** 成功结果钩子（仅非错误通道结果触发）——notify-once 的 arm/label 缓存编排 */
 	onResult?: (ctx: ExtensionContext, params: Record<string, unknown>, result: unknown) => void
+	/**
+	 * 一行收起态摘要（details.summary 的产出函数，六工具共用 executeTool 骨架统一
+	 * 组装）：输入 = 协议 params（toParams 产物）+ 成功回包；纯函数、缺数据省略
+	 * 对应段不抛错。消费方 = taiji GUI 对话流（details.summary）与本包 renderResult
+	 * 折叠态（pi TUI）。
+	 */
+	toSummary?: (params: Record<string, unknown>, result: unknown) => string
 }
 
 /**
@@ -182,6 +206,9 @@ function registerSessionTool<S extends TObject>(pi: ExtensionAPI, cfg: SessionTo
 		exposure: "deferred",
 		description: cfg.description,
 		parameters: cfg.parameters,
+		renderResult(result: unknown, options: { expanded: boolean }, theme: Theme) {
+			return renderSessionManagerResult(result, options, theme);
+		},
 		async execute(
 			_toolCallId: string,
 			params: Static<S>,
@@ -190,7 +217,7 @@ function registerSessionTool<S extends TObject>(pi: ExtensionAPI, cfg: SessionTo
 			// pi 1.0.0：ToolDefinition.execute 第 5 参 ctx 收窄为 ExtensionToolContext
 			ctx: ExtensionToolContext,
 		) {
-			return executeTool(ctx, cfg.action, cfg.toParams(params), cfg.onResult);
+			return executeTool(ctx, cfg.action, cfg.toParams(params), cfg.onResult, cfg.toSummary);
 		},
 	});
 }
@@ -250,6 +277,12 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 				coordinator.armSessionNotify(ctx, r.lifetimeNotifyId, name);
 			}
 		},
+		toSummary: (params, result) => {
+			const label = stringField(params, "label");
+			if (label) return `Created session "${label}"`;
+			const sessionId = stringField(asResultRecord(result), "sessionId");
+			return sessionId ? `Created session ${sessionId}` : "Created session";
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -268,6 +301,10 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 			if (typeof notifyId !== "string" || typeof sessionId !== "string") return;
 			coordinator.armSessionNotify(ctx, notifyId, coordinator.labelFor(sessionId));
 		},
+		toSummary: (params) => {
+			const sessionId = stringField(params, "sessionId");
+			return sessionId ? `Sent message to ${sessionId}` : "Sent message";
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -277,6 +314,13 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 		parameters: ReadSessionHistoryParams,
 		action: "history",
 		toParams: (p) => ({ sessionId: p.sessionId, tailTurns: p.tailTurns }),
+		toSummary: (params, result) => {
+			const sessionId = stringField(params, "sessionId");
+			const messages = arrayField(asResultRecord(result), "messages");
+			if (sessionId && messages) return `Read history of ${sessionId} · ${messages.length} entries`;
+			if (sessionId) return `Read history of ${sessionId}`;
+			return "Read history";
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -300,6 +344,10 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 				);
 			}
 		},
+		toSummary: (_params, result) => {
+			const sessions = arrayField(asResultRecord(result), "sessions");
+			return sessions ? `Listed ${sessions.length} managed sessions` : "Listed managed sessions";
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -309,6 +357,13 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 		parameters: GetSessionStatusParams,
 		action: "status",
 		toParams: (p) => ({ sessionId: p.sessionId }),
+		toSummary: (params, result) => {
+			const sessionId = stringField(params, "sessionId");
+			const status = stringField(asResultRecord(result), "status");
+			if (sessionId && status) return `${sessionId} · ${status}`;
+			if (sessionId) return `Status of ${sessionId}`;
+			return "Session status";
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -318,5 +373,9 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 		parameters: AbortSessionParams,
 		action: "abort",
 		toParams: (p) => ({ sessionId: p.sessionId }),
+		toSummary: (params) => {
+			const sessionId = stringField(params, "sessionId");
+			return sessionId ? `Aborted ${sessionId}` : "Aborted";
+		},
 	});
 }

package/src/render.ts

@@ -0,0 +1,22 @@
+// render.ts — session-manager 六工具共用 renderResult（pi TUI 侧；taiji GUI 对话流
+// 不走本文件——GUI 直读 details.summary）。形态对齐 todo / canvas 扩展 render 先例：
+// 折叠态一行摘要（dim 染色），展开态 / 无摘要（异常形态）回退原始 content 文本。
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { firstContentText } from "@zhushanwen/extension-protocol";
+
+/** pi toolResult 通用形状（AgentToolResult 的结构最小面，renderResult 入参收窄用）。 */
+interface ToolResultShape { // oe-exempt:20261017:framework:details 数据形状窄 view（单实现消费，非抽象接口）
+	content: Array<{ type: string; text?: string }>;
+	details?: { summary?: unknown };
+}
+
+export function renderSessionManagerResult(result: unknown, options: { expanded: boolean }, theme: Theme): Text {
+	const r = result as ToolResultShape;
+	const summary = r.details?.summary;
+	if (options.expanded === false && typeof summary === "string" && summary !== "") {
+		return new Text(theme.fg("dim", summary), 0, 0);
+	}
+	return new Text(firstContentText(r), 0, 0);
+}