@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/agent-registry.ts

@@ -1,193 +0,0 @@
-// src/execution/agent-registry.ts
-//
-// agent .md 文件发现与解析。
-//
-// 发现逻辑统一走 shared/resource-discovery（ADR-031），与 workflow 共享同一套
-// 扫描源前缀 + manifest 校验。hot-reload：每次调用重扫（mtime 缓存跳过未变文件）。
-//
-// builtin agent（包内 agents/*.md）走 pi.agents manifest（与 npm 包内发现规则一致）。
-
-
-import * as path from "node:path";
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import {
-  getCachedFile,
-} from "../shared/resource-discovery.ts";
-import { normalizeRef, AGENT_REF_EXT } from "../shared/agent-ref.ts";
-import { parseResourceMeta } from "../shared/meta-parser.ts";
-import { lintAgentMeta } from "../orchestration/script-lint.ts";
-import type { AgentMeta } from "../shared/resource-meta.ts";
-import type { AgentConfig } from "./model-resolver.ts";
-import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
-
-const logger = getLogger("subagents");
-
-/** mtime 缓存条目（跨 loadByPath 保留，靠 mtime 判失效）。 */
-interface FileCacheEntry {
-  mtimeMs: number;
-  config: AgentConfig;
-  /** AgentMeta（W4 lint 用——cache-miss 时 lint 一次，warn 随 mtime 变化刷）。 */
-  meta: AgentMeta | null;
-}
-
-// ============================================================
-// frontmatter 解析
-// ============================================================
-
-/** frontmatter 分隔符。 */
-const FM_DELIM = "---";
-
-/**
- * 解析 .md frontmatter（name/tools/model/thinkingLevel/defaultBackground）+ body（systemPrompt）。
- * 兼容简单 YAML（key: value 单行格式）。body 作为 systemPrompt。
- */
-export function parseAgentFrontmatter(filePath: string, content: string): AgentConfig {
-  return parseAgentWithMeta(filePath, content).config;
-}
-
-/**
- * 解析 agent .md → { config, meta } 二元组（m5 T2：W4 lint 需要 AgentMeta——
- * AgentConfig 投影时 examples 被丢弃，meta 供 lintAgentMeta 使用）。
- */
-export function parseAgentWithMeta(
-  filePath: string,
-  content: string,
-): { config: AgentConfig; meta: AgentMeta | null } {
-  const name = path.basename(filePath, ".md");
-
-  // 无 frontmatter → 整个内容作为 systemPrompt
-  if (!content.startsWith(FM_DELIM)) {
-    return { config: { name, systemPrompt: content.trim() }, meta: null };
-  }
-
-  const closeIdx = content.indexOf(FM_DELIM, FM_DELIM.length);
-  if (closeIdx === -1) {
-    // 未闭合 frontmatter：提取 name，其余作为 systemPrompt
-    const yamlBlock = content.slice(FM_DELIM.length);
-    return {
-      config: {
-        name: extractYamlField(yamlBlock, "name") ?? name,
-        systemPrompt: content.trim(),
-      },
-      meta: null,
-    };
-  }
-
-  const yamlBlock = content.slice(FM_DELIM.length, closeIdx);
-  const body = content.slice(closeIdx + FM_DELIM.length).trim();
-
-  // m2：结构化路由字段（name/model/tools）经 IF1 parseResourceMeta（统一 parser），
-  // 消灭本地 frontmatter parser 与 subagent-list-injector 的重复。thinkingLevel/defaultBackground
-  // 是执行配置（非 AgentMeta 路由字段），仍用 extractYamlField 取。
-  const meta = parseResourceMeta(content, "agent");
-  const agentMeta = meta?.kind === "agent" ? meta : null;
-  // MF-3 regression fix：agentMeta=null（IF1 要求 name/description 必填，缺则 parseResourceMeta
-  // 返 null）时，model/tools 不能静默丢失——fallback 用 extractYamlField 取（保留重构前行为）。
-  // 注入路由可见性由 discovery/injector 按 available 标志决定，与本处（direct-path loadByPath）无关。
-  const modelFallback = extractYamlField(yamlBlock, "model");
-  const toolsFallbackRaw = extractYamlField(yamlBlock, "tools");
-  const toolsFallback = toolsFallbackRaw
-    ? toolsFallbackRaw.split(",").map((s) => s.trim()).filter(Boolean)
-    : undefined;
-  if (!agentMeta && /^model:|^tools:/m.test(yamlBlock)) {
-    // m2 exec-review MINOR-2 + MF-3：IF1 未通过（缺 name/description）→ model/tools 经 legacy
-    // fallback 取（direct-path loadByPath 不丢配置，与重构前一致）；但结构化路由注入不可见，
-    // 建议 agent 作者补 description 以满足 IF1。
-    logger.warn(
-      `[agent-registry] ${filePath}: agent frontmatter 缺 name/description（IF1 必填），` +
-        "model/tools 经 legacy fallback 生效（直接路径不丢配置），但结构化路由不可见——请补充 description",
-    );
-  }
-  const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
-  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
-  // agentMeta 未通过 IF1 时配置不丢
-  const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
-  // 解析期校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。为什么在解析期而非
-  // 路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）
-  if (engine !== undefined && !hasEngine(engine)) {
-    throw new EngineNotFoundError(engine, listEngines(), filePath);
-  }
-
-  return {
-    config: {
-      name: agentMeta?.name ?? name,
-      systemPrompt: body,
-      model: agentMeta?.model ?? modelFallback ?? undefined,
-      thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
-      ...(engine !== undefined ? { engine } : {}),
-      tools: agentMeta?.tools && agentMeta.tools.length > 0
-        ? agentMeta.tools
-        : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),
-      defaultBackground: defaultBackgroundRaw === "true" ? true : undefined,
-    },
-    meta: agentMeta,
-  };
-}
-
-/** 提取简单 `key: value` 字段，剥离引号。 */
-function extractYamlField(yaml: string, key: string): string | undefined {
-  const regex = new RegExp(`^${key}:\\s*(.+)$`, "m");
-  const match = yaml.match(regex);
-  if (!match) return undefined;
-  let value = match[1].trim();
-  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-    value = value.slice(1, -1);
-  }
-  return value || undefined;
-}
-
-// ============================================================
-// AgentRegistry
-// ============================================================
-
-export class AgentRegistry {
-  /** 文件级 mtime 缓存（key=绝对路径，跨 loadByPath 保留）。 */
-  private readonly fileCache = new Map<string, FileCacheEntry>();
-
-  /**
-   * 按绝对路径加载 agent（agentRef 统一解析入口——S2 路径统一）。
-   *
-   * - ~/ 前缀展开；相对路径/非 .md 引用返回 undefined（引用唯一形态 = 绝对路径）
-   * - 文件不可读/不存在 → 驱逐缓存 + 返回 undefined（调用方给错误指引）
-   * - mtime 未变复用 config 缓存；cache-miss 时 W4 lint 一次
-   */
-  loadByPath(ref: string, require?: boolean): AgentConfig | undefined {
-    const filePath = normalizeRef(ref, AGENT_REF_EXT);
-    if (filePath === null) {
-      if (require) {
-        throw new Error(
-          `Invalid agent ref: ${ref}. Agent refs must be absolute paths to .md files (use <location> from <available_subagents>).`,
-        );
-      }
-      return undefined;
-    }
-
-    const file = getCachedFile(filePath);
-    if (file === null) {
-      // ENOENT/不可读 → 驱逐（mtime 缓存下文件删除不自愈的修复）
-      this.fileCache.delete(filePath);
-      if (require) {
-        throw new Error(
-          `Agent file not found or unreadable: ${filePath}. Use an absolute path from <available_subagents> <location>.`,
-        );
-      }
-      return undefined;
-    }
-
-    const cached = this.fileCache.get(filePath);
-    if (cached && cached.mtimeMs === file.mtimeMs) {
-      return cached.config;
-    }
-
-    const { config, meta } = parseAgentWithMeta(filePath, file.content);
-    // W4 lint：cache-miss（parse 时一次）——warn 只随 mtime 变化刷
-    const lintFindings = meta ? lintAgentMeta(meta) : [];
-    for (const finding of lintFindings) {
-      logger.warn(`[agent-registry] ${filePath}: ${finding.message}`);
-    }
-    this.fileCache.set(filePath, { mtimeMs: file.mtimeMs, config, meta });
-    return config;
-  }
-}

package/src/execution/agent-result-mapper.ts

@@ -1,90 +0,0 @@
-// src/execution/agent-result-mapper.ts
-//
-// D-A10: subagents AgentResult → workflow AgentResult 映射。
-// 纯 DTO 映射函数——executeAndAwait 出口调，SAR 不感知形状差异。
-//
-// 接线层级：[模块内直调] —— SubagentService.executeAndAwait 出口调。
-
-import type { AgentResult as WorkflowAgentResult, AgentUsage as WorkflowAgentUsage, ToolCallEntry } from "../orchestration/models/types.ts";
-import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "./types.ts";
-
-/** safeStringify 的 JSON 截断长度（字符），防大对象拼进 toolCalls 挤爆 trace。 */
-const TOOL_ARGS_JSON_MAX_CHARS = 500;
-
-/**
- * D-A10: subagents AgentResult → workflow AgentResult 映射。
- *
- * 字段映射表：
- *   subagents                         → workflow
- *   ─────────────────────────────────────────────
- *   text                              → content
- *   parsedOutput                      → parsedOutput（structured-output 契约，BC-8）
- *   !success && error                 → error（失败时填，成功时 undefined）
- *   !success && !error                → error fallback（abort 路径：session-runner 设 success=false,error=undefined，
- *                                      若直接透传 undefined 则 executeAgentCall 的 `error===undefined` 误判 completed。H4 修复：synthesize fallback）
- *   durationMs                        → durationMs
- *   sessionId                         → sessionId
- *   usage (AgentUsageTotal)           → usage (AgentUsage: input/output/cacheRead/cacheWrite/cost/contextTokens/turns)
- *   toolCalls (ToolCall[])            → toolCalls (ToolCallEntry[]: name/input)
- *
- * @param r subagents 管道产出的 AgentResult（runSpawn/collectResult 出口形状）
- * @returns workflow 编排层消费的 AgentResult（executeAgentCall/finalizeCall 入参形状）
- */
-export function mapToWorkflowAgentResult(
-  r: SubagentsAgentResult,
-): WorkflowAgentResult {
-  return {
-    content: r.text,
-    parsedOutput: r.parsedOutput,
-    error: r.success ? undefined : (r.error || "Agent call failed (aborted or unknown error)"),
-    durationMs: r.durationMs,
-    sessionId: r.sessionId,
-    sessionFile: r.sessionFile,
-    usage: r.usage ? mapUsage(r.usage, r.turns) : undefined,
-    toolCalls: r.toolCalls ? mapToolCalls(r.toolCalls) : undefined,
-  };
-}
-
-/**
- * AgentUsageTotal（subagents）→ AgentUsage（workflow）映射。
- *
- * subagents AgentUsageTotal: { input, output, cacheRead, cacheWrite, total, cost }
- * workflow AgentUsage:       { input, output, cacheRead, cacheWrite, cost, contextTokens, turns }
- *
- * contextTokens ≈ total（subagents 的四项之和，近似上下文 token 量）。
- * turns 来自 AgentResult.turns（非 usage 内字段）。
- */
-function mapUsage(u: AgentUsageTotal, turns: number): WorkflowAgentUsage {
-  return {
-    input: u.input,
-    output: u.output,
-    cacheRead: u.cacheRead,
-    cacheWrite: u.cacheWrite,
-    cost: u.cost,
-    contextTokens: u.total,
-    turns,
-  };
-}
-
-/**
- * ToolCall（subagents）→ ToolCallEntry（workflow）映射。
- *
- * subagents ToolCall:     { toolName, args?, result?, isError? }
- * workflow ToolCallEntry: { name, input }
- */
-function mapToolCalls(calls: ToolCall[]): ToolCallEntry[] {
-  return calls.map((c) => ({
-    name: c.toolName,
-    input: c.args === undefined ? "" : safeStringify(c.args),
-  }));
-}
-
-/** 安全序列化（args 可能含循环引用或大对象，截断防 OOM）。 */
-function safeStringify(value: unknown): string {
-  try {
-    const s = JSON.stringify(value);
-    return s.length > TOOL_ARGS_JSON_MAX_CHARS ? `${s.slice(0, TOOL_ARGS_JSON_MAX_CHARS)}...` : s;
-  } catch {
-    return String(value);
-  }
-}

package/src/execution/alive-store.ts

@@ -1,92 +0,0 @@
-// src/runtime/execution/alive-store.ts
-//
-// .alive sidecar 生产者 + pid 探活。
-//
-// 子进程启动时写 .alive（pid+id+startedAt），心跳检测时读它 + isProcessAlive
-// 判活。finalize/cancel 收尾时 remove。与 .cancelled/.finalized 构成三件套。
-//
-// 设计对齐 tombstone-store：单文件 sidecar、best-effort I/O、无全局 index。
-
-import * as fs from "node:fs";
-
-import type { AliveMarker } from "./types.ts";
-
-// ============================================================
-// 公开函数
-// ============================================================
-
-/**
- * 在 sessionFile 旁写 .alive sidecar（单行 JSON）。
- * 覆盖写——同一 sessionFile 只有最后一个 alive marker 有意义。
- */
-export function writeAliveMarker(sessionFile: string, marker: AliveMarker): void {
-  const alivePath = `${sessionFile}.alive`;
-  fs.writeFileSync(alivePath, `${JSON.stringify(marker)}\n`, "utf-8");
-}
-
-/**
- * 读 sessionFile 旁的 .alive sidecar。
- * 返回 undefined：不存在 / 损坏 / 解析失败。
- */
-export function readAliveMarker(sessionFile: string): AliveMarker | undefined {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(`${sessionFile}.alive`, "utf-8");
-  } catch {
-    return undefined;
-  }
-  try {
-    const parsed = JSON.parse(raw) as Partial<AliveMarker>;
-    if (
-      typeof parsed.pid === "number" &&
-      typeof parsed.id === "string" &&
-      typeof parsed.startedAt === "number"
-    ) {
-      return parsed as AliveMarker;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * 删除 sessionFile 旁的 .alive sidecar。
- * best-effort：不存在不抛（finalize/cancel 收尾调，sidecar 可能已被清理）。
- */
-export function removeAliveMarker(sessionFile: string): void {
-  try {
-    fs.unlinkSync(`${sessionFile}.alive`);
-  } catch {
-    void 0; // best-effort
-  }
-}
-
-/**
- * 检测 pid 是否存活。
- *
- * process.kill(pid, 0) 语义：不发信号，仅检查进程是否存在。
- *   - 无异常 → 存活
- *   - ESRCH（No such process）→ 死
- *   - EPERM（Process exists but no permission）→ 存活（保守）
- *   - 其他异常 → 保守判死 false，避免误删活进程
- */
-export function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err: unknown) {
-    if (isErrnoException(err) && err.code === "EPERM") {
-      return true; // 存在但无权限发信号 → 判活
-    }
-    return false; // ESRCH 或其他异常 → 保守判死
-  }
-}
-
-// ============================================================
-// 内部工具
-// ============================================================
-
-function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
-  return err instanceof Error && "code" in err;
-}

package/src/execution/argv-mirror.ts

@@ -1,109 +0,0 @@
-/**
- * 从主进程 argv 解析可镜像给子进程的 flag。
- *
- * 独立模块：argv 解析是独立职责，从 session-runner.ts 拆出避免该文件超行数上限。
- */
-
-/**
- * 镜像 flag 集合：从主进程 argv 解析出的可透传给子进程的 flag。
- * 面向 buildSpawnArgs 的入参形态（解析后）。undefined 字段语义与解析为空一致。
- */
-export interface MirrorFlags {
-  noExtensions: boolean;
-  approve: boolean;
-  extensionPaths: string[];
-  noContextFiles: boolean;
-}
-
-/**
- * 有值 flag 的解析规则表：成员是「后跟一个值」的 flag 名（含长短形式）。
- * 用于 mirrorMainProcessFlags 跳过其他 flag 的值时不误吃。
- */
-const VALUED_FLAGS = new Set<string>([
-  "--extension", "-e",
-  "--skill",
-  "--model", "--system-prompt", "--append-system-prompt",
-  "--tools", "-t", "--exclude-tools", "-xt",
-  "--fork", "--session-dir", "--mode",
-  "--thinking", "--models",
-]);
-
-/** argv 中 flag 的起始索引：argv[0]=runtime, argv[1]=binary 路径。 */
-const ARGV_FLAG_START = 2;
-
-/**
- * 从主进程 argv 解析可镜像的 flag（--no-extensions/--approve/--extension/--no-context-files）。
- *
- * 数据源是主 pi 进程的 process.argv：子进程 spawn 的父就是主进程，
- * 主进程 argv 完整保留启动时收到的全部 flag（已运行时验证）。这让子进程
- * extension/approve 加载行为与主进程一致，且对任意 pi 宿主通用（不止 xyz-agent）。
- *
- * 解析规则：
- * - --no-extensions / -ne、--approve / -a：布尔 flag
- * - --no-context-files / -nc：布尔 flag（镜像理由：--extension 镜像会把
- *   @zhushanwen/pi-system-prompt 带进每个 subagent，该扩展靠子进程自己的
- *   argv 检测此 flag 决定是否注入全局 AGENTS.md——不镜像则用户 opt-out
- *   在 subagent 路径失效）
- * - --extension / -e：支持 `--extension <path>`（空格）与 `--extension=<path>`（等号）
- * - 其他 flag（在 VALUED_FLAGS 中）的值不被误当 extension 路径
- * - positional 参数被忽略
- * - argv[0]/argv[1] 是 bun/pi binary 路径，从 argv[2:] 开始扫
- */
-// [perf] 进程内 process.argv 引用恒定（唯一调用点 session-runner 每次 spawn 传同一引用），
-// 解析结果按 argv 引用相等 memo——每次 spawn 免重复扫描/正则。测试传新数组引用不命中。
-let memoArgv: readonly string[] | undefined;
-let memoResult: MirrorFlags | undefined;
-
-export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
-  if (memoResult !== undefined && memoArgv === argv) return memoResult;
-  let hasNoExtensions = false;
-  let hasApprove = false;
-  let hasNoContextFiles = false;
-  const extensionPaths: string[] = [];
-
-  // argv[0]=runtime(bun), argv[1]=pi binary 路径；flag 从 argv[2] 起
-  const flagArgs = argv.length > ARGV_FLAG_START ? argv.slice(ARGV_FLAG_START) : [];
-
-  for (let i = 0; i < flagArgs.length; i++) {
-    const tok = flagArgs[i];
-    if (tok === "--no-extensions" || tok === "-ne") {
-      hasNoExtensions = true;
-      continue;
-    }
-    if (tok === "--approve" || tok === "-a") {
-      hasApprove = true;
-      continue;
-    }
-    if (tok === "--no-context-files" || tok === "-nc") {
-      hasNoContextFiles = true;
-      continue;
-    }
-    // 等号形式 --extension=path / -e=path
-    const eqMatch = /^(--extension|-e)=(.*)$/.exec(tok);
-    if (eqMatch) {
-      const val = eqMatch[2];
-      if (val) extensionPaths.push(val);
-      continue;
-    }
-    // 空格形式 --extension <path> / -e <path>：值在下一个 token
-    if (tok === "--extension" || tok === "-e") {
-      const next = flagArgs[i + 1];
-      if (next !== undefined && !next.startsWith("-") && next.length > 0) {
-        extensionPaths.push(next);
-        i++; // 跳过值
-      }
-      continue;
-    }
-    // 其他有值 flag：跳过其值，避免误吃（如 --skill /a 的 /a）
-    if (VALUED_FLAGS.has(tok)) {
-      i++;
-      continue;
-    }
-    // 其他情况（未知 flag、--flag=val 形式、positional）忽略
-  }
-
-  const result = { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths, noContextFiles: hasNoContextFiles };
-  memoArgv = argv;
-  memoResult = result;
-  return result;
-}

package/src/execution/best-effort.ts

@@ -1,38 +0,0 @@
-// src/utils/best-effort.ts
-//
-// best-effort IO 清理的错误吞咽 helper。
-//
-// 用途：sidecar 写入 / worktree remove / alive marker 删除等次要 IO，失败不影响
-// 主流程（session 已完成或正在收尾）。这类 catch 故意吞错——但 taste/no-silent-catch
-// 规则禁止空 catch 或仅 console 的 catch。本 helper 提供一条「实质调用语句」让
-// catch 合规，同时把错误记录到 debug/error 便于排查。
-//
-// 规则绕过原理：taste/no-silent-catch 仅检查 CatchClause 直接 body 是否为空或仅
-// console 调用。本 helper 是普通函数调用（ExpressionStatement），既非空也非仅
-// console，故合规。helper 函数体内部经共享 logger 路由（不裸 console）。
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("subagents");
-
-/** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
-export type BestEffortLevel = "debug" | "error";
-
-/**
- * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
- *
- *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
- *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
- *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
- *
- * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
- */
-export function bestEffort(err: unknown, context: string, level: BestEffortLevel = "debug"): void {
-  const detail = err instanceof Error ? err.message : err;
-  const msg = `[subagents] best-effort ${context} failed`;
-  if (level === "error") {
-    logger.error(msg, { detail });
-  } else {
-    logger.debug(msg, { detail });
-  }
-}

package/src/execution/channel-registry-access.ts

@@ -1,144 +0,0 @@
-// src/execution/channel-registry-access.ts
-//
-// Channel registry 的访问入口（本扩展内部用 + 契约文档化导出）。
-//
-// ask-user 等扩展通过本模块注册 channel handler，让 subagent 子进程的 UI 请求
-// 能透传到主进程渲染。所有扩展各自直接读写
-// globalThis[Symbol.for("@zhushanwen/pi-subagents.channelHandshake")]，
-// 拿到结构兼容 ChannelRegistryHandshake 的同一握手对象。
-//
-// ── 升级说明（决策 D 修复 M4）─────────────────────────────────
-// 历史问题：原协议槽位直接存 UiChannelRegistry 实例，谁先 session_start 谁创建。
-// ask-user 先到时会自建简化 registry 占位，劫持 canonical 槽位，subagent-workflow
-// 后到时拿到的是 ask-user 的非 canonical 实例，行为不一致。
-//
-// 修复：槽位从「存 registry 实例」升级为「存握手对象 {version, registry?, pending[]}」。
-// canonical registry 实例永远由 subagent-workflow 单一创建点（本模块的
-// getOrCreateChannelRegistry）实例化。ask-user 先到时只往 pending 推 handler，
-// 等 subagent-workflow 来 flush；subagent-workflow 先到时直接创建 registry 并
-// 接收后续 ask-user 推入的 pending。
-//
-// ── 跨扩展协议契约（必须与 ask-user 侧严格一致）──────────────
-// key 字面量：     "@zhushanwen/pi-subagents.channelHandshake"
-//                  ↑ 必须与 ask-user/src/channel-registry-register.ts 完全一致
-// handshake 形状： ChannelRegistryHandshake（version=1）
-// version 守卫：    slot.version !== 1 时 console.warn + 丢弃重建（向前兼容未来升级）
-
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-import { createUiChannelRegistry, type UiChannelRegistry, type ChannelHandler } from "./ui-channels.ts";
-
-const logger = getLogger("subagents");
-
-/** 进程级 channel 握手的 globalThis key（Symbol.for 跨模块共享）。
- *
- *  **协议契约**：字面量 `"@zhushanwen/pi-subagents.channelHandshake"` 必须与
- *  ask-user 扩展的 `ask-user/src/channel-registry-register.ts` 完全一致——
- *  两边读写同一个 Symbol.for key 才能拿到同一握手对象。
- *
- *  改名历史：原 `CHANNEL_REGISTRY_KEY`（字面量 `...channelRegistry`）在决策 D
- *  中升级为 `CHANNEL_HANDSHAKE_KEY`（字面量 `...channelHandshake`），槽位形状
- *  从 registry 实例改为握手对象。 */
-export const CHANNEL_HANDSHAKE_KEY = Symbol.for("@zhushanwen/pi-subagents.channelHandshake");
-
-/** 握手版本。未来若形状不兼容升级，递增此常量并在 getOrCreateChannelRegistry
- *  的 version 守卫里加迁移逻辑。 */
-const HANDSHAKE_VERSION = 1 as const;
-
-/** pending channel handler 条目。ask-user 先到、registry 未就绪时临时存放。 */
-export interface ChannelRegistryHandshakePendingEntry {
-  channel: string;
-  handler: ChannelHandler;
-}
-
-/** 跨扩展 channel registry 握手对象（globalThis 槽位形状）。
- *
- *  - `version`：协议版本，当前固定 1。读取时若 ≠1 视为不兼容，丢弃重建。
- *  - `registry`：canonical UiChannelRegistry 实例。仅由 subagent-workflow 的
- *    getOrCreateChannelRegistry 创建并填充。未就绪时为 undefined。
- *  - `pending`：ask-user 在 registry 就绪前推入的 handler 条目。
- *    subagent-workflow 创建 registry 后逐条 flush（注册），然后清空。 */
-export interface ChannelRegistryHandshake {
-  version: typeof HANDSHAKE_VERSION;
-  registry?: UiChannelRegistry;
-  pending: ChannelRegistryHandshakePendingEntry[];
-}
-
-/** 读取握手槽位；若 version 不匹配则视为缺失（warn + 返回 undefined）。
- *  类型不安全的 globalThis 反射访问集中在本函数，外层逻辑保持类型严谨。 */
-function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
-  const slot = Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as unknown;
-  if (slot === undefined) return undefined;
-  // 形状校验：必须是对象且 version===1，否则视为不兼容
-  if (typeof slot !== "object" || slot === null) {
-    logger.warn(
-      "[pi-subagent-workflow] channel handshake slot is not an object; discarding and recreating.",
-    );
-    return undefined;
-  }
-  // 断言目标含必填 version 字段（object/null 已守卫；version 值本身在下一行校验），
-  // 对齐 format.ts extractAgentName 的必填字段断言先例，避免全可选断言零校验。
-  const version = (slot as { version: unknown }).version;
-  if (version !== HANDSHAKE_VERSION) {
-    logger.warn(
-      `[pi-subagent-workflow] channel handshake version mismatch (got ${String(
-        version,
-      )}, expected ${HANDSHAKE_VERSION}); discarding and recreating.`,
-    );
-    return undefined;
-  }
-  // version 正确，但 pending 可能被恶意/错误地塞了非数组；防御性处理
-  const candidate = slot as ChannelRegistryHandshake;
-  if (!Array.isArray(candidate.pending)) {
-    logger.warn(
-      "[pi-subagent-workflow] channel handshake pending is not an array; discarding and recreating.",
-    );
-    return undefined;
-  }
-  return candidate;
-}
-
-/** 将 pending 条目逐个注册进 registry，注册完清空 pending。
- *  pending 内部 entry 的形状由 ask-user 侧保证，此处不再二次校验。 */
-function flushPending(registry: UiChannelRegistry, pending: ChannelRegistryHandshakePendingEntry[]): void {
-  for (const entry of pending) {
-    registry.register(entry.channel, entry.handler);
-  }
-}
-
-/** 获取或创建进程级 channel registry（canonical 单例）。
- *
- *  **唯一创建点**：canonical UiChannelRegistry 实例仅由本函数创建。
- *  ask-user 扩展绝不自建 registry——它在 registry 未就绪时只往 slot.pending 推条目。
- *
- *  行为分支：
- *    1. 槽位不存在或 version ≠ 1 → warn（version 不匹配时）+ 建新 slot
- *       `{version:1, pending:[], registry:<newly created>}`
- *    2. 槽位存在但 registry 未就绪（ask-user 先到过，塞过 pending）→
- *       创建 canonical registry + flush pending + 清空 pending
- *    3. 槽位存在且 registry 已就绪（本函数已被调用过）→
- *       直接返回同一实例引用（===），不重建、不重复 flush
- *
- *  @returns 进程级 canonical UiChannelRegistry 单例（永不返回 undefined） */
-export function getOrCreateChannelRegistry(): UiChannelRegistry {
-  let slot = readHandshakeSlot();
-  if (slot === undefined) {
-    // 分支 1：无合规槽位，新建并立即创建 canonical registry
-    const registry = createUiChannelRegistry();
-    slot = { version: HANDSHAKE_VERSION, registry, pending: [] };
-    Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
-    return registry;
-  }
-  if (slot.registry === undefined) {
-    // 分支 2：ask-user 先到过，flush pending 进 canonical registry
-    const registry = createUiChannelRegistry();
-    flushPending(registry, slot.pending);
-    slot.pending = [];
-    slot.registry = registry;
-    return registry;
-  }
-  // 分支 3：registry 已就绪，返回同一实例
-  return slot.registry;
-}
-
-export type { UiChannelRegistry, ChannelHandler };