@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/background/task-store.ts

@@ -0,0 +1,125 @@
+/**
+ * 模块级单例任务表（运行时权威，D17 的根基）。
+ *
+ * 为什么模块级而不是 extension 实例级：pi 同进程 session 替换（/fork、选择器切换、
+ * RPC session.*）会重新 load extension 实例，实例级状态随 dispose 消失；模块级 Map
+ * 跨替换存活，任务表无需恢复（pending-notifications 的 unsubscribers 列表同范式）。
+ *
+ * 条目唯一来源 = 本进程 execute 的 spawn（registerSpawnedTask 全仓唯一调用点 =
+ * spawn-background.ts）。他进程 / 历史 session 的 running 条目**永不进表**——
+ * 零恢复零接管，处置权统一归 M5 reaper 属主裁决；终态条目可从 registry 读，
+ * 仅供 bash_output 查历史。
+ *
+ * 终态条目 LRU 上限 MAX_TERMINAL_ENTRIES（与 registry 对称），淘汰后 bash_output
+ * 回落 registry 查询。
+ */
+
+import {
+	isActiveState,
+	isTerminalState,
+	type BackgroundTask,
+	type BackgroundTaskEndReason,
+	type KillingIntent,
+} from "./types.ts";
+
+/** 终态条目 LRU 上限（§3.5 两层存储分工：单例表与 registry 对称采用 LRU 50）。 */
+export const MAX_TERMINAL_TASKS = 50;
+
+const taskTable = new Map<string, BackgroundTask>();
+
+/**
+ * 登记新任务（条目唯一入口，仅 spawn-background 调用）。
+ * 同 taskId 已存在 = 编码错误（task_id 含 ts+rand 保证全局唯一），防御性覆盖并保留
+ * 日志语义由调用方保证不发生。
+ */
+export function registerSpawnedTask(task: BackgroundTask): void {
+	taskTable.set(task.taskId, task);
+}
+
+export function getTask(taskId: string): BackgroundTask | undefined {
+	return taskTable.get(taskId);
+}
+
+/** 全部条目（running/killing/exited/orphaned），bash_output list 用。 */
+export function getAllTasks(): BackgroundTask[] {
+	return [...taskTable.values()];
+}
+
+/** 活跃条目（running | killing），轮询器监护对象。 */
+export function getActiveTasks(): BackgroundTask[] {
+	return getAllTasks().filter((t) => isActiveState(t.state));
+}
+
+export function countActiveTasks(): number {
+	return getActiveTasks().length;
+}
+
+/** 最老活跃任务（并发上限满时列入错误文案）。 */
+export function oldestActiveTask(): BackgroundTask | undefined {
+	return getActiveTasks().sort((a, b) => a.startedAt - b.startedAt)[0];
+}
+
+/**
+ * 标 killing intent（瞬态 running→killing）。bash_kill 与后台 timeout 定时器共用；
+ * 调用方负责同步写 registry 侧（两侧一致是查询面可见性前提）。
+ */
+export function markKillingIntent(
+	taskId: string,
+	reason: KillingIntent["reason"],
+): BackgroundTask | undefined {
+	const task = taskTable.get(taskId);
+	if (task === undefined || !isActiveState(task.state)) return undefined;
+	task.state = "killing";
+	task.intent = { reason, at: Date.now() };
+	return task;
+}
+
+export interface FinalizeOutcome {
+	exitCode: number | null;
+	reason: BackgroundTaskEndReason;
+	endedAt: number;
+	tailSummary?: string;
+}
+
+/**
+ * 终态化（exited）：唯一终态写入口。轮询器 exit 边沿、进程退出收殓两条路径收敛
+ * 到这里（bash_kill 不直接写终态——单一终态归属，§3.5「bash_kill 终态收尾的
+ * 单点归属」）。消费 intent、清 timeout 定时器、算 durationMs、LRU 淘汰溢出终态。
+ */
+export function finalizeTask(taskId: string, outcome: FinalizeOutcome): BackgroundTask | undefined {
+	const task = taskTable.get(taskId);
+	if (task === undefined || isTerminalState(task.state)) return task;
+	if (task.timeoutTimer !== undefined) {
+		clearTimeout(task.timeoutTimer);
+		task.timeoutTimer = undefined;
+	}
+	task.state = "exited";
+	task.exitCode = outcome.exitCode;
+	task.reason = outcome.reason;
+	task.endedAt = outcome.endedAt;
+	task.durationMs = outcome.endedAt - task.startedAt;
+	task.tailSummary = outcome.tailSummary;
+	task.intent = undefined;
+	task.child = undefined; // 终态后不再需要 exitCode，释放 ChildProcess 引用
+	evictTerminalOverflow();
+	return task;
+}
+
+/** 终态条目超上限时按 endedAt 升序淘汰最老（LRU；endedAt 缺失退 startedAt）。 */
+function evictTerminalOverflow(): void {
+	const terminal = getAllTasks()
+		.filter((t) => isTerminalState(t.state))
+		.sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt));
+	const excess = terminal.length - MAX_TERMINAL_TASKS;
+	for (let i = 0; i < excess; i++) {
+		taskTable.delete(terminal[i].taskId);
+	}
+}
+
+/** 测试专用：清空单例表（模块级状态跨测试文件存活，必须显式复位）。 */
+export function clearTaskStoreForTest(): void {
+	for (const task of taskTable.values()) {
+		if (task.timeoutTimer !== undefined) clearTimeout(task.timeoutTimer);
+	}
+	taskTable.clear();
+}

package/src/background/types.ts

@@ -0,0 +1,103 @@
+/**
+ * background 任务核心数据模型（设计文档 docs/design/base-tool-enhance.md §3.5）。
+ *
+ * 两层存储分工：
+ *  - 单例任务表（task-store.ts，模块级 Map）= 运行时权威；条目唯一来源 = 本进程
+ *    execute 的 spawn——他进程 / 历史 session 的 running 条目永不进表（零恢复零接管）
+ *  - registry.json（registry.ts，per-sessionId 目录）= 持久化权威；M5 reaper 的
+ *    孤儿发现源，条目记 ownerPiPid（M2 只负责写入）
+ */
+
+import type { ChildProcess } from "node:child_process";
+
+/** 任务状态机：running → killing（intent 瞬态）→ exited；orphaned 由 M5 reaper 写入。 */
+export type BackgroundTaskState = "running" | "killing" | "exited" | "orphaned";
+
+/**
+ * 终态 reason 枚举（§3.5 bash_output 规格）：
+ *  - natural      进程自然退出（含外力终止——观测上不可区分，§3.5 两层存储分工节）
+ *  - timeout      后台显式 timeout 定时器触发
+ *  - killed       bash_kill 发令
+ *  - process-exit pi 进程退出收殓（D12）
+ */
+export type BackgroundTaskEndReason = "natural" | "timeout" | "killed" | "process-exit";
+
+/**
+ * killing intent：bash_kill / 后台 timeout 已发令、轮询器 exit 边沿未确认的瞬态标记。
+ * 标记写入单例表与 registry 两侧（查询面立即可见，无「已 kill 仍 running」倒挂）；
+ * 轮询边沿据此决定终态 reason，消费后清除。
+ */
+export interface KillingIntent {
+	reason: Extract<BackgroundTaskEndReason, "killed" | "timeout">;
+	at: number;
+}
+
+/**
+ * 单例任务表条目（运行时权威，D17 根基）。
+ *
+ * child 引用**只用于读 exitCode/signalCode，禁止挂事件监听**——exit 感知统一走
+ * 轮询器 kill(pid,0) 边沿；闭包式 exit 监听在同进程 session 替换后指向 stale bus
+ * （D17）。child.on("error") 是唯一例外（spawn-background 内的 no-op，防进程崩溃，
+ * 不做任何状态推进）。
+ */
+export interface BackgroundTask {
+	taskId: string;
+	pid: number;
+	/** 原始命令全文（bash_output list 展示时截前 80 字符） */
+	command: string;
+	outputFile: string;
+	/** 本条目 registry.json 路径（收殓同步写终态用；运行时字段，不序列化） */
+	registryPath: string;
+	startedAt: number;
+	state: BackgroundTaskState;
+	/** 发起任务的 pi 进程 pid（M5 reaper 属主判定依据；M2 只写入） */
+	ownerPiPid: number;
+	/** 发起 session（registry 目录归属） */
+	sessionId: string;
+	exitCode?: number | null;
+	reason?: BackgroundTaskEndReason;
+	endedAt?: number;
+	durationMs?: number;
+	/** exit 边沿组装的输出尾部摘要（M3 通知用；M2 存条目不消费） */
+	tailSummary?: string;
+	/** killing intent（瞬态，终态化时消费）；终态后为 undefined */
+	intent?: KillingIntent;
+	/** 后台显式 timeout 定时器（到点 kill-tree + 标 intent timeout）；终态化时清除 */
+	timeoutTimer?: ReturnType<typeof setTimeout>;
+	/**
+	 * 子进程 start time（epoch 秒，M3 补写 M5 预告字段）：spawn 后立即读取，供 reaper
+	 * 精确比较防 pid 复用误杀；读取失败省略（reaper 降级走 startedAt 秒级校验兜底）。
+	 */
+	pidStartTime?: number;
+	/** spawn 返回的 ChildProcess 引用：仅读 exitCode/signalCode（D17，见接口注释） */
+	child?: ChildProcess;
+}
+
+/** registry.json 持久化条目（BackgroundTask 剥离运行时字段后的形状）。 */
+export interface RegistryEntry {
+	taskId: string;
+	pid: number;
+	command: string;
+	outputFile: string;
+	startedAt: number;
+	state: BackgroundTaskState;
+	ownerPiPid: number;
+	sessionId: string;
+	exitCode?: number | null;
+	reason?: BackgroundTaskEndReason;
+	endedAt?: number;
+	durationMs?: number;
+	tailSummary?: string;
+	/** 子进程 start time（epoch 秒，reaper pid 复用防御精确比较用；缺失走降级校验）。 */
+	pidStartTime?: number;
+}
+
+/** 任务是否处于活跃态（轮询器监护对象）。 */
+export function isActiveState(state: BackgroundTaskState): boolean {
+	return state === "running" || state === "killing";
+}
+
+/** 任务是否处于终态（LRU 淘汰对象；orphaned 由 M5 写入，同属终态）。 */
+export function isTerminalState(state: BackgroundTaskState): boolean {
+	return state === "exited" || state === "orphaned";
+}

package/src/bash-kill-tool.ts

@@ -0,0 +1,144 @@
+/**
+ * bash_kill 工具（D9，§3.5「bash_kill 终态收尾的单点归属」+ 跨进程边界段）。
+ *
+ * 职责边界：只负责杀进程树 + kill 前把单例表与 registry **两侧**标 killing intent
+ * （查询面立即可见——kill 返回后 bash_output 即显示 killing，无「已 kill 仍 running」
+ * 倒挂窗口）。实际终态（exited, reason:"killed"）由轮询器 exit 边沿收尾写——
+ * bash_kill 不直接写终态（单一终态归属），也不 sendMessage（kill 调用方就在当前
+ * turn 内等结果，再发 steer 通知是双发噪音——那是 M3 的规则，此处先不实现通知）。
+ *
+ * kill 目标归属（§3.5）：**限定本进程单例表条目**；registry 回落限定终态条目
+ * （exited/orphaned → already exited）——registry 中他进程的 running/killing 条目
+ * **不可 kill**（跨进程边界：处置权归发起进程，孤儿由 reaper 属主判定收殓）。
+ * kill 前校验 pid 判活 + start time 匹配（防陈旧条目遇 pid 复用误杀无关进程，
+ * 宁不杀勿误杀，同 reaper 原则 §3.6）。
+ */
+
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { isPidAlive, killProcessTree } from "./kill-tree.ts";
+import { getProcessStartTimeSec } from "./reaper.ts";
+import { ensurePollerRunning } from "./background/poller.ts";
+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";
+
+const bashKillSchema = Type.Object({
+	task_id: Type.String({ description: "Task id returned by the background bash tool." }),
+});
+
+const BASH_KILL_DESCRIPTION = [
+	"Terminate a background bash task by killing its process tree (the task's whole process group).",
+	"Returns immediately; poll bash_output {task_id} for the final exited state.",
+].join("\n");
+
+/** JSON 输出缩进（registry.ts 同款）。 */
+const JSON_INDENT = 2;
+
+function textResult(text: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details: undefined };
+}
+
+function killedFalse(reason: string, hint?: string): AgentToolResult<unknown> {
+	return textResult(JSON.stringify({ killed: false, reason, ...(hint !== undefined ? { hint } : {}) }, null, JSON_INDENT));
+}
+
+export function createBashKillToolDefinition() {
+	return {
+		name: "bash_kill",
+		label: "bash_kill",
+		description: BASH_KILL_DESCRIPTION,
+		parameters: bashKillSchema,
+		async execute(
+			_toolCallId: string,
+			args: { task_id: string },
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<AgentToolResult<unknown>> {
+			const sessionId = ctx.sessionManager.getSessionId();
+			// 查找顺序（§3.5 kill 目标归属）：单例表（本进程，kill 权威目标）→ registry
+			// 回落（限定终态——他进程 running/killing 条目不可 kill）
+			const fromStore = getAllTasks().find((t) => t.taskId === args.task_id);
+			if (fromStore === undefined) {
+				const entry: RegistryEntry | undefined = readRegistry(getRegistryPath(getAgentDir(), sessionId)).get(
+					args.task_id,
+				);
+				if (entry === undefined) {
+					return killedFalse("no such task", "use bash_output to list");
+				}
+				if (isTerminalState(entry.state)) {
+					return killedFalse(
+						`already exited${entry.exitCode !== undefined && entry.exitCode !== null ? ` (code ${entry.exitCode})` : ""}`,
+					);
+				}
+				// registry-only 活跃条目 = 他进程任务（本进程活跃任务必在单例表）——跨进程
+				// 不可 kill：处置权归发起进程；属主若已死，孤儿由 reaper 在下次 session
+				// 启动时收殓（属主判定）
+				return killedFalse(
+					"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 reaper will collect the orphan at the next session start",
+				);
+			}
+			if (isTerminalState(fromStore.state)) {
+				return killedFalse(
+					`already exited${fromStore.exitCode !== undefined && fromStore.exitCode !== null ? ` (code ${fromStore.exitCode})` : ""}`,
+				);
+			}
+
+			// pid 复用防御（§3.6 同 reaper 原则，宁不杀勿误杀）：
+			//  - pid 已死 → already exited 风格返回，不发 kill（终态由轮询边沿收尾）
+			//  - 有 pidStartTime 字段 → 校验实际进程 start time 匹配；不匹配/读不到 =
+			//    复用嫌疑，拒绝 kill 并说明
+			//  - 无字段（spawn 时 ps 不可用平台）→ 放行：本进程轮询器 ≤2s 前判过活，
+			//    复用窗口毫秒级；registry 终态条目不会走到这里（上面 already exited）
+			if (!isPidAlive(fromStore.pid)) {
+				return killedFalse("already exited (process no longer alive; final state pending poll)");
+			}
+			if (fromStore.pidStartTime !== undefined) {
+				const actualStartSec = getProcessStartTimeSec(fromStore.pid);
+				if (actualStartSec === undefined) {
+					return killedFalse(
+						"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 poll edge, or kill the process group manually if certain",
+					);
+				}
+				if (actualStartSec !== fromStore.pidStartTime) {
+					return killedFalse(
+						`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>)",
+					);
+				}
+			}
+
+			// 两侧标 killing intent（单例表内存标记 + registry 同步写盘）→ 再杀进程树。
+			// intent 落盘在 kill 信号之前，查询面无倒挂窗口。markKillingIntent 只查
+			// 单例表——可 kill 目标此时必在单例表（registry-only 活跃条目上面已拒绝、
+			// registry 终态条目 already exited 返回），无另一侧需同步
+			const marked = markKillingIntent(fromStore.taskId, "killed");
+			if (marked !== undefined) {
+				writeRegistryEntry(marked.registryPath, taskToRegistryEntry(marked));
+			}
+			killProcessTree(fromStore.pid);
+			// 轮询器确保在跑：边沿收尾（写终态）依赖它
+			ensurePollerRunning();
+			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,
+				),
+			);
+		},
+	};
+}

package/src/bash-output-tool.ts

@@ -0,0 +1,131 @@
+/**
+ * bash_output 工具（D9：独立小工具，查询与 kill 权限语义分离）。
+ *
+ * 规格（§3.5）：{task_id?}。
+ *  - 省略 = list：单例表与 registry 终态条目合并（同 task_id 以单例表为准——它的
+ *    状态更新），返回 {tasks:[...]}，按 startedAt 升序
+ *  - 指定 = 详情：{state, exitCode?, reason?, durationMs?, output(tail 2000 行/50KB
+ *    截断，同内置规则), outputFile, truncated}；输出文件被删后返回
+ *    {output:"<lost>", state} 不崩溃（§3.6）
+ *
+ * 查询归属边界（§3.5 跨进程边界）：单例表 = 本进程全部任务（含同进程 session 替换
+ * 前发起的）；registry 侧只读当前 sessionId 目录。他进程任务查不到（回发起 session）。
+ */
+
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { readOutputTail } from "./background/output-tail.ts";
+import { getRegistryPath, readRegistry } from "./background/registry.ts";
+import { truncateCommand } from "./background/spawn-background.ts";
+import { getAllTasks } from "./background/task-store.ts";
+import { isTerminalState, type BackgroundTask, type RegistryEntry } from "./background/types.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." })),
+});
+
+/** JSON 输出缩进（registry.ts 同款）。 */
+const JSON_INDENT = 2;
+
+const BASH_OUTPUT_DESCRIPTION = [
+	"Fetch output and status of a background bash task started with bash {background:true}.",
+	"Provide task_id to get task detail: state (running|killing|exited|orphaned), exitCode, reason, duration and tail output (last 2000 lines / 50KB).",
+	"Omit task_id to list all background tasks of this session.",
+].join("\n");
+
+/** list 视图条目（§3.5：command 前 80 字符）。 */
+function toListRow(source: BackgroundTask | RegistryEntry) {
+	return {
+		task_id: source.taskId,
+		command: truncateCommand(source.command),
+		state: source.state,
+		...(source.exitCode !== undefined ? { exitCode: source.exitCode } : {}),
+		...(source.reason !== undefined ? { reason: source.reason } : {}),
+		startedAt: source.startedAt,
+		...(source.durationMs !== undefined ? { durationMs: source.durationMs } : {}),
+	};
+}
+
+function textResult(text: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text }], details: undefined };
+}
+
+/**
+ * list 视图：单例表优先，registry 终态条目补差（同 id 已在单例表则跳过）。
+ * registry 侧只并入终态（exited/orphaned）——running/killing 条目属他进程
+ * 任务（本进程活跃任务必在单例表），并入会显示幻影 running 行（§3.5
+ * 「单例表与 registry 终态条目合并」）。
+ */
+function listTasksText(registry: Map<string, RegistryEntry>): string {
+	const rows = new Map<string, ReturnType<typeof toListRow>>();
+	for (const task of getAllTasks()) rows.set(task.taskId, toListRow(task));
+	for (const entry of registry.values()) {
+		if (!isTerminalState(entry.state)) continue;
+		if (!rows.has(entry.taskId)) rows.set(entry.taskId, toListRow(entry));
+	}
+	const tasks = [...rows.values()].sort((a, b) => a.startedAt - b.startedAt);
+	return JSON.stringify({ tasks }, null, JSON_INDENT);
+}
+
+/**
+ * 按 taskId 定位任务：单例表 → 当前 session registry（回落限定终态条目——
+ * 他进程 running 条目不可查，§3.5 跨进程边界）。
+ */
+function findTask(
+	taskId: string,
+	registry: Map<string, RegistryEntry>,
+): BackgroundTask | RegistryEntry | undefined {
+	const registryEntry = registry.get(taskId);
+	return (
+		getAllTasks().find((t) => t.taskId === taskId) ??
+		(registryEntry !== undefined && isTerminalState(registryEntry.state) ? registryEntry : undefined)
+	);
+}
+
+/** 详情视图：tail 输出（丢失时 "<lost>"，§3.6）+ 终态字段按存在性展开。 */
+function taskDetailText(task: BackgroundTask | RegistryEntry): string {
+	const tail = readOutputTail(task.outputFile);
+	const detail = {
+		task_id: task.taskId,
+		state: task.state,
+		...(task.exitCode !== undefined ? { exitCode: task.exitCode } : {}),
+		...(task.reason !== undefined ? { reason: task.reason } : {}),
+		startedAt: task.startedAt,
+		...(task.durationMs !== undefined ? { durationMs: task.durationMs } : {}),
+		output: tail?.output ?? "<lost>",
+		truncated: tail?.truncated ?? false,
+		outputFile: task.outputFile,
+	};
+	return JSON.stringify(detail, null, JSON_INDENT);
+}
+
+export function createBashOutputToolDefinition() {
+	return {
+		name: "bash_output",
+		label: "bash_output",
+		description: BASH_OUTPUT_DESCRIPTION,
+		parameters: bashOutputSchema,
+		async execute(
+			_toolCallId: string,
+			args: { task_id?: string },
+			_signal: AbortSignal | undefined,
+			_onUpdate: unknown,
+			ctx: ExtensionContext,
+		): Promise<AgentToolResult<unknown>> {
+			const sessionId = ctx.sessionManager.getSessionId();
+			const registry = readRegistry(getRegistryPath(getAgentDir(), sessionId));
+
+			if (args.task_id === undefined) return textResult(listTasksText(registry));
+
+			const task = findTask(args.task_id, registry);
+			if (task === undefined) {
+				throw new Error(
+					`No such task: ${args.task_id}. Use bash_output without task_id to list all background tasks.`,
+				);
+			}
+			return textResult(taskDetailText(task));
+		},
+	};
+}