@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,144 @@
+// 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 "../core/logger.ts";
+
+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 };

package/src/execution/concurrency-pool.ts

@@ -0,0 +1,116 @@
+// src/core/concurrency-pool.ts
+//
+// 并发控制 + 优先级排队。background=1000（单一优先级，保留 priority 机制供未来扩展）。
+
+/** 队列条目：优先级 + resolver + rejecter + 入队序号（同优先级 FIFO）。 */
+interface QueueEntry {
+  priority: number;
+  resolve: () => void;
+  reject: (err: Error) => void;
+  seq: number;
+  /** abort listener（用于 resolve/abort 时清理）。 */
+  onAbort?: () => void;
+  /** 关联的 signal（用于 resolve 时 removeEventListener）。 */
+  signal?: AbortSignal;
+}
+
+/** 并发池接口（可注入，便于测试 mock）。 */
+export interface ConcurrencyPool {
+  /** 按优先级排队获取槽位（0=最高）。可选 effectiveMaxConcurrent 覆盖实例级默认配额。可选 AbortSignal 在 abort 时 reject 排队条目。 */
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void>;
+  /** 归还槽位。必须无条件执行（finally）。 */
+  release(): void;
+  /** 当前已占用槽位数（诊断/widget 用）。 */
+  readonly active: number;
+  /** 实例级最大并发配额。调用方可据此计算分层配额（max(1, maxConcurrent - depth)）。 */
+  readonly maxConcurrent: number;
+}
+
+/**
+ * 默认实现：maxConcurrent 槽位 + 优先级队列。
+ *
+ *   acquire(priority, effectiveMaxConcurrent?):
+ *     effective = effectiveMaxConcurrent ?? maxConcurrent
+ *     active < effective → active++, resolve
+ *     否则 → 入队 { priority, resolve, seq }, 队列按 priority 升序 + seq FIFO
+ *
+ *   release():
+ *     queue 非空 → 出队最高优先级 resolve（active 不变）
+ *     queue 空 → active--（防下溢）
+ */
+export class DefaultConcurrencyPool implements ConcurrencyPool {
+  private _active = 0;
+  private readonly queue: QueueEntry[] = [];
+  private seqCounter = 0;
+
+  /** 下限 1——maxConcurrent=0 会让 acquire 永久排队死锁（C3 修复）。 */
+  readonly maxConcurrent: number;
+
+  constructor(maxConcurrent: number) {
+    this.maxConcurrent = Math.max(1, maxConcurrent);
+  }
+
+  acquire(priority: number, effectiveMaxConcurrent?: number, signal?: AbortSignal): Promise<void> {
+    // effectiveMaxConcurrent 覆盖实例级默认配额（分层配额：调用方传 max(1, maxConcurrent - depth)）。
+    // 不修改实例级 maxConcurrent——实例配额是全局共享上限，分层配额是本次 acquire 的局部上限。
+    const effective = effectiveMaxConcurrent ?? this.maxConcurrent;
+    if (this._active < effective) {
+      this._active += 1;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      const entry: QueueEntry = { priority, resolve, reject, seq: this.seqCounter++ };
+      // H2: abort 时 reject 排队条目并从 queue 移除，防止永久挂起
+      if (signal) {
+        if (signal.aborted) {
+          // S1: abort reject 需带 name="AbortError"，对齐包内 AbortError 错误语义约定（消费方按 err.name 判别）
+          const err = new Error("acquire aborted");
+          err.name = "AbortError";
+          reject(err);
+          return;
+        }
+        entry.signal = signal;
+        entry.onAbort = (): void => {
+          const idx = this.queue.indexOf(entry);
+          if (idx >= 0) {
+            this.queue.splice(idx, 1);
+            // S1: abort reject 需带 name="AbortError"，与 pre-aborted 分支一致
+            const err = new Error("acquire aborted");
+            err.name = "AbortError";
+            reject(err);
+          }
+        };
+        signal.addEventListener("abort", entry.onAbort, { once: true });
+      }
+      this.queue.push(entry);
+    });
+  }
+
+  release(): void {
+    if (this.queue.length > 0) {
+      // 取优先级最高（priority 最小）的；同优先级 FIFO（seq 最小）
+      let bestIdx = 0;
+      for (let i = 1; i < this.queue.length; i++) {
+        const cur = this.queue[i];
+        const best = this.queue[bestIdx];
+        if (cur.priority < best.priority || (cur.priority === best.priority && cur.seq < best.seq)) {
+          bestIdx = i;
+        }
+      }
+      const next = this.queue.splice(bestIdx, 1)[0];
+      // H2: 条目已获槽位——移除 abort listener（防 listener 泄漏到长生命周期 signal）
+      if (next.onAbort && next.signal) {
+        next.signal.removeEventListener("abort", next.onAbort);
+      }
+      next.resolve();
+      // active 不变（一个离开队列立即进入活跃）
+    } else if (this._active > 0) {
+      // 防御性下界：release 调用次数多于 acquire 时不让 active 为负
+      this._active -= 1;
+    }
+  }
+
+  get active(): number {
+    return this._active;
+  }
+}

package/src/execution/config.ts

@@ -0,0 +1,165 @@
+// src/runtime/config/config.ts
+//
+// 全局配置（~/.pi/agent/subagents/config.json）。
+// 仅保留 maxConcurrent（pool 大小）。模型解析已退化为「主 agent model 优先」，
+// 不再有 category/fallback/session 级覆盖——相关字段读取时忽略。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+
+import type { SubagentsGlobalConfig } from "./types.ts";
+
+// 包内 execution 模块统一具名 logger（getLogger 缓存单例，见 notify-ledger.ts 同款）。
+const logger = getLogger("subagents");
+
+// ============================================================
+// 常量
+// ============================================================
+
+/**
+ * 开箱默认配置（单一真相源，内联在代码里）。
+ *
+ * 历史教训 [HISTORICAL]：曾用包内 config.json（与 src/ 同级）作为默认值源，
+ * 但 config.json 被 .gitignore 排除且不应随 npm 包分发用户私有配置——导致
+ * npm pack 后读不到文件，catch 兜底用空字段，pi install 后首次执行抛错。
+ * 修复：默认值内联在代码里，不依赖任何包内文件。
+ *
+ * export 供守护测试断言 package.json startupConfig 声明与此深相等（防漂移）。
+ */
+export const DEFAULT_CONFIG: SubagentsGlobalConfig = {
+  version: 1,
+  maxConcurrent: 6,
+};
+
+/** 默认 maxConcurrent（DEFAULT_CONFIG 的镜像，sanitize 用）。 */
+const DEFAULT_MAX_CONCURRENT = 6;
+// ============================================================
+// 路径
+// ============================================================
+
+/**
+ * 配置文件路径（<agentDir>/subagents/config.json）。
+ * agentDir 由 Pi 核心 getAgentDir() 决定（读 PI_CODING_AGENT_DIR，默认 ~/.pi/agent），
+ * 与 Pi 主进程的目录约定完全一致——支持宿主经环境变量整体重定向。
+ */
+export function getGlobalConfigPath(agentDir: string): string {
+  return path.join(agentDir, "subagents", "config.json");
+}
+
+// ============================================================
+// 全局配置加载
+// ============================================================
+
+/**
+ * 加载全局配置。文件不存在 / JSON 解析失败 / 字段缺失时返回默认配置。
+ * 旧 config.json 中的 categories/fallback/yoloByDefault 等字段读取时忽略
+ * （模型解析已退化为「主 agent model 优先」）。
+ *
+ * 注意：本函数是「静默回落」形态（ENOENT 与坏 JSON 同归默认值，历史行为保持
+ * 不动）。需要区分三态的调用方（引擎感知检测器，设计 D5）用 readGlobalConfig。
+ */
+export function loadGlobalConfig(agentDir: string): SubagentsGlobalConfig {
+  try {
+    const raw = fs.readFileSync(getGlobalConfigPath(agentDir), "utf-8");
+    const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    return sanitizeParsedConfig(parsed);
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+// ============================================================
+// 三态读取（设计 D5：明确值 / 明确缺省 / 读失败）
+// ============================================================
+
+/** 三态读取结果（判别联合，调用方按 status 分派）。 */
+export type GlobalConfigReadResult =
+  /** 读到明确值：JSON 可解析，字段已经 sanitize。 */
+  | { status: "ok"; config: SubagentsGlobalConfig }
+  /** 明确缺省：文件不存在（ENOENT）。这是用户意图（删配置切回缺省 pi），不是故障。 */
+  | { status: "absent"; config: SubagentsGlobalConfig }
+  /** 读失败：坏 JSON / 权限等。携带原始错误消息供诊断；调用方保持 lastEngine 不动。 */
+  | { status: "failed"; reason: string };
+
+/**
+ * 三态读取全局配置（设计 D5）。
+ *
+ * 为什么不用 loadGlobalConfig：后者 ENOENT 与坏 JSON 同归 DEFAULT_CONFIG（静默
+ * 回落），检测器若消费该形态会把「用户删配置切回缺省」（合法变更，须生效）误判成
+ * 「读失败」（须保持 lastEngine），也会把坏 JSON（torn write）误判成合法缺省——
+ * 两个方向都会产生错误的引擎切换信号。
+ */
+export function readGlobalConfig(agentDir: string): GlobalConfigReadResult {
+  const configPath = getGlobalConfigPath(agentDir);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(configPath, "utf-8");
+  } catch (err) {
+    // ENOENT 单独成态：subagents/ 目录不存在同样意味着没有配置文件，语义等同
+    if (errnoCodeOf(err) === "ENOENT") {
+      return { status: "absent", config: { ...DEFAULT_CONFIG } };
+    }
+    return readFailure(configPath, err);
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    return { status: "ok", config: sanitizeParsedConfig(parsed) };
+  } catch (err) {
+    return readFailure(configPath, err);
+  }
+}
+
+/** 读失败统一出口：落 warn 日志（现状 loadGlobalConfig catch 静默无日志的补漏）+ 携带原因。 */
+function readFailure(configPath: string, err: unknown): GlobalConfigReadResult {
+  const reason = err instanceof Error ? err.message : String(err);
+  logger.warn(`[subagents] global config read failed (read-failure) at ${configPath}: ${reason}`);
+  return { status: "failed", reason };
+}
+
+/** 从 unknown 错误提取 Node errno code（运行时 guard，不用类型断言）。 */
+function errnoCodeOf(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null || !("code" in err)) return undefined;
+  const code = Reflect.get(err, "code");
+  return typeof code === "string" ? code : undefined;
+}
+
+/**
+ * 已解析 JSON 的 sanitize（loadGlobalConfig 与 readGlobalConfig 共用，防两处漂移）。
+ * P4 引擎路由（D9）：非法值静默回缺省（'pi' / false）——config.json 是用户手编
+ * 文件，坏值不炸启动（与 maxConcurrent 同判）。
+ */
+function sanitizeParsedConfig(parsed: Partial<SubagentsGlobalConfig>): SubagentsGlobalConfig {
+  const defaultEngine = sanitizeDefaultEngine(parsed.defaultEngine);
+  const engineRouting = sanitizeEngineRouting(parsed.engineRouting);
+  return {
+    version: parsed.version ?? DEFAULT_CONFIG.version,
+    maxConcurrent: sanitizeMaxConcurrent(parsed.maxConcurrent),
+    ...(defaultEngine !== undefined ? { defaultEngine } : {}),
+    ...(engineRouting !== undefined ? { engineRouting } : {}),
+  };
+}
+
+/** maxConcurrent 校验：正整数，否则默认。 */
+function sanitizeMaxConcurrent(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_CONCURRENT;
+}
+
+/**
+ * defaultEngine 校验：非空字符串透传，其余 undefined（缺省引擎由路由层落 'pi'）。
+ * 为什么不在加载期对注册表校验 hasEngine：加载早于组合根注册（agentDir 解析在
+ * session_start），注册表此刻可能为空——校验归路由层（getEngine 抛 EngineNotFoundError）。
+ */
+function sanitizeDefaultEngine(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/** engineRouting 校验：仅认 strict 布尔，其余键忽略（向前兼容追加）。 */
+function sanitizeEngineRouting(value: unknown): { strict: boolean } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const strict = (value as Record<string, unknown>).strict;
+  return typeof strict === "boolean" ? { strict } : undefined;
+}