minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/test/runner.test.ts

@@ -0,0 +1,911 @@
+/**
+ * ============================================================
+ *  test/workflows/runner.test.ts
+ * ------------------------------------------------------------
+ *  runner P0 行为：
+ *    - tool / llm / assert step 成功路径
+ *    - capture 绑变量到 VarStack
+ *    - when=false → workflow_step_skipped
+ *    - onError=halt（默认）→ workflow halt + error
+ *    - onError=continue → 继续下一步
+ *    - 工作流完成 yield workflow_done
+ *
+ *  策略：
+ *    - tool 步骤用真实 Write 工具（写到 tmpdir，避免 mock executeTool）
+ *    - llm 步骤 mock.module('../../../src/llm/client.js')
+ *    - assert / when 走纯表达式引擎，无需 mock
+ * ============================================================
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { _resetWorkingDir } from '../../../src/bootstrap/workingDir.js';
+import { ALL_TOOLS } from '../../../src/tools/index.js';
+import { runWorkflow } from '../src/runner.js';
+import type {
+  LoopEvent,
+  Provider,
+} from '../../../src/types.js';
+import type {
+  RunContext,
+  WorkflowDef,
+  WorkflowEvent,
+} from '../src/types.js';
+
+type WfOrLoop = WorkflowEvent | LoopEvent;
+
+const fakeProvider: Provider = {
+  name: 'test',
+  baseURL: '',
+  apiKey: '',
+  model: 'm',
+  contextWindow: 128000,
+};
+
+async function collect(
+  gen: AsyncGenerator<WfOrLoop, void, void>,
+): Promise<WfOrLoop[]> {
+  const out: WfOrLoop[] = [];
+  for await (const ev of gen) out.push(ev);
+  return out;
+}
+
+describe('workflows/runner', () => {
+  let tmp: string;
+  let ctx: RunContext;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'wf-runner-'));
+    process.env.MINIMAL_AGENT_CWD = tmp;
+    _resetWorkingDir();
+    // 抵抗 pluginRunner.test.ts 等遗留的 workingDir.ts mock 全局污染
+    mock.module('../../../src/bootstrap/workingDir.js', () => ({
+      getWorkingDir: () => tmp,
+      initWorkingDir: () => tmp,
+      _resetWorkingDir: () => {},
+    }));
+    ctx = { provider: fakeProvider, history: [], cwd: tmp, tools: ALL_TOOLS };
+  });
+
+  afterEach(() => {
+    delete process.env.MINIMAL_AGENT_CWD;
+    _resetWorkingDir();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('线性 assert step 全通过 → workflow_done', async () => {
+    const def: WorkflowDef = {
+      name: 'pure-assert',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: '1 == 1' },
+        { id: 's2', type: 'assert', condition: '"a" != "b"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const types = events.map((e) => e.type);
+    expect(types[0]).toBe('workflow_start');
+    expect(types.filter((t) => t === 'workflow_step_end').length).toBe(2);
+    // v0.9 后 workflow 完成时可能在 workflow_done 前插入 assistant_message 等事件，
+    // 不再保证 workflow_done 严格是末位事件，改用 contains 检查存在性。
+    expect(types).toContain('workflow_done');
+  });
+
+  it('assert 失败 → halt + error 事件', async () => {
+    const def: WorkflowDef = {
+      name: 'assert-fail',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: '1 == 2', onFail: 'nope' },
+        { id: 's2', type: 'assert', condition: 'true' }, // 不应执行
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    // s2 不应有 step_start
+    const startedIds = events
+      .filter((e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> => e.type === 'workflow_step_start')
+      .map((e) => e.id);
+    expect(startedIds).toEqual(['s1']);
+    // 没 workflow_done
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('onError=continue → 失败后继续下一步', async () => {
+    const def: WorkflowDef = {
+      name: 'continue',
+      description: 'd',
+      steps: [
+        { id: 's1', type: 'assert', condition: 'false', onError: 'continue' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const ends = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end',
+    );
+    expect(ends.length).toBe(2);
+    expect(ends[0].ok).toBe(false);
+    expect(ends[1].ok).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('when=false → workflow_step_skipped 而不是 step_start', async () => {
+    const def: WorkflowDef = {
+      name: 'skip',
+      description: 'd',
+      inputs: [{ name: 'flag', type: 'string' }],
+      steps: [
+        {
+          id: 's1',
+          type: 'assert',
+          condition: 'true',
+          when: 'inputs.flag == "yes"',
+        },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { flag: 'no' }, ctx));
+    const skipped = events.find((e) => e.type === 'workflow_step_skipped');
+    expect(skipped).toBeDefined();
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('tool step 写文件 + ${var} 插值（用真实 Write 工具）', async () => {
+    const def: WorkflowDef = {
+      name: 'wr',
+      description: 'd',
+      inputs: [{ name: 'book', type: 'string' }],
+      steps: [
+        {
+          id: 'w',
+          tool: 'Write',
+          args: {
+            file_path: 'videos/${inputs.book}/x.txt',
+            content: 'hello ${inputs.book}',
+          },
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { book: '原则' }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+
+    const filePath = join(tmp, 'videos', '原则', 'x.txt');
+    expect(existsSync(filePath)).toBe(true);
+    expect(readFileSync(filePath, 'utf8')).toBe('hello 原则');
+  });
+
+  it('声明 artifacts 但最终缺失时不能标记 workflow_done', async () => {
+    const def: WorkflowDef = {
+      name: 'missing-artifact',
+      description: 'd',
+      artifacts: ['expected.txt'],
+      steps: [{ id: 'noop', type: 'assert', condition: 'true' }],
+    };
+
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    expect(
+      events.some(
+        (e) =>
+          e.type === 'error' &&
+          e.error.includes('工作流声明的产物缺失') &&
+          e.error.includes('expected.txt'),
+      ),
+    ).toBe(true);
+  });
+
+  it('capture 把 tool 结果绑到变量，下一步 assert 能用', async () => {
+    const def: WorkflowDef = {
+      name: 'cap',
+      description: 'd',
+      steps: [
+        {
+          id: 'w',
+          tool: 'Write',
+          args: { file_path: 'a.txt', content: 'data' },
+          capture: { content: 'last_write_content' },
+        },
+        {
+          id: 'check',
+          type: 'assert',
+          condition: 'length(last_write_content) > 0',
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('未知 tool → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'badtool',
+      description: 'd',
+      steps: [{ id: 'x', tool: 'NoSuchTool9999' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+  });
+
+  it('llm step 拿 chat 累积文本 + capture text', async () => {
+    mock.module('../../../src/llm/client.js', () => ({
+      chat: async function* () {
+        yield { type: 'text_delta', delta: 'Hello ' };
+        yield { type: 'text_delta', delta: 'world' };
+        yield { type: 'done', stopReason: 'stop' };
+      },
+    }));
+
+    const def: WorkflowDef = {
+      name: 'llm-cap',
+      description: 'd',
+      steps: [
+        {
+          id: 'g',
+          llm: 'irrelevant',
+          capture: { text: 'msg' },
+        },
+        {
+          id: 'check',
+          type: 'assert',
+          condition: 'msg == "Hello world"',
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('workflow_step_start 的 index 与 total 与 steps 长度一致', async () => {
+    const def: WorkflowDef = {
+      name: 'count',
+      description: 'd',
+      steps: [
+        { id: 'a', type: 'assert', condition: 'true' },
+        { id: 'b', type: 'assert', condition: 'true' },
+        { id: 'c', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const starts = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> => e.type === 'workflow_step_start',
+    );
+    expect(starts.length).toBe(3);
+    expect(starts.map((s) => s.index)).toEqual([0, 1, 2]);
+    expect(starts.every((s) => s.total === 3)).toBe(true);
+  });
+
+  it('signal.aborted → 立即 interrupted', async () => {
+    const ctrl = new AbortController();
+    ctrl.abort();
+    const def: WorkflowDef = {
+      name: 'abort',
+      description: 'd',
+      steps: [{ id: 'a', type: 'assert', condition: 'true' }],
+    };
+    const events = await collect(
+      runWorkflow(def, {}, { provider: fakeProvider, history: [], signal: ctrl.signal, cwd: tmp, tools: [] }),
+    );
+    expect(events.some((e) => e.type === 'interrupted')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('P1 branch step：condition=true → 走 then 分支，输出 branch=true', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-true',
+      description: 'd',
+      inputs: [{ name: 'x', type: 'number' }],
+      steps: [
+        {
+          id: 'br',
+          type: 'branch',
+          condition: 'inputs.x > 0',
+          then: [
+            {
+              id: 'then_w',
+              tool: 'Write',
+              args: { file_path: 'pos.txt', content: 'positive' },
+            },
+          ],
+          else: [
+            {
+              id: 'else_w',
+              tool: 'Write',
+              args: { file_path: 'neg.txt', content: 'negative' },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { x: 5 }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(existsSync(join(tmp, 'pos.txt'))).toBe(true);
+    expect(existsSync(join(tmp, 'neg.txt'))).toBe(false);
+    const ends = events.filter(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end',
+    );
+    // 至少 then_w (1) + br (1) = 2 个 step_end，且都 ok
+    expect(ends.length).toBe(2);
+    expect(ends.every((e) => e.ok)).toBe(true);
+    const brEnd = ends.find((e) => e.id === 'br');
+    expect(brEnd?.output).toBe('branch=true');
+  });
+
+  it('P1 branch step：condition=false → 走 else 分支', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-false',
+      description: 'd',
+      inputs: [{ name: 'x', type: 'number' }],
+      steps: [
+        {
+          id: 'br',
+          type: 'branch',
+          condition: 'inputs.x > 0',
+          then: [{ id: 'then_a', type: 'assert', condition: 'true' }],
+          else: [
+            {
+              id: 'else_w',
+              tool: 'Write',
+              args: { file_path: 'neg.txt', content: 'negative' },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, { x: -3 }, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(existsSync(join(tmp, 'neg.txt'))).toBe(true);
+    const brEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'br',
+    );
+    expect(brEnd?.output).toBe('branch=false');
+  });
+
+  it('P1 branch step：缺 then/else 也合法（cond 求值后空跳过）', async () => {
+    const def: WorkflowDef = {
+      name: 'branch-empty',
+      description: 'd',
+      steps: [
+        { id: 'br', type: 'branch', condition: '1 == 1' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const ids = events
+      .filter((e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> => e.type === 'workflow_step_end')
+      .map((e) => e.id);
+    expect(ids).toEqual(['br', 's2']);
+  });
+
+  it('set 步类型保留：单一 ${expr} 保布尔/数字/数组，多片段仍字符串（E2）', async () => {
+    const def: WorkflowDef = {
+      name: 'typed-set',
+      description: 'd',
+      steps: [
+        {
+          id: 'init',
+          type: 'set',
+          set: { qualified: true, count: 7, label: 'x' },
+        },
+        {
+          id: 'copy',
+          type: 'set',
+          set: {
+            // 单一表达式 → 类型保留
+            final_qualified: '${qualified}',
+            next_count: '${count + 1}',
+            arr: "${split('a,b', ',')}",
+            // 多片段模板 → 仍是字符串（向后兼容）
+            summary: '${label}-${count}',
+          },
+        },
+        // 布尔直接 == true 可过（不再需要 == 'true' 防御）——这是 E2 的验收标准
+        { id: 'check_bool', type: 'assert', condition: 'final_qualified == true' },
+        { id: 'check_num', type: 'assert', condition: 'next_count == 8' },
+        { id: 'check_arr', type: 'assert', condition: 'length(arr) == 2' },
+        { id: 'check_str', type: 'assert', condition: "summary == 'x-7'" },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('set 步确定性提取：extract + join 从输出抽 <learning> 标签（E1 落地）', async () => {
+    const def: WorkflowDef = {
+      name: 'extract-learning',
+      description: 'd',
+      steps: [
+        {
+          id: 'fake_output',
+          type: 'set',
+          set: {
+            output:
+              '做完了 <learning>坑一</learning> 其它 <learning>坑二</learning>',
+          },
+        },
+        {
+          id: 'extract',
+          type: 'set',
+          set: {
+            learning: "${join(extract(output, '<learning>(.*?)</learning>'), '; ')}",
+          },
+        },
+        { id: 'check', type: 'assert', condition: "learning == '坑一; 坑二'" },
+        // 无标签时 extract → [] → join → ''（ralph-loop 的 when 守卫依赖这个语义）
+        {
+          id: 'extract_none',
+          type: 'set',
+          set: { none: "${join(extract('无标签文本', '<learning>(.*?)</learning>'), '; ')}" },
+        },
+        { id: 'check_none', type: 'assert', condition: "none == ''" },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('P1 loop step：over=数组字面量，子步骤用 ${as} 和 ${as}_idx', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-lit',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '["a", "b", "c"]',
+          as: 'item',
+          do: [
+            {
+              id: 'w',
+              tool: 'Write',
+              args: {
+                file_path: 'items/${item_idx}-${item}.txt',
+                content: 'idx=${item_idx} val=${item}',
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    for (let i = 0; i < 3; i++) {
+      const val = ['a', 'b', 'c'][i];
+      const filePath = join(tmp, 'items', `${i}-${val}.txt`);
+      expect(existsSync(filePath)).toBe(true);
+      expect(readFileSync(filePath, 'utf8')).toBe(`idx=${i} val=${val}`);
+    }
+    const lpEnd = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'lp',
+    );
+    expect(lpEnd?.output).toBe('loop 3 次');
+  });
+
+  it('P1 loop step：迭代变量在循环外不再可见（push/pop 帧）', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-scope',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '[1, 2]',
+          as: 'i',
+          do: [{ id: 'noop', type: 'assert', condition: 'i > 0' }],
+        },
+        // 循环外的 ${i} 已 pop —— 这里把它当字符串拿不到，length()=0
+        { id: 'check', type: 'assert', condition: 'length(i) == 0' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('P1 loop step：over 求值不是数组 → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'loop-bad-over',
+      description: 'd',
+      steps: [
+        {
+          id: 'lp',
+          type: 'loop',
+          over: '"not an array"',
+          as: 'i',
+          do: [{ id: 'inner', type: 'assert', condition: 'true' }],
+        },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('pause 真 HITL：非交互宿主 askBridge 自动选推荐项（继续）→ 放行', async () => {
+    // 不注入 executeTool：走真 AskUserQuestion → askBridge 无 UI handler → 自动选首项「继续执行 (推荐)」
+    const def: WorkflowDef = {
+      name: 'pause-approve',
+      description: 'd',
+      steps: [
+        { id: 'p1', type: 'pause', prompt: '等用户确认' },
+        { id: 's2', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const end = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'p1',
+    );
+    expect(end?.ok).toBe(true);
+    expect(end?.output).toContain('审批通过');
+  });
+
+  it('pause 真 HITL：用户选「停止」→ halt 且现场保留（可 resume）', async () => {
+    // DI executeTool：模拟用户在 AskUserQuestion 界面选了「停止（保留现场）」
+    ctx.executeTool = async (name: string) => {
+      expect(name).toBe('AskUserQuestion');
+      return { ok: true, content: '用户已回答 AskUserQuestion：\nA1: 停止（保留现场）' };
+    };
+    const def: WorkflowDef = {
+      name: 'pause-stop',
+      description: 'd',
+      steps: [
+        { id: 'gate', type: 'pause', prompt: '等审批' },
+        { id: 'after', type: 'assert', condition: 'true' }, // 不应执行
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    const halt = events.find(
+      (e): e is { type: 'error'; error: string } =>
+        e.type === 'error' && e.error.includes('Workflow halted'),
+    );
+    expect(halt).toBeDefined();
+    expect(halt!.error).toContain('选择停止');
+    const startedIds = events
+      .filter(
+        (e): e is Extract<WorkflowEvent, { type: 'workflow_step_start' }> =>
+          e.type === 'workflow_step_start',
+      )
+      .map((e) => e.id);
+    expect(startedIds).not.toContain('after');
+  });
+
+  it('pause 真 HITL：提示语含「停止」字样 + 用户选「继续」→ 必须放行（事故回归锚）', async () => {
+    // 真事故：plan.yaml 的 pause 提示语写着『选「停止」会保留现场…』，
+    // 回执的 Q 行带问题原文——曾因看整个 content 把用户选的「继续」误判成停止。
+    ctx.executeTool = async (_name: string, rawArgsJson: string) => {
+      const args = JSON.parse(rawArgsJson) as {
+        questions: { question: string }[];
+      };
+      // 模拟 ask.ts 的真实回执格式：Q 行含问题原文（内含「停止」）+ A 行是用户的选择
+      return {
+        ok: true,
+        content: `用户已回答 AskUserQuestion：\n\nQ1 [审批闸门] ${args.questions[0].question}\nA1: 继续执行 (推荐)`,
+      };
+    };
+    const def: WorkflowDef = {
+      name: 'pause-q-contains-stop',
+      description: 'd',
+      steps: [
+        {
+          id: 'gate',
+          type: 'pause',
+          prompt: '计划已生成。选「停止」会保留现场，稍后可从断点续跑。',
+        },
+        { id: 'after', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const end = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'gate',
+    );
+    expect(end?.ok).toBe(true);
+  });
+
+  it('pause 真 HITL：自由输入（其他逃生项）→ 不放行，原话进 halt 文案', async () => {
+    ctx.executeTool = async () => ({
+      ok: true,
+      content: '用户已回答 AskUserQuestion：\n\nQ1 [审批闸门] 是否继续？\nA1: 先把第3步的方案换成方案B',
+    });
+    const def: WorkflowDef = {
+      name: 'pause-freetext',
+      description: 'd',
+      steps: [{ id: 'gate', type: 'pause', prompt: '是否继续？' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    const halt = events.find(
+      (e): e is { type: 'error'; error: string } =>
+        e.type === 'error' && e.error.includes('Workflow halted'),
+    );
+    expect(halt).toBeDefined();
+    expect(halt!.error).toContain('先把第3步的方案换成方案B');
+  });
+
+  it('pause 真 HITL：free_text=approve 时自由输入作为补充要求放行并 capture', async () => {
+    ctx.executeTool = async () => ({
+      ok: true,
+      content:
+        '用户已回答 AskUserQuestion：\n\nQ1 [审批闸门] 是否继续？\nA1: 确认使用 pptx skill，不要从头摸索 ppt 操作',
+    });
+    const def: WorkflowDef = {
+      name: 'pause-freetext-approve',
+      description: 'd',
+      steps: [
+        {
+          id: 'gate',
+          type: 'pause',
+          prompt: '是否继续？',
+          free_text: 'approve',
+          capture: { text: 'approval_notes' },
+        },
+        { id: 'after', type: 'assert', condition: "includes(approval_notes, 'pptx skill')" },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    const end = events.find(
+      (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+        e.type === 'workflow_step_end' && e.id === 'gate',
+    );
+    expect(end?.ok).toBe(true);
+    expect(end?.output).toContain('补充要求');
+    expect(end?.output).toContain('pptx skill');
+  });
+
+  // R1 减法重构：专用 approval_loop 步类型已删除（0 个 yaml 使用即孤儿）。
+  // 同一审批语义由通用组合表达（loop + pause(free_text:approve) + branch + llm 修订），
+  // 与 plan.yaml v4 的 stage4 审批环同范式——本测试锁定该组合的行为等价性。
+  it('plan 审批闭环（通用组合）：自由输入先改 PLAN.md，再次明确继续后才执行', async () => {
+    let askCount = 0;
+    ctx.executeTool = async (name: string, rawArgsJson: string, signal?: AbortSignal) => {
+      if (name === 'AskUserQuestion') {
+        askCount += 1;
+        return {
+          ok: true,
+          content:
+            askCount === 1
+              ? '用户已回答 AskUserQuestion：\n\nQ1 [审批闸门] 是否继续？\nA1: 图形都用 svg，不要位图'
+              : '用户已回答 AskUserQuestion：\n\nQ1 [审批闸门] 是否继续？\nA1: 继续执行 (推荐)',
+        };
+      }
+      return (await import('../../../src/tools/index.js')).executeTool(name, rawArgsJson, signal);
+    };
+    ctx.chat = async function* () {
+      yield { type: 'text_delta', delta: '最终计划：所有图形都用 svg\n## 产出物清单\n- [ ] executed.txt' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'plan-approval-loop',
+      description: 'd',
+      artifacts: ['PLAN.md', 'executed.txt'],
+      steps: [
+        { id: 'init', type: 'set', set: { final_plan_text: '初版计划：图形随意', plan_approved: false, approval_notes: '' } },
+        {
+          id: 'write_plan',
+          tool: 'Write',
+          args: { file_path: 'PLAN.md', content: '${final_plan_text}' },
+          artifacts: ['PLAN.md'],
+        },
+        {
+          id: 'approval',
+          type: 'loop',
+          max_iterations: 3,
+          do: [
+            {
+              id: 'gate',
+              type: 'pause',
+              prompt: '是否继续执行 PLAN.md？',
+              free_text: 'approve',
+              capture: { text: 'approval_notes' },
+            },
+            {
+              id: 'route',
+              type: 'branch',
+              condition: "approval_notes == ''",
+              then: [
+                { id: 'mark_approved', type: 'set', set: { plan_approved: 'true' } },
+                { id: 'approved_break', type: 'break' },
+              ],
+              else: [
+                {
+                  id: 'revise',
+                  llm: '把用户反馈合入计划：${approval_notes}\n当前计划：${final_plan_text}',
+                  capture: { text: 'final_plan_text' },
+                },
+                {
+                  id: 'revise_write',
+                  tool: 'Write',
+                  args: { file_path: 'PLAN.md', content: '${final_plan_text}' },
+                  artifacts: ['PLAN.md'],
+                },
+                { id: 'clear_notes', type: 'set', set: { approval_notes: '' } },
+              ],
+            },
+          ],
+        },
+        {
+          id: 'ensure_approved',
+          type: 'assert',
+          condition: "plan_approved == true || plan_approved == 'true'",
+        },
+        {
+          id: 'execute',
+          tool: 'Write',
+          args: { file_path: 'executed.txt', content: 'executed after approval' },
+          artifacts: ['executed.txt'],
+        },
+      ],
+    };
+
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(askCount).toBe(2);
+    expect(readFileSync(join(tmp, 'PLAN.md'), 'utf8')).toContain('svg');
+    expect(readFileSync(join(tmp, 'executed.txt'), 'utf8')).toBe('executed after approval');
+
+    const ended = events
+      .filter(
+        (e): e is Extract<WorkflowEvent, { type: 'workflow_step_end' }> =>
+          e.type === 'workflow_step_end',
+      )
+      .map((e) => e.id);
+    expect(ended.indexOf('revise_write')).toBeLessThan(ended.indexOf('execute'));
+  });
+
+  it('pause 真 HITL：用户取消提问（ESC）→ 不放行（审批门上取消 = 不批准）', async () => {
+    ctx.executeTool = async () => ({ ok: false, error: '提问被取消 / 中断：esc' });
+    const def: WorkflowDef = {
+      name: 'pause-cancel',
+      description: 'd',
+      steps: [{ id: 'gate', type: 'pause', prompt: '等审批' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+    expect(
+      events.some(
+        (e) => e.type === 'error' && e.error.includes('选择停止'),
+      ),
+    ).toBe(true);
+  });
+
+  it('P1 TUI 可见：每个 step 镜像 plugin_progress，tool 步骤发 tool_start/tool_end', async () => {
+    const def: WorkflowDef = {
+      name: 'visible',
+      description: 'd',
+      steps: [
+        { id: 'w', tool: 'Write', args: { file_path: 'out.txt', content: 'hi' } },
+        { id: 'a', type: 'assert', condition: 'true' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    const types = events.map((e) => e.type);
+
+    // 通用进度事件：开工(0/2) + 2 个 step 级 + 完成(2/2) = 4 条 plugin_progress
+    const pp = events.filter(
+      (e): e is Extract<LoopEvent, { type: 'plugin_progress' }> =>
+        e.type === 'plugin_progress',
+    );
+    expect(pp.length).toBe(4);
+    expect(pp.every((e) => e.pluginId === 'workflow-runner')).toBe(true);
+    expect(pp.some((e) => e.message?.includes('step w (tool)'))).toBe(true);
+
+    // tool 步骤像普通 ReAct 工具调用一样可见
+    expect(types.filter((t) => t === 'tool_start').length).toBe(1);
+    expect(types.filter((t) => t === 'tool_end').length).toBe(1);
+    const ts = events.find(
+      (e): e is Extract<LoopEvent, { type: 'tool_start' }> =>
+        e.type === 'tool_start',
+    );
+    expect(ts?.toolName).toBe('Write');
+
+    // 私有 workflow_* 仍在（-p / 既有 e2e 测试依赖），但末位可能因 v0.9 重构后
+    // runWorkflow 补发 assistant_message 而非严格以 workflow_done 收尾。
+    expect(types[0]).toBe('workflow_start');
+    expect(types).toContain('workflow_done');
+    expect(existsSync(join(tmp, 'out.txt'))).toBe(true);
+  });
+
+  it('P1 skill step：加载 cwd/skills/<name>/SKILL.md，跑 runQuery 累计 text', async () => {
+    // 在 tmp 准备一个最小 SKILL.md
+    const skillDir = join(tmp, 'skills', 'echo-bot');
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, 'SKILL.md'),
+      '---\nname: echo-bot\ndescription: echo\n---\n\n按用户指示原样输出',
+      'utf8',
+    );
+
+    // skill executor 经真实 runQuery(TAOR) 执行；用 ctx.chat DI 注入 stub chat，
+    // 让真实 runQuery 真把 assistant 消息推进 ctx.history（skill.ts 据此提取结果）。
+    // 不再 mock.module(loop.js)——那是空壳 runQuery 不推 history（提取空、必失败），
+    // 且会全局泄漏污染其它测试文件（recovery 等的 runRecovery 也走 runQuery）。
+    ctx.chat = async function* () {
+      yield { type: 'text_delta', delta: 'echoed-' };
+      yield { type: 'text_delta', delta: 'OK' };
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'skill-test',
+      description: 'd',
+      steps: [
+        {
+          id: 'sk',
+          skill: 'echo-bot',
+          input: 'say hi',
+          capture: { text: 'msg' },
+        },
+        { id: 'check', type: 'assert', condition: 'msg == "echoed-OK"' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+  });
+
+  it('P1 skill step：未找到 skill → halt + error', async () => {
+    const def: WorkflowDef = {
+      name: 'skill-missing',
+      description: 'd',
+      steps: [{ id: 'sk', skill: 'definitely-not-exists' }],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(false);
+  });
+
+  it('onError:continue 降级 → capture 绑明确占位文本（非空串）+ warning 可见化', async () => {
+    // chat 永远 throw → llm 步空产出抛异常 → max_retries=0 直接落 onError:continue。
+    // 此前降级完全静默且 capture 留空：下游 prompt 内插 ${req} 得空段，模型困惑。
+    ctx.chat = async function* () {
+      throw new Error('provider down');
+      // biome-ignore lint/correctness/noUnreachable: stub
+      yield { type: 'done', stopReason: 'stop' };
+    };
+
+    const def: WorkflowDef = {
+      name: 'continue-placeholder',
+      description: 'd',
+      steps: [
+        {
+          id: 'g',
+          llm: 'do it',
+          capture: { text: 'req' },
+          max_retries: 0,
+          onError: 'continue',
+        },
+        // 占位文本生效：req 非空且含机器可识别前缀
+        { id: 'check', type: 'assert', condition: 'includes(req, "上游步骤 g 失败")' },
+      ],
+    };
+    const events = await collect(runWorkflow(def, {}, ctx));
+
+    expect(events.some((e) => e.type === 'workflow_done')).toBe(true);
+    expect(
+      events.some(
+        (e) => e.type === 'warning' && e.message.includes('降级'),
+      ),
+    ).toBe(true);
+  });
+});