@zhushanwen/pi-base-tool-enhance 0.5.3 → 0.5.5

package/README.md

@@ -1,8 +1,8 @@
 # @zhushanwen/pi-base-tool-enhance
 
-同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。承接已废弃 unified-hooks 的核心能力（测试类拦截式 guard → force-test 白名单命中自动转后台，匹配语义较原 guard 有调整、登记于 force-patterns.ts；网络类挂死保护 → 可配置前台默认超时，弱承接；工具报错审计 → tool_error 审计 hook，entry customType 保持 `unified-hooks:tool-error` 历史连续）。
+同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。能力面：测试类命令 force-test 白名单命中自动转后台（模式登记于 force-patterns.ts）、网络类挂死保护（可配置前台默认超时）、工具报错审计（tool_error 审计 hook，entry customType 为 `unified-hooks:tool-error`）。
 
-设计文档（SSOT）：`docs/design/base-tool-enhance.md`。
+设计决策沉淀在包内源码注释与本文档。
 
 ## 配置
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal"
   },
   "pi": {
@@ -28,7 +28,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.11.0",
+    "@zhushanwen/extension-protocol": "0.11.0",
     "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0",
     "@zhushanwen/pi-file-lock": "0.4.0",
@@ -41,7 +41,7 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.2"
+    "@zhushanwen/pi-pending-notifications": "0.7.4"
   },
   "peerDependenciesMeta": {
     "@zhushanwen/pi-pending-notifications": {

package/skills/base-tool-enhance-ext-config/SKILL.md

@@ -16,10 +16,10 @@ description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/
 | 环境 | 路径 |
 |------|------|
 | 独立 pi CLI | `~/.pi/agent/config/base-tool-enhance-ext-config.json` |
-| xyz-agent dev | `~/.xyz-agent-dev/pi/agent/config/base-tool-enhance-ext-config.json` |
-| xyz-agent prod | `~/.xyz-agent/pi/agent/config/base-tool-enhance-ext-config.json` |
+| taiji dev | `~/.taiji-dev/agent/config/base-tool-enhance-ext-config.json` |
+| taiji prod | `~/.taiji/agent/config/base-tool-enhance-ext-config.json` |
 
-**动态推导（推荐）**：agentDir 由 pi 核心 `getAgentDir()` 决定（读 `PI_CODING_AGENT_DIR`，默认 `~/.pi/agent`）；xyz-agent 通过 `XYZ_AGENT_DATA_DIR` 隔离数据目录。排查时先查这两个 env 组合出实际路径，不要假设单一环境——写错环境的配置文件改了也不生效。
+**动态推导（推荐）**：agentDir 由 pi 核心 `getAgentDir()` 决定（读 `PI_CODING_AGENT_DIR`，默认 `~/.pi/agent`）；taiji 通过 `TAIJI_AGENT_DATA_DIR` 隔离数据目录。排查时先查这两个 env 组合出实际路径，不要假设单一环境——写错环境的配置文件改了也不生效。
 
 文件不存在 / JSON 解析失败 → 全默认值继续工作（工具不报错，warn 落扩展日志）。单键类型错/非法值 → **仅该键**回退默认 + warn，不整体拒载；未知键忽略（前向兼容）。
 

package/src/__tests__/background-lifecycle.test.ts

@@ -20,9 +20,9 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 // 进程原语（ext-simplify-13 后单点在 protocol 子出口）转发真实杀 + 记录调用
 //（timeout 分支断言 killProcessTree 被调）
 const { killTreeCalls } = vi.hoisted(() => ({ killTreeCalls: [] as number[] }));
-vi.mock("@xyz-agent/extension-protocol/background-task", async (importOriginal) => {
+vi.mock("@zhushanwen/extension-protocol/background-task", async (importOriginal) => {
 	const orig = await importOriginal<
-		typeof import("@xyz-agent/extension-protocol/background-task")
+		typeof import("@zhushanwen/extension-protocol/background-task")
 	>();
 	return {
 		...orig,
@@ -33,7 +33,7 @@ vi.mock("@xyz-agent/extension-protocol/background-task", async (importOriginal)
 	};
 });
 
-import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 
 import { createBashKillToolDefinition } from "../bash-kill-tool.ts";
 import { createBashOutputToolDefinition } from "../bash-output-tool.ts";
@@ -406,7 +406,7 @@ describe("bash_kill tool (killing intent, single-point finalization)", () => {
 		expect(result.killed).toBe(false);
 		expect(result.reason).toBe("cross-process running task owned by another pi process");
 		// 收殓已下沉 runtime（u-bte-remove）：hint 指向 runtime 收殓而非 reaper
-		expect(result.hint).toContain("xyz-agent runtime");
+		expect(result.hint).toContain("taiji runtime");
 		expect(killTreeCalls).not.toContain(foreignPid); // 未发 kill 信号
 	});
 

package/src/__tests__/notify.test.ts

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { killProcessTree } from "@xyz-agent/extension-protocol/background-task";
+import { killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import {
 	BACKGROUND_BASH_CUSTOM_TYPE,
 	buildNotificationContent,

package/src/__tests__/pending-reconcile.test.ts

@@ -10,7 +10,7 @@ import {
 	BACKGROUND_TASK_ID_PREFIX,
 	collectActivePendingIds,
 	mapReasonToStatus,
-} from "@xyz-agent/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {

package/src/__tests__/registry.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 
 import { afterEach, describe, expect, it } from "vitest";
 
-import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@xyz-agent/extension-protocol";
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@zhushanwen/extension-protocol";
 
 import {
 	getRegistryPath,

package/src/__tests__/subagent-guard.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/subagent-guard.test.ts
 //
 // subagent-guard 判据钉值（ext-simplify-17 D4 重锚定后）：
-//   - XYZ_AGENT_SUBAGENT === "1" 命中（引擎 spawn 链恒注入的现行标记）
+//   - TAIJI_AGENT_SUBAGENT === "1" 命中（引擎 spawn 链恒注入的现行标记）
 //   - 其他值 / 缺失不命中（顶层会话不误降级，background 正常后台化）
 //
 // [HISTORICAL] 对照（D4 重锚前的旧行为）：旧判据查 PI_SUBAGENT_* 身份键族两枚、
@@ -14,13 +14,13 @@ import { describe, expect, it } from "vitest";
 import { isSubagentProcess } from "../background/subagent-guard.ts";
 
 describe("isSubagentProcess（subagent-guard，D4 重锚后）", () => {
-	it("XYZ_AGENT_SUBAGENT=1 命中（引擎链 subagent → D14 background 降级前提恢复）", () => {
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+	it("TAIJI_AGENT_SUBAGENT=1 命中（引擎链 subagent → D14 background 降级前提恢复）", () => {
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "1" })).toBe(true);
 	});
 
 	it("值非 \"1\" 不命中", () => {
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "0" })).toBe(false);
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "" })).toBe(false);
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "0" })).toBe(false);
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "" })).toBe(false);
 	});
 
 	it("缺失不命中（顶层会话 → background 正常后台化，guard 不误命中）", () => {

package/src/background/output-tail.ts

@@ -8,7 +8,7 @@
  *  - readTailSummary：exit 边沿的 tail 摘要（存条目 / M3 通知用）
  */
 
-import { readOutputTail as readOutputTailPrimitive } from "@xyz-agent/extension-protocol/background-task";
+import { readOutputTail as readOutputTailPrimitive } from "@zhushanwen/extension-protocol/background-task";
 
 /** pi 内置 bash 同款截断上限（last 2000 lines / 50KB = 51200 bytes，先到为准）。 */
 export const TAIL_MAX_LINES = 2000;

package/src/background/pending-reconcile.ts

@@ -35,8 +35,8 @@ import {
 	BACKGROUND_TASK_ID_PREFIX,
 	collectActivePendingIds,
 	mapReasonToStatus,
-} from "@xyz-agent/extension-protocol";
-import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+} from "@zhushanwen/extension-protocol";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/poller.ts

@@ -13,7 +13,7 @@
  * 可查、对账可补），不加同步握手。
  */
 
-import { isPidAlive } from "@xyz-agent/extension-protocol/background-task";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 
 import { readTailSummary } from "./output-tail.ts";
 import { readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";

package/src/background/process-exit-guard.ts

@@ -18,16 +18,16 @@
  *    挂起进程，pi 的 ignore 语义完全失效
  *  - rpc/print 模式 Ctrl+C：pi 无 SIGINT listener（dist 全量 grep 唯一注册点在 TUI
  *    挂起态）→ 默认处置进程即死。探针实测：无 listener 的信号默认终止**不触发
- *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 xyz-agent runtime 收殓器按
+ *    exit 事件**，同步收殓在该路径本就不可达；孤儿由 taiji runtime 收殓器按
  *    属主判定收殓（u-bte-remove 下沉后；与 SIGKILL 强杀同类，设计内兜底）
  *  - cleanup-only listener 更不可取：注册即抑制默认终止，rpc 前台 Ctrl+C 后 pi 变
  *    成杀不死的僵尸进程
  *
- * 子进程死后 registry 目录由 xyz-agent runtime 启动期兜底扫描覆盖（收殓下沉）——
+ * 子进程死后 registry 目录由 taiji runtime 启动期兜底扫描覆盖（收殓下沉）——
  * 本单元不管。
  */
 
-import { killProcessTree } from "@xyz-agent/extension-protocol/background-task";
+import { killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/registry.ts

@@ -3,11 +3,11 @@
  *
  * 路径：<dataDir>/base-tool-enhance/<sessionId>/registry.json（dataDir = pi
  * getAgentDir() 同源路径，由调用方解析传入）。条目记 ownerPiPid——收殓侧属主
- * 判定依据（u-bte-remove 后 = xyz-agent runtime background-task-reaper），M2 只负责
+ * 判定依据（u-bte-remove 后 = taiji runtime background-task-reaper），M2 只负责
  * 写入。
  *
  * 行为原语单点（ext-simplify-13）：解析防御 / corrupt 隔离 / 原子写 / 序列化 /
- * 终态 LRU 裁剪自 @xyz-agent/extension-protocol background-task 子出口引入——此前
+ * 终态 LRU 裁剪自 @zhushanwen/extension-protocol background-task 子出口引入——此前
  * 本地实现与 runtime 侧逐字同构、靠注释对齐；本模块只保留 bte 形态薄壳：Map 投影
  * readRegistry 与锁内 RMW 写壳。
  *
@@ -17,7 +17,7 @@
  *    warn 等）经 onLog 注入本包 logger，落盘通道不变
  *  - 锁内 RMW（@zhushanwen/pi-file-lock withFileLockSync）——同 sessionId 目录可能
  *    被桌面端 ephemeral 附着进程与发起进程并发写，跨进程互斥只依赖同一 lockfile
- *    （runtime 收殓器写终态用 xyz-agent 统一锁，与该 lockfile 互斥）
+ *    （runtime 收殓器写终态用 taiji 统一锁，与该 lockfile 互斥）
  *  - 锁获取失败不降级无锁写：返回 {success:false}，条目停留 running 由 runtime
  *    收殓兜底（§3.5「registry/entry 写不进则条目停留 running」）
  */
@@ -26,14 +26,14 @@ import { join } from "node:path";
 
 // 契约常量（LRU 上限）走 index 出口（background-task.ts 契约面）；行为原语走
 // background-task 子出口（含 node 内建依赖，不进 index——renderer/core 零触达）
-import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@xyz-agent/extension-protocol";
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@zhushanwen/extension-protocol";
 import {
 	atomicWriteRegistry,
 	readRegistry as readRegistryEntries,
 	serializeRegistryFile,
 	trimTerminalEntries,
 	type RegistryFileLogFn,
-} from "@xyz-agent/extension-protocol/background-task";
+} from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { withFileLockSync } from "@zhushanwen/pi-file-lock";

package/src/background/spawn-background.ts

@@ -17,7 +17,7 @@ import { mkdirSync, openSync, closeSync, accessSync, constants } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
-import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "@xyz-agent/extension-protocol/background-task";
+import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/subagent-guard.ts

@@ -1,7 +1,7 @@
 /**
  * subagent 进程识别（bte background 降级判据——生命周期设计 D14 项，commit 8599abd0c）。
  *
- * 判据收敛于 ext-guards isSubagentProcess（`XYZ_AGENT_SUBAGENT === "1"`——引擎
+ * 判据收敛于 ext-guards isSubagentProcess（`TAIJI_AGENT_SUBAGENT === "1"`——引擎
  * spawn 链恒注入的统一标记，ext-simplify-17 D4 重锚定）。命中 = 当前 pi 进程是
  * 引擎链上的真 subagent → 本扩展降级：background:true 被忽略走前台同步语义。
  *

package/src/background/task-store.ts

@@ -7,7 +7,7 @@
  *
  * 条目唯一来源 = 本进程 execute 的 spawn（registerSpawnedTask 全仓唯一调用点 =
  * spawn-background.ts）。他进程 / 历史 session 的 running 条目**永不进表**——
- * 零恢复零接管，孤儿处置权统一归收殓侧（u-bte-remove 后 = xyz-agent runtime）
+ * 零恢复零接管，孤儿处置权统一归收殓侧（u-bte-remove 后 = taiji runtime）
  * 按属主裁决；终态条目可从 registry 读，仅供 bash_output 查历史。
  *
  * 终态条目 LRU 上限 MAX_TERMINAL_ENTRIES（与 registry 对称），淘汰后 bash_output
@@ -28,7 +28,7 @@
  * 未来新增写路径（如 maintenance 类）必须保持该顺序，违反即 intent 可丢失。
  */
 
-import { trimTerminalEntries } from "@xyz-agent/extension-protocol/background-task";
+import { trimTerminalEntries } from "@zhushanwen/extension-protocol/background-task";
 
 import {
 	isActiveState,

package/src/background/types.ts

@@ -8,7 +8,7 @@
  *    条目记 ownerPiPid（M2 只负责写入）
  *
  * 契约改引（u-bte-remove）：registry 持久化形状（RegistryEntry / 状态机 / reason
- * 枚举 / active·terminal 判定）与 @xyz-agent/extension-protocol background-task.ts
+ * 枚举 / active·terminal 判定）与 @zhushanwen/extension-protocol background-task.ts
  * 契约逐字段一致（契约文档头声明基线即本文件 + registry.ts），本地副本已删除、
  * 此处 re-export 并保留包内短名——消费方 import 路径与字段语义零变化。运行时
  * 对象类型（BackgroundTask / KillingIntent）不在契约内（剥离非持久字段前的形状），
@@ -19,18 +19,18 @@ import type { ChildProcess } from "node:child_process";
 import type {
 	BackgroundTaskEndReason as ContractEndReason,
 	BackgroundTaskState as ContractState,
-} from "@xyz-agent/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 /** 状态机与 reason 枚举 / 持久化条目 / active·terminal 判定：契约 SSOT re-export。 */
 export type {
 	BackgroundTaskRegistryEntry as RegistryEntry,
 	BackgroundTaskState,
 	BackgroundTaskEndReason,
-} from "@xyz-agent/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 export {
 	isActiveBackgroundTaskState as isActiveState,
 	isTerminalBackgroundTaskState as isTerminalState,
-} from "@xyz-agent/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 /**
  * killing intent：bash_kill / 后台 timeout 已发令、轮询器 exit 边沿未确认的瞬态标记。

package/src/bash-kill-tool.ts

@@ -10,7 +10,7 @@
  *
  * kill 目标归属（§3.5）：**限定本进程单例表条目**；registry 回落限定终态条目
  * （exited/orphaned → already exited）——registry 中他进程的 running/killing 条目
- * **不可 kill**（跨进程边界：处置权归发起进程；孤儿收殓已下沉 xyz-agent runtime，
+ * **不可 kill**（跨进程边界：处置权归发起进程；孤儿收殓已下沉 taiji runtime，
  * u-bte-remove 后由 background-task-reaper 按 ownerPiPid 属主判定处置）。
  * kill 前校验 pid 判活 + start time 匹配（防陈旧条目遇 pid 复用误杀无关进程，
  * 宁不杀勿误杀，§3.6 收殓侧同原则）。
@@ -18,7 +18,7 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@xyz-agent/extension-protocol/background-task";
+import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
 
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
@@ -81,7 +81,7 @@ export function createBashKillToolDefinition() {
 					);
 				}
 				// registry-only 活跃条目 = 他进程任务（本进程活跃任务必在单例表）——跨进程
-				// 不可 kill：处置权归发起进程；属主若已死，孤儿由 xyz-agent runtime 在
+				// 不可 kill：处置权归发起进程；属主若已死，孤儿由 taiji runtime 在
 				// session 销毁时或启动期兜底扫描时收殓（属主判定，u-bte-remove 下沉；
 				// 纯 CLI 独立安装无 runtime 收殓兜底，孤儿自然退出或手动杀——E11 已
 				// 接受边界，hint 按形态分流，不写死 runtime 承诺）
@@ -89,7 +89,7 @@ export function createBashKillToolDefinition() {
 					"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; " +
-						"inside the xyz-agent runtime it is collected when the owner's session ends or on app restart; " +
+						"inside the taiji runtime it is collected when the owner's session ends or on app restart; " +
 						"standalone pi: kill the process group manually (kill -- -<pgid>; the registered task pid is the pgid) if it lingers",
 				);
 			}

package/src/bash-output-tool.ts

@@ -14,7 +14,7 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { readOutputTail } from "@xyz-agent/extension-protocol/background-task";
+import { readOutputTail } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
 
 import { TAIL_MAX_BYTES, TAIL_MAX_LINES } from "./background/output-tail.ts";

package/src/index.ts

@@ -7,7 +7,7 @@
  * M3：pending-notifications 通知接入——load 时刷新轮询器通知通路的 pi 引用（D17
  * session 替换接管）+ 挂 exit 边沿通知回调（unregister emit + sendMessage steer）+
  * session_start 对账（appendEntry 权威路径兜底 pending 收尾）。
- * 收殓下沉（u-bte-remove）：M5 孤儿收殓已移交 xyz-agent runtime（background-task-
+ * 收殓下沉（u-bte-remove）：M5 孤儿收殓已移交 taiji runtime（background-task-
  * reaper 双触发面——session 销毁时 + 启动期兜底扫描，设计 file-lock-unification-
  * and-reaper-sink.md §3.2 D2），extension 不再做全局扫描/全局锁；session_start
  * 维护链仅剩 M3 对账（session 级豁免类，每 session_start 执行，D3 粒度段）。
@@ -72,7 +72,7 @@ export default function baseToolEnhanceExtension(pi: ExtensionAPI): void {
  * flag 后目标 session 的对账将永远被跳过（M3 对账在主链路被禁用，此处是唯一执行点）。
  *
  * 入口无条件 debug 日志（S6 观测通道）：每次 handler 派发都打，含 reason——
- * XYZ_AGENT_DEBUG=1 时落 extension 日志（默认 no-op），供「factory 二调下维护链
+ * TAIJI_AGENT_DEBUG=1 时落 extension 日志（默认 no-op），供「factory 二调下维护链
  * 行为」验收观测派发次数。变更登记（u-bte-remove）：reap 下沉 runtime 后本链
  * 不再含全局扫描/全局锁，原 reapSkipped 字段随 reap 调用一并移除——对应 S6
  * 场景「批 2 后 reap 类操作不再执行」。