@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/engine/common/persona-router.ts

@@ -1,108 +0,0 @@
-// src/execution/engine/common/persona-router.ts
-//
-// persona 路由与 argv 预算（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D4（persona 路由按 capabilities
-// 选择 file/flag/prompt 三策略，兼作 argv 长度分流）+ D5（preparer 在 spawn 前估算
-// argv 总长度：仅 argv 投递的引擎超长时在 prepare 期报 prompt_too_large，禁止 spawn
-// 后撞 E2BIG 才失败）+ §3.3.3 prompt_too_large 行。
-//
-// 路由产出按 capabilities.personaInjection 三分（中立层只决策通道与内容，具体 flag
-// 组装归各引擎 launcher）：
-//   - 'file'  → fileCandidate（人设全文落盘为文件，argv 只带文件路径——kimi
-//               --agent-file 形态）；promptSegment 为空（人设不进 prompt）。
-//   - 'flag'  → promptSegment 为人设全文（launcher 组 --system-prompt 类 flag 直传）。
-//   - 'prompt'→ promptSegment 为带引导结构的人设段（拼进最终 prompt——zcode 形态）。
-
-import { promptTooLargeError } from "./errors.ts";
-import type { EngineCapabilities, PersonaSpec } from "../types.ts";
-
-// ============================================================
-// persona 三策略路由
-// ============================================================
-
-/** applyPersona 的返回：按通道产出人设载体。 */
-export interface PersonaRouting {
-  /** 进 prompt / flag 通道的人设文本（file 通道为空串）。 */
-  promptSegment: string;
-  /** file 通道的人设文件落盘候选（suggestedPath 相对池目录，preparer 负责落位）。 */
-  fileCandidate?: { suggestedPath: string; content: string };
-}
-
-/** file 通道的人设文件建议名（相对池目录——preparer 知道池根，router 不感知）。 */
-const PERSONA_FILE_NAME = "persona.md";
-
-/**
- * 按 capabilities.personaInjection 路由 persona 的注入通道。
- *
- * router 不解析 agent .md / skill 文件内容（身份解析归宿主 resolveIdentity）——
- * 只把 PersonaSpec 声明的内容组装成通道载体：appendSystemPrompt 是人设正文，
- * agentRef/skillPath 以引用提示行进文本（prompt 通道）或正文头（file 通道）。
- */
-export function applyPersona(persona: PersonaSpec, capabilities: EngineCapabilities): PersonaRouting {
-  switch (capabilities.personaInjection) {
-    case "file": {
-      const content = buildPersonaBody(persona);
-      // 全空 persona 走 file 通道无意义（空文件白占 argv 一段）——降级为无载体
-      if (content === "") return { promptSegment: "" };
-      return { promptSegment: "", fileCandidate: { suggestedPath: PERSONA_FILE_NAME, content } };
-    }
-    case "flag":
-      // flag 直传：纯正文（launcher 把它作为 --append-system-prompt 类 flag 的值）
-      return { promptSegment: buildPersonaBody(persona) };
-    case "prompt":
-      return { promptSegment: buildPromptSegment(persona) };
-  }
-}
-
-/** 人设正文：appendSystemPrompt join + agentRef/skillPath 头部引用行。 */
-function buildPersonaBody(persona: PersonaSpec): string {
-  const parts: string[] = [];
-  if (persona.agentRef !== undefined) parts.push(`# Agent: ${persona.agentRef}`);
-  if (persona.skillPath !== undefined) parts.push(`Skill context: ${persona.skillPath}`);
-  const body = persona.appendSystemPrompt?.join("\n") ?? "";
-  if (body !== "") parts.push(body);
-  return parts.join("\n");
-}
-
-/** prompt 通道的人设段（带结构头，拼进最终 prompt）。 */
-function buildPromptSegment(persona: PersonaSpec): string {
-  const body = buildPersonaBody(persona);
-  if (body === "") return "";
-  return `## Persona\n${body}`;
-}
-
-// ============================================================
-// argv 长度预算（prepare 期前置拦截）
-// ============================================================
-
-/**
- * argv 预算默认上限（128KB）。依据：POSIX ARG_MAX 通常 ≥ 256KB（Linux 单字符串
- * MAX_ARG_STRLEN 128KB 是更紧的硬顶）——预算取 128KB 留出参数个数与 env 余量，
- * spawn 前拦截，绝不 spawn 后撞 E2BIG（D5）。可经 assertArgvBudget 第二参覆盖。
- */
-export const DEFAULT_ARGV_BUDGET_BYTES =
-  // eslint-disable-next-line no-magic-numbers -- 128KB = 128 * 1024 bytes 预算换算常数
-  128 * 1024;
-
-/**
- * 估算 argv 总字节数：各参数 UTF-8 字节数之和 + 每参数一个 NUL 分隔符。
- * execve 按字节计算参数区，估算口径与内核一致（字符数会低估多字节文本）。
- */
-export function estimateArgvBytes(argv: string[]): number {
-  let total = 0;
-  for (const arg of argv) {
-    total += Buffer.byteLength(arg, "utf8") + 1;
-  }
-  return total;
-}
-
-/**
- * argv 预算断言：估算超限抛 EngineError(prompt_too_large)（恢复指引三条：缩短 task /
- * persona 移 file 通道 / 换 stdin 引擎）。调用点在 preparer（进程创建前，D5）。
- */
-export function assertArgvBudget(argv: string[], limitBytes: number = DEFAULT_ARGV_BUDGET_BYTES): void {
-  const actual = estimateArgvBytes(argv);
-  if (actual > limitBytes) {
-    throw promptTooLargeError(actual, limitBytes);
-  }
-}

package/src/execution/engine/common/pool-manager.ts

@@ -1,226 +0,0 @@
-// src/execution/engine/common/pool-manager.ts
-//
-// 隔离目录池管理（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D5（隔离目录池化保留，随 record
-// 生命周期回收，清理只做到池粒度）+ §3.3.9（目录布局 / refs 方案）。
-//
-// P2 口径（与 §3.3.9 完整设计的差异，签名所限）：引用计数是**进程内注册表**——
-// acquire/release 的任务书签名无 taskId，refs.json 文件形态（登记 taskId + ts）留给
-// 后续 wave 在 preparer/host 接线时落地（宿主是唯一写者，升级为文件形态不改变本模块
-// 的 acquire/release 语义边界）。
-//
-// 删除边界（D5 三条硬规则）：
-//   1. 只删引擎原生状态（隔离 HOME / config / db.sqlite，均可由 preparer 重建）；
-//   2. journal-*.jsonl 不随池删——生命周期跟随 record，避免「池删导致仍存 record 的
-//      历史从②级静默跌③级」；
-//   3. 删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），启动期扫描该标记告警。
-
-import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { resolvePoolDir } from "../paths.ts";
-
-const logger = getLogger("subagents");
-
-/** 清理失败标记文件名（置于池目录内；内容为 JSON 失败清单）。 */
-export const POOL_CLEANUP_FAILED_MARKER = ".pool-cleanup-failed";
-
-/** readdir withFileTypes 的条目结构子集。 */
-interface DirEntryLike {
-  name: string;
-  isDirectory(): boolean;
-}
-
-/** 池管理的文件系统依赖面（结构接口：测试注入 fake，免 vi.mock 整个 fs 模块）。 */
-export interface PoolFsDeps {
-  mkdir(path: string, opts: { recursive: boolean }): Promise<unknown>;
-  readdir(path: string): Promise<DirEntryLike[]>;
-  rm(path: string, opts: { recursive: boolean; force: boolean }): Promise<void>;
-  rmdir(path: string): Promise<void>;
-  writeFile(path: string, data: string): Promise<void>;
-}
-
-// ============================================================
-// 进程内池注册表（引用计数）
-// ============================================================
-
-/**
- * key = 池目录绝对路径 → 活跃引用计数。进程级单例状态，用 globalThis[Symbol.for]
- * 持有防 jiti 双路径加载分裂（development-guide §7.5），不用模块级 const。
- */
-const POOL_REFS_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagent-workflow.poolRefs");
-
-function getPoolRefs(): Map<string, number> {
-  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
-  // 避免双重断言（同 model-config-service.ts 先例）。
-  let refs = Reflect.get(globalThis, POOL_REFS_SLOT_KEY) as Map<string, number> | undefined;
-  if (!refs) {
-    refs = new Map();
-    Reflect.set(globalThis, POOL_REFS_SLOT_KEY, refs);
-  }
-  return refs;
-}
-
-/** 测试隔离专用：清空进程内注册表（生产禁用——会丢失活跃引用计数）。 */
-export function resetPoolRegistryForTests(): void {
-  getPoolRefs().clear();
-}
-
-// ============================================================
-// acquire / release
-// ============================================================
-
-/**
- * 获取池目录：mkdir -p（幂等）+ 进程内引用计数 +1，返回池目录绝对路径。
- * 路径一律经 paths.ts resolvePoolDir 派生（双端同源，禁自拼）。
- */
-export async function acquirePool(
-  dataDir: string,
-  engineId: string,
-  poolKey: string,
-  fs: Pick<PoolFsDeps, "mkdir"> = nodeFs,
-): Promise<string> {
-  const poolDir = resolvePoolDir(dataDir, engineId, poolKey);
-  await fs.mkdir(poolDir, { recursive: true });
-  const poolRefs = getPoolRefs();
-  poolRefs.set(poolDir, (poolRefs.get(poolDir) ?? 0) + 1);
-  return poolDir;
-}
-
-/**
- * 释放一次池引用（record GC / 删除时调用）：计数递减；归零删整池——只删引擎原生
- * 状态，journal-*.jsonl 保留（D5）；删除失败置标记文件并 warn，不静默不 throw
- * （清理失败不是 record GC 的失败）。
- */
-export async function releasePoolRef(
-  dataDir: string,
-  engineId: string,
-  poolKey: string,
-  fs: PoolFsDeps = nodeFs,
-): Promise<void> {
-  const poolDir = resolvePoolDir(dataDir, engineId, poolKey);
-  const poolRefs = getPoolRefs();
-  const current = poolRefs.get(poolDir);
-  // 无计数（进程重启后释放 / 未 acquire 的释放）→ 保守不删池：删池决策必须有本进程
-  // 内的归零证据，凭空删除可能误删其他进程正在使用的池
-  if (current === undefined || current <= 0) {
-    poolRefs.delete(poolDir);
-    logger.debug(`[pool-manager] release without live ref, skip pool deletion: ${poolDir}`);
-    return;
-  }
-  if (current > 1) {
-    poolRefs.set(poolDir, current - 1);
-    return;
-  }
-  // 归零：删引擎原生状态（journal 保留）
-  poolRefs.delete(poolDir);
-  await deletePoolNativeState(poolDir, fs);
-}
-
-/** journal 文件名判定（与 paths.ts 的 journal-<taskId>.jsonl 命名约定一致）。 */
-function isJournalFile(name: string): boolean {
-  return name.startsWith("journal-") && name.endsWith(".jsonl");
-}
-
-/** 删池内引擎原生状态：逐条目删除（跳过 journal），目录清空后移除目录本身。 */
-async function deletePoolNativeState(poolDir: string, fs: PoolFsDeps): Promise<void> {
-  const failures: string[] = [];
-  let entries: DirEntryLike[];
-  try {
-    entries = await fs.readdir(poolDir);
-  } catch {
-    // 池目录不存在（从未创建 / 已删）= 无原生状态可清，视为成功
-    return;
-  }
-  for (const entry of entries) {
-    if (isJournalFile(entry.name)) continue;
-    try {
-      await fs.rm(join(poolDir, entry.name), { recursive: true, force: true });
-    } catch (err) {
-      failures.push(`${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-  if (failures.length > 0) {
-    await markCleanupFailed(poolDir, failures, fs);
-    return;
-  }
-  try {
-    // 目录内只剩 journal（或已空）：只剩 journal 时保留目录（journal 生命周期跟 record）
-    const remaining = await fs.readdir(poolDir);
-    if (remaining.every((e) => isJournalFile(e.name))) return;
-    await fs.rmdir(poolDir);
-  } catch (err) {
-    await markCleanupFailed(
-      poolDir,
-      [`(rmdir): ${err instanceof Error ? err.message : String(err)}`],
-      fs,
-    );
-  }
-}
-
-/** 置 .pool-cleanup-failed 标记（失败清单 JSON）+ warn——可观测不静默（D5）。 */
-async function markCleanupFailed(poolDir: string, failures: string[], fs: PoolFsDeps): Promise<void> {
-  const marker = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
-  const payload = JSON.stringify({ ts: Date.now(), failures });
-  logger.warn(
-    `[pool-manager] pool cleanup failed for ${poolDir} (${failures.length} item(s)); ` +
-      `marker written to ${marker} — re-run cleanup after fixing the underlying error`,
-  );
-  try {
-    await fs.writeFile(marker, `${payload}\n`);
-  } catch (err) {
-    // 标记本身也写不进（目录只读/磁盘满）——error 级留痕是最后防线，不再上抛
-    logger.warn(
-      `[pool-manager] failed to write cleanup-failed marker ${marker}: ` +
-        `${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-}
-
-// ============================================================
-// 单次性产物清理（spawnedFiles）
-// ============================================================
-
-/** cleanupSpawnedFiles 选项。 */
-export interface SpawnedFilesCleanupOpts {
-  /**
-   * resume 场景保留：true = 全部保留（no-op）。resume 续接原 session，prompt 文件
-   * 等单次性产物不再重写（§3.3.7 preparer resume 语义），清理留给 record 终局。
-   */
-  keepForResume: boolean;
-}
-
-/**
- * 清理单次性产物（preparer 的 spawnedFiles：临时 prompt / persona 文件）。
- * 任务结束即清理（D5）；单条失败收集 warn 不 throw（部分清理优于整体失败），ENOENT
- * 幂等忽略。
- */
-export async function cleanupSpawnedFiles(
-  paths: string[],
-  opts: SpawnedFilesCleanupOpts,
-  fs: Pick<PoolFsDeps, "rm"> = nodeFs,
-): Promise<void> {
-  if (opts.keepForResume) return;
-  for (const p of paths) {
-    try {
-      await fs.rm(p, { recursive: true, force: true });
-    } catch (err) {
-      logger.warn(
-        `[pool-manager] spawned file cleanup failed for ${p}: ` +
-          `${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-}
-
-// ── 默认 fs 实现 ────────────────────────────────────────────────
-
-const nodeFs: PoolFsDeps = {
-  mkdir: (p, o) => mkdir(p, o),
-  readdir: (p) => readdir(p, { withFileTypes: true }) as Promise<DirEntryLike[]>,
-  rm: (p, o) => rm(p, o),
-  rmdir: (p) => rmdir(p),
-  writeFile: (p, d) => writeFile(p, d, "utf8"),
-};

package/src/execution/engine/common/schema-emulation.ts

@@ -1,189 +0,0 @@
-// src/execution/engine/common/schema-emulation.ts
-//
-// schema 仿真降级（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D4（native/emulated 硬分流）+ §3.3.3
-// schema_emulation_failed 行 + §5 P2 行。
-//
-// ─── D4 硬分流（违反 = 历史事故形态） ───────────────────────────────
-// 本模块只服务 capabilities.schemaEnforcement === 'emulated' 的引擎
-// （zcode / opencode / kimi-code）。capabilities.schemaEnforcement === 'native' 的引擎
-// （pi 的 PI_WORKFLOW_SCHEMA env 注入链路、claude-code --json-schema、codex
-// --output-schema）**禁止** import 本模块做二次校验或改写其结果——宿主侧再叠一层
-// ajv 会制造第二校验权威，恰是 structured-output 方案 A [HISTORICAL]
-// （2026-08-01「校验自报 schema 致修复静默丢失」事故）的形态。
-// ajv 只允许出现在 emulated 路径（本模块），这是全仓唯一例外。
-//
-// 重试语义：本模块两个函数保持纯——校验失败/提取失败由调用方（宿主编排层）决定
-// 重试，语义与 structured-output 的 workflow-hook 对齐（重试一次、强化 prompt；
-// 仍失败报 schema_emulation_failed，错误含原始输出尾部）。
-//
-// 文案对齐：错误回显风格对齐 structured-output 的 execute.ts（"Schema validation
-// failed: ..."），但不 import 其内部模块（公共层自实现；structured-output 是
-// peer 依赖且可选，import 会造成公共层对 sibling extension 的硬依赖）。
-
-import Ajv, { type ValidateFunction } from "ajv";
-
-/** 原始输出尾部回显长度（结果对象的 tail 字段，供错误展示与重试 prompt 回灌）。 */
-export const SCHEMA_EMULATION_TAIL_CHARS = 500;
-
-// ============================================================
-// prompt 注入段
-// ============================================================
-
-/**
- * 构造 prompt 注入段：schema 声明 + 输出格式约定（emulated 引擎的 launcher 把它拼进
- * 最终 prompt，替代引擎不存在的 schema 强制通道）。
- *
- * 文案风格对齐 structured-output 的 promptGuidelines（"Do not output JSON in text"：emulated 引擎没有工具可调，JSON 必须出现在文本里）。
- */
-export function buildSchemaEmulationSegment(schema: object): string {
-  const schemaJson = JSON.stringify(schema);
-  return [
-    "## Structured Output Requirement",
-    "Your final answer MUST contain exactly one JSON value conforming to this JSON Schema (draft-07):",
-    schemaJson,
-    "Output rules:",
-    "- Output ONLY the JSON value — no prose before or after it.",
-    "- If you wrap it in a markdown code fence, use a single ```json fence.",
-    "- Do not output multiple JSON values; the first complete JSON value is extracted.",
-  ].join("\n");
-}
-
-// ============================================================
-// 三级容错提取 + ajv 校验
-// ============================================================
-
-/** 提取结果联合：ok=true 携带通过校验的 parsed；ok=false 携带 error 简述 + 原始输出尾部。 */
-export type StructuredOutputResult =
-  | { ok: true; parsed: unknown }
-  | { ok: false; error: string; tail: string };
-
-/**
- * 从模型文本输出提取并校验结构化 JSON（三级容错 → ajv）。
- *
- * 三级容错（逐级降级，任一级提取成功即进 ajv）：
- *   1. 直接 JSON.parse（trim 后整体是合法 JSON）；
- *   2. 剥 markdown code fence（```json ... ``` / ``` ... ```）取围栏内内容；
- *   3. 首尾括号扫描（首个 '{'/'[' 到末个 '}'/']' 的子串——容纳前后杂文本）。
- *
- * ajv 校验失败/三级提取失败返回 ok:false（不 throw）——重试与否是宿主编排层的
- * 决策（见文件头重试语义），本函数每次调用独立无状态。
- */
-export function extractAndValidateStructuredOutput(
-  text: string,
-  schema: object,
-): { ok: true; parsed: unknown } | { ok: false; error: string; tail: string } {
-  return extractImpl(text, schema);
-}
-
-/** 实现体（签名拆分只为让导出签名与契约声明逐字一致，见 StructuredOutputResult）。 */
-function extractImpl(text: string, schema: object): StructuredOutputResult {
-  const tail = text.length > SCHEMA_EMULATION_TAIL_CHARS
-    ? text.slice(text.length - SCHEMA_EMULATION_TAIL_CHARS)
-    : text;
-
-  const extracted = extractJsonCandidate(text);
-  if (extracted === undefined) {
-    return {
-      ok: false,
-      error:
-        "could not extract JSON from model output after 3-stage fallback " +
-        "(direct parse -> code-fence strip -> bracket scan)",
-      tail,
-    };
-  }
-
-  const validate = getOrCompileValidator(schema);
-  if (validate === undefined) {
-    return {
-      ok: false,
-      error: "host-side JSON Schema compilation failed (invalid schema object)",
-      tail,
-    };
-  }
-
-  const valid = validate(extracted);
-  if (!valid) {
-    // 错误格式对齐 structured-output："instancePath message" 逐条 join
-    const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join("; ");
-    return {
-      ok: false,
-      error: `Schema validation failed: ${errors ?? "(no detail)"}`,
-      tail,
-    };
-  }
-  return { ok: true, parsed: extracted };
-}
-
-// ── 内部：三级提取 ──────────────────────────────────────────────
-
-/** 三级容错提取 JSON candidate；全部失败返回 undefined。 */
-function extractJsonCandidate(text: string): unknown {
-  // 第 1 级：整体直接 parse（最常见——严格遵守输出约定的模型）
-  const direct = tryParse(text.trim());
-  if (direct.ok) return direct.value;
-
-  // 第 2 级：markdown code fence 剥离（模型爱用 ```json 包裹）
-  const fenced = extractFirstFencedBlock(text);
-  if (fenced !== undefined) {
-    const parsed = tryParse(fenced.trim());
-    if (parsed.ok) return parsed.value;
-  }
-
-  // 第 3 级：首尾括号扫描（前后杂文本："Here is the result: {...} Hope this helps"）
-  const scanned = extractByBracketScan(text);
-  if (scanned !== undefined) {
-    const parsed = tryParse(scanned.trim());
-    if (parsed.ok) return parsed.value;
-  }
-
-  return undefined;
-}
-
-/** JSON.parse 包装：失败返回 ok:false（malformed 不是异常态，是三级降级的输入）。 */
-function tryParse(raw: string): { ok: true; value: unknown } | { ok: false } {
-  if (raw === "") return { ok: false };
-  try {
-    return { ok: true, value: JSON.parse(raw) };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/** 取第一个 markdown code fence 块内容（```json / ``` 均可）；无 fence 返回 undefined。 */
-function extractFirstFencedBlock(text: string): string | undefined {
-  const match = /```(?:json)?\s*([\s\S]*?)\s*```/.exec(text);
-  return match?.[1];
-}
-
-/** 首尾括号扫描：首个 '{'/'[' 到末个 '}'/']' 的子串；边界不合法返回 undefined。 */
-function extractByBracketScan(text: string): string | undefined {
-  const objOpen = text.indexOf("{");
-  const arrOpen = text.indexOf("[");
-  const open = objOpen === -1 ? arrOpen : arrOpen === -1 ? objOpen : Math.min(objOpen, arrOpen);
-  const objClose = text.lastIndexOf("}");
-  const arrClose = text.lastIndexOf("]");
-  const close = Math.max(objClose, arrClose);
-  if (open === -1 || close === -1 || open >= close) return undefined;
-  return text.slice(open, close + 1);
-}
-
-// ── 内部：ajv 编译缓存 ──────────────────────────────────────────
-
-// WeakMap 缓存（schema 对象引用即 key，GC 友好）——模式对齐 structured-output 的
-// ajv-validator.ts（自实现，不跨包 import；见文件头依赖边界说明）。
-const ajvCache = new WeakMap<object, ValidateFunction>();
-
-/** 编译（或取缓存）validator；schema 非法（ajv 抛错）返回 undefined 由调用方报错。 */
-function getOrCompileValidator(schema: object): ValidateFunction | undefined {
-  const cached = ajvCache.get(schema);
-  if (cached) return cached;
-  try {
-    // strict:false 对齐 structured-output 的宽容度（非标 keyword 不炸编译）
-    const validate = new Ajv({ strict: false }).compile(schema);
-    ajvCache.set(schema, validate);
-    return validate;
-  } catch {
-    return undefined;
-  }
-}

package/src/execution/engine/common/session-view-projection.ts

@@ -1,51 +0,0 @@
-// src/execution/engine/common/session-view-projection.ts
-//
-// Turn → ReplayedTurn 投影 + usage 聚合的单一实现（P5 收敛）。此前三份同构副本：
-// common/journal-replay.ts（journal 重放投影）、engines/pi/pi-engine.ts read()（内联
-// 重写）、engines/pi/reader.ts（native reader）——投影语义唯一（strip 内部态 + closed
-// 恒 true + usageDelta 聚合），实现也必须唯一（防三处漂移）。
-//
-// 纯函数、零运行时依赖（仅类型 import）：reader.ts 的双端复用约束（设计 §3.3.7，
-// xyz-agent runtime 可 import）对本模块同样成立。
-//
-// 设计权威源：docs/architecture/subagent-engine-abstraction.md §3.3.6（重放等价性）。
-
-import type { AgentUsageTotal, InternalToolCall, ToolCall, Turn } from "../../types.ts";
-import type { ReplayedTurn } from "../types.ts";
-
-/** InternalToolCall → ToolCall（导出纯净形状，不泄漏 running/done/failed 内部状态机）。 */
-function toExportedToolCall(tc: InternalToolCall): ToolCall {
-  return {
-    toolName: tc.toolName,
-    ...(tc.args !== undefined ? { args: tc.args } : {}),
-    ...(tc.result !== undefined ? { result: tc.result } : {}),
-    ...(tc.isError !== undefined ? { isError: tc.isError } : {}),
-  };
-}
-
-/** Turn → ReplayedTurn：剥离内部态（closed 恒 true——重放物无进行时语义，§3.3.6）。 */
-export function toReplayedTurn(turn: Turn): ReplayedTurn {
-  return {
-    text: turn.text,
-    thinking: turn.thinking,
-    toolCalls: turn.toolCalls.map(toExportedToolCall),
-    closed: true,
-  };
-}
-
-/** 各 turn usageDelta 聚合为 AgentUsageTotal（无任何 usage 数据时 undefined）。 */
-export function aggregateUsage(turns: readonly Turn[]): AgentUsageTotal | undefined {
-  let acc: AgentUsageTotal | undefined;
-  for (const turn of turns) {
-    const d = turn.usageDelta;
-    if (!d) continue;
-    if (!acc) acc = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, total: 0 };
-    acc.input += d.input;
-    acc.output += d.output;
-    acc.cacheRead += d.cacheRead;
-    acc.cacheWrite += d.cacheWrite;
-    acc.cost += d.cost ?? 0;
-  }
-  if (acc) acc.total = acc.input + acc.output + acc.cacheRead + acc.cacheWrite;
-  return acc;
-}

package/src/execution/engine/engine-discovery.ts

@@ -1,65 +0,0 @@
-// src/execution/engine/engine-discovery.ts
-//
-// [U7] 引擎列表状态文件同步（registry → <agentDir>/subagents/engines.json）。
-//
-// 为什么落文件而不是 session entry：Settings 引擎选择器在无活跃 session 时也要可开
-// （冷启动/全局设置），session entry 绑定会话生命周期兜不住；engines.json 是进程外
-// 可读的全局状态，extension（pi 进程）为唯一写入者，runtime RPC 读——数据所有权清晰。
-//
-// 动态性（用户要求）：清单来自代码注册表（registerEngine 调用点），未来新增引擎
-// （AcpEngine 等）零改动出现在 GUI——本文件与前端都不枚举引擎。
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { SUBAGENTS_ENGINES_FILENAME, type SubagentEnginesFile } from "@xyz-agent/extension-protocol";
-
-import { listEngines } from "./registry.ts";
-
-/** engines.json 绝对路径（与 config.json 同目录；config.ts 的 getGlobalConfigPath 同构）。 */
-export function getEnginesFilePath(agentDir: string): string {
-  return path.join(agentDir, "subagents", SUBAGENTS_ENGINES_FILENAME);
-}
-
-/**
- * 把注册表引擎列表同步到 engines.json（session_start 时调用）。
- *
- * 幂等：内容与现文件一致时零写入（mtime 不动——读侧无谓失效）；写入走 tmp+rename
- * 原子替换（与池 config 同防线）。fail-safe：任何 IO 异常吞掉（可发现性降级不阻塞
- * session 启动——GUI 兜底显示 ['pi']）。
- */
-export function syncEnginesFile(agentDir: string): void {
-  try {
-    const filePath = getEnginesFilePath(agentDir);
-    const payload: SubagentEnginesFile = { v: 1, engines: listEngines(), updatedAt: Date.now() };
-    const serialized = JSON.stringify(payload, null, 2);
-    try {
-      const existing = fs.readFileSync(filePath, "utf8");
-      const parsed = JSON.parse(existing) as Partial<SubagentEnginesFile>;
-      // 引擎清单未变则跳过（updatedAt 仅诊断，不参与判变）
-      if (
-        Array.isArray(parsed.engines) &&
-        JSON.stringify(parsed.engines) === JSON.stringify(payload.engines) &&
-        parsed.v === 1
-      ) {
-        return;
-      }
-    } catch {
-      // 现文件缺失/损坏 → 走写入
-    }
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, serialized, "utf8");
-      fs.renameSync(tmp, filePath);
-    } finally {
-      try {
-        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
-      } catch {
-        // rename 失败路径的残留清理 best-effort
-      }
-    }
-  } catch {
-    // 吞掉：见文件头 fail-safe 说明
-  }
-}