@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/{argv-mirror.ts → engine/engines/pi/argv-mirror.ts}

@@ -17,7 +17,7 @@ export interface MirrorFlags {
 
 /**
  * 有值 flag 的解析规则表：成员是「后跟一个值」的 flag 名（含长短形式）。
- * 用于 mirrorMainProcessFlags 跳过其他 flag 的值时不误吃。
+ * 用于 parseMirrorFlagArgs 跳过其他 flag 的值时不误吃。
  */
 const VALUED_FLAGS = new Set<string>([
   "--extension", "-e",
@@ -28,6 +28,23 @@ const VALUED_FLAGS = new Set<string>([
   "--thinking", "--models",
 ]);
 
+/** MirrorFlags 的布尔字段名（extensionPaths 数组字段单列，不进此表）。 */
+type MirrorBooleanKey = "noExtensions" | "approve" | "noContextFiles";
+
+/**
+ * 布尔镜像 flag 表：token（长/短形式）→ MirrorFlags 布尔字段。
+ * 用 Map 而非对象字面量查表——对象查表对 "__proto__"/"constructor" 等 token
+ * 会命中原型链返回非 undefined，Map.get 无此陷阱。
+ */
+const BOOLEAN_FLAGS = new Map<string, MirrorBooleanKey>([
+  ["--no-extensions", "noExtensions"],
+  ["-ne", "noExtensions"],
+  ["--approve", "approve"],
+  ["-a", "approve"],
+  ["--no-context-files", "noContextFiles"],
+  ["-nc", "noContextFiles"],
+]);
+
 /** argv 中 flag 的起始索引：argv[0]=runtime, argv[1]=binary 路径。 */
 const ARGV_FLAG_START = 2;
 
@@ -39,7 +56,7 @@ const ARGV_FLAG_START = 2;
  * extension/approve 加载行为与主进程一致，且对任意 pi 宿主通用（不止 xyz-agent）。
  *
  * 解析规则：
- * - --no-extensions / -ne、--approve / -a：布尔 flag
+ * - --no-extensions / -ne、--approve / -a：布尔 flag（查 BOOLEAN_FLAGS 表）
  * - --no-context-files / -nc：布尔 flag（镜像理由：--extension 镜像会把
  *   @zhushanwen/pi-system-prompt 带进每个 subagent，该扩展靠子进程自己的
  *   argv 检测此 flag 决定是否注入全局 AGENTS.md——不镜像则用户 opt-out
@@ -56,26 +73,29 @@ let memoResult: MirrorFlags | undefined;
 
 export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
   if (memoResult !== undefined && memoArgv === argv) return memoResult;
-  let hasNoExtensions = false;
-  let hasApprove = false;
-  let hasNoContextFiles = false;
+  const result = parseMirrorFlagArgs(
+    argv.length > ARGV_FLAG_START ? argv.slice(ARGV_FLAG_START) : [],
+  );
+  memoArgv = argv;
+  memoResult = result;
+  return result;
+}
+
+/** 纯解析：扫描 flag 区段（argv[2:]）构造 MirrorFlags，不做 memo。 */
+function parseMirrorFlagArgs(flagArgs: readonly string[]): MirrorFlags {
+  const flags: Record<MirrorBooleanKey, boolean> = {
+    noExtensions: false,
+    approve: false,
+    noContextFiles: false,
+  };
   const extensionPaths: string[] = [];
 
   // argv[0]=runtime(bun), argv[1]=pi binary 路径；flag 从 argv[2] 起
-  const flagArgs = argv.length > ARGV_FLAG_START ? argv.slice(ARGV_FLAG_START) : [];
-
   for (let i = 0; i < flagArgs.length; i++) {
     const tok = flagArgs[i];
-    if (tok === "--no-extensions" || tok === "-ne") {
-      hasNoExtensions = true;
-      continue;
-    }
-    if (tok === "--approve" || tok === "-a") {
-      hasApprove = true;
-      continue;
-    }
-    if (tok === "--no-context-files" || tok === "-nc") {
-      hasNoContextFiles = true;
+    const booleanKey = BOOLEAN_FLAGS.get(tok);
+    if (booleanKey !== undefined) {
+      flags[booleanKey] = true;
       continue;
     }
     // 等号形式 --extension=path / -e=path
@@ -106,8 +126,10 @@ export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
     // 其他情况（未知 flag、--flag=val 形式、positional）忽略
   }
 
-  const result = { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths, noContextFiles: hasNoContextFiles };
-  memoArgv = argv;
-  memoResult = result;
-  return result;
+  return {
+    noExtensions: flags.noExtensions,
+    approve: flags.approve,
+    extensionPaths,
+    noContextFiles: flags.noContextFiles,
+  };
 }

package/src/execution/{get-state-handshake.ts → engine/engines/pi/get-state-handshake.ts}

@@ -1,4 +1,4 @@
-// src/execution/get-state-handshake.ts
+// src/execution/engine/engines/pi/get-state-handshake.ts
 //
 // FR-4: get_state RPC 握手逻辑。
 //
@@ -30,6 +30,31 @@ export interface GetStateResult {
   sessionId?: string;
 }
 
+/**
+ * get_state response 监听器注册函数形态（stdout pump / 测试注入）。
+ *
+ * 返回值：注销函数（从监听表移除该 resolver），可省略——performGetStateHandshake
+ * 忽略返回值（既有语义：迟到 response 靠 resolved 标志自弃，条目由 close 统一清）；
+ * requestGetStateOnce 消费返回值做单次请求的自清理（不依赖 close 兜底）。
+ */
+export type AddGetStateResponseListener = (
+  id: string,
+  resolver: (data: unknown) => void,
+) => void | (() => void);
+
+/** 从 get_state response data 提取 sessionFile/sessionId（提取规则单一来源，握手与惰性重试共用）。 */
+function extractGetStateFields(data: unknown, into: GetStateResult): void {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
+      into.sessionFile = d.sessionFile;
+    }
+    if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
+      into.sessionId = d.sessionId;
+    }
+  }
+}
+
 /**
  * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
  *
@@ -43,7 +68,7 @@ export interface GetStateResult {
  */
 export function performGetStateHandshake(
   child: ChildProcess,
-  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
+  addResponseListener: AddGetStateResponseListener,
 ): Promise<GetStateResult> {
   return new Promise<GetStateResult>((resolve) => {
     const collected: GetStateResult = {};
@@ -81,15 +106,7 @@ export function performGetStateHandshake(
         // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
         clearTimeout(timer);
         if (pendingRetry) clearTimeout(pendingRetry);
-        if (data && typeof data === "object") {
-          const d = data as Record<string, unknown>;
-          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
-            collected.sessionFile = d.sessionFile;
-          }
-          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
-            collected.sessionId = d.sessionId;
-          }
-        }
+        extractGetStateFields(data, collected);
         // sessionFile 已获取——立即 resolve（无需更多重试）
         if (collected.sessionFile) {
           resolved = true;
@@ -102,3 +119,61 @@ export function performGetStateHandshake(
     tryOnce();
   });
 }
+
+/**
+ * [T1/RC-1] 单次 get_state 请求（agent_end 决策点惰性回补专用）。
+ *
+ * 与 performGetStateHandshake 的关系：复用同一消息构造（sendGetStateCommand）与同一
+ * 字段提取（extractGetStateFields），但**不做重试循环、不 share 握手语义**——调用方
+ * （session-runner agent_end 处置）在子进程 idle 时现场补一次查询（探针 P-T1 实证
+ * 应答 0.3-0.4ms），超时/失败即放弃，由调用方走既有保守分支（行为不劣化）。
+ *
+ * 结果契约与 performGetStateHandshake 一致：resolve GetStateResult（可能为空对象），
+ * 永不 reject——stdin 已断（EPIPE/ERR_STREAM_DESTROYED）的同步写失败按「回补失败」
+ * 处理 resolve 空对象，调用方无需 try/catch。
+ *
+ * 自清理：超时或 response 到达后从监听表移除本请求的 resolver（消费注册器的返回值），
+ * 不留迟到条目；注册器不返回注销函数时退化为 no-op（与握手同形态，靠 close 统一清）。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
+ * @param timeoutMs 单次超时（决策点预算 1s 量级；P-T1 实测 idle 应答亚毫秒）
+ */
+export function requestGetStateOnce(
+  child: ChildProcess,
+  addResponseListener: AddGetStateResponseListener,
+  timeoutMs: number,
+): Promise<GetStateResult> {
+  return new Promise<GetStateResult>((resolve) => {
+    let settled = false;
+    let removeListener: () => void = () => {};
+
+    const finish = (r: GetStateResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      removeListener();
+      resolve(r);
+    };
+
+    let reqId: string;
+    try {
+      reqId = sendGetStateCommand(child);
+    } catch {
+      // stdin 已断等同步写失败 = 回补失败，空结果走调用方保守分支（同超时语义）
+      resolve({});
+      return;
+    }
+    removeListener =
+      addResponseListener(reqId, (data: unknown) => {
+        const r: GetStateResult = {};
+        extractGetStateFields(data, r);
+        // response 已到达：无论是否含目标字段都不再等（单次语义，无重试）
+        finish(r);
+      }) ?? (() => {});
+    // [#15] 同款时序模式：timer 在 resolver 注册后创建，resolver/finish 闭包引用它——
+    // 两者都只在 timer 初始化之后才可能被调用（response 到达是异步事件）。
+    const timer: ReturnType<typeof setTimeout> = setTimeout(() => finish({}), timeoutMs);
+    timer.unref();
+  });
+}

package/src/execution/{output-collector.ts → engine/engines/pi/output-collector.ts}

@@ -1,4 +1,4 @@
-// src/core/output-collector.ts
+// src/execution/engine/engines/pi/output-collector.ts
 //
 // 结果收集器（Record + CollectResultArgs → AgentResult）。
 //
@@ -14,21 +14,103 @@ import type {
   AgentResult,
   ExecutionRecord,
   ToolCall,
-} from "./types.ts";
+} from "../../../types.ts";
 import {
   getAllToolCalls,
   getFullText,
   getTotalUsage,
-} from "./execution-record.ts";
-// [F-R1] 值引用 stale-context 分诊 pattern 表（SSOT 在 execute-agent-call，消费点
-// isStaleContextErrorMsg 同源）。execution → orchestration 值引用有先例
-// （agent-registry.ts → script-lint.ts），且 execute-agent-call 对 execution 仅剩
-// type-only import（已擦除），无运行时循环。
-// [MF-1] 同向引用确定性失败标记前缀（SSOT 同在 execute-agent-call，同一布局理由）。
-import {
-  DETERMINISTIC_SCHEMA_FAILURE_PREFIX,
-  STALE_CONTEXT_PATTERNS,
-} from "../orchestration/execute-agent-call.ts";
+} from "../../../execution-record.ts";
+// AgentFailureKind 类型 SSOT 在 orchestration/models/types.ts（消费语义「unknown=
+// 可重试」与其文档同源）；type-only 引用，编译期擦除，零运行时依赖。
+import type { AgentFailureKind } from "../../../../orchestration/models/types.ts";
+// [D5-③ 词表归属声明] 分诊识别词表（STALE_CONTEXT_PATTERNS /
+// DETERMINISTIC_SCHEMA_FAILURE_PREFIX）SSOT 在本模块（产出侧包内单点识别）——
+// collectResult 识别 pi 错误文案后写 AgentResult.failureKind 结构化字段，消费侧
+// （execute-agent-call）只读字段分诊、不再扫文案子串。文案词表依存并未消除，而是
+// 从「跨模块消费 seam」收窄为「产出侧包内单点识别」；词表漂移的失效模式是
+// failureKind=unknown → 保守重试（安全默认），不再是静默漏诊。
+// （原 SSOT 在 execute-agent-call，2026-09 D5-③ 迁入——execution → orchestration
+// 的值引用随之消除，方向反转为测试/消费侧零依赖。）
+
+// ============================================================
+// 失败分诊词表（D5-③，产出侧单点）
+// ============================================================
+
+/**
+ * Stale context 检测模式（P1-5；W4b 对齐 pi 0.84.x 真实文案）。
+ *
+ * pi session context 被 compact/cancel 时报告的模式。这种情况下重试无意义——
+ * 同样的 call 会再次失败。分诊产出 failureKind="stale_context"（消费侧不重试）。
+ *
+ * W4b：原 "stale context"/"stalecontext" 与 pi 真实文案零匹配（真实文案为
+ * "This extension ctx is stale after session replacement or reload. ..."
+ * ——runner.ts:544（dist runner.js:352），词序是 "ctx is stale" 而非 "stale
+ * context"），stale 分诊对真实文案失效。现对齐：
+ * - "ctx is stale"：真实文案核心子串（词序修正）
+ * - "stale after session replacement"：scheduler 已验证 marker（runtime.ts
+ *   STALE_CTX_MARKER，同文案锚定）
+ * - "context canceled"/"aborted"：保留——abort 族错误同样不重试（signal.aborted
+ *   分支的先行分诊，防边界竞态漏网），删除会放宽重试语义。
+ */
+export const STALE_CONTEXT_PATTERNS = [
+  "ctx is stale",
+  "stale after session replacement",
+  "context canceled",
+  "aborted",
+] as const;
+
+/**
+ * 判断错误信息是否表示 stale/canceled pi session context。
+ * 命中时分诊 failureKind="stale_context"——重试只会再次失败（P1-5）。
+ */
+export function isStaleContextErrorMsg(msg: string | undefined): boolean {
+  if (!msg) return false;
+  const lower = msg.toLowerCase();
+  return STALE_CONTEXT_PATTERNS.some((p) => lower.includes(p));
+}
+
+/**
+ * [MF-1] 确定性 schema 失败标记（error 文本前缀，产出方 = 本模块的
+ * describeMissingParsedOutput）。
+ *
+ * 标记词逐字核对不命中 STALE_CONTEXT_PATTERNS 任一 pattern 与
+ * isStaleContextErrorMsg 的子串匹配（否则归因 error 被误诊 stale-context，
+ * 虽然同样不重试但归因语义被污染；output-collector.test 有交叉锁定）。
+ *
+ * 三态可重试性矩阵（F-1 归因）：
+ * | 归因态                     | 带本标记 | 分诊                | 可重试性 | 理由 |
+ * |----------------------------|---------|---------------------|---------|------|
+ * | ① 从未调用 SO tool         | 是      | schema_deterministic | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
+ * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | schema_deterministic | 不可重试 | 同 schema 重试必同结果（第五轮实测：3 attempts/4 子进程/235s 纯烧钱） |
+ * | ③ 调用过但无 details        | 否      | unknown             | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
+ */
+export const DETERMINISTIC_SCHEMA_FAILURE_PREFIX = "Structured output failed deterministically:";
+
+/**
+ * [MF-1] 判断错误信息是否为确定性 schema 失败（命中标记前缀）。
+ * 命中时分诊 failureKind="schema_deterministic"——同 schema 重试必同结果
+ * （矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）。
+ */
+export function isDeterministicSchemaFailureMsg(msg: string | undefined): boolean {
+  if (!msg) return false;
+  return msg.includes(DETERMINISTIC_SCHEMA_FAILURE_PREFIX);
+}
+
+/**
+ * [D5-③] 错误文案 → 结构化失败分诊标签（产出侧唯一识别点）。
+ *
+ * 判定优先级与收敛前的消费侧子串分诊一致（stale 在前）：标记词与 stale 词表
+ * 零交集（交叉锁定测试守护），两序等价。未命中任何词表 → unknown——消费侧
+ * 默认退避重试（语义守恒，r1 MF4）。
+ */
+export function classifyFailureKind(
+  msg: string | undefined,
+): AgentFailureKind | undefined {
+  if (msg === undefined) return undefined;
+  if (isStaleContextErrorMsg(msg)) return "stale_context";
+  if (isDeterministicSchemaFailureMsg(msg)) return "schema_deterministic";
+  return "unknown";
+}
 
 // ============================================================
 // Result 收集
@@ -87,9 +169,8 @@ export function extractParsedOutput(toolCalls: ToolCall[]): unknown {
  * 静态文案，已逐字核对无任何 pattern 命中，且由 output-collector.test.ts 的
  * "messages avoid STALE_CONTEXT_PATTERNS substrings" 用例锁定；动态段是
  * 模型/provider 的原始错误文本（可含 "aborted"/"ctx is stale" 等），不受本模块
- * 控制。不中和的话，拼接结果经 collectResult → result.error 流到
- * execute-agent-call 的 isStaleContextErrorMsg 分诊，SO 失败归因被误诊为
- * stale-context → 跳过重试。
+ * 控制。不中和的话，拼接结果经 collectResult 的 classifyFailureKind 分诊会被
+ * 误标为 stale_context（SO 失败归因被误诊），终态虽同样不重试但归因语义被污染。
  *
  * 导出以便直接单测（纯函数契约）。
  */
@@ -110,16 +191,16 @@ export function neutralizeStalePatterns(text: string): string {
  * 返回 undefined 表示 toolCalls 里有可用的 parsedOutput（无需归因）。
  * 三态判定优先级：校验失败（有 isError 调用）> 从未调用 SO tool > 调用过但无 details。
  *
- * [MF-1] 三态可重试性矩阵（标记 SSOT 与消费端判定见 execute-agent-call 的
- * DETERMINISTIC_SCHEMA_FAILURE_PREFIX / isDeterministicSchemaFailureMsg）：
+ * [MF-1] 三态可重试性矩阵（标记 SSOT 与分类判定均在本模块——D5-③ 收敛为产出侧
+ * 单点，消费端 execute-agent-call 只读 failureKind 字段）：
  * | 归因态                        | 带标记 | 可重试性 | 理由 |
  * |------------------------------|-------|---------|------|
  * | ① 从未调用 SO tool            | 是    | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
  * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | 不可重试 | 同 schema 重试必同结果（第五轮实测 retry 放大回归：3 attempts/4 子进程/235s） |
  * | ③ 调用过但无 details           | 否    | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
  *
- * 文案约束：不得命中 execute-agent-call 的 STALE_CONTEXT_PATTERNS（"aborted" 等
- * 子串）——命中会被误诊为 stale-context 跳过重试。固定前缀（含 MF-1 标记词）静态
+ * 文案约束：不得命中本模块的 STALE_CONTEXT_PATTERNS（"aborted" 等
+ * 子串）——命中会被 classifyFailureKind 误标 stale_context。固定前缀（含 MF-1 标记词）静态
  * 无命中（测试锁定）；动态段经 neutralizeStalePatterns 中和（F-R1）。
  *
  * 导出以便直接单测（纯函数契约）。
@@ -224,5 +305,13 @@ export function collectResult(
     result.success = false;
     result.error = describeMissingParsedOutput(toolCalls) ?? result.error;
   }
+  // [D5-③] 失败分诊结构化：error 最终确定后（含 F-1 归因覆写）一次分类写入。
+  // 消费侧（executeAgentCall）读 failureKind 字段分诊，不再扫 error 文案子串；
+  // 缺省（成功路径/上游未写）= unknown = 可重试（语义守恒）。H4 合成文案
+  // （agent-result-mapper 对 !success && !error 的 abort fallback）在此之后产生，
+  // 不经本分类——该场景 signal.aborted 检查兜底，不依赖分诊。
+  if (result.error !== undefined) {
+    result.failureKind = classifyFailureKind(result.error);
+  }
   return result;
 }