@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.0

package/src/execution/__tests__/ui-request-observability.test.ts

@@ -0,0 +1,101 @@
+// src/__tests__/ui-request-observability.test.ts
+//
+// M4 测试：ui-request-observability.ts — UiRequestObservability 纯逻辑类。
+//
+// 测试对象：extensions/subagent-workflow/src/execution/ui-request-observability.ts
+// 契约来源：类注释（per-session 去重 + resetMissingHandlerWarnings 清洗 + setMode/getMode 往返）
+//
+// UiRequestObservability 职责：
+//   - setMode/getMode：sessionMode 往返存储
+//   - notifyMissingHandler(sessionId)：per-session 去重，每 session 只 console.warn 一次
+//   - resetMissingHandlerWarnings()：清去重集合，清洗后可重新 warn
+//
+// 纯逻辑无异步，测试最简单。console.warn spy 验证调用次数。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { UiRequestObservability } from "../ui-request-observability.ts";
+
+// ── 公共 fixture ──────────────────────────────────────────────
+
+beforeEach(() => {
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("UiRequestObservability — setMode/getMode 往返", () => {
+  it("setMode('tui') → getMode() === 'tui'", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("tui");
+    expect(obs.getMode()).toBe("tui");
+  });
+
+  it("setMode('rpc') → getMode() === 'rpc'", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("rpc");
+    expect(obs.getMode()).toBe("rpc");
+  });
+
+  it("初始 getMode() === undefined（未 set）", () => {
+    const obs = new UiRequestObservability();
+    expect(obs.getMode()).toBeUndefined();
+  });
+
+  it("setMode(undefined) → getMode() === undefined（可重置）", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("json");
+    obs.setMode(undefined);
+    expect(obs.getMode()).toBeUndefined();
+  });
+});
+
+describe("UiRequestObservability — notifyMissingHandler per-session 去重", () => {
+  it("同 sessionId 调两次 → 只 warn 一次", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s1");
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("warn 内容含 sessionId 和 mode（可观测性）", () => {
+    const obs = new UiRequestObservability();
+    obs.setMode("tui");
+    obs.notifyMissingHandler("s1");
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining("session=s1"),
+    );
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining("mode=tui"),
+    );
+  });
+});
+
+describe("UiRequestObservability — resetMissingHandlerWarnings 后可重新 warn", () => {
+  it("notify(s1) → reset → notify(s1) → warn 被调 2 次", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    expect(console.warn).toHaveBeenCalledTimes(1);
+
+    obs.resetMissingHandlerWarnings();
+
+    obs.notifyMissingHandler("s1");
+    expect(console.warn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("UiRequestObservability — 不同 session 各自首次 warn", () => {
+  it("notify(s1) + notify(s2) → warn 被调 2 次（互不干扰）", () => {
+    const obs = new UiRequestObservability();
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s2");
+    expect(console.warn).toHaveBeenCalledTimes(2);
+
+    // 再次各自调用，已被去重，不再 warn
+    obs.notifyMissingHandler("s1");
+    obs.notifyMissingHandler("s2");
+    expect(console.warn).toHaveBeenCalledTimes(2);
+  });
+});

package/src/execution/__tests__/ui-request-queue.test.ts

@@ -0,0 +1,133 @@
+// src/__tests__/ui-request-queue.test.ts
+//
+// W3 测试：UI 请求队列机制（L1 per-child createUiRequestQueue）
+// 1. 多个请求按 FIFO 顺序处理
+// 2. 第一个请求未完成时第二个不开始
+//
+// 直接测试 createUiRequestQueue 的队列逻辑（纯函数，不需要 mock runSpawn）。
+// 用 fake child（PassThrough stdin）+ 手动控制 Promise resolve 时序。
+//
+// 协议迁移（W2）：enqueue 第二参从旧 Record params（含 questions/context）改为
+// ExtensionUiRequest（method 平铺）；handler 签名从 (questions,context) 改为
+// UiRequestHandler (req: UiRequest) => Promise<UiResponse>。
+
+import type { ChildProcess } from "node:child_process";
+import { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createUiRequestQueue,
+  type UiRequest,
+  type UiRequestHandler,
+  type UiResponse,
+} from "../ui-request-queue.ts";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+function makeFakeChild(): ChildProcess {
+  const stdin = new PassThrough();
+  return {
+    stdin,
+    killed: false,
+    pid: 10001,
+    on: vi.fn(),
+    removeListener: vi.fn(),
+  } as unknown as ChildProcess;
+}
+
+/** 构造 select method 的 ExtensionUiRequest（ask_user 借道 select dialog 通道）。 */
+function makeSelectReq(question: string): { method: "select"; title: string; options: string[] } {
+  return {
+    method: "select",
+    title: question,
+    options: [JSON.stringify({ question, options: [{ label: "A" }] })],
+  };
+}
+
+describe("UI 请求队列", () => {
+  it("多个 extension_ui_request 按 FIFO 顺序处理", async () => {
+    const callOrder: string[] = [];
+    // 每个请求返回独立的可控 Promise
+    const resolvers: Array<(v: unknown) => void> = [];
+
+    const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
+      callOrder.push(req.title ?? "");
+      return new Promise<UiResponse>((resolve) => {
+        resolvers.push(resolve);
+      });
+    }) as unknown as UiRequestHandler;
+
+    const child = makeFakeChild();
+    const ctx = { uiRequestHandler: handler } as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+    const enqueue = createUiRequestQueue(child, ctx);
+
+    // 快速入队三个请求（handler 被调用但不 resolve）
+    enqueue("r1", makeSelectReq("Q1"));
+    enqueue("r2", makeSelectReq("Q2"));
+    enqueue("r3", makeSelectReq("Q3"));
+
+    // 第一个请求立即开始处理
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual(["Q1"]);
+
+    // resolve 第一个 → 第二个开始处理
+    resolvers[0]({ value: "a1" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(callOrder).toEqual(["Q1", "Q2"]);
+
+    // resolve 第二个 → 第三个开始处理
+    resolvers[1]({ value: "a2" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(handler).toHaveBeenCalledTimes(3);
+    expect(callOrder).toEqual(["Q1", "Q2", "Q3"]);
+  });
+
+  it("第一个请求未 resolve 时第二个不调用 uiRequestHandler", async () => {
+    const callOrder: string[] = [];
+    let firstResolve: (v: unknown) => void;
+
+    const handler: UiRequestHandler = vi.fn((req: UiRequest) => {
+      callOrder.push(req.title ?? "");
+      if (req.title === "Q1") {
+        return new Promise<UiResponse>((resolve) => {
+          firstResolve = resolve;
+        });
+      }
+      return Promise.resolve<UiResponse>({ value: "done" });
+    }) as unknown as UiRequestHandler;
+
+    const child = makeFakeChild();
+    const ctx = { uiRequestHandler: handler } as Parameters<
+      typeof createUiRequestQueue
+    >[1];
+    const enqueue = createUiRequestQueue(child, ctx);
+
+    enqueue("r1", makeSelectReq("Q1"));
+    enqueue("r2", makeSelectReq("Q2"));
+
+    // 只有 Q1 被调用，Q2 还在队列里
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual(["Q1"]);
+
+    // 等一下，Q2 仍然不应该被调用
+    await vi.advanceTimersByTimeAsync(100);
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(callOrder).toEqual(["Q1"]);
+
+    // resolve Q1 → Q2 才开始
+    firstResolve!({ value: "a1" });
+    await vi.advanceTimersByTimeAsync(0);
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(callOrder).toEqual(["Q1", "Q2"]);
+  });
+});

package/src/execution/__tests__/worktree-manager.test.ts

@@ -72,8 +72,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { encodeCwd } from "../path-encoding.ts";
 import { isProcessAlive } from "../alive-store.ts";
+import { encodeCwd } from "../path-encoding.ts";
 import { WorktreeManager } from "../worktree-manager.ts";
 
 const mockExec = vi.mocked(execFileSync);

package/src/execution/agent-registry.ts

@@ -31,7 +31,7 @@ export interface BuiltinAgentRegistry {
  * manifest 缺失时 fallback 扫约定目录 agents/。
  *
  * [HISTORICAL] 此前 discoverAll 从未被调用，agentRegistry 永远为空——包内
- * agents/*.md（worker/reviewer/scout 等）pi install 后开箱不可用。修复：构造时扫描
+ * agents/*.md（worker/reviewer/explorer 等）pi install 后开箱不可用。修复：构造时扫描
  * 包内 agents/ 作为 builtin（优先级最低，被用户同名文件覆盖）。
  */
 export function createPackageBuiltinRegistry(): BuiltinAgentRegistry {

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

@@ -0,0 +1,138 @@
+// 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 { createUiChannelRegistry, type UiChannelRegistry, type ChannelHandler } from "./ui-channels.ts";
+
+/** 进程级 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) {
+    console.warn(
+      "[pi-subagent-workflow] channel handshake slot is not an object; discarding and recreating.",
+    );
+    return undefined;
+  }
+  const version = (slot as { version?: unknown }).version;
+  if (version !== HANDSHAKE_VERSION) {
+    console.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)) {
+    console.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 };