@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/path-encoding.ts

@@ -1,60 +0,0 @@
-// src/core/path-encoding.ts
-//
-// cwd → 安全目录名的编码逻辑。Core 叶子原语（零依赖）。
-//
-// 被 session-runner（subagent session 持久化目录）与 session-file-gc（清理过期
-// session 文件）共用——两处需要相同的编码，否则同一 cwd 会落到两个不同目录。
-
-import * as path from "node:path";
-
-/**
- * cwd → 安全目录名。复用 Pi SDK getDefaultSessionDir 的编码逻辑：
- * 去开头单个分隔符，全量替换剩余分隔符/冒号为 `-`，首尾补 `--`。
- * 例：`/Users/x/proj` → `--Users-x-proj--`。
- */
-export function encodeCwd(cwd: string): string {
-  return "--" + cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
-}
-
-/**
- * 获取 subagent session 持久化目录路径。
- *
- * D-004: 用主 cwd 编码——保证同一主 cwd 下所有 subagent 的 session 文件
- * 存放在同一目录，便于 session-file-gc 统一清理。
- * [MF-3] worktree 模式下调用方必须传树根 cwd（ROOT mainCwd，经 PI_SUBAGENT_ROOT_CWD
- * 贯穿），不能传子进程自身的 checkout 路径——否则深层 record 落盘到 enc(worktree) 段，
- * ROOT 磁盘重建扫不到（全树可见性断裂）。根进程传自身 cwd（行为不变）。
- *
- * @param agentDir agent 配置目录（如 ~/.pi/agent）
- * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
- *   是 ROOT 的 cwd，不是 checkout 路径）
- * @returns session 持久化目录绝对路径
- */
-export function getSubagentSessionDir(agentDir: string, mainCwd: string): string {
-  // [MF#1] 保持既有布局 subagents/<enc>/sessions/——曾改为 subagents/sessions/<enc>/ 会让
-  // 升级用户的既有 session 文件全部落到扫描目录外（历史记录消失 + GC 扫不到，双重 orphan）。
-  // 本分支未发布，回退到既有布局即无需迁移、无数据丢失。
-  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "sessions");
-}
-
-/**
- * 获取 subagent records（manifest）持久化目录路径。
- *
- * 与 getSubagentSessionDir 同用 encodeCwd(mainCwd)，保证 records 与 sessions 在同一
- * <enc> 段下物理相邻。
- * [MF-3] 调用方必须与 getSubagentSessionDir 传同一编码键（进程内 init.cwd /
- * buildSessionRunnerContext.mainCwd / record.worktreeHandle.mainCwd 恒等；worktree 模式
- * 跨进程时统一用贯穿的 ROOT cwd）——sessions 与 records 两套目录同段，GC/重建才不会
- * 互相找不到（enc 段不变量）。
- *
- * D-004 同源：用主 cwd 编码做物理隔离，使 session-file-gc 按 <enc>/records/ 子目录
- * 匹配 manifest .json 时天然限定在当前 cwd 范围内，不会越界清理其他 cwd 的 manifest。
- *
- * @param agentDir agent 配置目录（如 ~/.pi/agent）
- * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
- *   是 ROOT 的 cwd，不是 checkout 路径）
- * @returns records 持久化目录绝对路径
- */
-export function getSubagentRecordsDir(agentDir: string, mainCwd: string): string {
-  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "records");
-}

package/src/execution/pi-invocation.ts

@@ -1,120 +0,0 @@
-// src/execution/pi-invocation.ts
-//
-// 定位 pi 二进制并组装 spawn 调用。Core 叶子原语（仅依赖 node 内置）。
-//
-// spawn 改造（in-process → spawn pi --mode json）的基座模块。
-// 被 runSpawn（session-runner）调用，决定子进程用哪个命令启动。
-//
-// 移植自 nicobailon subagent example 的 getPiInvocation，处理三种运行时：
-//   1. bun bundle（/$bunfs/root/ 虚拟脚本）→ 退化到 pi-in-PATH
-//   2. 有真实脚本路径（node + script）→ node <script> <args>
-//   3. node/bun generic runtime（无脚本）→ pi <args>（依赖 PATH）
-//
-// 注意：pi 在扩展进程内运行时 process.execPath 是 node/bun，process.argv[1]
-// 是 pi 的入口脚本。子进程需要复现同样的启动方式才能保证扩展/配置一致加载。
-
-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 二进制）。 */
-  command: string;
-  /** 命令行参数（可能含 [scriptPath, ...userArgs] 或直接 [...userArgs]）。 */
-  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。
- */
-const BUN_VIRTUAL_PREFIX = "/$bunfs/root/";
-
-/**
- * 判断 execPath 的 basename 是否为通用运行时（node/bun）。
- * 通用运行时需要脚本路径才能启动 pi；非通用（如 pi 的 standalone binary）可直接执行。
- */
-function isGenericRuntime(execPath: string): boolean {
-  const execName = path.basename(execPath).toLowerCase();
-  return /^(node|bun)(\.exe)?$/.test(execName);
-}
-
-/**
- * 组装 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>
- *   3. 通用运行时但无可用脚本路径 → "pi" <userArgs>（依赖 PATH 中可找到 pi）
- */
-// [perf] 决策链只依赖 process.argv[1] / process.execPath（进程内恒定），其中唯一的
-// 磁盘探测（existsSync）结果 memo 一次——每次 spawn 免重复 syscall。memo 键含
-// argv[1] 值：测试 mock 切换 argv[1] 模拟不同运行时时自动失效重算。
-let scriptExistsCache: { script: string | undefined; exists: boolean } | undefined;
-
-/** process.argv[1] 是真实磁盘脚本（非 bun 虚拟路径）且存在。 */
-function currentScriptExists(): boolean {
-  const currentScript = process.argv[1];
-  if (scriptExistsCache === undefined || scriptExistsCache.script !== currentScript) {
-    scriptExistsCache = {
-      script: currentScript,
-      exists:
-        currentScript !== undefined &&
-        !currentScript.startsWith(BUN_VIRTUAL_PREFIX) &&
-        fs.existsSync(currentScript),
-    };
-  }
-  return scriptExistsCache.exists;
-}
-
-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] };
-  }
-
-  // 分支 2：非通用运行时（pi 自带 binary）→ 直接执行
-  if (!isGenericRuntime(process.execPath)) {
-    return { command: process.execPath, args: userArgs };
-  }
-
-  // 分支 3：通用运行时但脚本不可用 → 依赖 PATH
-  return { command: "pi", args: userArgs };
-}

package/src/execution/record-entry.ts

@@ -1,132 +0,0 @@
-// src/execution/record-entry.ts
-//
-// W16 [D4]：subagent record 自描述持久化 entry 的形态权威。
-//
-// pi 文件（session JSONL）是扩展数据持久化权威：record 状态每次迁移都经
-// pi.appendEntry 落一条自描述完整快照（字段即 SubagentRecord），读取方无需
-// 逆向解析 toolCall/toolResult。内存 record-store 保持运行时权威，entry 是
-// 重建源（两者不冲突）。
-//
-// customType 与既有 `subagent-identity`（session 文件首行身份 entry）同族命名
-//（连字符风格）；写点见 record-store.ts 的状态迁移点（register/archive/
-// reportRecordTransition），custom entry 由 pi 写进 session JSONL，不进 LLM context。
-
-import type {
-  AgentEventLogEntry,
-  ClosedReason,
-  DisplayItem,
-  ExecutionMode,
-  ExecutionStatus,
-  SubagentRecord,
-} from "./types.ts";
-
-/** 自描述 record entry 的 customType。写点字面量与本常量的等值由
- *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。 */
-export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
-
-/**
- * `subagent-record` entry 的 data schema（v1）。
- *
- * = 完整 SubagentRecord 快照（GUI 侧列表/详情需要的全部持久化字段）+ 版本号。
- * 显式排除三个非持久化字段（与 SubagentRecord 的差集）：
- *   - currentActivity：running 时的瞬时流态，重开 session 无重建价值；
- *   - externalInstance：跨重启探活态（pid/startedAt），由 .alive sidecar 重建；
- *   - worktreeHandle：不可 JSON 序列化的运行时句柄（布尔投影 worktree 保留）。
- *
- * undefined 字段经 JSON.stringify 自然缺省（与 SubagentRecord 重建侧语义一致）。
- */
-export interface SubagentRecordEntryData {
-  /** schema 版本（W16 起 v1）。消费方按 v 判别解析，不认识的版本跳过而非猜测。 */
-  v: 1;
-  id: string;
-  agent: string;
-  /** 任务提示词（详情面板置顶展示）。 */
-  task: string;
-  /** 短标签（≤35 字符）。 */
-  slug: string;
-  status: ExecutionStatus;
-  /** L2 关闭原因（仅 status="closed" 时有意义）。 */
-  closedReason?: ClosedReason;
-  mode: ExecutionMode;
-  startedAt: number;
-  /** 根 Pi session ID（session 隔离过滤用）。 */
-  rootSessionId: string | undefined;
-  /** 直接父 subagent record ID（层级树构建用）。顶层为 undefined。 */
-  parentRecordId: string | undefined;
-  /** subagent 递归深度。顶层 = 0。 */
-  depth: number;
-  endedAt: number | undefined;
-  /** turn 计数。 */
-  turns: number;
-  totalTokens: number;
-  model: string;
-  thinkingLevel: string | undefined;
-  /** 详情事件日志（/subagents 详情面板）。 */
-  eventLog: AgentEventLogEntry[];
-  /** 从 turns[] 派生的展示项。 */
-  displayItems: DisplayItem[];
-  result?: string;
-  error?: string;
-  sessionFile?: string;
-  /** [MF#3] worktree 模式改动 patch 文件路径。 */
-  patchFile?: string;
-  /** 创建时是否启用 worktree 隔离。 */
-  worktree?: boolean;
-  /** 对话轮次计数（仅 chatMode 有意义；round+1 由轮终迁移写点携带）。 */
-  round?: number;
-  /**
-   * 对话模式标志（residual-fixes）：chat 与否——GUI 侧 done/waiting 细分判据
-   * （one-shot 轮终 chatMode=false + result 有值 → 完成态）。register 起写入显式值
-   * （one-shot 为显式 false）；v1 前存量 entry 缺省，消费端按保守方向处理。
-   */
-  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 源）。 */
-export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEntryData {
-  return {
-    v: 1,
-    id: record.id,
-    agent: record.agent,
-    task: record.task,
-    slug: record.slug,
-    status: record.status,
-    closedReason: record.closedReason,
-    mode: record.mode,
-    startedAt: record.startedAt,
-    rootSessionId: record.rootSessionId,
-    parentRecordId: record.parentRecordId,
-    depth: record.depth,
-    endedAt: record.endedAt,
-    turns: record.turns,
-    totalTokens: record.totalTokens,
-    model: record.model,
-    thinkingLevel: record.thinkingLevel,
-    eventLog: record.eventLog,
-    displayItems: record.displayItems,
-    result: record.result,
-    error: record.error,
-    sessionFile: record.sessionFile,
-    patchFile: record.patchFile,
-    worktree: record.worktree,
-    round: record.round,
-    chatMode: record.chatMode,
-    resumable: record.resumable,
-    engine: record.engine,
-    engineFallback: record.engineFallback,
-    engineHandle: record.engineHandle,
-  };
-}