@zhushanwen/subagent-core 0.2.0

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]);
+}

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

@@ -0,0 +1,64 @@
+// 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

@@ -0,0 +1,120 @@
+// 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

@@ -0,0 +1,170 @@
+// src/execution/session-pending.ts
+//
+// agent_end 后代判定：读子进程的 session 文件，用 pending-notifications 的
+// register − unregister 差集计数（经通知域窄端口 NotifyDomainPorts 注入的
+// countActiveFromEntries——core 依赖闭包不含 pi-pending-notifications，见
+// core/notify-ports.ts；端口缺席时按零活跃处理 = pending 门全开）判断该 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 { getLogger } from "../core/logger.ts";
+import { getNotifyDomainPorts } from "../core/notify-ports.ts";
+
+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 });
+    }
+  }
+
+  // 计数器经通知域窄端口解析（缺省实现恒 0 = 零活跃，pending 门全开——安全侧缺省
+  // 收敛在端口层，见 core/notify-ports.ts DEFAULT_NOTIFY_PORTS；此处 `?? 0` 仅防御
+  // 宿主注入部分端口对象的形态）。
+  const countActive = getNotifyDomainPorts().countActiveFromEntries;
+  const active = countActive ? countActive(cursor.entries) : 0;
+  return {
+    count: active,
+    recentUnregister:
+      cursor.latestUnregisterMs > 0 &&
+      Date.now() - cursor.latestUnregisterMs < RECENT_UNREGISTER_WINDOW_MS,
+  };
+}