@zhushanwen/pi-structured-output 5.1.4 → 5.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "5.1.4",
+  "version": "5.1.6",
   "description": "Structured output tool for Pi — workflow schema enforcement via pi's parameter layer; interactive mode validates self-reported schemas with Ajv",
   "type": "module",
   "main": "index.ts",
@@ -24,7 +24,8 @@
     "index.ts"
   ],
   "dependencies": {
-    "ajv": "^8.17.0"
+    "ajv": "^8.17.0",
+    "@zhushanwen/pi-ext-guards": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/execute.ts

@@ -20,12 +20,13 @@
 
 import type { ValidateFunction } from "ajv";
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
+
 import { getOrCompileValidator } from "./ajv-validator.js";
 import {
 	CORRECT_USAGE_HINT,
 	echo,
 	hasSchemaKeyword,
-	isPlainObject,
 	tryParseJson,
 } from "./schema-guards.js";
 
@@ -47,7 +48,7 @@ import {
  * 其 ASP 文案按本判定同源条件化——改动本函数判定逻辑必须同步该副本。
  */
 export function isObjectRootSchema(schema: unknown): schema is Record<string, unknown> {
-	if (!isPlainObject(schema)) return false;
+	if (!isRecord(schema)) return false;
 	if (schema.type === "object") return true;
 	if (Array.isArray(schema.type) && schema.type.includes("object")) return true;
 	const OBJECT_ONLY_KEYS = [
@@ -71,7 +72,7 @@ export function isObjectRootSchema(schema: unknown): schema is Record<string, un
  * 不在 execute 层制造第二道校验。
  */
 function unwrapValueField(data: unknown): unknown {
-	if (isPlainObject(data) && "value" in data) {
+	if (isRecord(data) && "value" in data) {
 		return data.value;
 	}
 	return data;
@@ -88,7 +89,7 @@ export function validateAgainstSelfReported(schema: unknown, data: unknown): boo
 	// 1. 互换检测：schema 像数据（对象无 keyword）且 data 像 schema（对象有 keyword）。
 	// 这是最严重的静默腐败路径——若放行，ajv 会把"数据形态的 schema"编译成接受一切，
 	// 真正的 schema（此时在 data 里）被丢弃，校验通过并存入垃圾。
-	if (isPlainObject(schema) && !hasSchemaKeyword(schema) && isPlainObject(data) && hasSchemaKeyword(data)) {
+	if (isRecord(schema) && !hasSchemaKeyword(schema) && isRecord(data) && hasSchemaKeyword(data)) {
 		throw new Error(
 			"Likely swapped: schema looks like data and data looks like a schema. "
 			+ CORRECT_USAGE_HINT
@@ -98,7 +99,7 @@ export function validateAgainstSelfReported(schema: unknown, data: unknown): boo
 
 	// 2. keyword-less schema 拒绝：治静默腐败的根。{} / {a:1} 这类对象会被
 	// ajv strict:false 编译成"接受一切"的 validator，模型把答案塞进 schema 时会静默通过。
-	if (isPlainObject(schema) && !hasSchemaKeyword(schema)) {
+	if (isRecord(schema) && !hasSchemaKeyword(schema)) {
 		throw new Error(
 			"Invalid JSON Schema: schema has no recognized keyword "
 			+ "(type/properties/items/enum/...). If you passed the answer value as schema, "
@@ -113,7 +114,7 @@ export function validateAgainstSelfReported(schema: unknown, data: unknown): boo
 	// object|boolean，消除原先的 `as Record<string,unknown>` 不安全 cast。
 	let validate: ValidateFunction;
 	try {
-		if (isPlainObject(schema) || typeof schema === "boolean") {
+		if (isRecord(schema) || typeof schema === "boolean") {
 			validate = getOrCompileValidator(schema);
 		} else {
 			throw new Error(`schema must be a JSON Schema object or boolean, got ${typeof schema}`);

package/src/loop-gate.ts

@@ -41,8 +41,9 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { guardStaleCtx, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
-import { isPlainObject, isToolExecutionEndEvent } from "./schema-guards.js";
+import { isToolExecutionEndEvent } from "./schema-guards.js";
 import {
 	extractToolErrorText,
 	SIGNATURE_MAX_CHARS,
@@ -247,10 +248,10 @@ function keysAtPath(args: Record<string, unknown>, path: string): string[] {
 			current = current[index];
 			continue;
 		}
-		if (!isPlainObject(current) || !(segment in current)) return [];
+		if (!isRecord(current) || !(segment in current)) return [];
 		current = current[segment];
 	}
-	return isPlainObject(current) ? Object.keys(current) : [];
+	return isRecord(current) ? Object.keys(current) : [];
 }
 
 /**
@@ -282,7 +283,7 @@ function parseArgsEchoObject(errorText: string, markerIdx: number): Record<strin
 	if (!echoSection) return undefined;
 	try {
 		const parsed: unknown = JSON.parse(echoSection);
-		return isPlainObject(parsed) ? parsed : undefined;
+		return isRecord(parsed) ? parsed : undefined;
 	} catch {
 		return undefined;
 	}
@@ -391,36 +392,9 @@ export class LoopGate {
 /** terminal 日志的 appendEntry customType（session.jsonl 持久化，不进 LLM 上下文）。 */
 export const GATE_ENTRY_TYPE = "structured-output:gate";
 
-/**
- * setTimeout delay 安全域校验。[同源锚定] @zhushanwen/pi-subagent-workflow 的
- * shared/timer-delay.ts assertSafeTimerDelay 本地副本——两包独立 npm 不能直接
- * import（isObjectRootSchema 本地副本同例：跨包相对 import 在发布产物里悬空），
- * 本包仅此一个 timer 入口，取最小面副本。语义同源：非有限值 / 超 2^31-1 的 delay
- * 会被 Node 塌缩为 1ms 立即触发（语义反转：兜底窗口变成立即硬杀），fail-fast 不
- * 静默 clamp（clamp 把配置错误变成静默语义漂移）。
- */
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-
 /** 每秒毫秒数（teardown 日志 ms→s 换算用，no-magic-numbers）。 */
 const MS_PER_SECOND = 1000;
 
-export function assertSafeTimerDelay(ms: number, source: string): void {
-	if (!Number.isFinite(ms)) {
-		throw new Error(
-			`[structured-output] ${source} = ${ms} is not a finite number (NaN/±Infinity). `
-				+ "Non-finite delays collapse to 1ms in Node setTimeout and fire immediately. "
-				+ "Recovery: fix the constant/computation feeding this timer and retry.",
-		);
-	}
-	if (ms > MAX_TIMER_DELAY_MS) {
-		throw new Error(
-			`[structured-output] ${source} = ${ms} exceeds the Node setTimeout limit `
-				+ `(${MAX_TIMER_DELAY_MS} ms = 2^31-1); larger delays silently collapse to 1ms and fire immediately. `
-				+ `Recovery: clamp the value to <= ${MAX_TIMER_DELAY_MS} and retry.`,
-		);
-	}
-}
-
 /**
  * terminal 后 bounded teardown 的兜底硬退窗口（ms）。
  *
@@ -434,6 +408,10 @@ export function assertSafeTimerDelay(ms: number, source: string): void {
  * 后正常退出秒级完成），兜底只覆盖「pi 挂死不 settle」的异常态——此时宁可硬退
  *（父进程 SW 侧走「子进程结束未产出 structured-output」失败路径，stderr 已留原因）
  * 也不无限烧 token。
+ *
+ * 安全域：15_000 为字面量常量，处于 Node setTimeout 安全域内（非有限/超 2^31-1
+ * 会塌缩为 1ms 立即触发——若未来 delay 来源动态化，需引入安全域校验，参照
+ * packages/subagent-core/src/shared/timer-delay.ts 的 assertSafeTimerDelay）。
  */
 export const TEARDOWN_FORCE_EXIT_MS = 15_000;
 
@@ -443,24 +421,10 @@ export const TEARDOWN_FORCE_EXIT_MS = 15_000;
  */
 const TEARDOWN_EXIT_CODE = 1;
 
-/** 已武装的兜底硬退 timer：globalThis[Symbol.for] slot 持有（C-ext-06，照 notify-ledger
- *  先例）——jiti 路径分裂加载多份模块时裸模块级 let 双实例各持 timer（失效模式良性：
- *  至多双 timer 各自 process.exit，进程级幂等）；slot 化后单介质同源，幂等再清语义不变。 */
-const TEARDOWN_TIMER_SLOT_KEY = Symbol.for("@zhushanwen/pi-structured-output.loopGate.teardownTimer");
-
-type TeardownTimerSlot = { current: ReturnType<typeof setTimeout> | undefined };
-
-function getTeardownTimerSlot(): TeardownTimerSlot {
-	// globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写
-	//（notify-ledger getNotifyLedgerSlot 同款）。TeardownTimerSlot 是运行时保证的
-	// 固定形状（本文件唯一写入点）。
-	let slot = Reflect.get(globalThis, TEARDOWN_TIMER_SLOT_KEY) as TeardownTimerSlot | undefined;
-	if (!slot) {
-		slot = { current: undefined };
-		Reflect.set(globalThis, TEARDOWN_TIMER_SLOT_KEY, slot);
-	}
-	return slot;
-}
+// one-shot timer 不属 C-ext-06 §7.5 的「跨 session 存活进程级单例」范畴：
+// terminal 一次性武装、随 process.exit 消亡；jiti 双实例下双 timer 各自
+// process.exit 进程级幂等，模块级 let 即可。
+let teardownTimer: ReturnType<typeof setTimeout> | undefined;
 
 /**
  * 武装 terminal 后的 bounded teardown 兜底：TEARDOWN_FORCE_EXIT_MS 后进程仍未退出
@@ -474,14 +438,12 @@ function getTeardownTimerSlot(): TeardownTimerSlot {
  * 能做的最大硬杀就是对自身 process.exit。故采用任务预设的兜底形态：abort+shutdown
  * 优雅退出为主，定时 process.exit 兜底。
  *
- * timer 卫生：assertSafeTimerDelay 包裹（防未来常量演化溢出塌缩为 1ms 立即硬杀）+
+ * timer 卫生：delay 为字面量常量、处 setTimeout 安全域（见 TEARDOWN_FORCE_EXIT_MS 注释）+
  * unref（不阻止 pi 在窗口内自然退出；自然退出时本 timer 随进程消亡不再开火）+
  * terminal 路径幂等 clearTimeout（重复武装不叠加多个兜底 timer）。
  */
 export function armForceExitTeardown(): void {
-	const slot = getTeardownTimerSlot();
-	if (slot.current !== undefined) clearTimeout(slot.current);
-	assertSafeTimerDelay(TEARDOWN_FORCE_EXIT_MS, "structured-output gate teardown");
+	if (teardownTimer !== undefined) clearTimeout(teardownTimer);
 	const timer = setTimeout(() => {
 		process.stderr.write(
 			`[structured-output gate] graceful shutdown did not complete within ${TEARDOWN_FORCE_EXIT_MS / MS_PER_SECOND}s; `
@@ -491,7 +453,7 @@ export function armForceExitTeardown(): void {
 	}, TEARDOWN_FORCE_EXIT_MS);
 	// unref：窗口内 pi 自然退出时不被本 timer 拖住（timer 随进程消亡，不再开火）
 	timer.unref();
-	slot.current = timer;
+	teardownTimer = timer;
 }
 
 /**
@@ -522,7 +484,7 @@ function writeTerminatedLog(pi: PiAPI, gate: LoopGate): void {
 	} catch (err) {
 		// appendEntry 失败不阻断 shutdown——stderr 通道已落，此处补诊断（同 cache-probe 惯例）
 		process.stderr.write(
-			`[structured-output gate] appendEntry failed: ${err instanceof Error ? err.message : String(err)}\n`,
+			`[structured-output gate] appendEntry failed: ${toErrorMessage(err)}\n`,
 		);
 	}
 }
@@ -558,8 +520,23 @@ export function setupLoopGate(pi: PiAPI, options: LoopGateOptions = {}): LoopGat
 
 		options.onTerminal?.();
 		writeTerminatedLog(pi, gate);
-		ctx.abort();
-		ctx.shutdown();
+		// stale ctx 防御（crash-resilience D1）：abort/shutdown 均在 pi assertActive 面
+		// （PS-30，runner.js createContext）——session 替换窗口触发 terminal 时无人接的
+		// 同步 throw 会经 async handler 变 rejected Promise 杀 pi 进程。stale 静默跳过
+		// 优雅退出（此时进程的存在意义已随 session 替换消失），armForceExitTeardown 的
+		// 15s 硬退兜底保持武装——自清理语义不丢。非 stale 错误原样上抛（守卫不吞真实 bug）。
+		guardStaleCtx(() => {
+			ctx.abort();
+			ctx.shutdown();
+		}, {
+			label: "structured-output:terminal-teardown",
+			onStale: (error) => {
+				process.stderr.write(
+					`[structured-output gate] terminal teardown skipped (stale ctx, session replaced): `
+						+ `${toErrorMessage(error)}; force-exit timer stays armed.\n`,
+				);
+			},
+		});
 		armForceExitTeardown();
 	});
 

package/src/schema-guards.ts

@@ -10,6 +10,8 @@
  * keyword-less schema（{} / {a:1} 这种会被 ajv 静默放行）。
  */
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
+
 /** JSON Schema draft-07 识别 keyword。只要 schema 含其一就认为是"真 schema"。 */
 export const SCHEMA_KEYWORDS = [
 	// 核心类型
@@ -35,9 +37,12 @@ export const SCHEMA_KEYWORDS = [
 	"minLength", "maxLength", "pattern", "format",
 ] as const;
 
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+/**
+ * @deprecated 深路径公开名兼容别名（ext-simplify-18 D2）；新代码直接用 ext-guards isRecord。
+ * 本包独立发布、无 exports 字段且 files 含 src/（深路径对外可达），公开名直接删除是
+ * breaking——保留一个发布周期的 re-export，删除时点登记在 ext-simplify index 18 号行。
+ */
+export const isPlainObject = isRecord;
 
 export function hasSchemaKeyword(obj: Record<string, unknown>): boolean {
 	return SCHEMA_KEYWORDS.some((keyword) => keyword in obj);
@@ -79,7 +84,7 @@ export function tryParseJson(raw: unknown): unknown {
  * 避免在守卫块外直接用 unknown。非合法形态抛清晰错误。
  */
 export function assertJsonSchemaRoot(value: unknown): asserts value is Record<string, unknown> | boolean {
-	if (!(isPlainObject(value) || typeof value === "boolean")) {
+	if (!(isRecord(value) || typeof value === "boolean")) {
 		throw new Error(`authoritative schema must be a JSON Schema object or boolean, got ${typeof value}`);
 	}
 }

package/src/text-primitives.ts

@@ -40,10 +40,9 @@ export function truncateText(text: string, max: number): string {
  *
  * Pi 框架在参数层校验失败（immediate 路径）与 execute 抛错时，均构造
  * `{ content: [{ type: "text", text }] }` 塞进 result.content[0].text
- * （agent-loop.js createErrorToolResult；见 extensions/universal/unified-hooks 的
- * extractErrorText 及其文档：SDK 事件结构里没有独立 errorMessage 字段，错误文本只能从
- * result.content 里取）。loop-gate（D3）复用本函数提取签名原料，workflow-hook 取
- * steer 回灌文本。
+ * （agent-loop.js createErrorToolResult；SDK 事件结构里没有独立 errorMessage 字段，
+ * 错误文本只能从 result.content 里取）。loop-gate（D3）复用本函数提取签名原料，
+ * workflow-hook 取 steer 回灌文本。
  * 这里防御性取多种结构，取不到就返回 undefined（调用方降级为通用提示）。
  */
 export function extractToolErrorText(result: unknown): string | undefined {

package/src/tool-definition.ts

@@ -18,6 +18,7 @@
  * 两变体的描述文本均被 prompt-quality.test.ts 文本断言锁定。
  */
 
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 import { Type } from "typebox";
 
 import { executeStructuredOutput, isObjectRootSchema } from "./execute.js";
@@ -25,7 +26,6 @@ import {
 	assertJsonSchemaRoot,
 	echo,
 	hasSchemaKeyword,
-	isPlainObject,
 	tryParseJson,
 } from "./schema-guards.js";
 
@@ -93,7 +93,7 @@ export function createWorkflowToolDefinition(envSchema: string) {
 		);
 	}
 
-	if (isPlainObject(schema) && !hasSchemaKeyword(schema)) {
+	if (isRecord(schema) && !hasSchemaKeyword(schema)) {
 		// ERR-3 上移：keyword-less 对象会被编译成 accept-all，workflow 声明的约束静默失效。
 		throw new Error(
 			"Authoritative schema (PI_WORKFLOW_SCHEMA) has no recognized keyword. "

package/src/workflow-hook.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // 截断原语与错误块预算来自 text-primitives（共享叶节点，导出复用勿复制）。原
 // 「反向依赖（环）」已破除：本模块不再 import loop-gate，依赖图单向
@@ -95,7 +96,7 @@ export const HOOK_ENTRY_TYPE = "structured-output:hook";
  * 下一个正常收尾的轮仍会重试 steer，不产生静默哑火。
  */
 function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): void {
-	const message = err instanceof Error ? err.message : String(err);
+	const message = toErrorMessage(err);
 	process.stderr.write(
 		`[structured-output hook] steer send failed (retry budget NOT consumed, will retry at next turn end): ${message}\n`,
 	);
@@ -110,7 +111,7 @@ function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): v
 	} catch (appendErr) {
 		// appendEntry 失败不阻断 hook——stderr 通道已落，此处补诊断（同 cache-probe 惯例）
 		process.stderr.write(
-			`[structured-output hook] appendEntry failed: ${appendErr instanceof Error ? appendErr.message : String(appendErr)}\n`,
+			`[structured-output hook] appendEntry failed: ${toErrorMessage(appendErr)}\n`,
 		);
 	}
 }