@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/execution/relay-env.ts

@@ -1,37 +0,0 @@
-/**
- * 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]);
-}

package/src/execution/session-context-resolver.ts

@@ -1,64 +0,0 @@
-// src/core/session-context-resolver.ts
-//
-// resolveSessionContext 纯函数——解析 fork/worktree 意图，返回执行上下文。
-// D-014: 零副作用，零 Pi import。只返回意图，不调 forkFrom/不创建 sessionDir。
-
-import type { ResolvedSessionContext, SessionResolveInput } from "./types.ts";
-import { ForkDepthExceededError } from "./types.ts";
-import { getSubagentSessionDir } from "./path-encoding.ts";
-
-/**
- * fork 深度硬限。export 供 session-runner 注入 LLM env block 时引用同一常量，
- * 避免硬限（拦截）与展示（`N/10`）两处 10 漂移。
- *
- * 双层护栏（互补，共享本常量）：
- *   1. resolveSessionContext 的 fork 护栏（parentForkDepth >= MAX_FORK_DEPTH → 拒）：
- *      只计 fork 链（fork=true 才递增 parentForkDepth），控 session 体积（每层 createBranchedSession）。
- *   2. SubagentService.execute 入口的通用嵌套护栏（nestingDepth > MAX_FORK_DEPTH → 拒）：
- *      经 execCtxAls 计所有 subagent 嵌套（fork + 非 fork），更严——混合链
- *      （fork→非fork→fork）下 nestingDepth >= parentForkDepth，通用护栏先生效。
- * 两者均允许深度 0..MAX_FORK_DEPTH（共 MAX+1 层），第 MAX+1 层（深度=MAX+1）被拒。
- */
-export const MAX_FORK_DEPTH = 10;
-
-/**
- * 纯函数：解析 fork/worktree 意图 → 执行上下文。
- *
- * 只返回意图（shouldFork/forkSource/effectiveCwd/sessionDir），
- * 不调 forkFrom / 不创建 sessionDir / 不 git worktree add。
- *
- * @throws {ForkDepthExceededError} fork=true 且 parentForkDepth >= 10
- */
-export function resolveSessionContext(input: SessionResolveInput): ResolvedSessionContext {
-  const { fork, cwd, mainCwd, mainSessionFile, parentForkDepth, agentDir, worktreePath } =
-    input;
-
-  // fork 深度检查（D-007）
-  if (fork && (parentForkDepth ?? 0) >= MAX_FORK_DEPTH) {
-    throw new ForkDepthExceededError(
-      `fork depth ${parentForkDepth ?? 0} >= ${MAX_FORK_DEPTH}, refusing to fork`,
-    );
-  }
-
-  const shouldFork = fork === true;
-  const forkSource = shouldFork ? mainSessionFile : undefined;
-
-  // [MF#5] fork 显式请求但主 session 文件不可用（session_start 未缓存）时直接抛错，
-  // 不静默降级到 from-scratch——否则用户显式 fork 却得到无继承 session，且无任何告警。
-  if (shouldFork && !forkSource) {
-    throw new Error(
-      "fork requested but main session file is unavailable " +
-        "(session_start did not cache it); cannot fork without a source session",
-    );
-  }
-
-  // effectiveCwd: worktree 模式用 handle.path（真实 checkout，由调用方传入），
-  // 否则用显式 cwd 或 mainCwd。worktreePath 与 worktree 标志同源（都来自 WorktreeHandle），
-  // 不再靠 tmpdir 拼凑，保证 effectiveCwd 与实际 checkout 严格一致。
-  const effectiveCwd = worktreePath ?? (cwd ?? mainCwd);
-
-  // sessionDir 用 mainCwd 编码（D-004: 同一主 cwd 下所有 subagent 存同一目录）
-  const sessionDir = getSubagentSessionDir(agentDir, mainCwd);
-
-  return { shouldFork, forkSource, effectiveCwd, sessionDir };
-}

package/src/execution/session-file-gc.ts

@@ -1,120 +0,0 @@
-// src/runtime/session-file-gc.ts
-//
-// 概率性清理过期 subagent session 文件（TTL 30 天）。
-// session_start 时调用，best-effort（失败不影响启动）。
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { isProcessAlive, readAliveMarker } from "./alive-store.ts";
-
-/** 30 天 TTL（毫秒）。 */
-const TTL_DAYS = 30;
-const HOURS_PER_DAY = 24;
-const MINUTES_PER_HOUR = 60;
-const SECONDS_PER_MINUTE = 60;
-const MS_PER_SECOND = 1000;
-const TTL_MS = TTL_DAYS * HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
-
-/** 触发概率（1/20 = 5%，避免每次 session_start 都全扫）。 */
-const CLEANUP_PROBABILITY_DIVISOR = 20;
-const CLEANUP_PROBABILITY = 1 / CLEANUP_PROBABILITY_DIVISOR;
-
-/** subagent session 文件目录（相对 agentDir）。 */
-const SUBAGENTS_DIR = "subagents";
-
-/**
- * 概率性清理过期 session 文件。best-effort——任何异常不外抛。
- *
- *   1. 概率性触发（CLEANUP_PROBABILITY）
- *   2. 递归扫描 <agentDir>/subagents 下所有 .jsonl 文件
- *   3. mtime 超 TTL → unlink
- */
-export function maybeCleanupExpiredSessionFiles(agentDir: string, cwd: string): void {
-  void cwd;
-  try {
-    if (Math.random() >= CLEANUP_PROBABILITY) return;
-    const dir = path.join(agentDir, SUBAGENTS_DIR);
-    if (!fs.existsSync(dir)) return;
-    const now = Date.now();
-    walkAndClean(dir, now);
-  } catch (_e) {
-    // best-effort：任何异常不阻断 session_start
-    void _e;
-  }
-}
-
-/** 递归扫描目录，unlink 超 TTL 的 .jsonl 文件及其 .cancelled sidecar。
- *  [F2] 进入名为 records 的子目录时，额外清理超 TTL 的 manifest .json（跳过 .tmp.——
- *  recoverTmpFiles 同步处理）。allowManifestJson 仅由父调用按目录名开启，其他位置
- *  （如 subagents/worktrees.json）不匹配 .json，避免误删 worktree reaper 状态文件。 */
-function walkAndClean(dir: string, now: number, allowManifestJson = false): void {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch (_e) {
-    void _e;
-    return;
-  }
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      // 只在进入名为 records 的子目录时打开 manifest .json 清理。
-      // records 在 <enc>/records/ 下递归自动覆盖；其他位置（如 subagents/worktrees.json）
-      // 不能匹配 .json——否则会误删 worktree reaper 依赖的状态文件。
-      walkAndClean(full, now, entry.name === "records");
-    } else if (
-      allowManifestJson &&
-      entry.name.endsWith(".json") &&
-      // 跳过 .tmp.：recoverTmpFiles（session_start）同步处理 tmp，GC 不重复。
-      // 不校验内容——30 天 mtime 已是强 orphan 信号，扩展名 + 文件名足够。
-      !entry.name.includes(".tmp.")
-    ) {
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          fs.unlinkSync(full);
-        }
-      } catch (_e) {
-        // 文件可能已被删除，忽略
-        void _e;
-      }
-    } else if (entry.name.endsWith(".jsonl")) {
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          // .alive 探活：活进程的 session 不删（D-024 安全网）。
-          const aliveMarker = readAliveMarker(full);
-          if (aliveMarker !== undefined && isProcessAlive(aliveMarker.pid)) {
-            continue; // 活进程 → 跳过，不清理
-          }
-          fs.unlinkSync(full);
-          // 同名 sidecar 一起清理。
-          for (const ext of [".cancelled", ".finalized", ".alive"]) {
-            try { fs.unlinkSync(`${full}${ext}`); } catch (_e) { void _e; /* sidecar 可能不存在 */ }
-          }
-        }
-      } catch (_e) {
-        // 文件可能已被删除，忽略
-        void _e;
-      }
-    } else if (
-      entry.name.endsWith(".cancelled") ||
-      entry.name.endsWith(".finalized") ||
-      entry.name.endsWith(".alive") ||
-      // [MF#2] patch 回传（<branch>.patch）按 branch 命名，与 .jsonl basename 无关联，
-      // 删除 .jsonl 时无法同删；作为孤儿按 TTL 清理，避免永久堆积。
-      entry.name.endsWith(".patch")
-    ) {
-      // 孤儿 sidecar（兄弟 .jsonl 已被外部删除）：按同 TTL 清理。
-      try {
-        const stat = fs.statSync(full);
-        if (now - stat.mtimeMs > TTL_MS) {
-          fs.unlinkSync(full);
-        }
-      } catch (_e) {
-        void _e;
-      }
-    }
-  }
-}

package/src/execution/session-pending.ts

@@ -1,164 +0,0 @@
-// src/execution/session-pending.ts
-//
-// agent_end 后代判定：读子进程的 session 文件，用 pending-notifications 的
-// countActiveFromEntries（register − unregister 差集）判断该 subagent 是否还有
-// 活跃后代（background subagent / workflow）。
-//
-// 背景（v4 递归编排）：层主 planning-agent 派子 subagent 后结束 turn 等待被唤醒。
-// 若 runSpawn 在 agent_end 无条件 kill，进程被回收、steer 唤醒送不到，递归树断。
-// 判定依据：子进程的 session 文件里 pending:register entry（其进程内 appendEntry
-// 同步写盘，见 pi SessionManager._persist）减去 pending:unregister 的差集。
-// fork 继承的主 session register 残留由 pending-notifications 的 session_start
-// 重建流程补 unregister(expired) 抵消，纯差集不受污染。
-//
-// 纯函数 + fs，独立于 runSpawn，可单测。
-
-import * as fs from "node:fs";
-
-import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("subagents");
-
-/** 后代刚完成（unregister）后，notify 唤醒父 agent 可能仍在路上（triggerTurn 的
- *  steer/followUp 经 sendMessage → agent 队列排空（agent-session.js:1081-1087），
- *  不经 EventBus——EventBus 只用于扩展间 pi.events；与主进程处理 agent_end 行存在
- *  毫秒级竞态——explorer 3 秒完成时实测 unregister 先于 agent_end 判定写入，导致
- *  差集 0 误判完成）。此窗口内的 agent_end 不 kill，等父被唤醒后的下一次 agent_end 再判。 */
-const RECENT_UNREGISTER_WINDOW_MS = 60_000;
-
-/** 判定结果：count > 0 = 有活跃后代（应保持进程等唤醒）。 */
-export interface ActivePendingResult {
-  count: number;
-  /** 最近窗口内（60s）有 pending:unregister——后代刚完成，唤醒通知可能在路上。 */
-  recentUnregister: boolean;
-  /** 读取/解析失败的原因（undefined = 成功）。调用方对 error 采取保守策略（不 kill）。 */
-  error?: string;
-}
-
-/**
- * [perf] per-file 增量游标：session 文件 append-only，同文件重复判定（层主被多个
- * 后代唤醒 N 次 → N 次 agent_end）只需读上次 offset 之后的新增行，累计 entries
- * 差集语义与全量读完全一致。fork 继承的大 session（数十 MB）从「每次整读」降为
- * 「首读全量 + 后续增量」。
- * truncate/重建防御：size < offset → 重置全读。EOF 半行（写入竞态）不入账，
- * offset 只推进到完整行边界，下次补读。
- * 内存量级：每 sessionFile 一条（offset + 后代 entries，均有限）；测试隔离用
- * clearPendingCursors()。
- */
-interface PendingReadCursor {
-  offset: number;
-  entries: unknown[];
-  latestUnregisterMs: number;
-}
-
-const cursors = new Map<string, PendingReadCursor>();
-
-/** 清空增量游标缓存（测试隔离用）。 */
-export function clearPendingCursors(): void {
-  cursors.clear();
-}
-
-/** [taste/no-unsafe-cast] pending 行的最小结构守卫：非 null object 即可（字段访问
- *  侧均做了 undefined 检查，全可选类型断言无校验意义，改守卫带运行时检查）。 */
-function isPendingLineLike(v: unknown): v is { customType?: string; timestamp?: string } {
-  return typeof v === "object" && v !== null;
-}
-
-/**
- * 读 session 文件计算活跃 pending 数（增量读，见 PendingReadCursor）。
- *
- * 快速路径：行内含 pending 值（`"pending:register"` / `"pending:unregister"`）才解析，
- * 大量 message 行只付 includes 扫描跳过 JSON.parse。
- * [S-4] 按值匹配而非 `"customType":"pending:` 序列化格式——后者耦合 pi 的 JSON 序列化
- * 空格习惯（冒号后无空格），pi 改 pretty-print 会导致全过滤 → count=0 → keep-alive
- * 静默失效 → recursive tree 被杀、steer 丢失。值字符串本身不受序列化空格影响。
- *
- * 文件不存在（sessionFile 未回填/首次 assistant 前）→ error（调用方保守不 kill）。
- * 坏行跳过（append 中途崩溃的截断行）。
- */
-export function readActivePendingFromSessionFile(
-  sessionFile: string | undefined,
-): ActivePendingResult {
-  if (!sessionFile) {
-    return { count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" };
-  }
-
-  let size: number;
-  try {
-    size = fs.statSync(sessionFile).size;
-  } catch (err) {
-    return {
-      count: 0,
-      recentUnregister: false,
-      error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-
-  let cursor = cursors.get(sessionFile);
-  if (cursor === undefined || size < cursor.offset) {
-    // 首次（全量）或文件被 truncate/重建（offset 越界）→ 重置从头读
-    cursor = { offset: 0, entries: [], latestUnregisterMs: 0 };
-  }
-
-  let chunk: string;
-  try {
-    if (cursor.offset === 0) {
-      chunk = fs.readFileSync(sessionFile, "utf-8");
-    } else {
-      const fd = fs.openSync(sessionFile, "r");
-      try {
-        const len = size - cursor.offset;
-        const buf = Buffer.alloc(len);
-        let total = 0;
-        while (total < len) {
-          const n = fs.readSync(fd, buf, total, len - total, cursor.offset + total);
-          if (n <= 0) break;
-          total += n;
-        }
-        chunk = buf.toString("utf-8", 0, total);
-      } finally {
-        fs.closeSync(fd);
-      }
-    }
-  } catch (err) {
-    return {
-      count: 0,
-      recentUnregister: false,
-      error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-
-  // 只消费到最后一个完整行：EOF 半行（append 写入竞态）不入账，offset 不推进，
-  // 下次从该行起点重读（补全后正常入账）。
-  const lastNl = chunk.lastIndexOf("\n");
-  const complete = lastNl === -1 ? "" : chunk.slice(0, lastNl);
-  cursor.offset += Buffer.byteLength(complete, "utf-8");
-  cursors.set(sessionFile, cursor);
-
-  for (const line of complete.split("\n")) {
-    // [S-4] 按值匹配：countActiveFromEntries 只消费 register/unregister 两种 customType，
-    // 故只需检测这两个值字符串；冒号前后空格变化不影响（值始终是连续子串）。
-    if (!line.includes('"pending:register"') && !line.includes('"pending:unregister"')) continue;
-    try {
-      const entry: unknown = JSON.parse(line);
-      if (!isPendingLineLike(entry)) continue;
-      cursor.entries.push(entry);
-      if (entry.customType === "pending:unregister" && entry.timestamp) {
-        const ts = Date.parse(entry.timestamp);
-        if (Number.isFinite(ts) && ts > cursor.latestUnregisterMs) cursor.latestUnregisterMs = ts;
-      }
-    } catch {
-      // 截断行/坏行跳过——不影响其余 entry 的差集判定（罕见：append 中途崩溃）
-      logger.debug("skipped malformed pending line", { sessionFile });
-    }
-  }
-
-  const active = countActiveFromEntries(cursor.entries);
-  return {
-    count: active.count,
-    recentUnregister:
-      cursor.latestUnregisterMs > 0 &&
-      Date.now() - cursor.latestUnregisterMs < RECENT_UNREGISTER_WINDOW_MS,
-  };
-}