@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/execution/execution-record.ts

@@ -20,6 +20,7 @@ import type {
   AgentResult,
   AgentUsage,
   AgentUsageTotal,
+  ClosedReason,
   DisplayItem,
   ExecutionMode,
   ExecutionRecord,
@@ -156,6 +157,10 @@ export function createRecord(
     parentRecordId?: string;
     /** subagent 递归深度。顶层=0。 */
     depth?: number;
+    /** 对话模式标志（true = 可持续对话，轮次完成进 idle）。默认 undefined/false = 一次性。 */
+    chatMode?: boolean;
+    /** 空闲超时毫秒数（仅 chatMode 有意义）。覆盖默认 5min。 */
+    idleTimeoutMs?: number;
     controller?: AbortController;
   },
 ): ExecutionRecord {
@@ -171,6 +176,8 @@ export function createRecord(
     rootSessionId: identity.rootSessionId,
     parentRecordId: identity.parentRecordId,
     depth: identity.depth ?? 0,
+    chatMode: identity.chatMode,
+    idleTimeoutMs: identity.idleTimeoutMs,
 
     // 状态（实时更新）
     status: "running",
@@ -180,6 +187,8 @@ export function createRecord(
     turnCount: 0,
     totalTokens: 0,
     lastError: undefined,
+    // 对话轮次计数（首轮 = 0，每完成一轮 finalizeRoundToIdle +1）。非 chatMode 不自增。
+    round: 0,
 
     // 完成（completeRecord 唯一写点）
     endedAt: undefined,
@@ -233,6 +242,30 @@ function findRunningToolCall(
   return undefined;
 }
 
+/**
+ * [perf] running toolCall 倒序索引：tool_start push 位置入索引，tool_end 弹尾定位
+ *（尾部 = 最后 push 的同名项，与 findRunningToolCall 倒序全扫的语义等价），把每次
+ * tool_end 的 O(所有 turns × toolCalls) 扫描降为 O(1)。WeakMap 按 record 实例隔离
+ *（createRecord 新实例从空索引开始，不影响旧实例）。
+ * 索引 miss（重建 record 的历史 running toolCall / 外部注入工具无 tool_start）
+ * 回退 findRunningToolCall 全扫兜底——正确性不依赖索引完整性。
+ */
+const runningToolIndex = new WeakMap<ExecutionRecord, Map<string, Array<{ turn: Turn; idx: number }>>>();
+
+function indexToolStart(record: ExecutionRecord, turn: Turn, toolName: string): void {
+  let byName = runningToolIndex.get(record);
+  if (byName === undefined) {
+    byName = new Map();
+    runningToolIndex.set(record, byName);
+  }
+  const arr = byName.get(toolName);
+  if (arr === undefined) {
+    byName.set(toolName, [{ turn, idx: turn.toolCalls.length - 1 }]);
+  } else {
+    arr.push({ turn, idx: turn.toolCalls.length - 1 });
+  }
+}
+
 /**
  * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
  *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
@@ -271,13 +304,30 @@ export function updateFromEvent(record: ExecutionRecord, event: AgentEvent): voi
         _status: "running",
         startedTs: Date.now(),
       };
-      currentTurn(record).toolCalls.push(tc);
+      const turn = currentTurn(record);
+      turn.toolCalls.push(tc);
+      indexToolStart(record, turn, event.toolName);
       return;
     }
 
-    // ── tool_end：跨 turn 找 running 同名 toolCall，补全 result/isError/_status ──
+    // ── tool_end：索引弹尾 O(1) 定位 running 同名 toolCall，miss 回退全扫兜底 ──
     case "tool_end": {
-      const matched = findRunningToolCall(record, event.toolName);
+      let matched: readonly [Turn, number] | undefined;
+      const byName = runningToolIndex.get(record);
+      const arr = byName?.get(event.toolName);
+      if (arr !== undefined && arr.length > 0) {
+        const item = arr[arr.length - 1];
+        arr.pop();
+        const tc = item.turn.toolCalls[item.idx];
+        if (tc !== undefined && tc._status === "running") {
+          matched = [item.turn, item.idx] as const;
+        }
+      }
+      if (matched === undefined) {
+        // 兜底：重建 record 的历史 running toolCall（索引未覆盖）、索引项被外部路径
+        // 置非 running 等场景——保持与旧实现一致的跨 turn 倒序全扫。
+        matched = findRunningToolCall(record, event.toolName);
+      }
       if (matched !== undefined) {
         const [turn, i] = matched;
         const tc = turn.toolCalls[i]!;
@@ -488,6 +538,51 @@ export function getFullText(record: ExecutionRecord): string {
     .join("\n\n");
 }
 
+/**
+ * [增量通知] 从 fromTurnIndex 起聚合 turn 文本（getFullText 的增量视图）。
+ *
+ * 语义：record.turns.slice(Math.max(0, fromTurnIndex)) 的 text 数组
+ * filter(text => text.length > 0)（判据与 getFullText 逐字对齐——空白串 " " 按非空
+ * 处理，不发散）后 join("\n\n")。
+ *
+ * 不变式（单测锁死）：
+ *   - fromTurnIndex = 0 与 getFullText(record) 逐字节等价（one-shot/首轮回退零成本）
+ *   - fromTurnIndex >= turns.length 返回 ""（不抛错、不回绕）
+ *   - fromTurnIndex < 0 规范化为 0（防御，Math.max 不产生 slice 负偏移语义）
+ *
+ * 纯函数只读；getFullText 本体与既有调用方（collectResult 等）零改动。
+ * 唯一调用点 onRoundSettled 的增量派生（record.roundBaseTurnIndex ?? 0）。
+ */
+export function getFullTextFrom(record: ExecutionRecord, fromTurnIndex: number): string {
+  return record.turns
+    .slice(Math.max(0, fromTurnIndex))
+    .map((t) => t.text)
+    .filter((text) => text.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * [增量通知] 轮次边界推进公式（D1）：返回下一轮增量的 turns[] 起始下标。
+ *
+ * record.turns.length - (末 turn 存在且 !closed 且 text.length === 0 ? 1 : 0)
+ *
+ * - 末 turn 已闭合（pi 现序常态：带 usage 的 message_end 恒先于 turn_end，settle 时
+ *   全闭合）→ 返回 length，下一轮从新 turn 起。
+ * - 末 turn 是滞后 message_end 开出的空 turn（防御分支，pi 现序不可达）→ 不计入边界
+ *   （-1），留在下一轮增量内：新轮首个 text_delta 经 currentTurn 复用该空 turn，复用
+ *   累积被 slice(from) 覆盖；若直用 turns.length 会把这段文本挤出 slice 范围静默丢失（D1）。
+ * - 末 turn 未闭合且 text 非空（防御形态，pi 现序不可达）→ 计入本轮返回 length（该形态
+ *   即 onRoundSettled 推进前观测哨 logger.warn 的触发条件）。
+ *
+ * 纯函数只读不写 record；唯一调用点 onRoundSettled 第 5 步（notify 之后推进）。
+ */
+export function nextRoundBaseTurnIndex(record: ExecutionRecord): number {
+  const last = record.turns[record.turns.length - 1];
+  const trailingOpenEmpty =
+    last !== undefined && !last.closed && last.text.length === 0 ? 1 : 0;
+  return record.turns.length - trailingOpenEmpty;
+}
+
 /**
  * 聚合所有 turn 的 toolCalls（扁平化），并 strip InternalToolCall 的内部字段。
  * 供 collectResult / schema enforcement 读，替代旧闭包 toolCalls 旁路。
@@ -499,6 +594,17 @@ export function getAllToolCalls(record: ExecutionRecord): ToolCall[] {
   return record.turns.flatMap((t) => t.toolCalls.map(stripInternal));
 }
 
+/**
+ * 聚合所有 turn 的 toolCalls 总数（免克隆计数）。
+ *
+ * getAllToolCalls 会 flatMap + strip 克隆出完整数组——只需计数的调用方（渲染签名
+ * 每 200ms tick 调用一次）用它是纯浪费；本函数 reduce 累加各 turn 的 length，零分配。
+ * 与 getAllToolCalls(...).length 恒等（同一 turns 源）。
+ */
+export function countAllToolCalls(record: ExecutionRecord): number {
+  return record.turns.reduce((sum, t) => sum + t.toolCalls.length, 0);
+}
+
 /** 把 InternalToolCall 映射回纯净的 ToolCall（丢弃 _status / startedTs）。 */
 function stripInternal(tc: InternalToolCall): ToolCall {
   return {
@@ -540,21 +646,26 @@ export function getTotalUsage(record: ExecutionRecord): AgentUsageTotal | undefi
 /**
  * status 状态机的 CAS 互斥锁。仅当 `record.status === "running"` 时改为 target
  * 并返回 true，否则返回 false。**status 状态机本身就是互斥锁**——终态
- * （done/failed/cancelled/crashed）不可逆，check-then-set 在 JS 单线程事件循环里天然原子。
+ * （closed/cancelled）不可逆，check-then-set 在 JS 单线程事件循环里天然原子。
  *
  * 用途：executor 的收尾竞争。cancelBackground 与 background detached 完成回调
  * 都调 tryTransition 抢锁：抢到负责完整收尾，没抢到闭嘴不做事。
  *
- * target 仅限正常执行流的三终态。crashed 不作 target——它由重建路径推断
- * （alive marker 存在但 session 文件无终态），不走 CAS；重建路径用 markReconstructedStatus
- * 直接赋值。收窄 target 类型可在编译期拒绍误用 tryTransition(record, "crashed")。
+ * target 仅限正常执行流的两终态（closed + cancelled）。
+ * closed 携带 closedReason（L2 原因子枚举），由重建路径或正常执行流写入。
+ * 重建路径也可用 markReconstructedStatus 直接赋值（跳过 CAS）。
+ *
+ * @param closedReason closed 终态的 L2 关闭原因。仅 target="closed" 时有意义；
+ *   target="cancelled" 时忽略。缺省 "gc"（通用完成/失败）。
  */
 export function tryTransition(
   record: ExecutionRecord,
-  target: "done" | "failed" | "cancelled",
+  target: "closed",
+  closedReason?: ClosedReason,
 ): boolean {
   if (record.status !== "running") return false;
   record.status = target;
+  record.closedReason = closedReason ?? "gc";
   return true;
 }
 
@@ -577,13 +688,18 @@ export function markReconstructedStatus(
  * 不修改 turns/totalTokens——已由 updateFromEvent 累积，completeRecord 只读不重置。
  *
  * ⚠ 前置条件：调用方必须先通过 tryTransition 抢到锁（status 已被 CAS 设为 target）。
+ *
+ * @param closedReason closed 终态的 L2 关闭原因。仅 status="closed" 时写入；
+ *   "cancelled" 时忽略。
  */
 export function completeRecord(
   record: ExecutionRecord,
   result: AgentResult,
-  status: "done" | "failed" | "cancelled",
+  status: "closed",
+  closedReason?: ClosedReason,
 ): void {
   record.status = status;
+  record.closedReason = closedReason ?? "gc";
   record.endedAt = Date.now();
   record.agentResult = result;
   record.result = result.text;
@@ -663,6 +779,7 @@ export function snapshot(record: ExecutionRecord): RecordSnapshot {
     task: record.task,
     slug: record.slug,
     status: record.status,
+    chatMode: record.chatMode,
     turns: record.turnCount,
     totalTokens: record.totalTokens,
     startedAt: record.startedAt,

package/src/execution/finalize-record.ts

@@ -27,7 +27,7 @@ import type { ModelConfigService } from "./model-config-service.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
 import type { RecordStore } from "./record-store.ts";
 import { writeCancelledTombstone } from "./tombstone-store.ts";
-import type { AgentResult, ExecutionRecord } from "./types.ts";
+import type { AgentResult, ClosedReason, ExecutionRecord } from "./types.ts";
 import type { WorktreeManager } from "./worktree-manager.ts";
 
 const logger = getLogger("subagents");
@@ -40,10 +40,10 @@ export interface FinalizeDeps {
   modelService: ModelConfigService;
   /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
   pi: { appendEntry?: (type: string, data: unknown) => void } | null;
-  /** 清节流状态（防 trailing timer 在 record 归档后误发陈旧 onUpdate）。 */
-  clearThrottle(id: string): void;
   /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
   emitUnregister(id: string, status: string): void;
+  // [review 修复] 已删除 redeliverPending 回调（MF-1 消费确认制补投）：pendingMessages
+  // 三段消费链随 deliverToRunning 一并移除（无生产调用方，死机制）。
 }
 
 /**
@@ -57,11 +57,9 @@ export async function doFinalizeRecord(
   deps: FinalizeDeps,
   record: ExecutionRecord,
   result: AgentResult,
-  status: "done" | "failed" | "cancelled",
+  status: "closed",
+  closedReason?: ClosedReason,
 ): Promise<void> {
-  // 终态清节流状态：防 trailing timer 在 record 归档后误发陈旧 onUpdate
-  deps.clearThrottle(record.id);
-
   // ── Step 0: collectPatch（best-effort）──
   // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
   //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
@@ -73,7 +71,7 @@ export async function doFinalizeRecord(
       );
       fs.mkdirSync(sessionsDir, { recursive: true });
       const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
-      const patch = deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
       if (patch.written) record.patchFile = patchFile;
     } catch (pe: unknown) {
       bestEffort(pe, "collectPatch (finalizeRecord Step0)");
@@ -82,7 +80,7 @@ export async function doFinalizeRecord(
 
   // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
   try {
-    completeRecord(record, result, status);
+    completeRecord(record, result, status, closedReason);
   } catch (err) {
     bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
   }
@@ -100,8 +98,8 @@ export async function doFinalizeRecord(
   //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
   if (record.sessionFile) {
     try {
-      // MF-1 fix: cancelled 状态写 tombstone 而非 finalized，防重建丢失 cancelled
-      if (status === "cancelled") {
+      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
+      if (closedReason === "cancelled") {
         writeCancelledTombstone(record.sessionFile, {
           id: record.id,
           status: "cancelled",
@@ -118,7 +116,7 @@ export async function doFinalizeRecord(
   }
   if (record.worktreeHandle) {
     try {
-      deps.worktreeManager.cleanup(record.worktreeHandle);
+      await deps.worktreeManager.cleanup(record.worktreeHandle);
     } catch (err) {
       bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
     }
@@ -146,7 +144,8 @@ export async function doFinalizeRecord(
       rootSessionId: record.rootSessionId ?? "",
       parentRecordId: record.parentRecordId,
       agentName: record.agent,
-      status: status === "done" ? "completed" : status,
+      // v4 B-1: manifest status 统一为 closed（cancelled 折入 closed，区分靠 tombstone sidecar）
+      status: "closed",
       createdAt: record.startedAt,
       completedAt: record.endedAt ?? Date.now(),
       sessionFile: record.sessionFile,
@@ -163,3 +162,90 @@ export async function doFinalizeRecord(
     });
   }
 }
+
+/**
+ * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
+ *
+ * 与 doFinalizeRecord 的关键区别（M2-A idle 语义）：
+ *   - 不调 completeRecord（record 不冻结，保留 turns[] 等运行时状态供续聊累积）
+ *   - 不调 store.archive（record 留内存，getMutable 可查、list 可见）
+ *   - 不 cleanup worktree（保留对话模式工作目录）
+ *   - 不写 manifest（idle 非终态，manifest 是终态诊断辅助）
+ *   - 删 .alive marker（进程已 SIGTERM 回收，不再是活进程）
+ *   - emitUnregister（进程已死，从 pending 活跃后代差集移除；record 留内存不 archive）
+ *
+ * MF-2：设 record.result = result.text（否则 notifier idle 回复正文恒为 "(empty)"，
+ *   G1/G2 多轮回复送达不成立）。失败轮次（result.success=false，MF-6 回退 idle 路径）
+ *   的 result.text 可能为空，用 result.error 兜底让 notify 可读。
+ *
+ * 状态：record.status = "idle"（覆盖 tryTransition 设的 done/failed），record.round += 1。
+ * 各步骤 best-effort 互不阻断（参照 doFinalizeRecord 的 bestEffort 用法）。
+ *
+ * @param deps 与 doFinalizeRecord 同源（从 SubagentService 注入）
+ * @param result 本轮 AgentResult（MF-2：result.text 写入 record.result 供 notifier idle 回复）
+ */
+export async function doFinalizeRoundToIdle(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+): Promise<void> {
+  // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
+  // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
+  // [R2-1] 轮终写点恒写非空：one-shot 空文本成功完成（collectResult getFullText 返回 ""、
+  // success=true、真实可达，本写点被 subagent-service runAndFinalize 的成功分支共用）首轮
+  // result 前值 undefined，兜底补 "(empty)" 占位——措辞与 notifier buildLlmContent 的
+  // `record.result ?? "(empty)"` 兜底同款，通知文案逐字节不变（[增量 G2] G4 取舍保持）。
+  // 轮终信号优先：record.result 非 undefined 是 renderer hasRunning 排除「轮终
+  // running-resumable」的判据（shared SubagentRecord.result 契约），保持 undefined 会让
+  // 完成注入后末位 turn 永久「工作中」。续轮（前值存在）沿用前值：one-shot 无增量语义，
+  // record.result = 该 subagent 最终输出。chatMode 空增量轮 → 固定占位
+  // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
+  // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
+  let nextResult: string | undefined;
+  if (result.text) {
+    nextResult = result.text;
+  } else if (result.error) {
+    nextResult = `round did not complete: ${result.error}`;
+  } else if (record.chatMode) {
+    nextResult = "(no output this round)";
+  } else {
+    nextResult = record.result ?? "(empty)";
+  }
+  record.result = nextResult;
+
+  // 删 .alive marker（进程已 SIGTERM 回收）。
+  // sessionFile 窗口期可能 undefined（极少——对话模式轮次完成意味着 session 已跑过），
+  // 缺失时跳过但仍设内存 idle（重启后磁盘重建会落到 crashed，边界可接受）。
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (doFinalizeRoundToIdle)");
+    }
+  }
+
+  // pending-notifications：进程已死，从活跃后代差集移除（record 留内存不 archive，
+  // v4 B-1：record 现为 running-resumable，但 pending 注册的是进程活跃性，进程死了需注销）。
+  deps.emitUnregister(record.id, "running");
+
+  // 状态机（v4 B-1）：record 保持 running（旧 idle 折入 running，覆盖 tryTransition 设的 closed，
+  // 可冷路径 resume），轮次计数 +1。idleSince 时间戳独立保留供 GC 判据。
+  // [S10] closedReason 同步清除：调用方（runAndFinalize catch / MF-6 分支）先 tryTransition
+  // 设了 closed+closedReason 再回退 running——不清则 "gc"/"cancelled" 残留在 running record 上，
+  // 泄漏进 list 投影与后续 notify 载荷（toNotifyRecord 透传 record.closedReason），让一个
+  // 活跃 record 看起来像已被某原因关闭过。
+  record.status = "running";
+  record.closedReason = undefined;
+  record.round = (record.round ?? 0) + 1;
+  record.idleSince = Date.now();
+  // 执行态信号（residual-fixes）：轮终回 running-resumable = 无活进程驱动（idle timer
+  // 回收/保活等待续聊），GUI 侧据此判 waiting（非 streaming）。冷路径续轮（进程启动）清除。
+  record.resumable = true;
+
+  // W16 [D4]：轮终回 running-resumable 是类外状态写点（record 留内存不走 archive），
+  // 显式上报迁移——entry 携带新 round 与本轮 result，pi 文件的重建源不滞后。
+  deps.store.reportRecordTransition(record);
+
+  // [review 修复] 已删除残留 pendingMessages 的 redeliverPending 补投段（MF-1 消费
+  // 确认安全网）：三段消费链随 deliverToRunning 一并移除，本段不可达。
+}

package/src/execution/idle-gc.ts

@@ -0,0 +1,47 @@
+/**
+ * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
+ * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
+ * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
+ */
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { bestEffort } from "./best-effort.ts";
+import { isResumable } from "./lifecycle-predicates.ts";
+import type { RecordStore } from "./record-store.ts";
+
+const logger = getLogger("subagents");
+
+/** GC 扫描间隔：1 小时。 */
+// eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+/** idle record TTL：30 天（超龄归档）。 */
+// eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
+const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** 毫秒/天（GC 日志的 d 换算）。 */
+// eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
+ * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
+ * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ */
+export function startIdleGc(store: RecordStore): () => void {
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const record of store.listAllActive()) {
+      if (isResumable(record) && record.idleSince) {
+        const age = now - record.idleSince;
+        if (age > IDLE_TTL_MS) {
+          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
+          try {
+            store.archive(record);
+          } catch (err) {
+            bestEffort(err, `GC archive record ${record.id}`);
+          }
+        }
+      }
+    }
+  }, GC_INTERVAL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}