@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/turn-limiter-semantics.test.ts

@@ -0,0 +1,194 @@
+// src/execution/__tests__/turn-limiter-semantics.test.ts
+//
+// SP-9: turn-limiter chatMode 语义——chatMode 下 maxTurns 每轮 reset（不跨轮累计）。
+// 设计 D9 决策：续聊本质是无限轮，累计上限违背 G1。
+
+import { describe, expect, it, vi } from "vitest";
+
+import { createTurnLimiter } from "../turn-limiter.ts";
+
+describe("SP-9: turn-limiter chatMode semantics (maxTurns reset per round)", () => {
+  describe("TC-1: chatMode 多轮后 maxTurns 每轮 reset（不累计）", () => {
+    it("reset 后 maxTurns 不累计——第二轮从 0 开始，不触发 steer/abort", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 3, graceTurns: 2, steer, abort });
+
+      // 第一轮：3 turns → steer（达到 maxTurns=3）
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2);
+      limiter.onTurnEnd(3);
+      expect(steer).toHaveBeenCalledTimes(1);
+      expect(abort).not.toHaveBeenCalled();
+
+      // agent_settled → reset（模拟 chatMode 每轮 reset）
+      limiter.reset();
+
+      // 第二轮从 turnCount=0 开始（record.turnCount 由 session-runner 归零）：
+      // 2 turns 不触发 steer（距离 maxTurns=3 还差 1）
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2);
+      // steer 仍然是 1 次（第一轮那次），第二轮未触发
+      expect(steer).toHaveBeenCalledTimes(1);
+      expect(abort).not.toHaveBeenCalled();
+    });
+
+    it("reset 后第二轮同样达到 maxTurns 时仍触发 steer", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 1, steer, abort });
+
+      // 第一轮：steer + grace + abort
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2); // steer
+      limiter.onTurnEnd(3); // abort
+      expect(steer).toHaveBeenCalledTimes(1);
+      expect(abort).toHaveBeenCalledTimes(1);
+
+      // reset（chatMode 新轮）
+      limiter.reset();
+      expect(limiter.didSteer).toBe(false);
+      expect(limiter.didAbort).toBe(false);
+
+      // 第二轮：同样走完 steer + grace 路径
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2); // steer again
+      expect(steer).toHaveBeenCalledTimes(2);
+      expect(abort).toHaveBeenCalledTimes(1); // 还没到 abort
+
+      limiter.onTurnEnd(3); // abort again
+      expect(abort).toHaveBeenCalledTimes(2);
+    });
+
+    it("多轮连续 reset 后 limiter 始终可用", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 0, steer, abort });
+
+      for (let round = 1; round <= 5; round++) {
+        limiter.onTurnEnd(1);
+        limiter.onTurnEnd(2); // steer + abort (graceTurns=0)
+        expect(steer).toHaveBeenCalledTimes(round);
+        expect(abort).toHaveBeenCalledTimes(round);
+        limiter.reset();
+      }
+    });
+  });
+
+  describe("TC-2: graceTurns 每轮 reset", () => {
+    it("reset 后 graceTurns 从 0 重新计数", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 3, steer, abort });
+
+      // 第一轮：steer at turn 2，用掉 1 个 grace turn
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2); // steer
+      limiter.onTurnEnd(3); // grace turn 1
+      expect(abort).not.toHaveBeenCalled();
+
+      // reset（模拟 chatMode agent_settled）
+      limiter.reset();
+
+      // 第二轮：从 turn 1 开始，graceTurns 重新从 0 计数
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2); // steer again
+      limiter.onTurnEnd(3); // grace turn 1（重计）
+      limiter.onTurnEnd(4); // grace turn 2
+      limiter.onTurnEnd(5); // grace turn 3 → abort
+      expect(abort).toHaveBeenCalledTimes(1);
+    });
+
+    it("reset 前未 steer 时 reset 后仍正常工作", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 5, graceTurns: 2, steer, abort });
+
+      // 第一轮：只走了 2 turns（未达 maxTurns）
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2);
+      expect(steer).not.toHaveBeenCalled();
+
+      limiter.reset();
+
+      // 第二轮：从 turn 1 开始，到 maxTurns=5 触发 steer
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2);
+      limiter.onTurnEnd(3);
+      limiter.onTurnEnd(4);
+      limiter.onTurnEnd(5); // steer
+      expect(steer).toHaveBeenCalledTimes(1);
+      limiter.onTurnEnd(6);
+      limiter.onTurnEnd(7); // abort (5+2)
+      expect(abort).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("TC-3: 非 chatMode 行为不变（全程累计）", () => {
+    it("不调用 reset 时 turn-limiter 行为与原来完全一致", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 3, graceTurns: 2, steer, abort });
+
+      // 全程累计（非 chatMode，不 reset）：3→steer，5→abort
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2);
+      limiter.onTurnEnd(3); // steer
+      expect(steer).toHaveBeenCalledTimes(1);
+      limiter.onTurnEnd(4); // grace 1
+      limiter.onTurnEnd(5); // grace 2 → abort
+      expect(abort).toHaveBeenCalledTimes(1);
+      expect(limiter.didSteer).toBe(true);
+      expect(limiter.didAbort).toBe(true);
+    });
+
+    it("maxTurns=0（禁用）不因 reset 而误启用", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 0, graceTurns: 2, steer, abort });
+
+      limiter.onTurnEnd(100);
+      expect(steer).not.toHaveBeenCalled();
+
+      limiter.reset();
+      limiter.onTurnEnd(100);
+      // maxTurns=0（禁用），即使 reset 也不触发
+      expect(steer).not.toHaveBeenCalled();
+      expect(abort).not.toHaveBeenCalled();
+    });
+
+    it("全程累计（不 reset）达到 maxTurns+graceTurns 后不再触发", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 1, steer, abort });
+
+      limiter.onTurnEnd(1);
+      limiter.onTurnEnd(2); // steer
+      limiter.onTurnEnd(3); // abort
+      expect(steer).toHaveBeenCalledTimes(1);
+      expect(abort).toHaveBeenCalledTimes(1);
+
+      // 已 abort 后继续调用 onTurnEnd（不应再次触发）
+      limiter.onTurnEnd(4);
+      limiter.onTurnEnd(5);
+      expect(steer).toHaveBeenCalledTimes(1);
+      expect(abort).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("TC-4: reset 诊断属性", () => {
+    it("reset 清除 didSteer 和 didAbort 诊断标志", () => {
+      const steer = vi.fn();
+      const abort = vi.fn();
+      const limiter = createTurnLimiter({ maxTurns: 1, graceTurns: 0, steer, abort });
+
+      limiter.onTurnEnd(1); // steer + abort (graceTurns=0)
+      expect(limiter.didSteer).toBe(true);
+      expect(limiter.didAbort).toBe(true);
+
+      limiter.reset();
+      expect(limiter.didSteer).toBe(false);
+      expect(limiter.didAbort).toBe(false);
+    });
+  });
+});

package/src/execution/__tests__/turn-limiter.test.ts

@@ -0,0 +1,65 @@
+// src/__tests__/turn-limiter.test.ts
+import { describe, expect, it, vi } from "vitest";
+
+import { createTurnLimiter } from "../turn-limiter.ts";
+
+describe("createTurnLimiter", () => {
+  it("does nothing before maxTurns", () => {
+    const steer = vi.fn();
+    const abort = vi.fn();
+    const limiter = createTurnLimiter({ maxTurns: 3, graceTurns: 2, steer, abort });
+    limiter.onTurnEnd(1);
+    limiter.onTurnEnd(2);
+    expect(steer).not.toHaveBeenCalled();
+    expect(abort).not.toHaveBeenCalled();
+    expect(limiter.didSteer).toBe(false);
+    expect(limiter.didAbort).toBe(false);
+  });
+
+  it("steers on maxTurns and aborts after graceTurns", () => {
+    const steer = vi.fn();
+    const abort = vi.fn();
+    const limiter = createTurnLimiter({ maxTurns: 3, graceTurns: 2, steer, abort });
+    limiter.onTurnEnd(3); // 达到 maxTurns → steer
+    expect(steer).toHaveBeenCalledWith(expect.stringContaining("You have reached your turn limit"));
+    expect(abort).not.toHaveBeenCalled();
+    expect(limiter.didSteer).toBe(true);
+    limiter.onTurnEnd(4); // grace turn 1
+    expect(abort).not.toHaveBeenCalled();
+    limiter.onTurnEnd(5); // grace turn 2 → abort
+    expect(abort).toHaveBeenCalledTimes(1);
+    expect(limiter.didAbort).toBe(true);
+  });
+
+  it("disables when maxTurns is 0", () => {
+    const steer = vi.fn();
+    const abort = vi.fn();
+    const limiter = createTurnLimiter({ maxTurns: 0, graceTurns: 2, steer, abort });
+    limiter.onTurnEnd(100);
+    expect(steer).not.toHaveBeenCalled();
+    expect(abort).not.toHaveBeenCalled();
+    expect(limiter.didSteer).toBe(false);
+  });
+
+  it("steers only once", () => {
+    const steer = vi.fn();
+    const abort = vi.fn();
+    const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 3, steer, abort });
+    limiter.onTurnEnd(2);
+    limiter.onTurnEnd(3);
+    expect(steer).toHaveBeenCalledTimes(1);
+    expect(limiter.didSteer).toBe(true);
+  });
+
+  it("aborts on the same turn as steer when graceTurns is 0", () => {
+    const steer = vi.fn();
+    const abort = vi.fn();
+    const limiter = createTurnLimiter({ maxTurns: 2, graceTurns: 0, steer, abort });
+    // grace=0 → limit+grace == limit，steer 后同一 turn 即满足 abort 条件
+    limiter.onTurnEnd(2); // maxTurns → steer + abort（同 turn）
+    expect(steer).toHaveBeenCalledTimes(1);
+    expect(abort).toHaveBeenCalledTimes(1);
+    expect(limiter.didSteer).toBe(true);
+    expect(limiter.didAbort).toBe(true);
+  });
+});

package/src/execution/__tests__/ui-channels.test.ts

@@ -0,0 +1,187 @@
+// src/__tests__/ui-channels.test.ts
+//
+// W1 红灯测试：ui-channels.ts — channel 提取（marker 解析）+ channel 注册表。
+//
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-channels.ts（新建）
+// 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 2：channel 注册表」
+//
+// parseChannel(req): ExtensionUiRequest → { channel?, channelPayload? }
+//   - select → 从 title 解析 NUL 前缀（parseFromMarkerString）
+//   - setWidget → 从 widgetLines[0] 解析 NUL 前缀（parseFromMarkerArray）
+//   - 其他 method → {}（无 channel）
+//
+// marker 格式：\0<UPPER_CASE_ID>[:]<JSON-payload?>
+//   - ASK_USER_MARKER = "\0XYZ_ASK_USER"，payload 在 options[0]
+//   - GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:" + JSON，payload 在同行
+// channel 名规范化：去 "XYZ_" 前缀，小写化（XYZ_ASK_USER → ask_user）
+//
+// UiChannelRegistry:
+//   - register(channel, handler) / resolve(channel) / list()
+//
+// 边界：无 NUL 前缀 → {}；JSON parse 失败 → {}（不抛）；字段缺失 → {}
+//
+// 红灯原因：ui-channels.ts 尚未创建，import 失败。
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createUiChannelRegistry,
+  type ExtensionUiRequestLike,
+  parseChannel,
+} from "../ui-channels.ts";
+
+// ── 测试 fixture 构造助手 ────────────────────────────────────
+// ExtensionUiRequestLike 是 parseChannel 入参的最小形状（method + 对应字段）。
+
+function selectReq(title: string, options?: string[]): ExtensionUiRequestLike {
+  return { method: "select", title, options };
+}
+
+function setWidgetReq(widgetKey: string, widgetLines: string[] | undefined): ExtensionUiRequestLike {
+  return { method: "setWidget", widgetKey, widgetLines };
+}
+
+// ── ASK_USER_MARKER 样本（真实 Pi 协议格式） ─────────────────
+// title = "\0XYZ_ASK_USER"，options[0] = JSON.stringify({questions, allowCancel})
+const ASK_USER_MARKER = "\0XYZ_ASK_USER";
+const askUserPayload = {
+  questions: [{ question: "Pick one", options: [{ label: "A" }, { label: "B" }] }],
+  allowCancel: true,
+};
+
+// ── GUI_WIDGET_MARKER 样本（真实 Pi 协议格式） ───────────────
+// widgetLines[0] = "\0XYZ_GUI_WIDGET:" + JSON.stringify({component:{...}})
+const GUI_WIDGET_MARKER_PREFIX = "\0XYZ_GUI_WIDGET:";
+const guiWidgetPayload = { component: { name: "StatusCard", props: { ok: true } } };
+
+describe("parseChannel — select method（从 title 解析 NUL 前缀）", () => {
+  it("title 含 ASK_USER_MARKER → channel='ask_user' + payload 从 options[0] 解析", () => {
+    const req = selectReq(ASK_USER_MARKER, [JSON.stringify(askUserPayload)]);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+    expect(result.channelPayload).toEqual(askUserPayload);
+  });
+
+  it("title 无 NUL 前缀 → {}（普通 select，无 channel）", () => {
+    const req = selectReq("Choose a plan", ["basic", "pro"]);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+    expect(result.channelPayload).toBeUndefined();
+  });
+
+  it("title 含 marker 但 options 缺失 → channel 解析但 payload undefined", () => {
+    // marker 在 title，但 options 为空 → channel 名仍可提取，payload 无来源
+    const req = selectReq(ASK_USER_MARKER);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+  });
+});
+
+describe("parseChannel — setWidget method（从 widgetLines[0] 解析 NUL 前缀）", () => {
+  it("widgetLines[0] 含 GUI_WIDGET_MARKER → channel='gui_widget' + payload", () => {
+    const req = setWidgetReq("w1", [GUI_WIDGET_MARKER_PREFIX + JSON.stringify(guiWidgetPayload)]);
+    const result = parseChannel(req);
+    expect(result.channel).toBe("gui_widget");
+    expect(result.channelPayload).toEqual(guiWidgetPayload);
+  });
+
+  it("widgetLines 无 NUL 前缀 → {}（普通 setWidget）", () => {
+    const req = setWidgetReq("w1", ["plain content line"]);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("widgetLines 为 undefined → {}", () => {
+    const req = setWidgetReq("w1", undefined);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("widgetLines 为空数组 → {}", () => {
+    const req = setWidgetReq("w1", []);
+    const result = parseChannel(req);
+    expect(result.channel).toBeUndefined();
+  });
+});
+
+describe("parseChannel — 其他 method（无 channel 提取位置）", () => {
+  it("confirm → {}", () => {
+    const result = parseChannel({ method: "confirm", title: "t", message: "m" });
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("input → {}", () => {
+    const result = parseChannel({ method: "input", title: "t" });
+    expect(result.channel).toBeUndefined();
+  });
+
+  it("notify → {}", () => {
+    const result = parseChannel({ method: "notify", message: "hi" });
+    expect(result.channel).toBeUndefined();
+  });
+});
+
+describe("parseChannel — channel 名规范化规则", () => {
+  it("去 XYZ_ 命名空间前缀 + 小写化（XYZ_ASK_USER → ask_user）", () => {
+    const req = selectReq("\0XYZ_ASK_USER", [JSON.stringify({ x: 1 })]);
+    expect(parseChannel(req).channel).toBe("ask_user");
+  });
+
+  it("XYZ_GUI_WIDGET: 带冒号后缀 → gui_widget（去前缀 + 去冒号 + 小写）", () => {
+    const req = setWidgetReq("k", ["\0XYZ_GUI_WIDGET:" + JSON.stringify({ y: 2 })]);
+    expect(parseChannel(req).channel).toBe("gui_widget");
+  });
+});
+
+describe("parseChannel — 边界（不抛错）", () => {
+  it("marker 后 payload 非法 JSON → 不抛错，channel 仍解析（payload undefined）", () => {
+    const req = selectReq(ASK_USER_MARKER, ["not-valid-json{"]);
+    expect(() => parseChannel(req)).not.toThrow();
+    const result = parseChannel(req);
+    expect(result.channel).toBe("ask_user");
+  });
+
+  it("GUI_WIDGET_MARKER 后非法 JSON → 不抛错", () => {
+    const req = setWidgetReq("k", [GUI_WIDGET_MARKER_PREFIX + "broken{json"]);
+    expect(() => parseChannel(req)).not.toThrow();
+  });
+});
+
+// ── UiChannelRegistry ────────────────────────────────────────
+
+describe("UiChannelRegistry — 注册 + 解析 + 列举", () => {
+  it("register 后 resolve 返回注册的 handler", () => {
+    const registry = createUiChannelRegistry();
+    const handler = vi.fn();
+    registry.register("ask_user", handler);
+    expect(registry.resolve("ask_user")).toBe(handler);
+  });
+
+  it("未注册的 channel resolve 返回 undefined", () => {
+    const registry = createUiChannelRegistry();
+    expect(registry.resolve("unknown")).toBeUndefined();
+  });
+
+  it("list 返回所有已注册 channel 名", () => {
+    const registry = createUiChannelRegistry();
+    registry.register("ask_user", vi.fn());
+    registry.register("gui_widget", vi.fn());
+    const names = registry.list().sort();
+    expect(names).toEqual(["ask_user", "gui_widget"]);
+  });
+
+  it("list 空注册表返回 []", () => {
+    const registry = createUiChannelRegistry();
+    expect(registry.list()).toEqual([]);
+  });
+
+  it("重复 register 同名 channel 覆盖旧 handler", () => {
+    const registry = createUiChannelRegistry();
+    const old = vi.fn();
+    const fresh = vi.fn();
+    registry.register("ask_user", old);
+    registry.register("ask_user", fresh);
+    expect(registry.resolve("ask_user")).toBe(fresh);
+    expect(registry.list()).toEqual(["ask_user"]);
+  });
+});

package/src/execution/__tests__/ui-interaction-model.test.ts

@@ -0,0 +1,67 @@
+// src/__tests__/ui-interaction-model.test.ts
+//
+// W1 红灯测试：ui-interaction-model.ts — method 交互模型分类。
+//
+// 测试对象：extensions/universal/subagent-workflow/src/execution/ui-interaction-model.ts（新建）
+// 契约来源：.fix-plans/00-master-summary.md §一 冲突 2「维度 1：透传判定规则」
+//
+// isDialogMethod(method):
+//   - dialog（占输入焦点，等响应，需透传+排队）：select / confirm / input / editor → true
+//   - fire-and-forget（纯展示/写入，不等响应）：notify / setStatus / setWidget /
+//     setTitle / set_editor_text / 未知 method → false
+//
+// 红灯原因：ui-interaction-model.ts 尚未创建，import 失败。
+
+import { describe, expect, it } from "vitest";
+
+import { isDialogMethod } from "../ui-interaction-model.ts";
+
+describe("isDialogMethod — dialog 类 method（占输入焦点）", () => {
+  it("select → true（含 ask_user channel 借道 select）", () => {
+    expect(isDialogMethod("select")).toBe(true);
+  });
+
+  it("confirm → true", () => {
+    expect(isDialogMethod("confirm")).toBe(true);
+  });
+
+  it("input → true", () => {
+    expect(isDialogMethod("input")).toBe(true);
+  });
+
+  it("editor → true", () => {
+    expect(isDialogMethod("editor")).toBe(true);
+  });
+});
+
+describe("isDialogMethod — fire-and-forget 类 method（纯展示/写入）", () => {
+  it("notify → false", () => {
+    expect(isDialogMethod("notify")).toBe(false);
+  });
+
+  it("setStatus → false", () => {
+    expect(isDialogMethod("setStatus")).toBe(false);
+  });
+
+  it("setWidget → false（含 gui_widget channel 借道 setWidget）", () => {
+    expect(isDialogMethod("setWidget")).toBe(false);
+  });
+
+  it("setTitle → false", () => {
+    expect(isDialogMethod("setTitle")).toBe(false);
+  });
+
+  it("set_editor_text → false", () => {
+    expect(isDialogMethod("set_editor_text")).toBe(false);
+  });
+});
+
+describe("isDialogMethod — 未知 method 默认 fire-and-forget", () => {
+  it("未知 method 名 → false（未来 Pi 新增 method 不误判为 dialog）", () => {
+    expect(isDialogMethod("some_future_method")).toBe(false);
+  });
+
+  it("空字符串 → false", () => {
+    expect(isDialogMethod("")).toBe(false);
+  });
+});