@zhushanwen/pi-ext-guards 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ext-guards",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared runtime-environment guards for Pi extensions — oncePerProcess(key, fn) dedupes cross-session side-effect operations against pi factory re-invocation and handler accumulation (shared library, not a Pi extension, zero dependencies).",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/guard-stale-ctx.test.ts

@@ -3,7 +3,7 @@
 // guardStaleCtx 单测——验收条款逐条对应（crash-resilience u1-ext-guard）：
 //   a. 前置代际检查：isCtxStale=true → fn 不执行、stale 静默降级（返回 undefined）
 //   b. 非 stale 错误原样上抛（守卫不吞真实 bug，同步 throw 与 async rejection 双面）
-//   c. onStale 回调：前置命中无参调用；文案分诊命中携带错误调用；缺省走 XYZ_AGENT_DEBUG=1 stderr
+//   c. onStale 回调：前置命中无参调用；文案分诊命中携带错误调用；缺省走 TAIJI_AGENT_DEBUG=1 stderr
 //   d. 文案子串匹配：STALE_CTX_MARKER 命中即静默（isCtxStale=false 时文案兜底仍生效）
 //   e. async fn：stale rejection → resolve undefined；非 stale rejection → 原样 reject
 //   f. 正常路径：返回值/resolve 值原样透传（守卫不改变正常路径，A2 负面验证的单测面）
@@ -140,8 +140,8 @@ describe("guardStaleCtx async fn（F2 形态异步面，scheduler tick 迁移形
 });
 
 describe("guardStaleCtx onStale 缺省（默认 debug 日志）", () => {
-	it("XYZ_AGENT_DEBUG=1：stderr 写入守卫降级行（含 label 与错误文案）", () => {
-		vi.stubEnv("XYZ_AGENT_DEBUG", "1");
+	it("TAIJI_AGENT_DEBUG=1：stderr 写入守卫降级行（含 label 与错误文案）", () => {
+		vi.stubEnv("TAIJI_AGENT_DEBUG", "1");
 		const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
 
 		guardStaleCtx(() => {
@@ -154,8 +154,8 @@ describe("guardStaleCtx onStale 缺省（默认 debug 日志）", () => {
 		expect(line).toContain(STALE_CTX_MARKER);
 	});
 
-	it("XYZ_AGENT_DEBUG 未设：静默（不写 stderr）", () => {
-		vi.stubEnv("XYZ_AGENT_DEBUG", "");
+	it("TAIJI_AGENT_DEBUG 未设：静默（不写 stderr）", () => {
+		vi.stubEnv("TAIJI_AGENT_DEBUG", "");
 		const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
 
 		guardStaleCtx(() => {

package/src/__tests__/predicates.test.ts

@@ -59,14 +59,14 @@ describe("isEnoentError", () => {
 });
 
 describe("isSubagentProcess", () => {
-	it("XYZ_AGENT_SUBAGENT=1 命中（引擎 spawn 链恒注入的现行标记）", () => {
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+	it("TAIJI_AGENT_SUBAGENT=1 命中（引擎 spawn 链恒注入的现行标记）", () => {
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "1" })).toBe(true);
 	});
 
 	it("值非 \"1\" 不命中（标记必须是引擎注入的字面 \"1\"）", () => {
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "0" })).toBe(false);
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "" })).toBe(false);
-		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "true" })).toBe(false);
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "0" })).toBe(false);
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "" })).toBe(false);
+		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "true" })).toBe(false);
 	});
 
 	it("缺失不命中（顶层会话 → 消费方不降级）", () => {
@@ -74,28 +74,28 @@ describe("isSubagentProcess", () => {
 	});
 
 	it("env 参数注入隔离：传入的 env 与宿主 process.env 无关（宿主即使带标记，空 env 也不命中）", () => {
-		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		const saved = process.env.TAIJI_AGENT_SUBAGENT;
 		try {
-			process.env.XYZ_AGENT_SUBAGENT = "1";
+			process.env.TAIJI_AGENT_SUBAGENT = "1";
 			// 显式传 env：宿主的标记不渗透，判据只看参数
 			expect(isSubagentProcess({})).toBe(false);
-			expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+			expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "1" })).toBe(true);
 		} finally {
-			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
-			else process.env.XYZ_AGENT_SUBAGENT = saved;
+			if (saved === undefined) delete process.env.TAIJI_AGENT_SUBAGENT;
+			else process.env.TAIJI_AGENT_SUBAGENT = saved;
 		}
 	});
 
 	it("缺省参数读 process.env（不传 env 时以宿主环境为判据）", () => {
-		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		const saved = process.env.TAIJI_AGENT_SUBAGENT;
 		try {
-			process.env.XYZ_AGENT_SUBAGENT = "1";
+			process.env.TAIJI_AGENT_SUBAGENT = "1";
 			expect(isSubagentProcess()).toBe(true);
-			delete process.env.XYZ_AGENT_SUBAGENT;
+			delete process.env.TAIJI_AGENT_SUBAGENT;
 			expect(isSubagentProcess()).toBe(false);
 		} finally {
-			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
-			else process.env.XYZ_AGENT_SUBAGENT = saved;
+			if (saved === undefined) delete process.env.TAIJI_AGENT_SUBAGENT;
+			else process.env.TAIJI_AGENT_SUBAGENT = saved;
 		}
 	});
 

package/src/index.ts

@@ -109,14 +109,14 @@ export function isEnoentError(err: unknown): boolean {
 // （base-tool-enhance background 降级——bte background 生命周期设计的 D14 项，
 // commit 8599abd0c，该设计未在现行 docs 留档 / smart-context R6 不注册工具，
 // 规则定义见 smart-context src/index.ts R 规则族注释）。判据锚
-// XYZ_AGENT_SUBAGENT=1——subagent-engine-sdk env.ts 的 buildEngineChildEnv 对每个引擎
+// TAIJI_AGENT_SUBAGENT=1——subagent-engine-sdk env.ts 的 buildEngineChildEnv 对每个引擎
 // 子进程恒注入（L0 层最后写入），再经引擎内二次 spawn（buildOutboundChildEnv 全量
 // 继承）传到 subagent 内的 bash。旧判据（PI_SUBAGENT_ROOT_SESSION_ID /
 // PI_SUBAGENT_SELF_RECORD_ID 两键）在引擎协议化后已无写入方（20260914 探针证实，
 // 报告 .tmp/dev-flow/ext-simplify-17-d4-probe.md），判据失效态由 D4 重锚收敛于此。
 
 /** subagent 进程标记 env 键（引擎 spawn 链恒注入 "1"，subagent-engine-sdk env.ts L0）。 */
-export const SUBAGENT_MARKER_ENV = "XYZ_AGENT_SUBAGENT";
+export const SUBAGENT_MARKER_ENV = "TAIJI_AGENT_SUBAGENT";
 
 /**
  * 判断当前进程是否引擎链上的 subagent 子进程。
@@ -137,7 +137,7 @@ export function isSubagentProcess(
 
 // ── stale ctx 守卫（guardStaleCtx，崩溃韧性 D1）────────────────────────
 //
-// 背景（docs/design/crash-resilience.md §3.3 D1 / §2.2 事件 E1）：pi 的 extension API
+// 背景：pi 的 extension API
 // 对象（pi / ctx）在 session 替换（newSession/fork/switchSession/reload）后被 runner
 // 标记 stale，再调用其方法会**同步抛错**（loader.js/runner.js 的 assertActive，错误文案
 // 含 STALE_CTX_MARKER）。跨 session 生命周期存活的异步回调（compact 的 onComplete/onError、
@@ -172,7 +172,7 @@ export interface GuardStaleCtxOptions {
 	isCtxStale?: () => boolean;
 	/**
 	 * stale 降级通知（静默降级的观测点）：前置检查命中时无参调用；fn 抛错被分诊为
-	 * stale 时以捕获的错误为参调用。缺省 = 仅 XYZ_AGENT_DEBUG=1 时写一行 stderr
+	 * stale 时以捕获的错误为参调用。缺省 = 仅 TAIJI_AGENT_DEBUG=1 时写一行 stderr
 	 * debug（本包零依赖、无 pi handle，不能走 extension-logger；需要落盘日志的
 	 * 接入方传入自己的 debugLog/logger.warn）。
 	 */
@@ -189,9 +189,9 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 	);
 }
 
-/** 缺省降级通知：XYZ_AGENT_DEBUG=1 时 stderr 一行（对齐 extensions 包 XYZ_AGENT_DEBUG 惯例）。 */
+/** 缺省降级通知：TAIJI_AGENT_DEBUG=1 时 stderr 一行（对齐 extensions 包 TAIJI_AGENT_DEBUG 惯例）。 */
 function defaultOnStale(label: string, error?: unknown): void {
-	if (process.env.XYZ_AGENT_DEBUG !== "1") return;
+	if (process.env.TAIJI_AGENT_DEBUG !== "1") return;
 	const detail =
 		error === undefined
 			? "generation check (isCtxStale)"