@zhushanwen/pi-session-manager 0.1.16 → 0.2.1

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

@@ -0,0 +1,145 @@
+// session-start-recovery.test.ts — 重启收口腿（notify-once D7③ / U4）。
+// 断言面：活跃 type 'session' register 重开 watch（入参 = entry id 即 notifyId）/
+// 类型过滤（workflow 与已注销条目不触碰）/ 覆盖序（W1 悬置被 W2 覆盖后该 entry 恰一次
+// unregister、后续 entry 不受阻塞——每 entry 独立 handler 禁串行 await）/
+// 收口腿 label 降级源 = register 三键 name。
+// pi/ctx 装配、respondWatch、flushMicrotasks 走共享 harness（helpers/extension-harness.ts）；
+// watch-only select（非 watch action 即抛）为本文件域行为，留在本地。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	flushMicrotasks,
+	makeRespondWatch,
+	mountExtension,
+	type ExtensionHarness,
+	type WatchInvocation,
+} from "./helpers/extension-harness.ts";
+
+const LEDGER_SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.notifyLedger");
+
+interface Harness extends ExtensionHarness {
+	watches: WatchInvocation[];
+	respondWatch(index: number, value: unknown): void;
+}
+
+const E1 = "sm-aaaaaaaa-0000-4000-8000-000000000001";
+const E2 = "sm-bbbbbbbb-0000-4000-8000-000000000002";
+const E3 = "sm-cccccccc-0000-4000-8000-000000000003";
+const WF = "wf-run-1";
+
+function staleEntries(): unknown[] {
+	return [
+		{ customType: "pending:register", data: { id: E1, type: "session", name: "Alpha", registeredAt: 1, sessionId: "parent-1" } },
+		{ customType: "pending:register", data: { id: E2, type: "session", name: "Beta", registeredAt: 2, sessionId: "parent-1" } },
+		// workflow 类型归 core 对账 sweep，收口腿不得触碰
+		{ customType: "pending:register", data: { id: WF, type: "workflow", name: "run-1" } },
+		// 已注销（差集净空）→ 不重开
+		{ customType: "pending:register", data: { id: E3, type: "session", name: "Gamma", registeredAt: 3, sessionId: "parent-1" } },
+		{ customType: "pending:unregister", data: { id: E3, reason: "completed", status: "completed" } },
+	];
+}
+
+function createHarness(entries: unknown[]): Harness {
+	const watches: WatchInvocation[] = [];
+	const selectMock = vi.fn((_marker: unknown, args: unknown[], _opts?: unknown) => {
+		const payload = JSON.parse((args as string[])[0]) as {
+			action: string;
+			params: Record<string, unknown>;
+		};
+		if (payload.action !== "watch") throw new Error(`unexpected action ${payload.action}`);
+		return new Promise((resolve) => {
+			watches.push({ notifyId: String(payload.params.notifyId), resolve });
+		});
+	});
+	return {
+		...mountExtension(selectMock, entries),
+		watches,
+		respondWatch: makeRespondWatch(watches),
+	};
+}
+
+function unregistersOf(h: Harness): Array<[string, unknown]> {
+	return h.emitted
+		.filter((e) => e.event === "pending:unregister")
+		.map((e) => [String(e.data.id), e.data.reason]);
+}
+
+/** 单条 session register 的收口腿驱动（fail-closed / label 降级两用例共用前置）：
+ * 开表（session_start）→ 排干微任务 → 应答首个 watch → 再排干 */
+async function startSingleEntrySession(respondValue: unknown): Promise<Harness> {
+	const h = createHarness([
+		{ customType: "pending:register", data: { id: E1, type: "session", name: "Alpha", registeredAt: 1, sessionId: "parent-1" } },
+	]);
+	h.handlers.session_start({ type: "session_start" }, h.ctx);
+	await flushMicrotasks();
+	h.respondWatch(0, respondValue);
+	await flushMicrotasks();
+	return h;
+}
+
+beforeEach(() => {
+	vi.useFakeTimers();
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+	Reflect.deleteProperty(globalThis, LEDGER_SLOT_KEY);
+});
+
+describe("session_start 重启收口腿（D7③）", () => {
+	it("重开 watch 覆盖序：W1 悬置被 W2 覆盖后该 entry 恰一次 unregister，且后续 entry 不受阻塞", async () => {
+		const h = createHarness(staleEntries());
+		expect(h.handlers.session_start).toBeTypeOf("function");
+
+		// 第一次 session_start：E1 的 watch 永挂（模拟被后续 W2 覆盖 / runtime 只应答最新槽），
+		// E2 仍须立刻开表——串行 await 链（先等 E1 再开 E2）在此必挂死
+		h.handlers.session_start({ type: "session_start" }, h.ctx);
+		await flushMicrotasks();
+		expect(h.watches.map((w) => w.notifyId)).toEqual([E1, E2]);
+
+		// E2 先应答 orphaned（杀父腿，触发器②批量转移先行）→ 即时静默 unregister
+		h.respondWatch(1, JSON.stringify({ reason: "orphaned", sessionId: "child-b" }));
+		await flushMicrotasks();
+		expect(unregistersOf(h)).toEqual([[E2, "orphaned"]]);
+
+		// 第二次 session_start（如 /resume 再触发）：E1 的 W2 到达并获应答——
+		// W1 悬置全程未 resolve，恰一次 unregister 由「单槽只应答最新 + 写侧差集幂等」保证
+		h.handlers.session_start({ type: "session_start" }, h.ctx);
+		await flushMicrotasks();
+		expect(h.watches).toHaveLength(4);
+		expect(h.watches[2].notifyId).toBe(E1);
+		h.respondWatch(2, JSON.stringify({ reason: "cancelled" }));
+		await flushMicrotasks();
+		await vi.advanceTimersByTimeAsync(50);
+
+		// E1 恰一次、E2 恰一次（第二次的 watch 不再应答 → 不重复注销）
+		expect(unregistersOf(h).sort()).toEqual(
+			[
+				[E1, "cancelled"],
+				[E2, "orphaned"],
+			].sort(),
+		);
+		// workflow / 已注销条目全程未触碰
+		const watchedIds = h.watches.map((w) => w.notifyId);
+		expect(watchedIds).not.toContain(WF);
+		expect(watchedIds).not.toContain(E3);
+	});
+
+	it("runtime 已重启查无 claim → fail-closed 'cancelled' 腿：静默注销（活跃集回归基线）", async () => {
+		const h = await startSingleEntrySession(JSON.stringify({ reason: "cancelled" }));
+		expect(unregistersOf(h)).toEqual([[E1, "cancelled"]]);
+	});
+
+	it("收口腿 label 降级源 = register 三键 name（D9 label 两路径的恢复路径）", async () => {
+		Reflect.set(globalThis, LEDGER_SLOT_KEY, {
+			current: { record: vi.fn(() => true), compactionCheck: () => 0 },
+		});
+		const record = Reflect.get(globalThis, LEDGER_SLOT_KEY).current.record;
+		const h = await startSingleEntrySession(
+			JSON.stringify({ reason: "completed", sessionId: "child-x", settleSeq: 1, fulfillsN: 1 }),
+		);
+		await vi.advanceTimersByTimeAsync(50);
+		expect(record).toHaveBeenCalledTimes(1);
+		expect(String(record.mock.calls[0][1])).toContain('Managed session "Alpha" (child-x)');
+	});
+});

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

@@ -1,81 +1,75 @@
-// tool-error-handling.test.ts — U5-A4: null/undefined returns → cancelled result; exceptions → caught error result
+// tool-error-handling.test.ts — U5-A4: null/undefined returns → cancelled throw; exceptions → propagate;
+// {error} respond → throw（W4 throw 范式：pi agent-loop 仅在 execute throw 时置 isError:true——
+// pi-agent-core dist/agent-loop.js:453-483 executePreparedToolCall 正常 return 硬编码 isError:false；
+// 语义登记 PS-56）
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import registerExtension from "../index.ts";
-
-function createHarness(selectImpl: (...args: unknown[]) => Promise<unknown>) {
-	const registered: Array<{ name: string; execute: Function }> = [];
-	const selectMock = vi.fn(selectImpl);
-	const pi = {
-		registerTool: (tool: { name: string; execute: 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 };
-}
+import { createToolHarness, expectToolRejects, runToolForText } from "./helpers/extension-harness.ts";
 
 describe("U5-A4 tool-error-handling", () => {
-	it("select returning undefined (user cancel/timeout) → cancelled result, no throw", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue(undefined));
-		const tool = registered.find((t) => t.name === "create_managed_session")!;
-		const result = await tool.execute("call-1", { cwd: "/tmp" }, undefined, undefined, ctx);
-		expect(result.content).toHaveLength(1);
-		expect(result.content[0].text).toContain("cancelled");
+	beforeEach(() => {
+		vi.clearAllMocks();
 	});
 
-	it("select returning null → cancelled result, no throw", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue(null));
-		const tool = registered.find((t) => t.name === "send_to_session")!;
-		const result = await tool.execute("call-1", { sessionId: "s1", prompt: "hi" }, undefined, undefined, ctx);
-		expect(result.content).toHaveLength(1);
-		expect(result.content[0].text).toContain("cancelled");
+	it("select returning undefined (user cancel/timeout) → cancelled throw（W4 范式：错误路径 throw）", async () => {
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockResolvedValue(undefined)),
+			"create_managed_session",
+			{ cwd: "/tmp" },
+			/cancelled/,
+		);
 	});
 
-	it("select throwing exception → caught, returns error result, no throw", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockRejectedValue(new Error("channel closed")));
-		const tool = registered.find((t) => t.name === "get_session_status")!;
-		const result = await tool.execute("call-1", { sessionId: "s1" }, undefined, undefined, ctx);
-		expect(result.content).toHaveLength(1);
-		expect(result.content[0].text).toContain("cancelled");
+	it("select returning null → cancelled throw", async () => {
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockResolvedValue(null)),
+			"send_to_session",
+			{ sessionId: "s1", prompt: "hi" },
+			/cancelled/,
+		);
 	});
 
-	it("select throwing non-Error → caught, returns error result, no throw", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockRejectedValue("string error"));
-		const tool = registered.find((t) => t.name === "abort_session")!;
-		const result = await tool.execute("call-1", { sessionId: "s1" }, undefined, undefined, ctx);
-		expect(result.content).toHaveLength(1);
-		expect(result.content[0].text).toContain("cancelled");
+	it("select throwing exception → cancelled throw（select 通道异常同折叠）", async () => {
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockRejectedValue(new Error("channel closed"))),
+			"get_session_status",
+			{ sessionId: "s1" },
+			/cancelled/,
+		);
+	});
+
+	it("select throwing non-Error → cancelled throw", async () => {
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockRejectedValue("string error")),
+			"abort_session",
+			{ sessionId: "s1" },
+			/cancelled/,
+		);
 	});
 
-	it("runtime respond 携带 {error} JSON → isError: true（禁止错误成功模式）", async () => {
-		const { registered, ctx } = createHarness(
-			vi.fn().mockResolvedValue(JSON.stringify({ error: "session unreachable", hint: "check get_session_status" })),
+	it("runtime respond 携带 {error} JSON → throw（禁止错误成功模式；pi 置 isError:true）", async () => {
+		await expectToolRejects(
+			createToolHarness(
+				vi.fn().mockResolvedValue(JSON.stringify({ error: "session unreachable", hint: "check get_session_status" })),
+			),
+			"send_to_session",
+			{ sessionId: "s1", prompt: "hi" },
+			/session unreachable[\s\S]*hint/,
 		);
-		const tool = registered.find((t) => t.name === "send_to_session")!;
-		const result = await tool.execute("call-1", { sessionId: "s1", prompt: "hi" }, undefined, undefined, ctx);
-		expect(result.isError).toBe(true);
-		expect(result.content[0].text).toContain("session unreachable");
-		expect(result.content[0].text).toContain("hint");
 	});
 
-	it("runtime respond 正常 JSON → 无 isError", async () => {
-		const { registered, ctx } = createHarness(
-			vi.fn().mockResolvedValue(JSON.stringify({ queued: true })),
+	it("runtime respond 正常 JSON → 成功返回（不含 isError 字段）", async () => {
+		const result = await runToolForText(
+			createToolHarness(vi.fn().mockResolvedValue(JSON.stringify({ queued: true }))),
+			"send_to_session",
+			{ sessionId: "s1", prompt: "hi" },
 		);
-		const tool = registered.find((t) => t.name === "send_to_session")!;
-		const result = await tool.execute("call-1", { sessionId: "s1", prompt: "hi" }, undefined, undefined, ctx);
-		expect(result.isError).toBeUndefined();
+		expect(Object.hasOwn(result, "isError")).toBe(false);
+		expect(JSON.parse(result.content[0].text)).toEqual({ queued: true });
 	});
 
-	it("all 6 tools handle null gracefully", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue(null));
+	it("all 6 tools handle null gracefully（cancelled throw）", async () => {
+		const { registered, ctx } = createToolHarness(vi.fn().mockResolvedValue(null));
 		for (const tool of registered) {
 			const params = tool.name === "create_managed_session"
 				? { cwd: "/tmp" }
@@ -86,9 +80,9 @@ describe("U5-A4 tool-error-handling", () => {
 						: tool.name === "list_my_sessions"
 							? {}
 							: { sessionId: "s1" };
-			const result = await tool.execute("call-1", params, undefined, undefined, ctx);
-			expect(result.content).toHaveLength(1);
-			expect(result.content[0].text).toContain("cancelled");
+			await expect(tool.execute("call-1", params, undefined, undefined, ctx)).rejects.toThrow(
+				/cancelled/,
+			);
 		}
 	});
 });

package/src/__tests__/tool-non-json-response.test.ts

@@ -1,64 +1,46 @@
-// tool-non-json-response.test.ts — 行为微变①（D8）：非 JSON 回包 → isError + 留痕
+// tool-non-json-response.test.ts — 行为微变①（D8）：非 JSON 回包 → throw + 留痕
 //
 // [HISTORICAL] 改前行为（D8 前）：executeTool 对回包 try JSON.parse、catch 后
 // parsed=undefined，非 JSON 字符串静默当成功文本返回（content[0].text = raw、无
 // isError）——runtime 协议漂移对 agent 不可辨。D8
-// （docs/architecture/ext-simplify-17-shared-extraction.md §3.3，有意微变）统一为
+//（docs/architecture/ext-simplify-17-shared-extraction.md §3.3，有意微变）统一为
 // 对齐 plugin-bridge 形态：logger.error 留痕（callMarkerRpc 原语经注入的 log 承担）
-// + isError:true + 提示文本。
+// + 错误路径 throw（W4 范式：pi agent-loop 仅在 execute throw 时置 isError:true——
+// pi-agent-core dist/agent-loop.js:453-483，语义登记 PS-56）。
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
+// logger mock helper 必须先于 extension-harness（其 import 链触发被 mock 模块加载）
+import { createLoggerModuleMock, getLoggerMock } from "./helpers/logger-mock.ts";
+import { createToolHarness, expectToolRejects, runToolForText } from "./helpers/extension-harness.ts";
 
-const loggerMock = vi.hoisted(() => ({
-	error: vi.fn(),
-	warn: vi.fn(),
-	debug: vi.fn(),
-}));
-vi.mock("@zhushanwen/pi-extension-logger", () => ({
-	getLogger: () => loggerMock,
-	setPiHandle: vi.fn(),
-}));
+vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
 
-import registerExtension from "../index.ts";
+const loggerMock = getLoggerMock();
 
-function createHarness(selectImpl: (...args: unknown[]) => Promise<unknown>) {
-	const registered: Array<{ name: string; execute: Function }> = [];
-	const selectMock = vi.fn(selectImpl);
-	const pi = {
-		registerTool: (tool: { name: string; execute: 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 };
-}
-
-describe("D8 行为微变①：非 JSON 回包 → isError + 留痕", () => {
+describe("D8 行为微变①：非 JSON 回包 → throw + 留痕", () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
 	});
 
-	it("非 JSON 回包 → isError:true + 提示文本（不再静默当成功文本返回）", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue("plain text response"));
-		const tool = registered.find((t) => t.name === "send_to_session")!;
-		const result = await tool.execute("call-1", { sessionId: "s1", prompt: "hi" }, undefined, undefined, ctx);
-		expect(result.isError).toBe(true);
-		expect(result.content).toHaveLength(1);
-		expect(result.content[0].text).toContain("non-JSON");
-		// 改前对照：text 曾是 raw 本身（'plain text response'），无 isError
-		expect(result.content[0].text).not.toBe("plain text response");
+	it("非 JSON 回包 → throw 提示文本（不再静默当成功文本返回；pi 侧置 isError:true）", async () => {
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockResolvedValue("plain text response")),
+			"send_to_session",
+			{ sessionId: "s1", prompt: "hi" },
+			/non-JSON/,
+			"call-1",
+		);
+		// 改前对照：text 曾是 raw 本身（'plain text response'）静默当成功
 	});
 
 	it("留痕：logger.error 收到 non-JSON 消息 + responseHead（原语经注入 log 承担）", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue("plain text response"));
-		const tool = registered.find((t) => t.name === "list_my_sessions")!;
-		await tool.execute("call-2", {}, undefined, undefined, ctx);
+		await expectToolRejects(
+			createToolHarness(vi.fn().mockResolvedValue("plain text response")),
+			"list_my_sessions",
+			{},
+			/non-JSON/,
+			"call-2",
+		);
 		expect(loggerMock.error).toHaveBeenCalled();
 		const [msg, detail] = loggerMock.error.mock.calls.at(-1)!;
 		expect(msg).toContain("[session-manager]");
@@ -66,11 +48,14 @@ describe("D8 行为微变①：非 JSON 回包 → isError + 留痕", () => {
 		expect(detail).toMatchObject({ responseHead: "plain text response" });
 	});
 
-	it("对照：合法 JSON 回包仍走成功路径（raw 透传、无 isError、无留痕）", async () => {
-		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue('{"queued":true}'));
-		const tool = registered.find((t) => t.name === "send_to_session")!;
-		const result = await tool.execute("call-3", { sessionId: "s1", prompt: "hi" }, undefined, undefined, ctx);
-		expect(result.isError).toBeUndefined();
+	it("对照：合法 JSON 回包仍走成功路径（raw 透传、无 isError 字段、无留痕）", async () => {
+		const result = await runToolForText(
+			createToolHarness(vi.fn().mockResolvedValue('{"queued":true}')),
+			"send_to_session",
+			{ sessionId: "s1", prompt: "hi" },
+			"call-3",
+		);
+		expect(Object.hasOwn(result, "isError")).toBe(false);
 		expect(result.content[0].text).toBe('{"queued":true}');
 		expect(loggerMock.error).not.toHaveBeenCalled();
 	});