@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/execution/{spawn-event-adapter.ts → engine/engines/pi/spawn-event-adapter.ts}

@@ -1,4 +1,4 @@
-// src/core/spawn-event-adapter.ts
+// src/execution/engine/engines/pi/spawn-event-adapter.ts
 //
 // pi 子进程 stdout JSON 事件流的解析器。Core 叶子原语（仅依赖 types.ts）。
 //
@@ -20,7 +20,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import type { SdkEvent } from "./types.ts";
+import type { SdkEvent } from "../../../types.ts";
+import { toErrorMessage } from "../../../../core/error-message.ts";
 
 /** pi stdout header 行（session 元信息）。type 固定为 "session"。 */
 export interface SpawnSessionHeader {
@@ -158,6 +159,56 @@ function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
   );
 }
 
+/** 必填 string 字段提取：类型不符降级空串（字段容错——仍归类已知 method，不丢 method 信息）。 */
+function reqStr(r: Record<string, unknown>, key: string): string {
+  const v = r[key];
+  return typeof v === "string" ? v : "";
+}
+
+/** string[] 字段提取：数组剔除非字符串元素；非数组降级 onMissing（options 传 []，
+ *  widgetLines 传 undefined——两者对缺失值的载荷语义不同：前者恒挂键，后者键挂值 undefined）。 */
+function strArrayField<T extends string[] | undefined>(
+  r: Record<string, unknown>,
+  key: string,
+  onMissing: T,
+): string[] | T {
+  const v = r[key];
+  return Array.isArray(v)
+    ? v.filter((x): x is string => typeof x === "string")
+    : onMissing;
+}
+
+/** timeout 条件展开：非 number 不挂键（timeout?: number 的字段省略语义）。 */
+function optTimeout(r: Record<string, unknown>): { timeout?: number } {
+  return typeof r.timeout === "number" ? { timeout: r.timeout } : {};
+}
+
+/** placeholder 条件展开：非 string 不挂键。 */
+function optPlaceholder(r: Record<string, unknown>): { placeholder?: string } {
+  return typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {};
+}
+
+/** prefill 条件展开：非 string 不挂键。 */
+function optPrefill(r: Record<string, unknown>): { prefill?: string } {
+  return typeof r.prefill === "string" ? { prefill: r.prefill } : {};
+}
+
+/** notifyType 条件展开：仅接受三种已知枚举值，其余不挂键。 */
+function optNotifyType(
+  r: Record<string, unknown>
+): { notifyType?: "info" | "warning" | "error" } {
+  const v = r.notifyType;
+  return v === "info" || v === "warning" || v === "error" ? { notifyType: v } : {};
+}
+
+/** widgetPlacement 条件展开：仅接受两种已知枚举值，其余不挂键。 */
+function optWidgetPlacement(
+  r: Record<string, unknown>
+): { widgetPlacement?: "aboveEditor" | "belowEditor" } {
+  const v = r.widgetPlacement;
+  return v === "aboveEditor" || v === "belowEditor" ? { widgetPlacement: v } : {};
+}
+
 /**
  * 从已通过 isExtensionUiRequest 守卫的 envelope 构造 ExtensionUiRequest 变体。
  *
@@ -166,6 +217,7 @@ function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
  *
  * 字段类型容错：协议字段类型不符（如 options 非数组）时，该字段降级为空数组/undefined
  *（数组类字段做元素类型过滤，剔除非字符串元素），仍归类为已知 method（不丢 method 信息）。
+ * 字段级提取/条件展开由上方字段 helper 承担，本函数只做 method 分发。
  */
 function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRequest {
   const r: Record<string, unknown> = env;
@@ -173,69 +225,58 @@ function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRe
     case "select":
       return {
         method: "select",
-        title: typeof r.title === "string" ? r.title : "",
-        options: Array.isArray(r.options)
-          ? r.options.filter((x): x is string => typeof x === "string")
-          : [],
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        options: strArrayField(r, "options", []),
+        ...optTimeout(r),
       };
     case "confirm":
       return {
         method: "confirm",
-        title: typeof r.title === "string" ? r.title : "",
-        message: typeof r.message === "string" ? r.message : "",
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        message: reqStr(r, "message"),
+        ...optTimeout(r),
       };
     case "input":
       return {
         method: "input",
-        title: typeof r.title === "string" ? r.title : "",
-        ...(typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {}),
-        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+        title: reqStr(r, "title"),
+        ...optPlaceholder(r),
+        ...optTimeout(r),
       };
     case "editor":
       return {
         method: "editor",
-        title: typeof r.title === "string" ? r.title : "",
-        ...(typeof r.prefill === "string" ? { prefill: r.prefill } : {}),
+        title: reqStr(r, "title"),
+        ...optPrefill(r),
       };
     case "notify":
       return {
         method: "notify",
-        message: typeof r.message === "string" ? r.message : "",
-        ...(r.notifyType === "info" || r.notifyType === "warning" || r.notifyType === "error"
-          ? { notifyType: r.notifyType }
-          : {}),
+        message: reqStr(r, "message"),
+        ...optNotifyType(r),
       };
     case "setStatus":
       return {
         method: "setStatus",
-        statusKey: typeof r.statusKey === "string" ? r.statusKey : "",
+        statusKey: reqStr(r, "statusKey"),
         statusText: typeof r.statusText === "string" ? r.statusText : undefined,
       };
-    case "setWidget": {
-      const placement = r.widgetPlacement;
-      const widgetLines = Array.isArray(r.widgetLines)
-        ? r.widgetLines.filter((x): x is string => typeof x === "string")
-        : undefined;
+    case "setWidget":
       return {
         method: "setWidget",
-        widgetKey: typeof r.widgetKey === "string" ? r.widgetKey : "",
-        widgetLines,
-        ...(placement === "aboveEditor" || placement === "belowEditor"
-          ? { widgetPlacement: placement }
-          : {}),
+        widgetKey: reqStr(r, "widgetKey"),
+        widgetLines: strArrayField(r, "widgetLines", undefined),
+        ...optWidgetPlacement(r),
       };
-    }
     case "setTitle":
       return {
         method: "setTitle",
-        title: typeof r.title === "string" ? r.title : "",
+        title: reqStr(r, "title"),
       };
     case "set_editor_text":
       return {
         method: "set_editor_text",
-        text: typeof r.text === "string" ? r.text : "",
+        text: reqStr(r, "text"),
       };
     default:
       // 未知 method：保留全部原始字段，避免协议演进时丢信息
@@ -273,7 +314,7 @@ export function parseSpawnLine(line: string): ParsedSpawnLine | null {
     return {
       kind: "invalid",
       raw: trimmed,
-      error: err instanceof Error ? err.message : String(err),
+      error: toErrorMessage(err),
     };
   }
 

package/src/execution/{stdin-writer.ts → engine/engines/pi/stdin-writer.ts}

@@ -1,4 +1,4 @@
-// src/execution/stdin-writer.ts
+// src/execution/engine/engines/pi/stdin-writer.ts
 //
 // 向 rpc 子进程 stdin 写入命令的 helper 集合。
 //
@@ -10,9 +10,10 @@
 import type { ChildProcess } from "node:child_process";
 import * as crypto from "node:crypto";
 
-import { getLogger } from "../core/logger.ts";
+import { getLogger } from "../../../../core/logger.ts";
 
-import type { UiResponse } from "./dialog-queue.ts";
+import type { UiResponse } from "../../../dialog-queue.ts";
+import { toErrorMessage } from "../../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
@@ -25,7 +26,7 @@ const logger = getLogger("subagents");
  * 是 stdin 域中立模块，epipe 计数属 stdin 错误域，职责合理。
  *
  * 错误处理两半面共用本计数器（合并计数，防 spawn→EPIPE→resume 死循环）：
- *   ① 同步 write 抛错（writeStdinLine throw → deliverMessage catch 递增）
+ *   ① 同步 write 抛错（writeStdinLine throw → PiEngine.deliverPrompt catch 递增）
  *   ② 异步 stream 'error' event（session-runner.ts child.stdin.on('error') 递增）
  */
 const epipeConsecutiveFailures = new Map<string, number>();
@@ -79,7 +80,7 @@ export function respond(child: ChildProcess, id: string, out: UiResponse, signal
   } catch (err) {
     // [R2] out.value 含循环引用/BigInt 等不可序列化结构——降级 cancelled，避免父进程崩溃。
     logger.warn(`[subagents] JSON.stringify failed for ui response ${id}, degrading to cancelled`, {
-      detail: err instanceof Error ? err.message : String(err),
+      detail: toErrorMessage(err),
     });
     line = JSON.stringify({ type: "extension_ui_response", id, cancelled: true });
   }
@@ -158,7 +159,7 @@ export function sendGetStateCommand(child: ChildProcess): string {
  *
  * [R1] write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
  * [R3] write 抛 EPIPE / ERR_STREAM_DESTROYED 时 throw 含 EPIPE 关键词的 Error，
- *      让上层（deliverMessage）能捕获并自动转冷路径 resume。
+ *      让上层（PiEngine.deliverPrompt）能捕获并自动转冷路径 resume。
  * stdin 已关闭/销毁时跳过——respond 已检查 signal，sendPromptCommand 已检查 destroyed。
  *
  * @param child 子进程
@@ -173,11 +174,11 @@ function writeStdinLine(child: ChildProcess, line: string, warnTag: string): voi
     if (!ok) logger.warn(`[subagents] stdin backpressure on ${warnTag}`);
   } catch (err) {
     // [R3] EPIPE / ERR_STREAM_DESTROYED：stdin 管道已断，子进程已退出或 stdin 被销毁。
-    // [v4 A-1] 错误处理两半面：① 同步 write 抛错（本 catch）——上层 deliverMessage 捕获后
+    // [v4 A-1] 错误处理两半面：① 同步 write 抛错（本 catch）——上层（PiEngine.deliverPrompt）捕获后
     //   调 recordEpipeFailure 递增计数；② 异步 stream 'error' event（session-runner.ts 的
     //   child.stdin.on('error') listener）。两者共用本模块 export 的 recordEpipeFailure
     //   helper 合并计数（防 spawn→EPIPE→resume 死循环）。
-    // throw 让上层（deliverMessage）捕获并自动转冷路径 resume + 消息重放。
+    // throw 让上层（PiEngine.deliverPrompt）捕获并自动转冷路径 resume + 消息重放。
     if (
       err !== null &&
       typeof err === "object" &&
@@ -192,7 +193,7 @@ function writeStdinLine(child: ChildProcess, line: string, warnTag: string): voi
     }
     // 非 EPIPE 错误（不应发生，但兜底降级为 warn 不崩溃）
     logger.warn(`[subagents] unexpected stdin write error on ${warnTag}`, {
-      detail: err instanceof Error ? err.message : String(err),
+      detail: toErrorMessage(err),
     });
   }
 }

package/src/execution/{temp-prompt.ts → engine/engines/pi/temp-prompt.ts}

@@ -1,4 +1,4 @@
-// src/core/temp-prompt.ts
+// src/execution/engine/engines/pi/temp-prompt.ts
 //
 // 将 agent systemPrompt 写入临时文件，供 pi CLI --append-system-prompt 使用。
 // Core 叶子原语（node 内置 + 同目录 bestEffort 清理 helper）。注意 bestEffort
@@ -14,7 +14,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { bestEffort } from "./best-effort.ts";
+import { bestEffort } from "../../../best-effort.ts";
 
 /** 临时 prompt 文件创建结果。dir 供调用方清理。 */
 export interface TempPromptFile {

package/src/execution/{turn-limiter.ts → engine/engines/pi/turn-limiter.ts}

@@ -1,4 +1,4 @@
-// src/core/turn-limiter.ts
+// src/execution/engine/engines/pi/turn-limiter.ts
 //
 // soft/hard turn 限制器。maxTurns 到达 → steer 提醒收尾；
 // graceTurns 后仍不结束 → abort。

package/src/execution/engine/engines/zcode/__tests__/__fixtures__/fake-appserver.mjs

@@ -43,13 +43,29 @@
  *     sendPushes?:  [frame, ...]       send 应答前逐帧推送（推送流 + 终态帧全显式
  *                                      逐字回放，不经 withExtra 改写）
  *     sendResult?:  object             缺省 {accepted:true}
+ *     crashAfterSendMs?: number        [P0-1 U4] send 应答后 N ms 自杀 exit(1)（连接
+ *                                      崩溃收割注入——onClose → failAllTurns 在途
+ *                                      turn 收割；进程死 → 下次 request 惰性重建
+ *                                      boot 新代重读 scenario，重试轮/下一任务形态
+ *                                      切换经测试侧 rewriteScenario）
+ *     rebootSendPushes?: [frame, ...]  [P0-1 U4] 非首代进程（本 fake 启动时 state 流水
+ *                                      已有 boot 记录——崩溃/杀链后的重建代）的 send
+ *                                      推送序列，替代 sendPushes：崩溃后惰性重建的
+ *                                      重试轮拿到不同行为（如完整终态流）——首轮挂起
+ *                                      + 重试轮成功的静态注入通道（同任务重试轮无法
+ *                                      经测试侧 rewriteScenario 插手，run 整体 await）
  *     readError?:   {code,message,data} read 应答 error 帧（read 兜底降级链断言）
  *     readResult?:  object             覆盖 read 应答
- *     stopBehavior?: 'terminal'|'none'  session/stop 的行为（R4 abort 链断言面）：
+ *     stopBehavior?: 'terminal'|'none'|'hang'
+ *                                      session/stop 的行为（R4 abort 链断言面）：
  *                                      'terminal'（缺省）= stop 时推送该会话的
  *                                      turn.terminal 终态帧（stop 优雅生效——不杀
  *                                      进程的 abort 路径）；'none' = 只应答不推终态
- *                                      （grace 窗口耗尽 → killChain 兜底路径）
+ *                                      （grace 窗口耗尽 → killChain 兜底路径）；
+ *                                      'hang' = 连应答都不给（P0-1 U2 超时入口态③——
+ *                                      控制面假死注入，stop 3s 超时 → 连接级失败判据）
+ *     stopError?:   {code,message,data} stop 应答 error 帧（P0-1 U2 超时入口态②——
+ *                                      协议性 error（如会话已回收）注入，断言不升级杀链）
  *   }
  *
  * 多会话支持（R4 引擎接线 / RA3 双会话地基）：
@@ -59,15 +75,6 @@
  *                          （缺省关：R2/R3 单会话用例的字节级行为不变。）
  *   session/stop           应答 {stopped:true}；按 scenario.stopBehavior 决定是否
  *                          推送终态帧（见上）。stopTerminal 推送同样受 STAMP 改写。
- *
- * 探针连接支持（R5 降级链——D8 冒烟探针 / D2 门控断言面）：
- *   ZCODE_APPSERVER_PROBE_CONN=1  本进程是探针连接（引擎 runAppServerSmokeProbe 叠加
- *                          的 env 标记）：scenario 只读 FAKE_PROBE_SCENARIO（常驻
- *                          主连接的 FAKE_SESSION_SCENARIO 不作用于探针——故障注入可
- *                          只命中主连接或只命中探针）；env 快照记 probe 标志。
- *   FAKE_PROBE_SCENARIO=<path>    仅探针进程消费的 JSON：
- *     { createError?: {code,message,data} }  探针 create 应答 error 帧（探针失败注入）
- *     { hangCreate?: true }                   create 永不应答（预算超时注入）
  */
 import fs from 'node:fs';
 import readline from 'node:readline';
@@ -77,25 +84,28 @@ const EXTRA_KEYS = process.env.FAKE_EXTRA_KEYS === '1';
 const PROTOCOL_AS_PUSH = process.env.FAKE_PROTOCOL_PUSH === '1';
 // [R4] 多会话推送改写开关（见文件头注释）
 const STAMP_SESSION = process.env.FAKE_STAMP_SESSION === '1';
-// [R5] 探针连接判定（引擎探针在 env 叠 ZCODE_APPSERVER_PROBE_CONN=1——见 appserver-probe.ts）
-const IS_PROBE = process.env.ZCODE_APPSERVER_PROBE_CONN === '1';
 
-// 会话场景（R3/R5）：启动时读取一次（env 固化语义与其他 FAKE_ 开关一致）。探针进程
-// 只读 FAKE_PROBE_SCENARIO（与主连接的故障注入互不串扰）
+// 会话场景（R3）：启动时读取一次（env 固化语义与其他 FAKE_ 开关一致）
 let SCENARIO = null;
-if (process.env.FAKE_SESSION_SCENARIO && !IS_PROBE) {
+if (process.env.FAKE_SESSION_SCENARIO) {
   try {
     SCENARIO = JSON.parse(fs.readFileSync(process.env.FAKE_SESSION_SCENARIO, 'utf8'));
   } catch (err) {
     log('scenario-load-failed', { message: String(err && err.message) });
   }
 }
-if (process.env.FAKE_PROBE_SCENARIO && IS_PROBE) {
+
+// [P0-1 U4] 本进程代数（state 流水已有 boot 记录数 + 1）：崩溃/杀链后的惰性重建代
+// ≥2——rebootSendPushes 仅对重建代生效（重试轮拿到与首轮不同的推送序列）
+let BOOT_GEN = 1;
+if (STATE_FILE && SCENARIO && SCENARIO.rebootSendPushes) {
   try {
-    SCENARIO = JSON.parse(fs.readFileSync(process.env.FAKE_PROBE_SCENARIO, 'utf8'));
-  } catch (err) {
-    log('scenario-load-failed', { message: String(err && err.message) });
-  }
+    const priorBoots = fs
+      .readFileSync(STATE_FILE, 'utf8')
+      .split('\n')
+      .filter((l) => l.includes('"ev":"boot"')).length;
+    BOOT_GEN = priorBoots + 1;
+  } catch { /* 流水读失败按首代处理 */ }
 }
 
 let seq = 0;
@@ -130,7 +140,6 @@ log('env', {
   telemetry: process.env.ZCODE_MODEL_TELEMETRY_ENABLED,
   nested: process.env.ZSW_NESTED,
   unifiedNested: process.env.XYZ_AGENT_SUBAGENT,
-  probe: process.env.ZCODE_APPSERVER_PROBE_CONN,
 });
 log('boot', { pid: process.pid, argv: process.argv.slice(2) });
 if (process.env.FAKE_STDERR === '1') {
@@ -212,8 +221,6 @@ async function handleRequest(f) {
       process.exit(1);
       return; // 不可达（exit 先行），保持 switch 完整
     case 'session/create': {
-      // [R5] 探针预算超时注入：hangCreate 时永不应答（探针 deadline 收割判据）
-      if (SCENARIO && SCENARIO.hangCreate) return;
       if (SCENARIO && SCENARIO.createError) {
         return replyErr(id, SCENARIO.createError.code, SCENARIO.createError.message, SCENARIO.createError.data);
       }
@@ -228,13 +235,33 @@ async function handleRequest(f) {
       if (SCENARIO && SCENARIO.sendError) {
         return replyErr(id, SCENARIO.sendError.code, SCENARIO.sendError.message, SCENARIO.sendError.data);
       }
-      // 推送帧逐字回放（STAMP_SESSION 时按目标会话归因改写）
-      pushFrames(SCENARIO && SCENARIO.sendPushes, String(params.sessionId || ''));
+      // 推送帧逐字回放（STAMP_SESSION 时按目标会话归因改写）；重建代走 rebootSendPushes
+      // （U4：重试轮的不同行为通道）
+      const pushes =
+        BOOT_GEN > 1 && SCENARIO && SCENARIO.rebootSendPushes
+          ? SCENARIO.rebootSendPushes
+          : SCENARIO && SCENARIO.sendPushes;
+      pushFrames(pushes, String(params.sessionId || ''));
+      // [P0-1 U4] 崩溃收割注入：应答后 N ms 自杀（onClose → failAllTurns 在途 turn
+      // 收割的确定性触发面；exit(1) 非零码与 test/suicide 同形态）
+      const crashAfterSendMs = SCENARIO && SCENARIO.crashAfterSendMs;
+      if (typeof crashAfterSendMs === 'number' && crashAfterSendMs >= 0) {
+        setTimeout(() => {
+          log('crash-injected', { afterMs: crashAfterSendMs });
+          process.exit(1);
+        }, crashAfterSendMs).unref();
+      }
       return reply(id, (SCENARIO && SCENARIO.sendResult) || { accepted: true });
     }
     case 'session/stop': {
-      // [R4] abort 链断言面：缺省推终态（stop 优雅生效）；stopBehavior:'none' 只应答
+      // [R4] abort 链断言面：缺省推终态（stop 优雅生效）；stopBehavior:'none' 只应答；
+      // stopError 注入协议性 error 应答帧（P0-1 U2 态②——不升级杀链判据）；
+      // stopBehavior:'hang' 永不应答（态③——stop 3s 超时 = 连接级失败判据）
       const behavior = (SCENARIO && SCENARIO.stopBehavior) || 'terminal';
+      if (behavior === 'hang') return;
+      if (SCENARIO && SCENARIO.stopError) {
+        return replyErr(id, SCENARIO.stopError.code, SCENARIO.stopError.message, SCENARIO.stopError.data);
+      }
       if (behavior === 'terminal') {
         pushFrames([TURN_TERMINAL_FRAME], String(params.sessionId || ''));
       }