@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/sessions-index.ts

@@ -0,0 +1,304 @@
+// src/execution/sessions-index.ts
+//
+// [perf L-1] sessions-index.json —— identity 探测结果的磁盘种子。
+//
+// 背景：RecordStore 冷启动首扫需逐个探测 sessions/*.jsonl 的 identity（头部 64KB →
+// 尾部 64KB → 全文 fallback）。session 数量大时该探测是冷扫描的主要成本。本模块把
+// 「本目录的探测结论」（per-file identity 或负标记）持久化到 sessionsDir 的兄弟位置
+// （<enc> 段内），下次进程/实例首扫直接用索引条目构造缓存条目（零内容读取）。
+//
+// 语义：
+//   - 读侧（loadIndex）永不抛：文件缺失/JSON 损坏/结构不符/版本低 → 空索引（= 今天的
+//     全量行为，下轮 dirty 重写自愈）；版本高于自身 → 空索引 + higherVersion 标志
+//     （整体忽略不消费，RecordStore 据此抑制本轮及后续落盘，防 v1/v2 last-writer-wins
+//     覆盖振荡）。
+//   - 写侧（saveIndex）：tmp(pid+seq)+fsync+rename+目录 fsync 原子写（逐环复刻
+//     ManifestStore.writeManifest 的生产模式）。失败本身向上抛；fire-and-forget 的
+//     .catch 兜底在 RecordStore 侧。
+//   - 损坏/降级走 logger.debug（PI_EXT_DEBUG=1 可见，默认 no-op），不 console.error
+//     ——索引是纯性能缓存，降级自愈不应告警。
+//
+// 无状态纯函数模块：不依赖 RecordStore 任何内部状态。
+
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { bestEffort } from "./best-effort.ts";
+import type { ExecutionMode } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+// ============================================================
+// 常量（测试锚点 SSOT：RecordStore 与测试从同一来源引用，禁止内联字面量）
+// ============================================================
+
+/** 索引文件名（落 sessionsDir 兄弟位置——写索引不改 sessionsDir 目录 mtime，不击穿 L0 快路径）。 */
+export const INDEX_FILENAME = "sessions-index.json";
+
+/** 索引格式版本。schema 变更必须递增：低版本文件整体丢弃（空索引，下轮 dirty 重写自愈）；高版本整体忽略（higherVersion，不重写）。 */
+export const INDEX_VERSION = 1;
+
+/** 两次成功落盘的最小墙钟间隔（节流：overlay 打开期间的高频扫描不放大磁盘写）。 */
+export const INDEX_WRITE_MIN_INTERVAL_MS = 60_000;
+
+/** tmp 文件单调计数：同一进程内并发的 saveIndex 各用独立 tmp。节流基准只在写成功后
+ *  推进——W1 在途时新一轮过窗扫描可再 dispatch W2，共用同一 tmp 会交错（W2 truncate
+ *  落在 W1 write 与 rename 之间 → 半成品被 rename / rename 后失败 → 假失败日志）。
+ *  pid+seq 双后缀保证 tmp 唯一：交错 rename 的终态必为某次完整快照（last-writer-wins，
+ *  与跨进程 pid 隔离同语义；陈旧快照胜出时下轮戳不匹配自愈）。 */
+let tmpSeq = 0;
+
+// ============================================================
+// 类型（DM1 磁盘顶层 + DM2 条目）
+// ============================================================
+
+/**
+ * 正索引条目：「该文件有 identity」的身份字段 + stat 戳。
+ *
+ * 不含 sessionFile（加载侧由 sessionsDir + basename 重构，绝对路径因 agentDir 迁移
+ * 整体失效）；不含 forkDepth/chatMode（投影源 SubagentRecord 无此二字段，buildRecord
+ * 构造 light 时不读——存了也无消费方；未来需要时升 INDEX_VERSION）。
+ */
+export interface SessionsIndexEntry {
+  /** tagged union 判别（负条目为 true）。显式声明 false 供 TS narrowing（与 record-store.ts FileCacheEntry 同款）。 */
+  negative?: false;
+  /** jsonl stat 戳（mtime+size）——不匹配 = 内容变化，调用方回退重探测。 */
+  mtimeMs: number;
+  size: number;
+  id: string;
+  agent: string;
+  /** 执行模式。运行时校验宽容历史 "sync" 值（白名单 sync|background，镜像 isIdentityData）；类型层由 ExecutionMode 收窄。 */
+  mode: ExecutionMode;
+  task: string;
+  slug: string;
+  startedAt: number;
+  /** undefined 表示缺失（旧文件/顶层）。JSON 序列化时被丢弃，往返保持 undefined。 */
+  rootSessionId: string | undefined;
+  parentRecordId: string | undefined;
+  depth: number;
+  /** 空串合法：尾部探测（readIdentityTail）拿不到 model 时的合法结果，不当损坏。 */
+  model: string;
+  thinkingLevel: string | undefined;
+}
+
+/**
+ * 负索引条目：「该文件确认无 identity」（junk/异构文件）。与内存负缓存
+ * NegativeFileEntry 语义对齐——把「没有」这一事实持久化，跨实例零重探测。
+ */
+export interface SessionsIndexNegativeEntry {
+  negative: true;
+  mtimeMs: number;
+  size: number;
+}
+
+/** 磁盘 JSON 顶层结构（key = jsonl basename 不含路径）。 */
+export interface SessionsIndexFile {
+  version: 1;
+  pid: number;
+  entries: Record<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+}
+
+/** saveIndex 输入（内存形态）。 */
+export interface SessionsIndexData {
+  entries: Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+}
+
+/** loadIndex 输出。恒返回该形态对象（不抛、不返回 null）。 */
+export interface LoadedSessionsIndex {
+  entries: Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+  /** true = 磁盘版本高于自身：条目整体不消费，且本进程及后续不得写盘（防 v1/v2 互相覆盖振荡）。 */
+  higherVersion: boolean;
+}
+
+// ============================================================
+// 条目级校验（ES3：单条目损坏仅丢弃该条目，不放大为整体失效）
+// ============================================================
+
+/** 正条目类型谓词：镜像 isIdentityData（session-reconstructor.ts:244-253）的字段检查 + 索引特有戳/形态字段。 */
+function isPositiveIndexEntry(raw: unknown): raw is SessionsIndexEntry {
+  if (typeof raw !== "object" || raw === null) return false;
+  const v = raw as Record<string, unknown>;
+  return (
+    typeof v.mtimeMs === "number" &&
+    typeof v.size === "number" &&
+    typeof v.id === "string" &&
+    typeof v.agent === "string" &&
+    // 宽容历史 "sync" 值（ExecutionMode 现值仅 "background"，"sync" 是旧数据合法值，放行不丢弃）
+    (v.mode === "sync" || v.mode === "background") &&
+    typeof v.task === "string" &&
+    typeof v.slug === "string" &&
+    typeof v.startedAt === "number" &&
+    (v.rootSessionId === undefined || typeof v.rootSessionId === "string") &&
+    (v.parentRecordId === undefined || typeof v.parentRecordId === "string") &&
+    typeof v.depth === "number" &&
+    typeof v.model === "string" && // 空串合法（DS4）
+    (v.thinkingLevel === undefined || typeof v.thinkingLevel === "string")
+  );
+}
+
+/** 负条目类型谓词（tagged union 形态检查）。 */
+function isNegativeIndexEntry(raw: unknown): raw is SessionsIndexNegativeEntry {
+  if (typeof raw !== "object" || raw === null) return false;
+  const v = raw as Record<string, unknown>;
+  return v.negative === true && typeof v.mtimeMs === "number" && typeof v.size === "number";
+}
+
+/**
+ * 校验单条索引条目。返回 undefined = 条目损坏，调用方仅丢弃该条目
+ * （该文件本轮回退探测，其余条目正常保留/命中）。
+ */
+export function validateIndexEntry(
+  raw: unknown,
+): SessionsIndexEntry | SessionsIndexNegativeEntry | undefined {
+  if (!isPositiveIndexEntry(raw) && !isNegativeIndexEntry(raw)) return undefined;
+  return raw;
+}
+
+// ============================================================
+// 读侧（IF1：永不抛）
+// ============================================================
+
+/**
+ * 读取指定目录（<enc> 段）的 sessions-index.json。永不抛：
+ *   - 文件不存在/读失败/JSON.parse 失败/顶层结构不符/版本低于自身
+ *     → { entries: 空 Map, higherVersion: false }（空索引 = 今天的全量行为）
+ *   - 版本高于自身 → { entries: 空 Map, higherVersion: true }
+ *     （整体忽略——即使 entries 合法也不消费，防陈旧 schema 灌入；RecordStore 据此抑制落盘）
+ *   - 版本匹配 → 逐条 validateIndexEntry（坏条目丢弃，其余保留）
+ *
+ * 只读精确路径 INDEX_FILENAME：.tmp. 残留文件不匹配文件名，天然被忽略。
+ */
+export function loadIndex(encDir: string): LoadedSessionsIndex {
+  const empty: LoadedSessionsIndex = { entries: new Map(), higherVersion: false };
+  const indexPath = path.join(encDir, INDEX_FILENAME);
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(indexPath, "utf-8");
+  } catch (err) {
+    // ENOENT = 正常首跑，保持静默；其余读失败（EACCES 等长期权限异常）留 debug 线索
+    // ——空索引回退本身可自愈，但权限类异常不会自己消失，需可诊断。
+    const code = err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : undefined;
+    if (code !== "ENOENT") {
+      logger.debug("[subagents] sessions-index read failed, fallback to empty", {
+        detail: { dir: encDir, code },
+      });
+    }
+    return empty;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    // 损坏（截断/外部编辑）走 debug：可降级自愈场景，不 console.error
+    logger.debug("[subagents] sessions-index corrupted JSON, fallback to empty", {
+      detail: { path: indexPath, error: err instanceof Error ? err.message : String(err) },
+    });
+    return empty;
+  }
+
+  if (typeof parsed !== "object" || parsed === null) {
+    logger.debug("[subagents] sessions-index invalid top-level shape, fallback to empty", {
+      detail: { path: indexPath },
+    });
+    return empty;
+  }
+  const top = parsed as Record<string, unknown>;
+  if (
+    typeof top.version !== "number" ||
+    typeof top.entries !== "object" ||
+    top.entries === null ||
+    Array.isArray(top.entries)
+  ) {
+    logger.debug("[subagents] sessions-index invalid header fields, fallback to empty", {
+      detail: { path: indexPath },
+    });
+    return empty;
+  }
+
+  if (top.version > INDEX_VERSION) {
+    // 高版本：整体忽略（entries 即使合法也不消费）；调用方据 higherVersion 抑制写盘
+    return { entries: new Map(), higherVersion: true };
+  }
+  if (top.version < INDEX_VERSION) {
+    // 低版本：整体丢弃 → 空索引；本轮全扫 dirty 后重写自愈
+    logger.debug("[subagents] sessions-index stale version, discarded", {
+      detail: { path: indexPath, version: top.version, expected: INDEX_VERSION },
+    });
+    return empty;
+  }
+
+  const entries = new Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>();
+  for (const [key, value] of Object.entries(top.entries)) {
+    const entry = validateIndexEntry(value);
+    if (entry !== undefined) entries.set(key, entry);
+  }
+  return { entries, higherVersion: false };
+}
+
+// ============================================================
+// 写侧（IF2：原子写；失败向上抛——fire-and-forget 的 .catch 兜底在调用方）
+// ============================================================
+
+/**
+ * 原子写索引（tmp(pid+seq) → fsync → rename → fsync 目录；逐环复刻
+ * ManifestStore.writeManifest 的生产模式）。tmp 带 pid+单调序号双后缀：pid 防两进程
+ * 共用同一 tmp，seq 防同进程内并发 saveIndex（节流基准在写成功后才推进，W1 在途时
+ * 新一轮过窗扫描可 dispatch W2）共用同一 tmp；rename 原子性保证读侧看到旧版或完整
+ * 新版，绝无半成品。
+ *
+ * 失败向上抛——RecordStore 的 flushIndexAfterScan 以 fire-and-forget .catch 消费
+ * （写失败不影响任何扫描结果，恢复 dirty 待下轮过窗重试）。
+ */
+export async function saveIndex(encDir: string, data: SessionsIndexData): Promise<void> {
+  const filePath = path.join(encDir, INDEX_FILENAME);
+  const tmpPath = `${filePath}.tmp.${process.pid}.${++tmpSeq}`;
+  const file: SessionsIndexFile = {
+    version: INDEX_VERSION,
+    pid: process.pid,
+    entries: Object.fromEntries(data.entries),
+  };
+  const content = JSON.stringify(file);
+
+  let renamed = false;
+  try {
+    // 1. 写 tmp → fsync 文件
+    const fh = await fsPromises.open(tmpPath, "w");
+    try {
+      await fh.writeFile(content, "utf-8");
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+
+    // 2. rename tmp → final（放在 try 内：失败时 catch 清理 tmp）
+    await fsPromises.rename(tmpPath, filePath);
+    renamed = true;
+
+    // 3. fsync 目录（best-effort：POSIX 不要求，失败不否定已成功的 rename）
+    try {
+      const dirFh = await fsPromises.open(encDir, "r");
+      try {
+        await dirFh.sync();
+      } finally {
+        await dirFh.close();
+      }
+    } catch (dirSyncErr) {
+      bestEffort(dirSyncErr, "fsync dir (saveIndex)");
+    }
+  } catch (err) {
+    // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
+    if (!renamed) {
+      try {
+        await fsPromises.unlink(tmpPath);
+      } catch (cleanupErr) {
+        bestEffort(cleanupErr, "unlink tmp (saveIndex)");
+      }
+    }
+    throw err;
+  }
+}

package/src/execution/stdin-writer.ts

@@ -16,6 +16,43 @@ import type { UiResponse } from "./dialog-queue.ts";
 
 const logger = getLogger("subagents");
 
+/**
+ * EPIPE 连续失败计数器（record.id → 连续 EPIPE 次数）。
+ *
+ * [v4 A-1] 计数器从 subagent-service.ts 迁移到本模块（stdin 错误域）。迁移原因：
+ * session-runner.ts 已被 subagent-service.ts import（runSpawn 等），若 session-runner
+ * 反向 import subagent-service 的 helper 会循环依赖。stdin-writer 不 import 两者，
+ * 是 stdin 域中立模块，epipe 计数属 stdin 错误域，职责合理。
+ *
+ * 错误处理两半面共用本计数器（合并计数，防 spawn→EPIPE→resume 死循环）：
+ *   ① 同步 write 抛错（writeStdinLine throw → deliverMessage catch 递增）
+ *   ② 异步 stream 'error' event（session-runner.ts child.stdin.on('error') 递增）
+ */
+const epipeConsecutiveFailures = new Map<string, number>();
+
+/** 连续 EPIPE 失败阈值：达到即不再尝试 resume（避免无限 spawn → EPIPE → resume 循环）。 */
+export const EPIPE_FAILURE_THRESHOLD = 2;
+
+/**
+ * 递增 recordId 的 EPIPE 连续失败计数，返回递增后的新计数。
+ * 同步 writeStdinLine throw 与异步 child.stdin 'error' event 共用此入口（合并计数）。
+ */
+export function recordEpipeFailure(recordId: string): number {
+  const count = (epipeConsecutiveFailures.get(recordId) ?? 0) + 1;
+  epipeConsecutiveFailures.set(recordId, count);
+  return count;
+}
+
+/** 成功写入时清零某 record 的 EPIPE 连续失败计数（热路径成功 → 重置，允许后续重新计数）。 */
+export function clearEpipeFailure(recordId: string): void {
+  epipeConsecutiveFailures.delete(recordId);
+}
+
+/** dispose 时清空所有 EPIPE 计数（防跨 session 泄漏）。 */
+export function resetAllEpipeFailures(): void {
+  epipeConsecutiveFailures.clear();
+}
+
 /**
  * 按 UiResponse 形状构造 Pi 原生 extension_ui_response 并写 stdin。
  *
@@ -62,19 +99,40 @@ export function respond(child: ChildProcess, id: string, out: UiResponse, signal
  * pi 在 await rebindSession() 后才挂 stdin reader（rpc-mode.ts:778-781），
  * reader 处理 prompt 时 session 已就绪。
  *
+ * [V2 决策 3] chatMode 续聊热路径用 prompt + streamingBehavior 统一投递（替代 steer/followUp
+ * 命令），pi 权威裁决 busy/idle（设计 F3/F4）：busy 时 followUp 入队/steer 抢占；idle 时
+ * streamingBehavior 被忽略、直接开新 turn。不传 streamingBehavior（首帧 prompt / 旧调用方）
+ * 行为完全不变——向后兼容。
+ *
  * @param child 子进程（stdin 写入 prompt 命令）
  * @param task 完整 task 文本（含 schema 指令）
+ * @param options.streamingBehavior V2 统一投递语义：`"followUp"`（排队，当前轮后处理）/ `"steer"`（抢占，立即中断 streaming）。
+ *        省略时不写入该字段（首帧 prompt / 非 chatMode 调用方，行为不变）。
  */
-export function sendPromptCommand(child: ChildProcess, task: string): void {
+export function sendPromptCommand(
+  child: ChildProcess,
+  task: string,
+  options?: { streamingBehavior?: "followUp" | "steer" },
+): void {
   if (!child.stdin || child.stdin.destroyed) return;
-  const command = JSON.stringify({
+  const payload: Record<string, unknown> = {
     id: crypto.randomUUID(),
     type: "prompt",
     message: task,
-  });
-  writeStdinLine(child, command, "prompt command");
+  };
+  if (options?.streamingBehavior) {
+    payload.streamingBehavior = options.streamingBehavior;
+  }
+  writeStdinLine(child, JSON.stringify(payload), "prompt command");
 }
 
+/**
+ * [review 修复 round2] 已删除 sendFollowUpCommand / sendSteerCommand——deliverToRunning
+ * （busy 投递死机制，S2 删除）的唯一消费方移除后两函数成零生产调用方死 export。
+ * busy 投递语义由 prompt + streamingBehavior（sendPromptCommand 的
+ * options.streamingBehavior: "followUp" | "steer"，pi 权威裁决）承担。
+ */
+
 /**
  * 向 rpc 子进程 stdin 写 get_state 命令，查询 sessionFile/sessionId。
  *
@@ -96,17 +154,45 @@ export function sendGetStateCommand(child: ChildProcess): string {
 }
 
 /**
- * 向子进程 stdin 写一行（自动补换行），带背压检查。
+ * 向子进程 stdin 写一行（自动补换行），带背压检查 + EPIPE 检测。
  *
  * [R1] write 返回 false 时记 warn（不阻塞，内核缓冲会随后排空）。
+ * [R3] write 抛 EPIPE / ERR_STREAM_DESTROYED 时 throw 含 EPIPE 关键词的 Error，
+ *      让上层（deliverMessage）能捕获并自动转冷路径 resume。
  * stdin 已关闭/销毁时跳过——respond 已检查 signal，sendPromptCommand 已检查 destroyed。
  *
  * @param child 子进程
  * @param line JSON 行（不含换行）
  * @param warnTag warn 日志的语义标记
+ * @throws Error 含 "EPIPE" 关键词——stdin 管道已断（子进程已退出 / stdin 被销毁）
  */
 function writeStdinLine(child: ChildProcess, line: string, warnTag: string): void {
   if (!child.stdin || child.stdin.destroyed) return;
-  const ok = child.stdin.write(line + "\n");
-  if (!ok) logger.warn(`[subagents] stdin backpressure on ${warnTag}`);
+  try {
+    const ok = child.stdin.write(line + "\n");
+    if (!ok) logger.warn(`[subagents] stdin backpressure on ${warnTag}`);
+  } catch (err) {
+    // [R3] EPIPE / ERR_STREAM_DESTROYED：stdin 管道已断，子进程已退出或 stdin 被销毁。
+    // [v4 A-1] 错误处理两半面：① 同步 write 抛错（本 catch）——上层 deliverMessage 捕获后
+    //   调 recordEpipeFailure 递增计数；② 异步 stream 'error' event（session-runner.ts 的
+    //   child.stdin.on('error') listener）。两者共用本模块 export 的 recordEpipeFailure
+    //   helper 合并计数（防 spawn→EPIPE→resume 死循环）。
+    // throw 让上层（deliverMessage）捕获并自动转冷路径 resume + 消息重放。
+    if (
+      err !== null &&
+      typeof err === "object" &&
+      "code" in err &&
+      ((err as NodeJS.ErrnoException).code === "EPIPE" ||
+        (err as NodeJS.ErrnoException).code === "ERR_STREAM_DESTROYED")
+    ) {
+      throw new Error(
+        `[subagents] EPIPE on stdin write (${warnTag}): pipe broken, child process likely exited. ` +
+          `Recovery: treat as dead process and resume via cold path.`,
+      );
+    }
+    // 非 EPIPE 错误（不应发生，但兜底降级为 warn 不崩溃）
+    logger.warn(`[subagents] unexpected stdin write error on ${warnTag}`, {
+      detail: err instanceof Error ? err.message : String(err),
+    });
+  }
 }

package/src/execution/stream-sink.ts

@@ -12,7 +12,7 @@
  * 设计要点：
  * - leading edge：第一个 delta 立即 flush（前端尽快看到开始）
  * - trailing edge：后续 delta 追加 buffer，timer 到期后 flush
- * - 每次 flush 把 buffer 的累积全文 split("\n") 传给 setWidget
+ * - 每次 flush 把 buffer 的累积文本 split("\n") 截尾 MAX_WIDGET_LINES 行传给 setWidget
  * - dispose 清除 widget + 清 timer
  */
 
@@ -25,9 +25,17 @@ export interface StreamSink {
   setWidget(key: string, lines: string[] | undefined): void;
 }
 
-/** delta 合并窗口时间（ms）。与 onEventThrottled 的节流间隔对齐。 */
+/** delta 合并窗口时间（ms）。 */
 const STREAM_FLUSH_MS = 100;
 
+/** widget 发送的最大行数上限。
+ *
+ * flush 把 buffer 累积全文 split 后经 setWidget RPC 通道整包发送——长输出 subagent
+ * （数百 KB）下每 100ms 一次 O(当前总量) 的序列化+传输，累计 O(n²)。widget 是实时
+ * 预览（完整输出在 record/eventLog 与 session 文件），只保留尾部行即可；超限时以
+ * 一行 truncated 提示替代被裁掉的头部。 */
+const MAX_WIDGET_LINES = 200;
+
 /**
  * subagent text_delta streaming 生命周期对象。
  *
@@ -78,6 +86,15 @@ export class SubagentStream {
   private flush(): void {
     this.timer = undefined;
     if (this.buffer.length === 0 || this.disposed) return;
-    this.sink.setWidget(this.widgetKey, this.buffer.split("\n"));
+    const lines = this.buffer.split("\n");
+    if (lines.length <= MAX_WIDGET_LINES) {
+      this.sink.setWidget(this.widgetKey, lines);
+      return;
+    }
+    const dropped = lines.length - MAX_WIDGET_LINES;
+    this.sink.setWidget(this.widgetKey, [
+      `(... ${dropped} earlier lines truncated, full output in /subagents detail)`,
+      ...lines.slice(dropped),
+    ]);
   }
 }