@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/output-collector.ts

@@ -20,6 +20,15 @@ import {
   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";
 
 // ============================================================
 // Result 收集
@@ -32,28 +41,149 @@ export interface CollectResultArgs {
   error: string | undefined;
   sessionId: string;
   sessionFile: string | undefined;
+  /**
+   * [F-1] 本次执行是否要求结构化产出（opts.schema 或 opts.schemaEnv 任一存在）。
+   * true 且 run 结束仍无有效 parsedOutput 时：结果不得静默 success——置 success=false
+   * 并把三态失败归因写进 error（上层 executeAgentCall 只看 error 判 completed/failed）。
+   * 缺省 false（非 schema 模式 parsedOutput===undefined 是正常态，不动成败）。
+   */
+  schemaExpected?: boolean;
 }
 
 /** structured-output tool 名（与 structured-output 扩展 TOOL_NAME 一致，见 session-runner.ts）。 */
 const STRUCTURED_OUTPUT_TOOL = "structured-output";
 
+/** F-1 失败摘要截断长度（字符）：错误详情拼进 run 结果 error 字段，防大 payload 撑爆。 */
+const FAILED_SO_SUMMARY_MAX_CHARS = 300;
+
 /**
  * 从 toolCalls 提取 structured-output 的 result.details（schema 模式产出）。
  * schema enforcement 保证 agent 调过该 tool（漏调会 steer 重试）；这里只做逆向提取。
  * 未调或无 details 返回 undefined。
  *
+ * [F-1 失败吞没修复] isError:true 的调用一律跳过——失败调用的 details（pi 失败
+ * 路径默认 {}）不是通过 schema 校验的产出，把它当 parsedOutput 会让 gate 终止/
+ * 模型自弃的 run 以 parsedOutput={} 静默 completed。isError 字段缺失（旧 record/
+ * 进行中调用）不误伤——仅显式 true 跳过。
+ *
  * 导出以便直接单测（纯函数契约）。
  */
 export function extractParsedOutput(toolCalls: ToolCall[]): unknown {
   for (let i = toolCalls.length - 1; i >= 0; i--) {
     const tc = toolCalls[i]!;
-    if (tc.toolName === STRUCTURED_OUTPUT_TOOL && tc.result?.details !== undefined) {
+    if (tc.toolName === STRUCTURED_OUTPUT_TOOL && tc.isError !== true && tc.result?.details !== undefined) {
       return tc.result.details;
     }
   }
   return undefined;
 }
 
+/**
+ * [F-R1] 中和动态错误摘要中的 stale-context 命中词：对每个 STALE_CONTEXT_PATTERNS
+ * 做大小写不敏感的子串替换为 "[redacted]"（分诊 isStaleContextErrorMsg 是
+ * toLowerCase 后的子串匹配，故中和也必须大小写不敏感）。
+ *
+ * 为何只中和动态段（summarizeToolContent 产物）、不中和固定前缀：前缀是本模块
+ * 静态文案，已逐字核对无任何 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 → 跳过重试。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function neutralizeStalePatterns(text: string): string {
+  let out = text;
+  for (const pattern of STALE_CONTEXT_PATTERNS) {
+    // pattern 当前均为纯小写词/短语（无 regex 元字符），escape 仅为防未来 pattern
+    // 演化引入元字符时静默改变语义。
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    out = out.replace(new RegExp(escaped, "gi"), "[redacted]");
+  }
+  return out;
+}
+
+/**
+ * schema 模式下无有效 parsedOutput 时的三态失败归因（F-1）。
+ *
+ * 返回 undefined 表示 toolCalls 里有可用的 parsedOutput（无需归因）。
+ * 三态判定优先级：校验失败（有 isError 调用）> 从未调用 SO tool > 调用过但无 details。
+ *
+ * [MF-1] 三态可重试性矩阵（标记 SSOT 与消费端判定见 execute-agent-call 的
+ * DETERMINISTIC_SCHEMA_FAILURE_PREFIX / isDeterministicSchemaFailureMsg）：
+ * | 归因态                        | 带标记 | 可重试性 | 理由 |
+ * |------------------------------|-------|---------|------|
+ * | ① 从未调用 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 标记词）静态
+ * 无命中（测试锁定）；动态段经 neutralizeStalePatterns 中和（F-R1）。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function describeMissingParsedOutput(toolCalls: ToolCall[]): string | undefined {
+  if (extractParsedOutput(toolCalls) !== undefined) return undefined;
+  const soCalls = toolCalls.filter((tc) => tc.toolName === STRUCTURED_OUTPUT_TOOL);
+  if (soCalls.length === 0) {
+    // 覆盖独立安装盲区（C1）：schema enforcement 依赖 SO extension 注册 tool，
+    // 未安装时 agent 无工具可调、steer 无法生效——只能在这里事后暴露。
+    // [MF-1] 态① 带确定性标记：缺 extension 是环境确定性，不重试。
+    return (
+      `${DETERMINISTIC_SCHEMA_FAILURE_PREFIX} ` +
+      "Agent finished without producing a structured output: the structured-output tool was never called. " +
+      "Recovery: verify the structured-output extension is installed and enabled for this agent, " +
+      "and that the agent's final answer conforms to the requested schema."
+    );
+  }
+  const failed = soCalls.filter((tc) => tc.isError === true);
+  if (failed.length > 0) {
+    const last = failed[failed.length - 1]!;
+    // [F-R1] 先截断后中和：截断边界把 pattern 切断时不产生新命中（半截词本就
+    // 匹配不到分诊子串），完整落入截断窗口的 pattern 一定被中和。
+    const lastErrorSummary = neutralizeStalePatterns(summarizeToolContent(last.result?.content));
+    // [F-R4] 失败原因分类：isError 只说明「调用失败」，原因未必是 schema 校验
+    // （provider 错误/pi abort/扩展内部错误同样走 isError），硬编码
+    // "(schema validation)" 会误导排障。按最后错误的实际内容分类——权威锚点是
+    // structured-output 扩展校验失败的固定文案前缀 "Schema validation failed: ..."
+    //（structured-output/src/execute.ts），大小写不敏感匹配；其余归为 execution
+    // failure。在已中和的摘要上分类：中和仅替换 stale 词，与校验词无交集。
+    const failureKind = lastErrorSummary.toLowerCase().includes("validation failed")
+      ? "schema validation"
+      : "execution failure";
+    // [MF-1] 态② 带确定性标记：gate 终止/不可满足 schema 同 schema 重试必同结果。
+    // 注：failureKind=execution failure（provider 瞬态错误）同样不重试——isError 态
+    // 整体从重试面摘除（实测回归即此态循环烧钱），瞬态恢复交由上层 workflow 编排。
+    return (
+      `${DETERMINISTIC_SCHEMA_FAILURE_PREFIX} ` +
+      `Agent finished without a valid structured output: ${failed.length} structured-output call(s) failed ` +
+      `(${failureKind}). Last error: ${lastErrorSummary}`
+    );
+  }
+  return (
+    "Agent finished without a valid structured output: structured-output was called but none of the " +
+    "successful calls carried result details."
+  );
+}
+
+/** 从 tool result.content 提取可读错误文本（[{type:"text",text}] 形态，防御未知形状）。 */
+function summarizeToolContent(content: unknown): string {
+  let summary = "(no detail)";
+  if (Array.isArray(content)) {
+    const texts = content
+      .map((item) => (item && typeof item === "object" && "text" in item ? String((item as { text: unknown }).text) : ""))
+      .filter((t) => t !== "");
+    if (texts.length > 0) summary = texts.join(" ");
+  } else if (typeof content === "string" && content !== "") {
+    summary = content;
+  }
+  return summary.length > FAILED_SO_SUMMARY_MAX_CHARS
+    ? `${summary.slice(0, FAILED_SO_SUMMARY_MAX_CHARS)}...`
+    : summary;
+}
+
 /**
  * 从 record + args 组装 AgentResult。每个字段来源单一且收口于 record：
  *   text      ← getFullText(record)（聚合 turns[].text，单一数据源）
@@ -73,7 +203,8 @@ export function collectResult(
   args: CollectResultArgs,
 ): AgentResult {
   const toolCalls = getAllToolCalls(record);
-  return {
+  const parsedOutput = extractParsedOutput(toolCalls);
+  const result: AgentResult = {
     text: getFullText(record),
     turns: record.turnCount,
     durationMs: Date.now() - args.startTime,
@@ -83,6 +214,15 @@ export function collectResult(
     toolCalls,
     usage: getTotalUsage(record),
     sessionFile: args.sessionFile,
-    parsedOutput: extractParsedOutput(toolCalls),
+    parsedOutput,
   };
+  // [F-1 失败吞没修复] schema 模式下 run 结束仍无有效 parsedOutput 时不得静默
+  // success：只在「本将成功」的路径上标注（success=false 的路径已有真实 error/
+  // abort 语义，不覆写）。error 经 mapToWorkflowAgentResult（仅 !success 透传）
+  // → executeAgentCall（error!==undefined 即 failed）逐层可见。
+  if (args.schemaExpected === true && result.success && parsedOutput === undefined) {
+    result.success = false;
+    result.error = describeMissingParsedOutput(toolCalls) ?? result.error;
+  }
+  return result;
 }

package/src/execution/pi-invocation.ts

@@ -1,4 +1,4 @@
-// src/core/pi-invocation.ts
+// src/execution/pi-invocation.ts
 //
 // 定位 pi 二进制并组装 spawn 调用。Core 叶子原语（仅依赖 node 内置）。
 //
@@ -16,6 +16,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { isRelayActive, RELAY_ENV_NODE, RELAY_ENV_SCRIPT } from "./relay-env.ts";
+
 /** spawn 调用描述符：command + args（透传给 child_process.spawn）。 */
 export interface PiInvocation {
   /** 可执行文件路径（node/bun/pi 二进制）。 */
@@ -24,6 +26,16 @@ export interface PiInvocation {
   args: string[];
 }
 
+/** getPiInvocation 可选项。 */
+export interface PiInvocationOptions {
+  /**
+   * false = 强制直连 spawn 真实 pi（不经 relay 代理）。唯一现役消费点是 PiEngine.probe
+   * ——探针意图是 pi 本体可解析性，经 relay 探到的是 runtime 健康，语义错位（E 方案 §5.1）。
+   * 缺省（undefined / true）时按 relay env 激活判定走代理。
+   */
+  relay?: boolean;
+}
+
 /**
  * bun 虚拟文件系统前缀。bun bundle 模式下 process.argv[1] 形如
  * /$bunfs/root/pi——这不是磁盘上的真实文件，不能直接 spawn。
@@ -43,9 +55,12 @@ function isGenericRuntime(execPath: string): boolean {
  * 组装 pi 子进程的 spawn 调用。
  *
  * @param userArgs pi CLI 参数（如 ["--mode", "rpc", "--session-dir", "..."]）
+ * @param opts 可选项（relay:false 强制直连——probe 用，见 PiInvocationOptions）
  * @returns spawn 描述符（command + 完整 args）
  *
  * 决策链（按优先级）：
+ *   0. relay 激活（三 env 齐备且未显式禁用）→ <RELAY_NODE> <RELAY_SCRIPT> <userArgs>
+ *      （E 方案 §5.1：xyz-agent runtime 存在时经代理 spawn，改的是进程拓扑不是 pi 语义）
  *   1. process.argv[1] 是真实磁盘文件且非 bun 虚拟路径 → <execPath> <argv[1]> <userArgs>
  *      （复现当前 pi 进程的启动方式，确保扩展/配置/版本一致）
  *   2. execPath 非通用运行时（pi standalone binary）→ <execPath> <userArgs>
@@ -71,10 +86,25 @@ function currentScriptExists(): boolean {
   return scriptExistsCache.exists;
 }
 
-export function getPiInvocation(userArgs: string[]): PiInvocation {
+export function getPiInvocation(userArgs: string[], opts?: PiInvocationOptions): PiInvocation {
   const currentScript = process.argv[1];
   const isBunVirtualScript = currentScript?.startsWith(BUN_VIRTUAL_PREFIX);
 
+  // 分支 0（前置）：relay 激活（E 方案 §5.1）——runtime 注入三 env 齐备且未显式禁用时，
+  // spawn 目标切换为 <RELAY_NODE> <RELAY_SCRIPT> <原 pi spawnArgs>，形态与分支 1「node +
+  // script」同构（command 是执行器、args[0] 是脚本）。ELECTRON_RUN_AS_NODE 不在此补：
+  // 打包态执行器为 Electron 时由 runtime 与三 env 同点注入主 pi 进程 env（E-2
+  // getRelaySpawnEnv），本进程 {...process.env} 继承即达代理进程，extension 不重复判定。
+  // isRelayActive 已保证三 env 非空，下方取局部变量仅为 TS 收窄（isRelayActive 的
+  // 收窄不跨函数边界传导）。
+  if (opts?.relay !== false && isRelayActive(process.env)) {
+    const relayNode = process.env[RELAY_ENV_NODE];
+    const relayScript = process.env[RELAY_ENV_SCRIPT];
+    if (relayNode !== undefined && relayScript !== undefined) {
+      return { command: relayNode, args: [relayScript, ...userArgs] };
+    }
+  }
+
   // 分支 1：有真实脚本路径 → 复现启动方式（node <pi-script> <args>）
   if (currentScript && !isBunVirtualScript && currentScriptExists()) {
     return { command: process.execPath, args: [currentScript, ...userArgs] };

package/src/execution/record-entry.ts

@@ -82,6 +82,17 @@ export interface SubagentRecordEntryData {
   chatMode?: boolean;
   /** 执行态信号（residual-fixes）：true = 无活进程驱动的 running（轮终/孤儿兜底）。 */
   resumable?: boolean;
+  /**
+   * 实际执行引擎 id（P4 路由留痕，D9①）。缺省（存量 entry）= pi 投影，消费方零迁移。
+   */
+  engine?: string;
+  /** 引擎 fallback 留痕（probe 失败路由回默认引擎）。GUI 警告条数据源。 */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * 引擎自描述定位符（U1：read 降级链①②级数据源）。引擎无关——sessionRef 整体
+   * 透传不枚举内部键（zcode = { sessionId, dbPath }）；缺省 = pi（存量 entry 零迁移）。
+   */
+  engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
 }
 
 /** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
@@ -114,5 +125,8 @@ export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEnt
     round: record.round,
     chatMode: record.chatMode,
     resumable: record.resumable,
+    engine: record.engine,
+    engineFallback: record.engineFallback,
+    engineHandle: record.engineHandle,
   };
 }

package/src/execution/record-store.ts

@@ -267,9 +267,39 @@ function rebuildEntryRecord(id: string, d: Record<string, unknown>): SubagentRec
     sessionFile: undefined,
     chatMode: d.chatMode === true,
     round: num("round"),
+    engine: str("engine"),
+    engineFallback:
+      isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
+    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
   };
 }
 
+/** engineFallback entry 值的运行时 guard（未知 JSON 不裸收）。 */
+function isEngineFallbackShape(v: unknown): v is { from: string; reason: string } {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  return typeof r.from === "string" && typeof r.reason === "string";
+}
+
+/** engineHandle entry 值的运行时 guard（未知 JSON 不裸收；形状与 runtime 读侧
+ *  subagent-engine-history 的 extractRecordEngineHandle 守卫语义对齐：poolKey
+ *  必有非空 string + sessionRef 值全 string 才收，journalPath 可选 string）。 */
+function isEngineHandleShape(
+  v: unknown,
+): v is { sessionRef: Record<string, string>; journalPath?: string; poolKey: string } {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const h = v as Record<string, unknown>;
+  if (typeof h.poolKey !== "string" || h.poolKey.length === 0) return false;
+  if (typeof h.sessionRef !== "object" || h.sessionRef === null || Array.isArray(h.sessionRef)) {
+    return false;
+  }
+  for (const value of Object.values(h.sessionRef as Record<string, unknown>)) {
+    if (typeof value !== "string") return false;
+  }
+  if (h.journalPath !== undefined && typeof h.journalPath !== "string") return false;
+  return true;
+}
+
 /** stat 戳（不存在 → null）。 */
 function statStamp(p: string): Stamp | null {
   try {
@@ -1195,6 +1225,10 @@ export class RecordStore {
       resumable: r.resumable,
       // [review round2] worktree 隔离标志：内存源有 handle 或跨重启重建带 hadWorktree 均为 true。
       worktree: r.worktreeHandle !== undefined || r.hadWorktree === true,
+      engine: r.engine,
+      engineFallback: r.engineFallback,
+      // U2：engineHandle 经 entry 持久化（register/archive 双写点均经本投影），无则 undefined 自然省略
+      engineHandle: r.engineHandle,
     };
   }
 }

package/src/execution/relay-env.ts

@@ -0,0 +1,37 @@
+/**
+ * subagent relay 通道 env 名与协议常量 SSOT（docs/architecture/subagent-realtime-channel.md §5.1/§5.2/§3.1）。
+ *
+ * 为什么独立成模块：三方消费同一份常量——extension 侧（pi-invocation 激活判定 /
+ * buildChildEnv 归属写入）、runtime 侧（env 注入与镜像校验）、代理脚本 relay.mjs
+ * （零依赖脚本不能 import workspace 包，只能内嵌镜像，镜像一致性由 conformance
+ * relay 变体断言锁定）。禁各处手写字符串。
+ *
+ * env 语义：SOCKET/NODE/SCRIPT 三者同时非空 = relay 激活（全有或全无，无中间态）；
+ * SESSION_ID/RECORD_ID 是 tee 帧归属键（缺失由代理握手前自检拒绝，退出码 13）。
+ */
+
+export const RELAY_ENV_SOCKET = 'XYZ_SUBAGENT_RELAY_SOCKET';
+export const RELAY_ENV_NODE = 'XYZ_SUBAGENT_RELAY_NODE';
+export const RELAY_ENV_SCRIPT = 'XYZ_SUBAGENT_RELAY_SCRIPT';
+export const RELAY_ENV_SESSION_ID = 'XYZ_SUBAGENT_RELAY_SESSION_ID';
+export const RELAY_ENV_RECORD_ID = 'XYZ_SUBAGENT_RELAY_RECORD_ID';
+
+/** relay 协议版本（握手帧 v 字段；runtime 与代理同包分发，不匹配=安装损坏）。 */
+export const RELAY_PROTOCOL_VERSION = 1;
+
+/** 代理专用退出码（extension 侧表现为「子进程非零退出」→ engine_run_failed 语义）。 */
+export const RELAY_EXIT_CODES = {
+  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
+  VERSION_MISMATCH: 10,
+  /** relay socket 不可达（runtime 未运行或已重启）。 */
+  SOCKET_UNREACHABLE: 11,
+  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
+  SOCKET_CLOSED: 12,
+  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
+  MISSING_IDENTITY: 13,
+} as const;
+
+/** 激活判定：三 env 同时非空才走 relay，任一缺失回落直连 spawn 真实 pi（TUI/独立 pi 零回归）。 */
+export function isRelayActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
+  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
+}