@zhushanwen/pi-session-manager 0.1.1

package/README.md

@@ -0,0 +1,30 @@
+# @zhushanwen/pi-session-manager
+
+agent-managed session pi extension：把 session 的创建/发送/读取/列表/状态/中止交给 agent 自主管理——agent 通过 6 个工具以子 session 形态并行工作，父 session 统一编排。
+
+## 通道契约
+
+- 工具调用经 `ctx.ui.select(SESSION_MANAGER_MARKER, [JSON], {timeout: 30s})` 发出；marker 为 `\x00XYZ_SESSION_MANAGER`（NUL 前缀防与普通 select title 冲突，SSOT 在 `@xyz-agent/extension-protocol`）
+- 请求体为嵌套形状 `{ action, params }`（`SessionManagerRequest` 协议类型）；**不要扁平化展开**——runtime event-adapter 按 `data.params` 提取，扁平化会导致 params 丢失
+- 应答方是 xyz-agent runtime 的 `SessionManagerHandler`（select value 通道回写 JSON 字符串；取消/超时返回 null）
+
+## 工具（6 个 action）
+
+| 工具 | action | 说明 |
+|------|--------|------|
+| `create_managed_session` | create | 在指定 cwd 创建子 session（可选 label）；服务端注入 `spawnSource: 'agent'` 与父 session id，`.agent.json` sidecar 落盘供重启恢复 |
+| `send_to_session` | send | 向子 session 发送 prompt（异步处理） |
+| `read_session_history` | history | 读子 session 对话历史（可选 tailTurns 截尾部 N 个 turn） |
+| `list_my_sessions` | list | 列出本 agent 管理的 session（可按 spawnSource / parentAgentSessionId 过滤） |
+| `get_session_status` | status | 查询子 session 状态与模型信息 |
+| `abort_session` | abort | 中止运行中的子 session |
+
+## 运行要求
+
+应答端（runtime handler）在 xyz-agent 桌面应用内；独立 pi CLI 环境无 handler 时工具将等待至 30s 超时并返回 cancelled。
+
+## 测试
+
+```bash
+cd extensions/universal/session-manager && npx vitest run
+```

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhushanwen/pi-session-manager",
+  "version": "0.1.1",
+  "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",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "xyz-agent": {
+    "role": "universal"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "session-manager"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "0.6.0",
+    "@zhushanwen/pi-extension-logger": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

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

@@ -0,0 +1,99 @@
+// tool-error-handling.test.ts — U5-A4: null/undefined returns → cancelled result; exceptions → caught error result
+
+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 };
+}
+
+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");
+	});
+
+	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 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 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("runtime respond 携带 {error} JSON → isError: true（禁止错误成功模式）", async () => {
+		const { registered, ctx } = createHarness(
+			vi.fn().mockResolvedValue(JSON.stringify({ error: "session unreachable", hint: "check get_session_status" })),
+		);
+		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");
+		expect(result.details).toEqual({
+			kind: "error",
+			error: { error: "session unreachable", hint: "check get_session_status" },
+		});
+	});
+
+	it("runtime respond 正常 JSON → 无 isError，details kind=ok", async () => {
+		const { registered, ctx } = createHarness(
+			vi.fn().mockResolvedValue(JSON.stringify({ queued: true })),
+		);
+		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(result.details).toEqual({ kind: "ok", result: { queued: true } });
+	});
+
+	it("all 6 tools handle null gracefully", async () => {
+		const { registered, ctx } = createHarness(vi.fn().mockResolvedValue(null));
+		for (const tool of registered) {
+			const params = tool.name === "create_managed_session"
+				? { cwd: "/tmp" }
+				: tool.name === "send_to_session"
+					? { sessionId: "s1", prompt: "hi" }
+					: tool.name === "read_session_history"
+						? { sessionId: "s1" }
+						: 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");
+		}
+	});
+});

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

@@ -0,0 +1,102 @@
+// tool-execute.test.ts — U5-A2: each tool's execute calls ctx.ui.select with SESSION_MANAGER_MARKER + JSON payload
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { SESSION_MANAGER_MARKER } from "@xyz-agent/extension-protocol";
+import registerExtension from "../index.ts";
+
+/** Capture registered tools and provide a mock ctx.ui.select. */
+function createHarness() {
+	const registered: Array<{ name: string; execute: Function }> = [];
+	const selectMock = vi.fn().mockResolvedValue('{"ok":true}');
+	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("U5-A2 tool-execute", () => {
+	let harness: ReturnType<typeof createHarness>;
+
+	beforeEach(() => {
+		harness = createHarness();
+	});
+
+	it.each([
+		["create_managed_session", "create", { cwd: "/tmp" }],
+		["send_to_session", "send", { sessionId: "s1", prompt: "hello" }],
+		["read_session_history", "history", { sessionId: "s1" }],
+		["list_my_sessions", "list", {}],
+		["get_session_status", "status", { sessionId: "s1" }],
+		["abort_session", "abort", { sessionId: "s1" }],
+	])('tool "%s" calls select with action="%s"', async (toolName, expectedAction, params) => {
+		const tool = harness.registered.find((t) => t.name === toolName)!;
+		harness.selectMock.mockClear();
+		harness.selectMock.mockResolvedValue('{"ok":true}');
+
+		await tool.execute("call-1", params, undefined, undefined, harness.ctx);
+
+		expect(harness.selectMock).toHaveBeenCalledTimes(1);
+		const [marker, options, opts] = harness.selectMock.mock.calls[0];
+		// first arg = SESSION_MANAGER_MARKER
+		expect(marker).toBe(SESSION_MANAGER_MARKER);
+		// second arg = string array with JSON payload containing action
+		expect(Array.isArray(options)).toBe(true);
+		expect(options).toHaveLength(1);
+		const payload = JSON.parse(options[0]);
+		expect(payload.action).toBe(expectedAction);
+		// third arg has timeout
+		expect(opts).toHaveProperty("timeout");
+	});
+
+	it("create_managed_session includes cwd and label in payload.params", async () => {
+		const tool = harness.registered.find((t) => t.name === "create_managed_session")!;
+		harness.selectMock.mockResolvedValue('{"sessionId":"s1"}');
+		await tool.execute("call-1", { cwd: "/work", label: "test" }, undefined, undefined, harness.ctx);
+		const payload = JSON.parse(harness.selectMock.mock.calls[0][1][0]);
+		expect(payload.params.cwd).toBe("/work");
+		expect(payload.params.label).toBe("test");
+	});
+
+	it("send_to_session includes sessionId and prompt in payload.params", async () => {
+		const tool = harness.registered.find((t) => t.name === "send_to_session")!;
+		harness.selectMock.mockResolvedValue('{"queued":true}');
+		await tool.execute("call-1", { sessionId: "s1", prompt: "hi" }, undefined, undefined, harness.ctx);
+		const payload = JSON.parse(harness.selectMock.mock.calls[0][1][0]);
+		expect(payload.params.sessionId).toBe("s1");
+		expect(payload.params.prompt).toBe("hi");
+	});
+
+	it("read_session_history includes tailTurns in payload.params when provided", async () => {
+		const tool = harness.registered.find((t) => t.name === "read_session_history")!;
+		harness.selectMock.mockResolvedValue('{"messages":[]}');
+		await tool.execute("call-1", { sessionId: "s1", tailTurns: 5 }, undefined, undefined, harness.ctx);
+		const payload = JSON.parse(harness.selectMock.mock.calls[0][1][0]);
+		expect(payload.params.tailTurns).toBe(5);
+	});
+
+	it("read_session_history omits tailTurns from payload.params when not provided", async () => {
+		const tool = harness.registered.find((t) => t.name === "read_session_history")!;
+		harness.selectMock.mockResolvedValue('{"messages":[]}');
+		await tool.execute("call-1", { sessionId: "s1" }, undefined, undefined, harness.ctx);
+		const payload = JSON.parse(harness.selectMock.mock.calls[0][1][0]);
+		expect(payload.params.tailTurns).toBeUndefined();
+	});
+
+	it("select result is returned as text content", async () => {
+		const tool = harness.registered.find((t) => t.name === "list_my_sessions")!;
+		harness.selectMock.mockResolvedValue('{"sessions":[]}');
+		const result = await tool.execute("call-1", {}, undefined, undefined, harness.ctx);
+		expect(result.content).toHaveLength(1);
+		expect(result.content[0].type).toBe("text");
+		expect(result.content[0].text).toBe('{"sessions":[]}');
+	});
+});

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

@@ -0,0 +1,72 @@
+// tool-registration.test.ts — U5-A1: 6 tools registered with correct name/description/parameters + SESSION_MANAGER_MARKER import
+
+import { describe, it, expect, vi } from "vitest";
+import { SESSION_MANAGER_MARKER } from "@xyz-agent/extension-protocol";
+import registerExtension from "../index.ts";
+
+/** Proxy-based mock: capture registerTool calls for assertion. */
+function createMockPi() {
+	const registered: Array<{ name: string; description: string; parameters: unknown }> = [];
+	const pi = {
+		registerTool: (tool: { name: string; description: string; parameters: unknown }) => {
+			registered.push(tool);
+		},
+		on: vi.fn(),
+		getAllTools: vi.fn(() => []),
+		setActiveTools: vi.fn(),
+	};
+	return { pi, registered };
+}
+
+const EXPECTED_TOOL_NAMES = [
+	"create_managed_session",
+	"send_to_session",
+	"read_session_history",
+	"list_my_sessions",
+	"get_session_status",
+	"abort_session",
+] as const;
+
+describe("U5-A1 tool-registration", () => {
+	it("registers exactly 6 tools", () => {
+		const { pi, registered } = createMockPi();
+		registerExtension(pi as never);
+		expect(registered).toHaveLength(6);
+	});
+
+	it.each(EXPECTED_TOOL_NAMES)('registers tool "%s"', (name) => {
+		const { pi, registered } = createMockPi();
+		registerExtension(pi as never);
+		const tool = registered.find((t) => t.name === name);
+		expect(tool).toBeDefined();
+		expect(tool!.name).toBe(name);
+	});
+
+	it("every tool has a non-empty description", () => {
+		const { pi, registered } = createMockPi();
+		registerExtension(pi as never);
+		for (const tool of registered) {
+			expect(typeof tool.description).toBe("string");
+			expect(tool.description.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("every tool has a parameters schema (object type)", () => {
+		const { pi, registered } = createMockPi();
+		registerExtension(pi as never);
+		for (const tool of registered) {
+			expect(tool.parameters).toBeDefined();
+			const schema = tool.parameters as Record<string, unknown>;
+			expect(schema.type).toBe("object");
+		}
+	});
+
+	it("SESSION_MANAGER_MARKER is imported from @xyz-agent/extension-protocol", () => {
+		expect(typeof SESSION_MANAGER_MARKER).toBe("string");
+	});
+
+	it("SESSION_MANAGER_MARKER value is '\\x00XYZ_SESSION_MANAGER' (NUL prefix, 20 chars)", () => {
+		expect(SESSION_MANAGER_MARKER).toBe("\x00XYZ_SESSION_MANAGER");
+		expect(SESSION_MANAGER_MARKER).toHaveLength(20);
+	});
+});

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

@@ -0,0 +1,115 @@
+// tool-schema.test.ts — U5-A3: verify parameter schemas match spec requirements
+
+import { describe, it, expect } from "vitest";
+import registerExtension from "../index.ts";
+
+function getRegisteredSchemas() {
+	const registered: Array<{ name: string; parameters: Record<string, unknown> }> = [];
+	const pi = {
+		registerTool: (tool: { name: string; parameters: Record<string, unknown> }) => registered.push(tool),
+		on: () => {},
+		getAllTools: () => [],
+		setActiveTools: () => {},
+	};
+	registerExtension(pi as never);
+	return Object.fromEntries(registered.map((t) => [t.name, t.parameters]));
+}
+
+describe("U5-A3 tool-schema", () => {
+	const schemas = getRegisteredSchemas();
+
+	describe("create_managed_session", () => {
+		it("requires cwd (string)", () => {
+			const s = schemas.create_managed_session;
+			expect(s.type).toBe("object");
+			const props = s.properties as Record<string, unknown>;
+			expect(props.cwd).toBeDefined();
+			expect((props.cwd as Record<string, unknown>).type).toBe("string");
+			const required = s.required as string[];
+			expect(required).toContain("cwd");
+		});
+
+		it("has optional label (string)", () => {
+			const props = schemas.create_managed_session.properties as Record<string, unknown>;
+			expect(props.label).toBeDefined();
+			expect((props.label as Record<string, unknown>).type).toBe("string");
+			const required = schemas.create_managed_session.required as string[];
+			expect(required).not.toContain("label");
+		});
+
+		it("has optional prompt (string) — sd-u5: create 带 prompt 的工具 schema 暴露", () => {
+			const props = schemas.create_managed_session.properties as Record<string, unknown>;
+			expect(props.prompt).toBeDefined();
+			expect((props.prompt as Record<string, unknown>).type).toBe("string");
+			const required = schemas.create_managed_session.required as string[];
+			expect(required).not.toContain("prompt");
+		});
+	});
+
+	describe("send_to_session", () => {
+		it("requires sessionId (string) and prompt (string)", () => {
+			const s = schemas.send_to_session;
+			const props = s.properties as Record<string, unknown>;
+			expect(props.sessionId).toBeDefined();
+			expect((props.sessionId as Record<string, unknown>).type).toBe("string");
+			expect(props.prompt).toBeDefined();
+			expect((props.prompt as Record<string, unknown>).type).toBe("string");
+			const required = s.required as string[];
+			expect(required).toContain("sessionId");
+			expect(required).toContain("prompt");
+		});
+	});
+
+	describe("read_session_history", () => {
+		it("requires sessionId (string)", () => {
+			const s = schemas.read_session_history;
+			const props = s.properties as Record<string, unknown>;
+			expect(props.sessionId).toBeDefined();
+			expect((props.sessionId as Record<string, unknown>).type).toBe("string");
+			const required = s.required as string[];
+			expect(required).toContain("sessionId");
+		});
+
+		it("has optional tailTurns (number)", () => {
+			const props = schemas.read_session_history.properties as Record<string, unknown>;
+			expect(props.tailTurns).toBeDefined();
+			expect((props.tailTurns as Record<string, unknown>).type).toBe("number");
+			const required = schemas.read_session_history.required as string[];
+			expect(required).not.toContain("tailTurns");
+		});
+	});
+
+	describe("list_my_sessions", () => {
+		it("has no required parameters", () => {
+			const s = schemas.list_my_sessions;
+			expect(s.type).toBe("object");
+			const required = s.required as string[] | undefined;
+			// No required fields (empty object or no required array)
+			if (required) {
+				expect(required).toHaveLength(0);
+			}
+		});
+	});
+
+	describe("get_session_status", () => {
+		it("requires sessionId (string)", () => {
+			const s = schemas.get_session_status;
+			const props = s.properties as Record<string, unknown>;
+			expect(props.sessionId).toBeDefined();
+			expect((props.sessionId as Record<string, unknown>).type).toBe("string");
+			const required = s.required as string[];
+			expect(required).toContain("sessionId");
+		});
+	});
+
+	describe("abort_session", () => {
+		it("requires sessionId (string)", () => {
+			const s = schemas.abort_session;
+			const props = s.properties as Record<string, unknown>;
+			expect(props.sessionId).toBeDefined();
+			expect((props.sessionId as Record<string, unknown>).type).toBe("string");
+			const required = s.required as string[];
+			expect(required).toContain("sessionId");
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,232 @@
+// src/index.ts — @zhushanwen/pi-session-manager
+// 6 个 session 管理工具，通过 ctx.ui.select(SESSION_MANAGER_MARKER) 通道与 runtime handler 通信。
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SESSION_MANAGER_MARKER, type SessionManagerAction } from "@xyz-agent/extension-protocol";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
+import { Type, type Static, type TObject } from "typebox";
+
+// 模块级 logger（default export 首行 setPiHandle 注入后自动走 appendEntry 持久化，
+// 注入前/失败降级文件日志——见 extension-logger 三层通道设计）
+const logger = getLogger("session-manager");
+
+// ── 参数 Schema ──
+
+const CreateManagedSessionParams = Type.Object({
+	cwd: Type.String({ description: "Working directory for the new session" }),
+	label: Type.Optional(Type.String({ description: "Human-readable label for the session" })),
+	prompt: Type.Optional(Type.String({ description: "Initial prompt injected right after creation (atomic create+send)" })),
+});
+
+const SendToSessionParams = Type.Object({
+	sessionId: Type.String({ description: "Target session ID" }),
+	prompt: Type.String({ description: "Message to send to the session" }),
+});
+
+const ReadSessionHistoryParams = Type.Object({
+	sessionId: Type.String({ description: "Target session ID" }),
+	tailTurns: Type.Optional(Type.Number({ description: "Number of recent turns to return (default: all)" })),
+});
+
+const ListMySessionsParams = Type.Object({});
+
+const GetSessionStatusParams = Type.Object({
+	sessionId: Type.String({ description: "Target session ID" }),
+});
+
+const AbortSessionParams = Type.Object({
+	sessionId: Type.String({ description: "Target session ID to abort" }),
+});
+
+// ── select 通道辅助 ──
+
+/** select 超时（ms）：工具等待 runtime handler respond 的最大时间（read/create 走长链路放宽） */
+const SELECT_TIMEOUT_MS: Record<SessionManagerAction, number> = {
+	create: 60_000,
+	send: 30_000,
+	history: 60_000,
+	status: 30_000,
+	list: 30_000,
+	abort: 30_000,
+};
+
+/** runtime handler respond 的 JSON 形状（错误闭环：{ error, hint?, sessionId? }） */
+interface SessionManagerRawError {
+	error: string;
+	hint?: string;
+	sessionId?: string;
+}
+
+/** 工具 details 的可消费形状（下游消费不再 any） */
+type SessionManagerToolDetails =
+	| { kind: "error"; error: SessionManagerRawError }
+	| { kind: "ok"; result: unknown }
+	| { kind: "cancelled" };
+
+/**
+ * 通过 select 通道向 runtime handler 发送 session 管理请求。
+ * 返回 handler respond 的 JSON 字符串，用户取消/超时返回 null。
+ */
+async function callSessionManager(
+	ctx: ExtensionContext,
+	action: SessionManagerAction,
+	params: Record<string, unknown>,
+): Promise<string | null> {
+	// 契约 SSOT：SessionManagerRequest = { action, params }（协议包 extension-protocol 的
+	// session-manager 模块 types.ts，嵌套 params）。runtime event-adapter 的 marker
+	// 分支按 data.params 提取——若扁平化展开（{action, ...params}）params 会丢失变 {}。
+	const payload = JSON.stringify({ action, params });
+	try {
+		const value = await ctx.ui.select(
+			SESSION_MANAGER_MARKER,
+			[payload],
+			{ timeout: SELECT_TIMEOUT_MS[action] },
+		);
+		return value ?? null;
+	} catch (err) {
+		// select 通道异常（非用户取消/超时——那两类是 resolve null）：折叠为 null 供
+		// executeTool 统一转 isError，但必须留痕（静默吞 = runtime handler 故障不可排查）
+		logger.error(`[session-manager] select channel threw for action="${action}"`, {
+			reason: err instanceof Error ? err.message : String(err),
+		});
+		return null;
+	}
+}
+
+/**
+ * 统一的 execute 包装：调用 select 通道并解析结果。
+ * 返回标准 AgentToolResult 形状；select 取消/超时/异常是错误路径，
+ * 必须带 isError: true（extension-conventions「禁止错误成功模式」——
+ * 调用方 agent 需能区分成功与失败以决定重试/放弃）。
+ */
+async function executeTool(
+	ctx: ExtensionContext,
+	action: SessionManagerAction,
+	params: Record<string, unknown>,
+): Promise<{ isError?: boolean; content: Array<{ type: "text"; text: string }>; details: SessionManagerToolDetails }> {
+	const raw = await callSessionManager(ctx, action, params);
+	if (raw === null) {
+		return {
+			isError: true,
+			content: [{ type: "text" as const, text: `Session manager ${action}: cancelled or timed out.` }],
+			details: { kind: "cancelled" },
+		};
+	}
+	// runtime 错误闭环（respond({error}) 走同一 select 通道）——解析后检测 error 字段，
+	// 命中即 isError: true（extension-conventions「禁止错误成功模式」：agent 需能区分
+	// 成功与同步失败以决定重试/放弃，不能靠读 content 文本自行判错）。
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		parsed = undefined;
+	}
+	if (parsed !== null && typeof parsed === "object" && typeof (parsed as SessionManagerRawError).error === "string") {
+		const err = parsed as SessionManagerRawError;
+		const text = err.hint ? `${err.error}\nhint: ${err.hint}` : err.error;
+		return {
+			isError: true,
+			content: [{ type: "text" as const, text }],
+			details: { kind: "error", error: err },
+		};
+	}
+	return {
+		content: [{ type: "text" as const, text: raw }],
+		details: { kind: "ok", result: parsed },
+	};
+}
+
+// ── Extension 入口 ──
+
+/** 单个 session 工具的声明式配置（registerSessionTool 的输入）。 */
+interface SessionToolConfig<S extends TObject> {
+	name: string
+	label: string
+	description: string
+	parameters: S
+	action: SessionManagerAction
+	/** schema params → 协议 params 的映射（undefined 字段由 JSON.stringify 丢弃） */
+	toParams: (params: Static<S>) => Record<string, unknown>
+}
+
+/**
+ * 注册一个 session 管理工具。6 个工具共用同一 execute 骨架——
+ * 统一忽略 signal/onUpdate（session 管理是单次请求-响应，无流式更新），
+ * 不 ctx.ui 交互（走 marker select 通道，不弹用户 UI）。
+ */
+function registerSessionTool<S extends TObject>(pi: ExtensionAPI, cfg: SessionToolConfig<S>): void {
+	pi.registerTool({
+		name: cfg.name,
+		label: cfg.label,
+		description: cfg.description,
+		parameters: cfg.parameters,
+		async execute(
+			_toolCallId: string,
+			params: Static<S>,
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		) {
+			return executeTool(ctx, cfg.action, cfg.toParams(params));
+		},
+	});
+}
+
+export default function sessionManagerExtension(pi: ExtensionAPI): void {
+	// logger 持久化通道接入（appendEntry custom entry，不进 LLM 上下文）
+	setPiHandle(pi);
+
+	registerSessionTool(pi, {
+		name: "create_managed_session",
+		label: "Create Managed Session",
+		description: "Create a new agent-managed session in the specified working directory. Optionally provide an initial prompt, which is sent immediately (new sessions are always idle, so it is delivered directly). Returns a session ID and initial status.",
+		parameters: CreateManagedSessionParams,
+		action: "create",
+		toParams: (p) => ({ cwd: p.cwd, label: p.label, prompt: p.prompt }),
+	});
+
+	registerSessionTool(pi, {
+		name: "send_to_session",
+		label: "Send to Session",
+		description: "Send a prompt/message to an existing managed session. The message is asynchronously queued: if the target session is busy (generating/compacting/running bash) it is delivered at its next turn boundary, and {queued: true} is returned immediately. On synchronous failure the tool returns an error result (isError) with a hint (check get_session_status, then retry).",
+		parameters: SendToSessionParams,
+		action: "send",
+		toParams: (p) => ({ sessionId: p.sessionId, prompt: p.prompt }),
+	});
+
+	registerSessionTool(pi, {
+		name: "read_session_history",
+		label: "Read Session History",
+		description: "Read the conversation history of a managed session. Optionally limit to the last N turns.",
+		parameters: ReadSessionHistoryParams,
+		action: "history",
+		toParams: (p) => ({ sessionId: p.sessionId, tailTurns: p.tailTurns }),
+	});
+
+	registerSessionTool(pi, {
+		name: "list_my_sessions",
+		label: "List My Sessions",
+		description: "List all sessions managed by the current agent. Returns session IDs, labels, and statuses.",
+		parameters: ListMySessionsParams,
+		action: "list",
+		toParams: () => ({}),
+	});
+
+	registerSessionTool(pi, {
+		name: "get_session_status",
+		label: "Get Session Status",
+		description: "Get the current status of a managed session (running, idle, error, etc.) and its model info.",
+		parameters: GetSessionStatusParams,
+		action: "status",
+		toParams: (p) => ({ sessionId: p.sessionId }),
+	});
+
+	registerSessionTool(pi, {
+		name: "abort_session",
+		label: "Abort Session",
+		description: "Abort a running managed session. The session will stop processing and enter aborted state.",
+		parameters: AbortSessionParams,
+		action: "abort",
+		toParams: (p) => ({ sessionId: p.sessionId }),
+	});
+}